README

pilotphp/core is the minimal package lifecycle and application kernel for the PilotPHP agent-first microservice framework.

It provides:

• immutable package manifests;
• Composer package discovery through vendor/composer/installed.php;
• manifest loading;
• package and capability dependency resolution;
• service provider registration and boot phases;
• typed extension and capability registries;
• diagnostic check registration;
• shutdown handlers and rollback for long-lived workers;
• DI container contracts without a concrete container implementation.

It does not provide RoadRunner, gRPC, HTTP, ORM, queues, logging, OpenTelemetry, configuration loading, service discovery, Kubernetes integration, console commands, or a concrete DI container.

Install

composer require pilotphp/core

Minimal Bootstrap

<?php

declare(strict_types=1);

use App\AppServiceProvider;
use PilotPHP\Core\Application\ApplicationBuilder;

$kernel = ApplicationBuilder::create(__DIR__)
    ->name('user-service')
    ->environment('production')
    ->debug(false)
    ->withContainerBuilder($containerBuilder)
    ->withManifest(__DIR__ . '/pilotphp.package.php')
    ->withProvider(AppServiceProvider::class)
    ->buildKernel();

$application = $kernel->boot();

$containerBuilder must implement CompilableContainerBuilderInterface. Core intentionally does not implement autowiring or a production container.

Package Manifest

<?php

declare(strict_types=1);

use PilotPHP\Core\Package\PackageManifest;
use Vendor\Package\ExampleServiceProvider;

return new PackageManifest(
    name: 'pilotphp/example-package',
    version: '0.1.0',
    providers: [ExampleServiceProvider::class],
    requires: ['pilotphp/core' => '^0.1'],
    providesCapabilities: ['example.capability' => '1.0.0'],
    requiresCapabilities: ['container.scopes' => '^1.0'],
    metadata: [
        'agent' => [
            'summary' => 'Example PilotPHP package.',
            'documentation' => 'docs/agent.md',
        ],
    ],
);

Composer packages are discovered when composer.json contains either type: pilotphp-package or extra.pilotphp.manifest.

Provider

<?php

declare(strict_types=1);

use PilotPHP\Core\Provider\AbstractServiceProvider;
use PilotPHP\Core\Provider\RegistrationContext;

final class ExampleServiceProvider extends AbstractServiceProvider
{
    public function register(RegistrationContext $context): void
    {
        $context->container()->singleton(Foo::class, Foo::class);
    }
}

Providers receive restricted contexts. They do not receive the mutable kernel.

Lifecycle

created
  -> discovering
  -> registering
  -> compiling
  -> booting
  -> ready
  -> stopping
  -> stopped

Failures move the kernel to failed. Shutdown handlers run in reverse registration order and are used for normal shutdown and boot rollback.

Status

This package is an initial working core. It is suitable for building pilotphp/container and transport/runtime packages against the public contracts, but the public API should still be treated as pre-1.0.