README

BlackOpsは、PHP 8.5向けのHeadless Operation Frameworkです。同期HTTP実行とPostgreSQLを使ったDeferred実行を同じOperation Modelで扱い、Lifecycle Journal、Retry、Outcome、Retention、BlackOps CLIを提供します。

Stable 1.2.0ではNamed Doctrine DBAL Connection、Constructor Injection、#[Transactional]付きOperation／Service、Nested Required、#[AfterCommit]を利用できます。BlackOpsはExperimentalであり、1.x Minor間の互換性を保証しません。

Status

Latest Experimental StableはFramework／Skeleton 1.2.0です。BlackOpsはExperimentalであり、1.x Minor間のBackward CompatibilityとProduction Readinessを保証しません。破壊的変更と移行手順はCHANGELOGとUpgrade Guideで確認してください。

Framework／Skeleton 1.2.0はannotated Tag、GitHub Release、Packagistへ公開済みです。Experimental Releaseのため、Production Readyや1.x Minor間のBackward Compatibilityは保証しません。

Documentation WebsiteはCloudflare Pagesへ公開済みで、Local／CI Buildと公開Artifact境界を検証しています。

利用者向けの機能差と制約はCurrent Statusを参照してください。

Installation

公開済みSkeletonからApplicationを作成します。

composer create-project blackops/skeleton my-app 1.2.0
cd my-app

blackops new専用Installerは提供していません。Composer標準のcreate-projectが公式の作成方法です。

生成されたApplicationはFramework-owned withEnvironmentFile()とBlackOps\Http\SapiRuntimeを利用するため、Dotenv／PSR-7／SAPI／UUIDv7 Runtime PackageをApplication Composerへ重複宣言しません。DBAL／MigrationsなどApplication Sourceが直接ImportするPackageだけを追加します。

このCommandが作成するのは公開済みExperimental Stable 1.2.0のApplicationです。1.2.0のHeader Authentication、Database／Transaction、Deferred Worker Journeyを確認できます。

Stable 1.2.0 Quickstart

公開済みStable 1.2.0で作成したmy-appのQuickstartです。利用者向けQuickstartで公開PackageのInstall、Docker Image、Artifact、Databaseを明示的に準備します。

docker compose build app http
docker compose run --rm app composer install
docker compose run --rm app php blackops operation:list
docker compose run --rm app php blackops database:migrate
docker compose run --rm app php blackops build:compile
docker compose run --rm app php blackops database:seed
docker compose up -d

確認用Endpoint:

curl -H 'X-Sample-Token: local-example' http://127.0.0.1:8080/welcome

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Sample-Token: local-example' \
  -d '{"reference":"order-001"}' \
  http://127.0.0.1:8080/orders

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Sample-Token: local-example' \
  -d '{"reportName":"weekly","recipientEmail":"reports@example.com"}' \
  http://127.0.0.1:8080/reports

curl -X POST -H 'Content-Type: application/json' \
  -H 'X-Sample-Token: local-example' \
  -d '{"reference":"incident-demo-001","sensitiveNote":"private diagnostic note"}' \
  http://127.0.0.1:8080/failures

/failuresのSafe 500が返すOperation IDは、Docker-only Quickstartではdocker compose run --rm app php blackops operation:inspect <id> [--json]へ渡します。PostgreSQLはHostへPublishせず、ViewerはCLI ContainerのLoopback限定なので、このDocker構成からHost BrowserへViewerを公開できません。ViewerはConsumer E2EのようにViewerとHTTP Clientを同じCLI Container／Local Network Namespaceへ置いて検証します。

Browserでphp blackops operation:viewerを使うには、Application／PHP CLI／PostgreSQL／Browserが同じLocal Network Namespaceから到達可能なNative Runtimeが必要です。Non-loopback Bindへ緩めません。Application／Framework相関Logはvar/log/application.jsonlで同じIDを使い、Sensitive ValueとActor IDをSafe Projectionします。

Stable 1.2.0の準備方法と利用可能なEndpointは利用者向けQuickstartを参照してください。

Full-stack Reference Application

BlackOps Boardは、Repository mainだけで提供するLocal Full-stack Reference Applicationです。QuickstartがFrameworkの最短ContractをHTTPとWorkerで確認するのに対し、BlackOps BoardはApplication-owned Identity、Framework Session Core、Generated Ephemeral Auth Operation、SvelteKit Same-origin BFF、DBAL Domain Repository、Inline Post／Comment、Deferred Digest、Accessible Product UIまでを一つのBrowser Journeyで示します。

Community Board Guideは、空のLocal StateからSetup、Seed、通常Login、Inline／Deferred Journeyを再現し、BrowserからPostgreSQL／Workerまでの責任境界を説明します。公開Demo CredentialはLocal／Test Fixtureであり、Stable 1.2.0 Skeletonには含まれません。Community Boardは外部Hostingしていません。

BlackOps CLI

Project Rootに置く薄いblackops EntrypointからFramework所有Generatorを利用できます。

php blackops make:operation Billing/CreateInvoice --type=billing.invoice.create
php blackops make:migration CreateOrdersTable
php blackops make:seeder Catalog/ProductSeeder
php blackops build:compile
php blackops database:migrate --dry-run
php blackops database:seed

Framework UpdateはProject Rootのblackopsや生成済みSourceを書き換えません。更新後のCommandとStubは、その後に新規生成するFileへ反映されます。

Development

Frameworkの開発CommandはWSL2内のRepository Rootで、Docker Composeを通して実行します。

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

docker compose run --rm app mago format --check src tests examples
docker compose run --rm app mago lint
docker compose run --rm app mago analyze
docker compose run --rm app vendor/bin/phpunit
docker compose run --rm app vendor/bin/deptrac

同じ品質GateはGitHub Actions CIでmainへのPushとPull Requestごとに実行されます。詳細な環境構築はDevelopment Setupを参照してください。

Documentation

License

MIT License

blackops / framework

Maintainers

Package info

Statistics

Security