Jetpack Autoloader Laravel Package

Product Decisions This Supports

• Build vs. buy for dependency isolation. This is a "buy" (well, take-for-free) answer to a recurring WordPress ecosystem problem: when two plugins on the same site each bundle a different version of the same Composer package, the first one loaded wins and the other plugin breaks in confusing, intermittent ways. Adopting the Jetpack Autoloader removes that failure mode as a support category rather than having the team invent and maintain its own version-resolution layer.
• Roadmap: shared internal libraries across a plugin portfolio. If we plan to ship more than one plugin (or a plugin plus an add-on/companion plugin) that depend on common internal packages, this package is the enabler. It lets each plugin ship its own vendor/ directory with whatever version it was built against, while guaranteeing the site loads the newest available copy at runtime. Without it, "shared library" effectively means "lockstep releases across every plugin," which is a roadmap constraint we'd otherwise have to accept.
• Feature decisions about bundling vs. depending on site configuration. It commits us to shipping dependencies inside the plugin rather than asking site owners to manage Composer. That is the correct call for distributed WordPress products and should be stated explicitly as a product principle, not left implicit.
• Support and triage design. The package ships two diagnostic constants (JETPACK_AUTOLOAD_DEBUG_EARLY_LOADS and JETPACK_AUTOLOAD_DEBUG_CONFLICTING_LOADERS) aimed at the two most common root causes of "worked yesterday, broken today" bug reports: classes autoloaded before plugins_loaded, and third-party autoloaders registered at a higher priority. That directly reduces time-to-diagnosis for support and gives us a documented first-response playbook.
• Use-case qualification for sales/partnerships. If a prospect or integration partner runs a stack of plugins that co-bundle shared libraries, this is a concrete technical differentiator we can point at when discussing compatibility guarantees.
• Caveat that shapes planning, not just engineering: the benefit is only guaranteed when every plugin touching the shared package uses this autoloader. If a partner plugin uses vanilla Composer, resolution falls back to load order. That is a product-level constraint on any "compatible with everything" claim we make.

When to Consider This Package

Consider it when most of the following hold:

• We are shipping WordPress plugins as distributed artifacts (not a single hosted application), and users install them by uploading a zip with vendor/ included.
• We have, or expect to have, more than one plugin in the wild sharing at least one Composer package — including the case where the shared package is something like a common utility or an HTTP client.
• We are willing to follow the package's conventions: default vendor directory, classmap-oriented autoloading, loading vendor/autoload_packages.php from the main plugin file, and generating an optimized autoloader in release builds.
• Our team is comfortable that the class-to-package version hierarchy is driven by package semantic versions, and will avoid moving classes between packages in ways that break that hierarchy.

Look elsewhere when:

• Single plugin, no shared dependencies. The package solves a multi-plugin conflict problem that does not exist yet; it adds a non-standard autoload entry point and an extra build convention for no benefit.
• Not a WordPress plugin context. Classic Laravel services, single-tenant apps, or anything where Composer's own resolution at build time is authoritative don't need runtime version arbitration.
• You want true namespace isolation instead. If the goal is "my dependencies can never collide with anyone else's," PHP-Scoper-style prefixing is a different and often better answer; this package arbitrates between versions rather than isolating them.
• You need vendor-backed support or a stability contract. This repository is explicitly a read-only mirror of the Jetpack monorepo, with issue tracking and development happening upstream. The low star count and zero listed dependents are artifacts of the mirroring, not a real signal of adoption — but they also mean there is no independent issue queue, no third-party ecosystem, and no support channel. Treat it as "maintained because Automattic needs it," not "maintained because we asked."
• You need strict PSR-4 semantics or heavy static analysis tooling. The optimized path converts PSR-4/PSR-0 namespaces to classmaps, and the project explicitly standardizes on classmap autoloading to accommodate WordPress coding standards. That's a reasonable trade, but it's a trade.
• You're unwilling to own the operational caveats. The in-memory classmap is built at load time and is not updated after a plugin update within the same request; renamed or moved class files can produce errors. There is also transient-cached plugin discovery, which can mask ordering bugs and produce intermittent failures that are hard to reproduce in QA.

How to Pitch It (Stakeholders)

For executives — one paragraph. This is a small, free, Automattic-maintained component that eliminates a class of breakage we would otherwise inherit: two of our plugins, or our plugin and a partner's, shipping different versions of the same bundled library and fighting over which one loads. Adopting it costs us a build convention and a documented debugging setting; not adopting it costs us either lockstep releases across our plugin line or a stream of intermittent, hard-to-reproduce support tickets. The realistic risks are that it's an internal tool published as a mirror (so no external support contract), and that its guarantees only hold if everything in the shared-library path uses it.

For engineering — one paragraph. Add automattic/jetpack-autoloader as a Composer requirement, keep the default vendor directory, and require vendor/autoload_packages.php from the main plugin file. Release builds must generate an optimized autoloader (composer install -o). It builds an in-memory classmap from jetpack_autoload_classmap.php / jetpack_autoload_filemap.php and resolves each class to the highest semantic version present across all installed plugins using it. Three things to internalize: (1) the classmap is built once at load and is not refreshed after a plugin update, so never move or rename a class file in a way that could be autoloaded post-update; (2) version comparison is by package version, so moving a class into a newer package with a lower version number will silently shadow it; (3) don't autoload our own classes before plugins_loaded — that can pin an older version before the newer provider registers, and it will only show up when the plugin-discovery transient is invalidated. Turn on JETPACK_AUTOLOAD_DEBUG_EARLY_LOADS and JETPACK_AUTOLOAD_DEBUG_CONFLICTING_LOADERS in staging to catch both patterns early. Note that the repository we'd link to is a read-only mirror — development and issue tracking live in automattic/jetpack upstream, so file bugs there and pin a specific major version rather than tracking dev.