coenjacobs/mozart

Composes all dependencies as a package inside a WordPress plugin

Fund package maintenance!
coenjacobs

Installs: 56 664

Dependents: 6

Suggesters: 5

Security: 0

Stars: 263

Watchers: 7

Forks: 19

Open Issues: 42

0.6.0 2021-01-17 15:41 UTC

README

Composes all dependencies as a package inside a WordPress plugin. Load packages through Composer and have them wrapped inside your own namespace. Gone are the days when plugins could load conflicting versions of the same package, resulting in hard to reproduce bugs.

This package requires PHP 7.3 or higher in order to run the tool. You can use the resulting files as a bundle, requiring any PHP version you like, even PHP 5.2.

Warning: This package is very experimental and breaking changes are very likely until version 1.0.0 is tagged. Use with caution, always wear a helmet when using this in production environments.

Installation

Docker

Pull the Docker image from the registry:

docker pull coenjacobs/mozart

Then you can start the container and run the mozart compose command in the container. In a single command:

docker run --rm -it -v ${PWD}:/project/ coenjacobs/mozart /mozart/bin/mozart compose

Above command automatically adds the current working directory as a volume into the designated directory for the project: /project/. In the Docker container, Mozart is installed in the /mozart/ directory. Using the above command will run Mozart on the current working directory.

Please note that the Docker image for Mozart is only available starting from the latest build of version 0.7.0. The latest tag is always the latest build of the master branch and not a stable version. You can see all available tags on Docker Hub.

Composer

Install through Composer, only required in development environments:

composer require coenjacobs/mozart --dev

This gives you a bin file named mozart inside your vendor/bin directory, after loading the whole package inside your project. Try running vendor/bin/mozart to verify it works.

After configuring Mozart properly, the mozart compose command does all the magic.

Configuration

Mozart requires little configuration. All you need to do is tell it where the bundled dependencies are going to be stored and what namespace they should be put inside. This configuration needs to be done in the extra property of your composer.json file:

"extra": {
    "mozart": {
        "dep_namespace": "CoenJacobs\\TestProject\\Dependencies\\",
        "dep_directory": "/src/Dependencies/",
        "classmap_directory": "/classes/dependencies/",
        "classmap_prefix": "CJTP_",
        "packages": [
            "pimple/pimple"
        ],
        "exclude_packages": [
            "psr/container"
        ],
        "override_autoload": {
            "google/apiclient": {
                "classmap": [
                    "src/"
                ]
            }
        },
        "delete_vendor_directories": true
    }
},

The following configuration values are required:

  • dep_namespace defines the root namespace that each package will be put in. Example: Should the package we're loading be using the Pimple namespace, then the package will be put inside the CoenJacobs\\TestProject\\Dependencies\\Pimple namespace, when using the configuration example above.
  • dep_directory defines the directory the files of the package will be stored in. Note that the directory needs to correspond to the namespace being used in your autoloader and the namespace defined for the bundled packages. Best results are achieved when your projects are using the PSR-4 autoloader specification.
  • classmap_directory defines the directory files that are being autoloaded through a classmap, will be stored in. Note that this directory needs to be autoloaded by a classmap in your projects autoloader.
  • classmap_prefix defines the prefix that will be applied to all classes inside the classmap of the package you bundle. Say a class named Pimple and the defined prefix of CJTP_ will result in the class name CJTP_Pimple.

Important: Since Mozart automatically processes the full dependency tree of the packages you specify, you need to specify all these configuration options, because you can't reliably determine what kind of autoloaders are being used in the full dependency tree. A package way down the tree might suddenly use a classmap autoloader for example. Make sure you also include the namespace directory and classmap directory in your own autoloader, so they are always loaded.

The following configuration is optional:

  • delete_vendor_directories is a boolean flag to indicate if the packages' vendor directories should be deleted after being processed. default: true.
  • packages is an optional array that defines the packages to be processed by Mozart. The array requires the slugs of packages in the same format as provided in your composer.json. Mozart will automatically rewrite dependencies of these packages as well. You don't need to add dependencies of these packages to the list. If this field is absent, all packages listed under composer require will be included.
  • exclude_packages is an optional array that defines the packages to be excluded from the processing performed by Mozart. This is useful if some of the packages in the packages array define dependent packages whose namespaces you want to keep unchanged. The array requires the slugs of the packages, as in the case of the packages array.
  • override_autoload a dictionary, keyed with the package names, of autoload settings to replace those in the original packages' composer.json autoload property.

After Composer has loaded the packages as defined in your composer.json file, you can now run mozart compose and Mozart will bundle your packages according to the above configuration. It is recommended to dump the autoloader after Mozart has finished running, in case there are new classes or namespaces generated that aren't included in the autoloader yet.

Scripts

Mozart is designed to install and be forgotten about. Using Composer scripts, the Mozart script can be run as soon as Composer either installs a new package, or updates an already installed one. This ensures that the packages you want to bundle, are always bundled in the latest installed version, automatically. These scripts also offer you the possibility to script dumping the autoloader, after Mozart is finished running:

"scripts": {
    "post-install-cmd": [
        "\"vendor/bin/mozart\" compose",
        "composer dump-autoload"
    ],
    "post-update-cmd": [
        "\"vendor/bin/mozart\" compose",
        "composer dump-autoload"
    ]
}