Use Composer on VIP

Composer is a package manager for PHP that can be used when developing for VIP.

It can be used to pull in runtime dependency packages during a local or continuous integration (CI) builds, and development dependencies tools and configurations for local development and CI jobs.

Composer Tips

The root /vendor directory is not available at runtime

By default, Composer installs dependencies to the /vendor directory from where it is called. For a composer.json in the root of the repository, it would be the /vendor at the root of the repository.

However, this directory is not one of the recognised directories available in the application on VIP. Because of this, references to the /vendor directory and to any files within it will fail.

To make a dependency available to multiple plugins, set the vendor-dir to /client-mu-plugins/vendor or a similar directory, in the root composer.json.

{
    "config": {
        "vendor-dir": "client-mu-plugins/vendor"
    }
	"require": {
		"example/package": "^1"
	}
}

Configuring .deployignore

A  .deployignore file can be created and added to a repository. During the build process, the .deployignore file is renamed .gitignore just before the built files are pushed to *-built branches. Files and directories referenced in .gitignore will not be pushed to *-built branches, including files generated by a build process.

Pattern-matching rules for including or excluding files and directories in  .gitignore:

If there is a separator at the beginning or middle (or both) of the pattern, then the pattern is relative to the directory level of the particular .gitignore file itself. Otherwise the pattern may also match at any level below the .gitignore level.

•  /vendor will only match the root vendor directory (which should only contain the PHPCS and other dev-dependencies) since this is the root .gitignore
•  vendor/ will match all vendor directories at all levels.
• For applications with a runtime dependency, vendor/—or other directories named vendor â€”should not be included in the .deployignore file.

To prevent other non-root directories named vendor from being ignored, add the directory paths for those vendor directories to the .gitignore file with a ! appended to the directory path.

In the example below, the first line indicates that all directories named vendor will be ignored. The second line adds an exclusion for the /vendor directory specific to the plugin “my-custom-plugin”. As a result, all directories named vendor will be ignored except for the plugins/my-custom-plugin/vendor/ directory.

vendor/
!plugins/my-custom-plugin/vendor/

Development dependencies

Development dependencies are not needed when building for an application on a VIP environment. Use composer install --no-dev as the command to only install the runtime dependencies.

Runtime dependency

There are two considerations to make use of a runtime dependency package, such as code in a framework or library: where to install the dependency, and when to install the dependency.

Where to install a Composer runtime dependency

If only one custom plugin needs a dependency, then you can create a composer.json file in that plugin’s directory (e.g. plugin/my-custom-plugin/composer.json) with the required dependency, and run composer install --no-dev from that plugin directory. This will put the dependency into, for example, plugins/my-custom-plugin/vendor/. The call to require __DIR__ . '/vendor/autoloader.php'; can be in that plugin’s root file.

Alternatively, if you need the dependency available to multiple plugins or themes, then you can set the vendor-dir to client-mu-plugins/vendor or a similar directory, in the root composer.json (as /vendor is not available at runtime), and install to there. If you want to make use of autoloading, then you can check for the existence of the vendor/autoloader.php file and require it if it exists, with logic in the client-mu-plugins/plugin-loader.php file.

When to install a Composer runtime dependency

There are two points in the workflow when you can install a runtime dependency.

• The first (and recommended) is to make use of the Automated Build and Deploy process that VIP supports, so that the dependency is excluded from the local commit, but is pulled down during a build job, just before any tests and the deployment (push to a *-built deployment branch).
• The second approach is to use Composer on your local machine to install the runtime dependency, and include this code in a commit and push it to the repository on GitHub. Note that this has the drawback of potentially making the pull request (and repository) very large, which makes code review considerably trickier. It is not recommended.

Use Composer for a development tool and configurations

If you want all of your team to use the same versions of your code standards, testing and other development tools configurations, then this can also be set in Composer. This can be set in the root composer.json.

The typical install location of /vendor should be added to the .gitignore as per usual; since the directory isn’t available for VIP environments, then it won’t hurt to have it deployed, but none of the files will be accessible during runtime, so committing it only adds to the size of the repo, which then makes it take longer to clone.