PHP Autoload Ordering: Determinism Beyond Alphabetical
ملخص
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...

Powered by Readybot.io