English | 中文文档
Package: super-kernel/metadata · Packagist · Documentation index
super-kernel/metadata tells an application where it is installed and which packages it consists of, without parsing Composer files or scanning sources when it starts. skernel build writes the packages, their environment requirements, and their class maps once, below the vendor directory; this package restores them, checks that they still match the project's composer.lock, and serves them through the shared SuperKernel\Contract interfaces.
Collecting the metadata belongs to skernel build; autoloading stays with Composer's vendor/autoload.php. The Attribute records that skernel build writes next to the metadata belong to super-kernel/annotator.
Three providers restore the metadata. Each carries the #[FactoryProvider] Attribute, so a SuperKernel container resolves the interfaces through them; outside a container, call them in this order:
new VendorDirProvider()()returns theSuperKernel\Contract\VendorDirInterfaceof the first registered Composer class loader that loads this package. A local directory is canonicalized; aphar://path is kept as registered.new BasePathProvider()($vendorDir)returns theSuperKernel\Contract\BasePathInterface: the project directory that the build recorded, resolved against the vendor directory.new PackageManagerProvider()($vendorDir, $basePath)checks the build stamp against the project'scomposer.lockand returns theSuperKernel\Contract\PackageManagerInterface.
Each call reads the files again and returns a new value. A container keeps one instance of each interface, and super-kernel/di calls the providers itself when it creates the root container, before the container exists.
A class of the project, saved as src/Billing/Invoice.php:
<?php
declare(strict_types=1);
namespace Src\Billing;
final class Invoice
{
}A script that restores the metadata, saved as bin/packages.php:
<?php
declare(strict_types=1);
use Src\Billing\Invoice;
use SuperKernel\Metadata\Provider\BasePathProvider;
use SuperKernel\Metadata\Provider\PackageManagerProvider;
use SuperKernel\Metadata\Provider\VendorDirProvider;
require dirname(__DIR__) . '/vendor/autoload.php';
$vendorDir = new VendorDirProvider()();
$basePath = new BasePathProvider()($vendorDir);
$packages = new PackageManagerProvider()($vendorDir, $basePath);
echo $packages->packageForClass(VendorDirProvider::class)?->name(), PHP_EOL;
echo $packages->root()->composerType(), PHP_EOL;
var_dump($packages->packageForClass(Invoice::class) === $packages->root());
var_dump($packages->root()->locatedPath() === (string) $basePath);Build the project and run the script:
skernel build
php bin/packages.phpIt prints:
super-kernel/metadata
project
bool(true)
bool(true)
PackageManagerInterface answers from the restored metadata only:
all()returns the root package first, followed by the installed packages sorted by name;packages()returns the installed packages without the root.root()returns the project;get($name)finds the root or an installed package by its name in any case and returnsnullfor an unknown one;ofComposerType($type)returns the packages whose declared Composer type is exactly$type.classes($name)returns the class map of one package, from class name to absolute file path, ornullfor an unknown package.allClasses()returns the class maps of all packages together; when two packages declare the same class, the one earlier inall()owns it.packageForClass($class)returns the owning package, ornull.
Each package is a SuperKernel\Contract\PackageMetadataInterface:
name()is the lowercase Composer name.version()is the version exactly as Composer recorded it, ornullwhen the root manifest declares none; it is not normalized or compared.reference()is the distribution reference, falling back to the source reference, ornull.locatedPath()is the package directory; for the root it is the project directory.- The restored packages also expose
composerType(), which islibrarywhen the package declares no type, andenvironmentRequirements().
environmentRequirements() of the package manager returns the requirements on Composer platform packages, such as php or ext-swoole, declared by the root and by every installed package; hasEnvironmentRequirements() reports whether there are any. Each is a SuperKernel\Contract\EnvironmentRequirementInterface:
name()is the lowercase platform package name,constraint()the constraint exactly as declared, andrequiredBy()the declaring package.isDevRequirement()istrueonly for a requirement in the root'srequire-dev; therequire-devof installed packages is never recorded.
super-kernel/environment checks these requirements against the running PHP.
A script that prints the requirements of one package, saved as bin/requirements.php:
<?php
declare(strict_types=1);
use SuperKernel\Metadata\Provider\BasePathProvider;
use SuperKernel\Metadata\Provider\PackageManagerProvider;
use SuperKernel\Metadata\Provider\VendorDirProvider;
require dirname(__DIR__) . '/vendor/autoload.php';
$vendorDir = new VendorDirProvider()();
$packages = new PackageManagerProvider()($vendorDir, new BasePathProvider()($vendorDir));
foreach ($packages->environmentRequirements() as $requirement) {
if ($requirement->requiredBy() === 'super-kernel/metadata') {
echo $requirement->name(), ' ', $requirement->constraint(), PHP_EOL;
}
}After skernel build, php bin/requirements.php prints php >=8.4.27 <8.5.
In an application, take the interfaces as constructor parameters; the container supplies the instances it keeps.
A service that reports on installed packages, saved as src/Diagnostics/PackageReport.php:
<?php
declare(strict_types=1);
namespace Src\Diagnostics;
use SuperKernel\Contract\PackageManagerInterface;
use SuperKernel\Contract\VendorDirInterface;
use function basename;
final readonly class PackageReport
{
public function __construct(private PackageManagerInterface $packages, private VendorDirInterface $vendorDir)
{
}
public function describe(string $name): string
{
$package = $this->packages->get($name);
if (null === $package) {
return "{$name} is not installed";
}
return $package->name() . ' is installed in ' . basename((string) $this->vendorDir);
}
}A script that uses it, saved as bin/report.php:
<?php
declare(strict_types=1);
use Src\Diagnostics\PackageReport;
use SuperKernel\Context\ApplicationContext;
require dirname(__DIR__) . '/vendor/autoload.php';
$report = ApplicationContext::getContainer()->get(PackageReport::class);
echo $report->describe('Super-Kernel/Metadata'), PHP_EOL;
echo $report->describe('acme/missing'), PHP_EOL;After skernel build, php bin/report.php prints:
super-kernel/metadata is installed in vendor
acme/missing is not installed
skernel build writes two files below the vendor directory. SuperKernel\Metadata\Constants\ArtifactLayout names them.
| File | Content |
|---|---|
.cache/build.json |
The build stamp: the build protocol, the SKERNEL version, the SHA-256 of composer.lock, and the project directory relative to the vendor directory. |
.cache/metadata.ser |
Every package with its class map, with paths relative to the project and vendor directories, protected by a checksum. |
A build stamp looks like this:
{
"protocol": 1,
"skernel": "1.0.0-alpha.2",
"lock": "3f9c5d0e6a1b2c4d8e7f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5",
"base-path": ".."
}- Ship both files and the project's
composer.lockwith the application;skernel packagedoes. Restoration hashescomposer.lockand refuses metadata built for different contents. - When the vendor directory lies inside the project,
base-pathis relative, so the project and its vendor directory can move together. Inside a Phar, the paths start withphar://. A vendor directory outside the project records the project directory as an absolute path, so that project cannot move. - A build removes the stamp first and writes it last, so an interrupted build leaves no stamp and restoration refuses it.
- The files are trusted local data: restoration deserializes the records. Never let an untrusted writer place them.
- The stamp does not record whether the build ran with or without development packages. Build again after switching between
composer installandcomposer install --no-dev.
skernel build publishes the metadata in the project's own process, with the version of this package that the project installs, so the format always matches the reader. SuperKernel\Metadata\Constants\Protocol::VERSION names the protocol of that format; skernel build builds only a project whose protocol it supports.
new SuperKernel\Metadata\Build\MetadataPublisher($vendorDir, $basePath) takes the canonical absolute vendor and project directories. Call its methods in this order:
invalidate()removes the stamp, then the package records.publishPackages($manager)writes the records of aSuperKernel\Metadata\Manager\PackageManager, whose root must be located at the project directory.- Publish the Attribute records with
super-kernel/annotator. commit($skernelVersion)checks that the records restore and then writes the stamp for the currentcomposer.lock. The version, such as1.0.0-alpha.2ordev, appears only in messages.
Each file is written to a temporary file in the same directory and renamed into place, with the permissions the umask allows.
A script that publishes the restored metadata again, saved as bin/republish.php:
<?php
declare(strict_types=1);
use SuperKernel\Metadata\Build\MetadataPublisher;
use SuperKernel\Metadata\Manager\PackageManager;
use SuperKernel\Metadata\Provider\BasePathProvider;
use SuperKernel\Metadata\Provider\PackageManagerProvider;
use SuperKernel\Metadata\Provider\VendorDirProvider;
require dirname(__DIR__) . '/vendor/autoload.php';
$vendorDir = new VendorDirProvider()();
$basePath = new BasePathProvider()($vendorDir);
$packages = new PackageManagerProvider()($vendorDir, $basePath);
assert($packages instanceof PackageManager);
$publisher = new MetadataPublisher($vendorDir, $basePath);
$publisher->invalidate();
$publisher->publishPackages($packages);
$publisher->commit('dev');
echo count(new PackageManagerProvider()($vendorDir, $basePath)->all()), ' packages republished', PHP_EOL;After skernel build, php bin/republish.php prints the number of packages including the root, such as 33 packages republished.
SuperKernel\Metadata\Exception\BuildRequiredException and SuperKernel\Metadata\Exception\MetadataException implement SuperKernel\Metadata\Exception\MetadataExceptionInterface. Every BuildRequiredException message ends with Run `skernel build` to generate the project metadata., which the table leaves out.
| Situation | Message |
|---|---|
| No build stamp | The build stamp <path> is missing. |
| The stamp cannot be decoded or has other keys | The build stamp is invalid. or The build stamp has an unexpected structure. |
| The stamp was written under another protocol | The metadata was generated by SKERNEL <version> under build protocol <n>, but this project expects <n>. |
The project has no composer.lock |
The project <path> has no readable composer.lock. |
composer.lock changed since the build |
The metadata generated by SKERNEL <version> does not match the current composer.lock. |
| No package records | The package records <path> are missing. |
| The package records are damaged | The package records are invalid. or The package records cannot be restored. |
No Composer class loader loads this package (MetadataException) |
No registered Composer class loader serves super-kernel/metadata. |
commit() before the records restore (MetadataException) |
The published package records do not restore. |
publishPackages() with a root outside the project (MetadataException) |
The root package must be located at the base path. |
super-kernel/contractdeclaresVendorDirInterface,BasePathInterface,PackageManagerInterface,PackageMetadataInterface, andEnvironmentRequirementInterface. Type your code against these interfaces.super-kernel/attributedeclares the#[FactoryProvider]Attribute on the providers.super-kernel/dicalls the providers when it creates the root container and keeps the three services; it reports missing metadata as this package'sBuildRequiredException.super-kernel/annotatorchecks its Attribute records against the package manager and writes them next to the metadata.super-kernel/environmentchecks the environment requirements;super-kernel/autoloaderuses the class maps.skernel buildcollects and publishes the metadata;skernel packageships it withcomposer.lock.
Do not ship the generated files without composer.lock. Restoration compares the stamp with the hash of composer.lock and raises The project <path> has no readable composer.lock. when the file is missing. Ship composer.lock with the application, as skernel package does.
Do not switch between development and production installs without building. composer install --no-dev after a development build leaves composer.lock unchanged, so the stale metadata is not detected and still lists the removed packages. Run skernel build after every install.
Do not edit or merge the generated files. The records carry a checksum and are rejected with The package records are invalid.; a changed stamp is rejected or no longer matches. Run skernel build instead.
Do not call commit() before the records are published. It refuses to write a stamp for records that do not restore, raising The published package records do not restore., and the application cannot start until a complete build. Call invalidate(), publishPackages(), publish the Attribute records, and commit(), in that order.