pilotphp/operation

Operation-to-handler model, compiled handler map, and runtime dispatcher for the PilotPHP Agent-First framework.

0.1.4 2026-08-02 19:20 UTC

Requires

• php: ^8.5
• pilotphp/contracts: ^0.1.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.88
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^11.5

MIT

• dispatcher
• handler
• operation
• agent-first
• pilotphp

Published on Packagist.org on 2026-08-02 16:22 UTC

README

Operation-to-handler model, deterministic handler-map compilation, and runtime dispatcher for the PilotPHP Agent-First framework.

Responsibility

active package registration
→ contracts-owned declaration replay
→ OperationBuildStage
→ finalized operation artifact
→ app loads compiled map
→ OperationDispatcher
→ contracts ContainerInterface
→ application handler

This package owns:

• stable operation identity (OperationId);
• immutable OperationHandlerDeclaration;
• deterministic compiled HandlerMap;
• versioned JSON artifact + fail-closed loader;
• OperationDispatcher / OperationDispatcherInterface;
• domain exceptions for unknown operations, missing services, and contract violations;
• OperationPackage registering OperationBuildStage.

It does not own package discovery, generic build orchestration, container compilation, console command maps, runtime lifecycle, or transport parsing.

Requirements

• PHP ^8.5
• pilotphp/contracts 0.1.4-dev (Composer only; not a Pilot activation edge)

Install

composer require pilotphp/operation

Path-repository development (monorepo layout):

{
  "repositories": [
    {
      "type": "path",
      "url": "../contracts",
      "options": { "symlink": true, "versions": { "pilotphp/contracts": "0.1.4-dev" } }
    }
  ]
}

Quick start

Declare a handler (build time)

use PilotPHP\Operation\Declaration\OperationHandlerDeclaration;

$registration->add(new OperationHandlerDeclaration(
    operation: 'orders.create',
    handlerServiceId: 'App\\Handler\\CreateOrderHandler',
));

Implement the handler

use PilotPHP\Contracts\Runtime\RequestContextInterface;
use PilotPHP\Operation\Handler\OperationHandlerInterface;

final class CreateOrderHandler implements OperationHandlerInterface
{
    public function handle(object $input, RequestContextInterface $context): object
    {
        // ...
        return $result;
    }
}

Dispatch (runtime)

use PilotPHP\Operation\Artifact\OperationArtifactLoader;
use PilotPHP\Operation\Dispatch\OperationDispatcher;

$map = (new OperationArtifactLoader())->loadFromBytes($artifactBytes);
$dispatcher = new OperationDispatcher($map, $container); // contracts ContainerInterface
$result = $dispatcher->dispatch($invocation);

Development

composer install
composer check

Docs

See docs/ for public API, architecture, declarations, compilation, artifacts, runtime dispatch, compatibility, security, performance, and migration notes.

Status

Line 0.1.4-dev. Intentional hard break from former PilotPHP\Core\Dispatch\* types. End-to-end runtime kernel wiring remains blocked until contracts publishes an invocation-dispatcher SPI (see docs/compatibility.md).