Autoloader

Whatever project you’re working on in the Jetpack Monorepo, you may have to use the Jetpack Autoloader. For example, if you’re working on a Composer package that requires other Jetpack packages.

What is the Jetpack Autoloader

It’s an implementation of a PHP autoloader handler that relies Composer’s autoloader classmap generators. This article is meant to describe what Jetpack Autoloader (JPA for brevity) is, how it works and what are some gotchas that you should be aware of.

First of all, the purpose of JPA is to allow several plugins ship the same packages and always load the latest implementation of a class based on the package versions.

This is solved by keeping an in-memory map of all the different classes that can be loaded, and updating the map with the path to the latest version of the package for JPA to find when we instantiate the class. If you have worked with Composer’s autoloader before, here are some key differences:

It creates jetpack_autoload_classmap.php and jetpack_autoload_filemap.php files in the vendor/composer directory.
This file includes the version numbers from each package that is used.
The autoloader will only load the latest version of the package no matter what plugin loads the package. This behavior is guaranteed only when every plugin that uses the package uses the Jetpack Autoloader. If any plugin that requires the package uses a different autoloader, this autoloader may not be able to control which version of the package is loaded.

Usage

If you have generated a plugin using the Monorepo CLI and chose the “Starter Plugin” option, you are already using JPA, no need to do anything else. Otherwise in your project’s composer.json, add the following lines:

{
    "require": {
        "automattic/jetpack-autoloader": "^3"
    }
}

Alternatively you can have Composer do the legwork for you:

$ composer require automattic/jetpack-autoloader ^3

Your project must use the default Composer vendor directory, vendor.

After the next update/install, you will have a vendor/autoload_packages.php file. Load that file in the main plugin rather than Composer’s usual vendor/autoload.php:

require_once  plugin_dir_path( __FILE__ ) . '/vendor/autoload_packages.php';

Generating Autoloader files

All new Jetpack package development that is intended for use with WordPress should use classmap autoloading, which allows the class and file names to comply with the WordPress Coding Standards. Otherwise PSR-4 is recommended as the current PHP standard. A good rule of thumb to choose between these two is this: if you have to ignore WordPress code sniffs in your code, you should go for PSR-4.

If you are using the Jetpack Monorepo CLI to build your projects, the autoloader files will be generated for you automatically by the jetpack CLI commands. In case you have specific reasons to run the generator manually, you can either use:

Optimized Autoloader

An optimized autoloader is generated when:

composer install or composer update is called with -o or --optimize-autoloader
composer dump-autoload is called with -o or --optimize

PSR-4 and PSR-0 namespaces are converted to classmaps.

Unoptimized Autoloader

Supports PSR-4 autoloading. PSR-0 namespaces are converted to classmaps.

File generation under the hood

If you take a look at what the JPA package looks like, you can see that there are two types of files in there. One type are classes that run at Composer install time to generate autoloader files, the other type are placeholder files that will be concatenated with a specific header and footer to make sure they are shipped with the correct namespace.

The placeholder classes have distinctive comments at the top of the file. Let’s look at projects/packages/autoloader/src/class-autoloader-handler.php:

<?php
/* HEADER */ // phpcs:ignore

use Automattic\Jetpack\Autoloader\AutoloadGenerator;

/**
 * This class selects the package version for the autoloader.
 */
class Autoloader_Handler {

The /* HEADER */ comment is going to be replaced and will be saved as a file in your vendor folder called vendor/jetpack-autoloader/class-autoloader-handler.php:

<?php
/**
 * This file was automatically generated by automattic/jetpack-autoloader.
 *
 * @package automattic/jetpack-autoloader
 */

namespace Automattic\Jetpack\Autoloader\jpf11009ded9fc4592b6a05b61ce272b3c_jetpackⓥ14_0_a_1\al3_1_1;

 // phpcs:ignore

use Automattic\Jetpack\Autoloader\AutoloadGenerator;

/**
 * This class selects the package version for the autoloader.
 */
class Autoloader_Handler {

This is how runtime classes are generated. In addition, class mapping files are generated that list loadable classes and their corresponding package versions:

vendor/composer/jetpack_autoload_classmap.php
vendor/composer/jetpack_autoload_filemap.php
vendor/composer/jetpack_autoload_psr4.php

At runtime JPA uses these files to get information from all plugins that use JPA. To see it in action you can use the Jetpack Debug Helper plugin and enable the Autoload Debug Helper section.

Note that only JPA files are namespaced this way. This is done to make sure we can load all versions of the Autoloader files and yield control to the latest version. Other files that are put into classmaps, filemaps and PSR-4 paths are not namespaced.

Things you should be aware of

While the main idea of JPA is such that you always get the latest version of a class from the Jetpack Monorepo, there are some caveats and limitations you should know about.

Autoloader detection

To make sure we have a full map of all files that we should be loading, JPA does a search as soon as it’s loaded. It looks for other enabled plugins in the current WordPress installation that use JPA. WordPress usually loads plugins one by one, but JPA does its own thing and as soon as the first instance of JPA is loaded, it loads all others.

Consider this as an example. You have four plugins, two of them are using JPA:

drwxr-xr-x  akismet
drwxr-xr-x  jetpack
drwxr-xr-x  regenerate-thumbnails
drwxr-xr-x  woocommerce

Jetpack and WooCommerce here are using JPA. While WooCommerce is going to get loaded last, Woo’s bundled JPA is going to get loaded as soon as Jetpack loads its own. This will make all bundled classes available for autoloading immediately, but it’s still best to wait until all plugins are loaded before using autoloaded code.

Wait until plugins_loaded

It’s best to always use the plugins_loaded hook before starting to use autoloaded code. If you must make an exception for this rule, be aware of some caveats:

Make sure that JPA provided classes are not autoloaded from any other plugins using other implementations of autoloaders. To help with this you can use the JETPACK_AUTOLOAD_DEBUG_EARLY_LOADS constant. JPA will raise notices if it detects cases like this that can cause problems with early loads.
JPA caches active plugins in a transient. This will obscure problematic cases with early loading of code, so make sure to clear transients when testing your changes.

Be careful when making changes to shipped code

JPA decides what version to load by the package version the class is located in. If you’re migrating a class from one package to another, you can run into a problem if both of these packages remain available. You can either rename the class, or manually bump the new package version to a higher number. If all else fails, using some kind of feature detection can also work. But if you have to resort to the latter, it means you won’t be able to use newer code until the old package is completely phased out.

The best practice is to always be mindful of backwards and forward compatibility. For example, when you decide to stop using a function or a method, don’t remove it completely. Deprecate it instead using WordPress standard mechanisms.

Avoid changing method prototypes. Adding a required argument to a method will cause fatal errors if there’s existing code that’s based on the old prototype. Create new wrappers instead.

If you’re planning to remove the class entirely, leave it as a legacy shell until you’re sure that it’s not required by older versions anymore.

Watch out for update flows

When moving a package class file, renaming a package class file, or changing a package class namespace, make sure that the class will not be loaded after a plugin update.

JPA builds the in memory classmap as soon as the autoloader is loaded. The package class file paths in the map are not updated after a plugin update. If a plugins’s package class files are moved during a plugin update and a moved file is autoloaded after the update, an error will occur.

Older JPA versions are disabled

JPA has a mechanism to disable older versions of itself. This may trip you if you’re making changes in JPA code, but there’s a different newer version in the same development site.

Development versions are not loaded by default

JPA is set up to not load anything from packages that are versioned as development, except if they are the only remaining option.

The definition of “dev version” is that the version number is something like “dev-trunk” or “9999999-dev”. A version like “1.2.3-alpha” is not considered as being “dev” for this check, it will be compared like normal so 1.2.2 < 1.2.3-alpha < 1.2.3-beta < 1.2.3. Keep that in mind when testing your changes.

The “dev-trunk” is what your packages will get when developing in the Monorepo in your local environment, which will carry over to sites you update from your local environment with jetpack rsync or the like. But the GitHub CI build artifacts, including the versions used by Jetpack Beta Tester, will get “1.2.3-alpha” style versions.

To enable JPA to load development versions, use the JETPACK_AUTOLOAD_DEV constant, setting it to true.

In this article

Autoloader

Optimized Autoloader

Unoptimized Autoloader