PHP Autoload Ordering: Determinism Beyond Alphabetical

Résumé

Pixel’s announcement explores how PHP package installers can produce different runtime behavior despite including the same files. It explains why Composer’s autoload.files needs dependency-aware ordering rather than simple alphabetical sorting, and why preserving initialization dependencies matters for reliable application startup.

DEV Community

Deterministic Does Not Mean Alphabetical: Dependency Ordering in PHP Package Tooling

Coretsia Engineering Notes — 01 Two package installers can generate exactly the same set of autoload entries for the same application and still produce different runtime behavior. One generated bootstrap initializes successfully, while the other fails with an undefined-function error before reaching the application's own entry point. The difference lies not in which files were installed, but in the order in which they are executed. Sorting generated PHP artifacts alphabetically may seem like a straightforward way to achieve determinism. While this approach works well for unordered collections, executable initialization sequences require stronger guarantees: their ordering must preserve the underlying dependency relationships. When deterministic ordering breaks application startup While exploring PHP package tooling, I came across an interesting problem involving the order of generated autoload entries. A package installer can correctly identify every file that needs to be included, yet generate an invalid initialization sequence by sorting packages alphabetically instead of respecting their dependency relationships. If a package invokes a function provided by one of its dependencies during initialization, loading the dependent package first may cause application startup to fail despite all required packages being correctly installed. This raises an important engineering question: what does it actually mean for a generated artifact to be deterministic? Comparing package lists, file counts or unordered collections of autoload entries is insufficient when execution order is itself part of the contract. Why autoload.files is different PHP's class autoloading mechanism can resolve a class when it is needed, but it does not provide an equivalent mechanism for discovering arbitrary standalone function definitions. Composer's autoload.files addresses this by eagerly including designated PHP files when vendor/autoload.php is required, after the class loader has been registered. The Composer schema documentation defines dependency-aware inclusion order, alphabetical ordering for equally ranked packages, and the placement of root-package files after dependency files. This distinction matters because an autoload.files entry is not simply a path in a lookup table: it represents executable PHP code. If that code invokes a function supplied by another package during inclusion, the function must already exist. A minimal reproduction To isolate the underlying ordering problem, I prepared a minimal reproduction consisting of two local PHP packages, without external package dependencies. The package names are intentional: application sorts before helpers, even though the dependency must be initialized first. acme/application requires acme/helpers
packages/helpers/composer.json: {
"name": "acme/helpers",
"version": "1.0.0",
"autoload": {"files": ["functions.php"]}
}
packages/helpers/functions.php: <?php

declare(strict_types=1);

namespace Acme\Helpers;

function greeting(): string
{
return 'Application initialized';
}
packages/application/composer.json: {
"name": "acme/application",
"version": "1.0.0",
"require": {"acme/helpers": "1.0.0"},
"autoload": {"files": ["bootstrap.php"]}
}
packages/application/bootstrap.php: <?php

declare(strict_types=1);

echo \Acme\Helpers\greeting(), PHP_EOL;
The reproduction script reads the local package manifests, extracts their declared dependencies and autoload files, and selects one of two ordering strategies. Unlike a hard-coded inclusion sequence, this allows the dependency-aware order to be derived directly from package metadata. The experiment operates on a predefined package collection without performing version resolution or package installation. The graph strategy uses the dependencyOrder() function defined in order.php, presented later in the article. reproduce.php: <?php

declare(strict_types=1);

require DIR . '/order.php';

$mode = $argv[1] ?? '';

if (!i...
PHP Autoload Ordering: Determinism Beyond Alphabetical
Powered by Readybot.io

Les dernières actus de Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …