Manual:External libraries

This page documents how to add new external libraries to MediaWiki core.

We use [https://getcomposer.org/ composer] to manage dependencies.


 * 1) Find your external library.  It should be available on packagist, and have a tagged release that you wish to use.


 * 1) File a bug for requesting a security review of the library.  Please add the [https://phabricator.wikimedia.org/project/view/818/ MediaWiki-Vendor] project to the task.


 * 1) Once the security review is approved, submit a patch to the mediawiki/vendor repository, adding the library.
 * Your patch should use fixed version numbers (e.g. 1.0.0) so we always use a specific version of the library instead of depending upon the upstream maintainer to properly follow the [http://semver.org/ semantic versioning rules] as many don't.


 * 1) Upload your mediawiki/core patchset which uses the library and include a link to your mediawiki/vendor commit in the comments.  (This step can be done earlier, but can't be merged until the security review is complete.)


 * You will also need to update core's composer.json file in your patch (using a fixed version number)


 * 1) Go through the normal code review process.  Once your code is ready for merging, the mediawiki/vendor patch should be merged, and then the mediawiki/core patch, so unit tests will be able to use the library.

For Wikimedia-deployed extensions, the process is similar. You will need to create a composer.json file for your extension listing your dependencies. In your extension.json file, set  (documentation) so those dependencies are loaded.

The dist>Special:ExtensionDistributor|extension distributor automatically packages composer dependencies, so tarball users won't have to do it manually.

You'll then need to add the library to the mediawiki/vendor repository after the security review is complete.