README

Its provide a simple Composer script to symlink paths. Compatible with Composer v2.

Installation

To install the latest stable version of this component, open a console and execute the following command:

$ composer require somework/composer-symlinks

Usage

1. Define symlinks

Create the symlinks definition adding a somework/composer-symlinks section inside the extra section of the composer.json file.

The behaviour of the plugin can be tuned via the following configuration keys:

Key	Default	Description
`skip-missing-target`	`false`	Do not fail when the target does not exist.
`absolute-path`	`false`	Create symlinks using the real path to the target.
`throw-exception`	`true`	Throw an exception on errors instead of just printing the message.
`force-create`	`false`	Remove any existing file or directory at the link path before creating the symlink.

You can set personal configs for any symlink.
For personal configs link must be defined

{
    "extra": {
        "somework/composer-symlinks": {
            "symlinks": {
                "common/upload": "web/upload",
                "common/static/dest": {
                    "link": "web/dest",
                    "skip-missing-target": false,
                    "absolute-path": true,
                    "throw-exception": false
                }
            },
            "force-create": false,
            "skip-missing-target": false,
            "absolute-path": false,
            "throw-exception": true
        }
    }
}

3. Execute composer

DO NOT use --no-plugins for composer install or update

Dry run

Set environment variable SYMLINKS_DRY_RUN=1 to preview created links without modifying the filesystem.

Example output:

$ SYMLINKS_DRY_RUN=1 composer install --no-interaction
  [DRY RUN] Symlinking /tmp/sample/linked.txt to /tmp/sample/source/file.txt

Typical error messages

Message	Meaning
`No link passed in config`	The `link` option was missing for a symlink definition.
`No target passed in config`	The key of the `symlinks` map was empty.
`Invalid symlink target path`	The target path was absolute but should be relative.
`Invalid symlink link path`	The link path was absolute but should be relative.
`The target path ... does not exists`	The target file or directory was not found.
`Link ... already exists`	A file/directory already occupies the link path.
`Cant unlink ...`	The plugin failed to remove a file when using `force-create`.

Windows compatibility

On Windows, creating symlinks requires either Administrator privileges or that the system is running in Developer Mode. The plugin itself works, but the underlying operating system may refuse to create a link if permissions are insufficient. Additionally, relative symlinks use Unix-style / separators internally which Windows resolves correctly.

License

This component is under the MIT license. See the complete license in the LICENSE file.

Reporting an issue or a feature request

Issues and feature requests are tracked in the Github issue tracker.

somework / composer-symlinks

Maintainers

Details