Using Composer on VIP

Composer is a package manager for PHP that can be used when developing for an application on the WordPress VIP Platform.

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

Referencing the root /vendor directory

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 recognized 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/

Runtime dependencies

Dependencies needed by one custom plugin

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.

Dependencies needed by multiple plugins or themes

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 dependences there. To make use of autoloading, check for the existence of the vendor/autoloader.php file and require it if it exists. Logic for this check should be aded to the client-mu-plugins/plugin-loader.php file.

When to install a Composer runtime dependency

There are two points in a workflow when a runtime dependency can be installed.

• Recommended Option 1: Make use of the continuous integration and deployment (CI/CD) 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).
• Option 2: Use Composer on the local machine to install the runtime dependency. Include this built code in a commit and push it to the repository on GitHub. That method has the drawback of potentially making the pull request (and repository) very large, and makes code review more difficult.

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.

Use Composer for a development tool and configurations

Members of a team can use the same versions of code standards, testing and other development tools configurations, by setting them into the root composer.json.

The typical install location of /vendor should be added to .gitignore. Because the directory is not available for VIP environments, none of the files will be accessible during runtime. The increased size of the repo will also cause it to take longer to clone.