Install

Stable 1.2.1 Skeletonを作成し、認証付きHTTP 200まで確認する。

BlackOps Applicationは、Packagistで公開済みのSkeletonからComposer標準のcreate-projectで作成します。StableのInstall手順はPHP 8.5、Composer、Docker Composeだけで完走します。公開済み1.2.1 PackageにはAuthentication、Seeder、Frontend Operation BridgeのSourceが含まれますが、Node／pnpm、Seeder実行、Frontend生成はこの最小Install手順では実行しません。

Stable 1.2.1を作成する

Versionを明示してApplicationを作成します。

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

Composer ScriptはProject所有のbin/setupを実行します。.envが存在しない場合だけ.env.exampleをCopyし、var/build/とvar/log/を準備します。既存の.envは上書きしません。

SetupはDocker、Database、Migration、Artifact Build、Worker、Schedulerを起動しません。normal／--no-scriptsのどちらも、下の共通Key Stepを完了してからRuntime Commandへ進みます。

Composer Scriptを使わない場合

Script実行を禁止する環境では、同じSetupを手動で実行します。

composer create-project --no-scripts blackops/skeleton my-app 1.2.1
cd my-app
php bin/setup

bin/setupは再実行可能です。既存.envを保持したまま不足するLocal Directoryだけを確認できます。 Setup後は下のnormal／--no-scripts共通Key Stepへ合流します。

公開済み1.2.1 Quickstart Runtimeには32-byte Base64のLocal Development Key／Local StorageKeyProviderが必要です。normal／--no-scriptsのどちらも、Setup直後に次の同じ必須Key Stepを実行します。Key値はstdoutへ出さず、Gitへ保存せず、ProductionではApplication-owned Secret Manager／KMS Providerへ置き換えます。

(
    set -euo pipefail
    umask 077
    chmod 600 .env
    test "$(stat -c '%a' .env)" = 600
    storage_key="$(head -c 32 /dev/urandom | base64 -w 0)"
    test -n "${storage_key}"
    decoded_storage_key_length="$(printf '%s' "${storage_key}" | base64 --decode | wc -c)"
    test "${decoded_storage_key_length}" -eq 32
    sed -i "s|^BLACKOPS_STORAGE_KEY=.*|BLACKOPS_STORAGE_KEY=${storage_key}|" .env
    test "$(grep -c '^BLACKOPS_STORAGE_KEY=' .env)" -eq 1
    test "$(grep -c '^BLACKOPS_STORAGE_KEY=$' .env)" -eq 0
)

共通Key Stepの後、Project RootでApplication ContainerとPostgreSQLを順に準備します。HostのPHP CLIとContainer CLIを混在させず、php blackopsはすべてContainer内で実行します。

docker compose build app http
docker compose up -d postgres
docker compose run --rm app php blackops database:migrate
docker compose run --rm app php blackops build:compile
docker compose up -d http
curl -i -H 'X-Sample-Token: local-example' http://127.0.0.1:8080/welcome
docker compose down

期待結果はHTTP 200と次のJSONです。

{"message":"Welcome to BlackOps"}

/welcomeは公開済み1.2.1の#[Authorize]付きInline Operationです。SAMPLE_API_TOKEN=local-exampleを設定したApplicationへX-Sample-Token: local-exampleを送るとSample UserとしてAuthenticationされ、Sample Authorization Policyを通過してHTTP 200を返します。Headerを省略したAnonymous Requestと不正なHeaderは401となり、後者はOperation受付前に拒否されます。Responseを確認したらdocker compose downで停止します。MigrationとBuildはHTTP起動へ暗黙に含まれません。

Release Policy

Stable 1.2.1にはProject Root blackops、Generator、Application Migration Runtime、7 Validation Attribute、FrankenPHP Worker Mode、Authentication、Durable ActorContext、#[Authorize]、Frontend Operation Bridgeが含まれます。このWebsiteは公開Releaseのドキュメントであり、Experimentalな制約はReleasesで明示します。

BlackOpsはExperimentalです。1.x Minor間のBackward CompatibilityとProduction Readinessを保証しません。Upgrade前にRelease NoteとUpgrade Guideを確認し、検証環境でApplicationをTestしてください。Releasesには利用可能な機能と既知の制約をまとめています。

公開済みStable 1.2.1を使う場合は上記提供範囲に留めてください。Quickstart and Skeletonの認証付きJourneyも公開済み1.2.1 Packageから開始できます。接続や起動で詰まった場合はTroubleshootingを参照してください。