aryelgois/composer-front-end

A utility to install front-end files with Composer

A utility to install front-end files with Composer, _(*1)

Intro

By default Composer installs all package files under the vendor directory.
It is ok for Composer's main purpose: a tool for dependency management in PHP., _(*2)

But often, PHP projects involve other languages, like those used in front-end (JavaScript, CSS and their derivatives)., _(*3)

You could use different package managers to deal with each kind of file, but it would be too much work, and I think it is good to have a unified tool., _(*4)

This is where this package comes in. You will use Composer to fetch repositories containing front-end assets, and this package will symlink them to their appropriate directory., _(*5)

Install

Run this inside your project:, _(*6)

composer require aryelgois/composer-front-end, _(*7)

In order to avoid Composer warnings during a fresh install, keep the package entry at the beginning of composer.json require directive., _(*8)

Setup

Add this to your composer.json:, _(*9)

{
    "scripts": {
        "post-package-install": "aryelgois\\Composer\\FrontEnd::postPackageInstall",
        "front-end-refresh": "aryelgois\\Composer\\FrontEnd::refresh"
    },
}

Now, whenever you install a new package with front-end files, they will be symlinked., _(*10)

If you already installed some front-end packages, run composer front-end-refresh to look in every vendor package., _(*11)

Config files

These JSON files are used to tell which files should be symlinked and where., _(*12)

You could use any key you like for the file_group, but it needs to be the same in the vendor config and in your project., _(*13)

frontend.json

Used in vendor packages., _(*14)

It contains a map of 'file_group': ['file'] of files to be symlinked into your project.
Paths are relative to the vendor package directory., _(*15)

not vendor/, but vendor/some/package/, _(*16)

Example:

{
    "css": "assets/superduperstyle.css",
    "js": [
        "main.js",
        "src/myawesomescript.js"
    ]
}

It is possible to specify a single file without an array., _(*17)

frontend-config.json

Used in your project., _(*18)

It can include the following keys:, _(*19)

directories

(required), _(*20)

A map of 'file_group': 'directory' to contain symlinks from other packages.
Paths are relative to the root directory., _(*21)

packages

(optional), _(*22)

A map of 'package/name': files to be symlinked. The content would be the same as in frontend.json., _(*23)

Useful when a vendor does not include the frontend.json., _(*24)

It replaces the frontend.json, _(*25)

structure

(optional), _(*26)

Defines how the symlinks are placed in the directory of each file_group:, _(*27)

• nest: Symlinks will be created at vendor/package/, inside the specified directories. It helps with files with same name.
• flat: Symlinks will stay directly inside the defined directories.

structure_default

(optional), _(*28)

Defines the default structure for all directories. If not specified, nest is used., _(*29)

Example:

{
    "directories": {
        "css": "public/css",
        "js": "public/js"
    },
    "structure": {
        "css": "flat",        
    }
}

public/ is the Document Root, _(*30)

Notes

• You still need to manually add the markup to use the symlinked files in your webpage:, _(*31)

  , _(*32)

• Even with nest, all symlinks are placed flattened, i.e., the file structure in the vendor package is not preserved., _(*33)

TODO

• [ ] Add path expansion for frontend.json