Manual:External libraries

From mediawiki.org

This page documents how to add new external PHP libraries to MediaWiki core. (For adding external CSS/JS/LESS libraries, see the foreign resources system.) We use 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.
  2. Use this Phabricator form to request a security review of the library. Security reviews are required for any externally-written code (not by a MediaWiki developer). Security review requests are prioritised on a quarterly basis per this section of the relevant SOP. This checklist will be used as a basic set of best practices when reviewing all third-party code. Please add the MediaWiki-Vendor project to the task.
  3. 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 semantic versioning rules as many don't.
  4. 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)
  5. 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 "load_composer_autoloader": true, (documentation) so those dependencies are loaded.

The 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.

See also[edit]