Local Runtime

Docker ComposeでArtifact、Migration、HTTPを準備し、Install直後のApplicationを実行する。

InstallしたApplicationは、Docker ComposeでPHP 8.5 CLI、FrankenPHP 1、PostgreSQL 18を起動できます。依存Install、Artifact Build、MigrationはImage起動へ含まれないため、順番に明示実行します。OperationのRuntime検索情報を持つManifestはBuildで生成します。

ImageとDependency

Project Rootで実行します。

docker compose build app http
docker compose run --rm app composer install

Defaultのdocker compose upはPostgreSQLとWorker Mode HTTPだけを継続起動します。Deferred Worker、Scheduler、Migration、Retention Purgeは自動開始しません。

OperationとArtifact

Discovery対象のOperationを確認し、Operation Manifest、HTTP Manifest、DI Containerをvar/build/へCompileします。

docker compose run --rm app php blackops operation:list
docker compose run --rm app php blackops build:compile

BuildはTyped Self-handled Signatureを検証し、OperationをHandlerとしてContainerへ自動登録します。HTTP／Worker RuntimeはCompile済みArtifactだけを読み、Request処理中にSource Discoveryや再Compileを行いません。

Database Migration

Statusを確認してからFramework Migrationを適用します。

docker compose run --rm app php blackops database:status
docker compose run --rm app php blackops database:migrate --dry-run
docker compose run --rm app php blackops database:migrate

HTTPやWorkerの起動時にMigrationは実行されません。Application Migrationがある場合も同じCommandへ統合されます。

HTTPを起動する

docker compose up -d

既定Portは8080です。.envのHTTP_PORTで変更できます。Stable 1.1.0の/welcomeは匿名Inline Operationです。

curl http://127.0.0.1:8080/welcome

{"message":"Welcome to BlackOps"}

Repository main PreviewでSample Authenticationを有効にした場合だけ、同じPreview内の全RequestへX-Sample-Token: local-exampleを付けます。

FrankenPHPはLocalではplain HTTPのWorker Modeで動作します。TLS、Domain、Process SupervisionはDeployment環境が所有します。

Worker ModeのRequest境界

Default Worker ModeはApplication、Environment、Configuration、Compile済みRuntimeをProcess起動時に一度だけ構成します。

docker compose up -d http
curl -H 'X-Sample-Token: local-example' http://127.0.0.1:8080/welcome

Worker ModeのPortは既定8080で、HTTP_PORTから変更できます。1 WorkerあたりのRequest上限はFRANKENPHP_MAX_REQUESTSで指定し、既定1000に達するとFrankenPHPがWorker Threadを再起動します。

Frameworkは各Request前にDatabase Connectionを確認し、Stale Connectionをcloseして一度だけ再接続します。再接続できないRequest、Throwableが発生したRequest、未完了Transactionを残したRequestは500となり、次RequestへConnectionを持ち越しません。Operation ScopeはRequest終了時に空であることを確認し、JSONL Journalは毎Request flushします。

Worker ModeではApplication ServiceもRequest間で再利用されます。Request Body、Actor、Tenant、PSR-7 Request等をService propertyやstaticへ保存せず、Operation ValueまたはExecution Contextから受け取ります。FrankenPHPが自動resetしない$_ENVはEntrypointがProcess開始時の値へ復元します。

Classic Modeは明示Fallbackとしてclassic-mode Profileから起動します。同じconfig/、Build Artifact、Database Configurationを使うため、Application Codeの別実装は不要です。既定Portは8081で、CLASSIC_HTTP_PORTから変更できます。

docker compose --profile classic-mode up -d http-classic
curl -H 'X-Sample-Token: local-example' http://127.0.0.1:8081/welcome

WorkerとMaintenance

Deferred OperationはHTTP Processとは別のWorkerで実行します。

docker compose run --rm app php blackops worker:run --iterations=1
docker compose --profile worker up -d worker

SchedulerとRetentionも明示Profile／Commandだけで開始します。

docker compose run --rm app php blackops retention:plan
docker compose run --rm app php blackops retention:purge --dry-run
docker compose --profile maintenance up -d scheduler

変更を伴うPurgeは--confirmを明示するまで実行されません。作業後はLocal Runtimeを停止できます。

docker compose down

InlineとDeferredを続けて試す場合はQuickstart and Skeletonへ進んでください。Runtime構成の詳細はApplication BootstrapとInline and Deferredを参照してください。起動、Token、Migrationの問題はTroubleshootingへ戻ってください。