README

Agent-first PHP framework for modular applications.

Requirements

PHP 8.5+

Current status

Experimental early development.

PilotPHP is a standalone framework. Its runtime does not depend on Symfony or Laravel components.

Installation

Create a new PilotPHP application:

composer create-project pilotphp/app my-project
cd my-project
php bin/pilot doctor

For local development before packages are published, use the helper script from this repository:

./tools/create-local-app ../my-pilot-app

The helper copies skeleton, adds a Composer path repository to the local framework checkout, runs composer install, and executes php bin/pilot app:install.

Runtime dependencies

PilotPHP runtime intentionally avoids framework component dependencies.

Allowed runtime dependencies:

• PSR contracts

PilotPHP provides its own minimal implementations for:

• application kernel
• dependency container
• module loader
• console application
• router
• HTTP kernel

Console commands

PilotPHP has its own console subsystem.

Commands are registered through PHP attributes:

#[AsCommand(name: 'app:health', description: 'Display health status.')]
final readonly class HealthCommand implements CommandHandler
{
    public function handle(ParsedInput $input, Output $output): int
    {
        $output->writeln('OK');

        return 0;
    }
}

Application modules can expose commands through module.php:

return [
    'commands' => [
        App\App\Console\HealthCommand::class,
    ],
];

The console application discovers and registers framework and module commands automatically.

Agent AI First

PilotPHP is designed to be understandable by coding agents.

The framework can describe itself:

php bin/pilot agent:context
php bin/pilot agent:map
php bin/pilot agent:rules
php bin/pilot agent:instructions

These commands expose:

• framework metadata
• runtime packages
• application modules
• console commands
• HTTP routes
• architecture rules
• important files
• recommended verification commands

Agent rules are resolved from:

1. PilotPHP defaults
2. config/agent.php
3. module.php agent section
4. custom providers registered in the container

Project-level agent configuration lives in config/agent.php.

Configurable Agent AI First layer

Agent context is built from configurable sources:

1. PilotPHP framework defaults
2. config/agent.php
3. module.php agent section
4. Runtime providers

Rules, important files and recommended commands are resolved through providers and resolvers.

Agent config

return [
    'rules' => [
        'merge_defaults' => true,
        'custom' => [],
        'disabled' => [],
        'severity_overrides' => [],
    ],
];

Module-level agent config

return [
    'agent' => [
        'purpose' => 'Billing module.',
        'rules' => [],
        'important_files' => [],
        'recommended_commands' => [],
    ],
];

First goal

Minimal framework runtime:

• Application Kernel
• Container
• Module Registry
• HTTP Kernel
• Router
• Console Application

Usage

composer install
php bin/pilot
php bin/pilot list
php bin/pilot about
php bin/pilot modules

Skeleton

cd skeleton
php -S localhost:8000 -t public

Health endpoint:

curl http://localhost:8000/health

Expected response:

{
  "status": "ok",
  "framework": "PilotPHP"
}

Doctor

PilotPHP includes a self-diagnostic command:

php bin/pilot doctor
php bin/pilot doctor --format=json
php bin/pilot doctor --no-tools

doctor checks:

• PHP runtime
• composer setup
• framework boot
• module manifests
• console commands
• HTTP routes
• Agent AI First configuration
• runtime dependency boundaries
• linter/tooling configuration
• recommended verification commands

The JSON output is designed for coding agents:

php bin/pilot doctor --format=json

Architecture Check

PilotPHP can check executable architecture rules:

php bin/pilot architecture:check
php bin/pilot architecture:check --format=json
php bin/pilot architecture:check --module=App

The architecture checker validates:

• runtime package boundaries
• forbidden framework dependencies
• runtime-to-tooling dependencies
• module manifests
• module commands
• module routes
• console command conventions
• mapping between Agent AI First rules and executable checks

JSON output is designed for coding agents.

Package manifests and service providers

Every PilotPHP package describes itself with package.php:

return [
    'name' => 'console',
    'type' => 'runtime',
    'namespace' => 'PilotPhp\\Console',
    'purpose' => 'Console application and command discovery.',
    'dependencies' => [
        'core',
        'container',
        'module',
    ],
    'providers' => [
        PilotPhp\Console\ConsoleServiceProvider::class,
    ],
];

Service providers register package services:

final readonly class ConsoleServiceProvider implements ServiceProvider
{
    public function register(Application $app): void
    {
        // register console services
    }

    public function boot(Application $app): void
    {
        // boot console services
    }
}

ApplicationKernel only orchestrates loading manifests and providers.

Blueprint planning

PilotPHP can build safe generation plans from PHP blueprint files:

php bin/pilot blueprint:plan examples/blueprints/create-user.php
php bin/pilot blueprint:plan examples/blueprints/create-user.php --format=json

Blueprint files are PHP files returning arrays:

return [
    'type' => 'use_case',
    'module' => 'User',
    'name' => 'CreateUser',
    'input' => [
        'email' => 'string',
    ],
    'output' => [
        'user_id' => 'string',
    ],
    'tests' => [
        'unit' => true,
    ],
];

blueprint:plan does not modify files. It only reports the files that would be created or updated.

Extensible Blueprints

Blueprints are extensible by packages.

The blueprint core does not know about ORM, RabbitMQ, OpenAPI or other technologies.

Packages can register blueprint sections:

final readonly class OrmBlueprintExtension implements BlueprintExtension
{
    public function name(): string
    {
        return 'orm';
    }

    public function sections(): array
    {
        return [
            new RegisteredBlueprintSection(
                name: 'orm',
                validator: new OrmBlueprintValidator(),
                planner: new OrmBlueprintPlanner(),
            ),
        ];
    }
}

A blueprint can then include:

return [
    'type' => 'use_case',
    'module' => 'Billing',
    'name' => 'CreateInvoice',

    'orm' => [
        'entity' => 'Invoice',
        'repository' => true,
    ],
];

Creating modules

Create a new module:

php bin/pilot make:module User

Preview without writing files:

php bin/pilot make:module User --dry-run

The command is a thin wrapper around the blueprint/generator pipeline.

It creates:

• src/User/module.php
• src/User/routes.php
• src/User/Console
• src/User/Application
• src/User/Domain
• src/User/Infrastructure
• tests/User

You can also use the module blueprint directly:

php bin/pilot blueprint:plan examples/blueprints/create-user-module.php
php bin/pilot blueprint:apply examples/blueprints/create-user-module.php