production: bin/compile.php must load .compile.php explicitly

[koriym]

Summary

The compile docs described the bear.compile era and never said when ahead-of-time compilation is actually needed, nor that Compiler::fromInjector() / bin/compile.php (BEAR.Package 1.21+, bearsunday/BEAR.Package#482) does not auto-load the root .compile.php the way bear.compile did. A reader who followed the migration and wrote a .compile.php would find it silently ignored, and nothing framed the fake-env baking pitfall.

Changes (ja / en)

• Frame the Compilation section around two deployment models: compile on the deploy target (default; real env/paths present, so no writable override needed) vs ahead-of-time (serverless / read-only root / fixed /tmp — combine writable-path override, AOT reuse, and .compile.php, and resolve runtime-variable values at runtime instead of baking them). .compile.php is orthogonal — it addresses compile-time constructability (e.g. authentication, which is absent during compile) and can be needed even on the deploy target.
• bin/compile.php example now loads .compile.php (guarded require), matching the skeleton.
• .compile.php section: a Note that fromInjector() does not auto-load it, and sharpened guidance that its contents should be null objects (compile-time constructability, including auth-dependent resources) — not fakes of values that must be real at runtime, which get baked into the compiled scripts.
• Stable #compilation anchor on the Compilation heading (linked from the skeleton's bin/compile.php docblock @see).
• Fix a broken example line: $_SERVER[__REQUIRED_KEY__] (undefined constant, fatal on PHP 8) → $_SERVER['YOUR_REQUIRED_ENV'].
• Multi-context preload: note that opcache.preload is per-process, so each context's evacuated preload.php is wired to its own PHP process (explains the mv step and the example's asymmetry); link opcache.preload to the PHP preloading page.
• Clarify that autoload.php is a no-preload optimization / fallback (redundant when preloading — use composer's vendor/autoload.php); fix two typos (dumpa-autoload, autload.php).

Companion skeleton change in bearsunday/BEAR.Skeleton (loads .compile.php in bin/compile.php).

Refs bearsunday/BEAR.Package#482

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

英語版・日本語版の本番コンパイル手順を更新し、bin/compile.phpからの明示的な読み込み、.compile.phpの用途、コンパイル時に扱う値に関する説明を追加しました。

Changes

コンパイル手順

Layer / File(s)	Summary
コンパイルエントリポイントの読み込み手順 manuals/1.0/en/production.md, manuals/1.0/ja/production.md	vendor/autoload.phpと存在する場合の.compile.phpをbin/compile.phpから読み込む例を追加し、Compiler::fromInjector()の自動読み込み仕様を説明しました。英語版には実環境でのコンパイル方針と例外も追記しました。
.compile.phpの値と用途の説明 manuals/1.0/en/production.md, manuals/1.0/ja/production.md	オフライン構築用のNullオブジェクトやダミー値に限定する注意書きを追加し、環境変数の例をYOUR_REQUIRED_ENVへ更新しました。英語版ではRedisAdapter例の空行も調整しました。

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• bearsunday/bearsunday.github.io#385: 同じ本番コンパイル手順とCompiler::fromInjector()の呼び出し文脈を更新しています。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	主要変更である bin/compile.php から .compile.php を明示的に読み込む必要性を的確に示しており、タイトルとして適切です。

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@manuals/1.0/ja/production.md`:
- Line 233:
「記述することによってコンパイルをすることができます」という冗長な表現を、「記述することでコンパイルできます」など、簡潔で自然な表現に修正してください。

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7c9ca1b3-e358-48b3-b122-f5fa9e59b045

📥 Commits

Reviewing files that changed from the base of the PR and between 447e671 and b05555b.

📒 Files selected for processing (2)

• manuals/1.0/en/production.md
• manuals/1.0/ja/production.md

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

冗長な表現を簡潔にしてください。

「記述することによってコンパイルをすることができます」は、「記述することでコンパイルできます」などにすると自然です。

🧰 Tools

🪛 LanguageTool

[uncategorized] ~233-~233: 「ことができる」という表現は冗長な可能性があります。
Context: ...込みをルートの.compile.phpに記述することによってコンパイルをすることができます。 注意（BEAR.Package 1.21+）: `Compil...

(DOUSI_KOTOGADEKIRU)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@manuals/1.0/ja/production.md` at line 233,
「記述することによってコンパイルをすることができます」という冗長な表現を、「記述することでコンパイルできます」など、簡潔で自然な表現に修正してください。

Source: Linters/SAST tools

[NaokiTsuchiya]

@koriym

ありがとうございます。どちらの点も納得できます。

2番について：compile()の各ステップは、すべてが同程度にビルド環境に依存しているわけではありません。DIスクリプトの生成／プリロード／dumpAutoload()は純粋な変換処理であり、CIでも安全に実行できます。インジェクタキャッシュ（PackageInjector::getInstance()）のみが、.compile.phpのフェイク環境に依存しています。

これを独自のオプションステップ（例：Compiler::warmInjectorCache()、実際の環境に対してデプロイ先ごとに実行）に分割すれば、CIでは純粋なステップのみを検証できるようになり、本番環境で読み込まれるものにフェイク環境が組み込まれるのを防げます。これは、__invoke()のclean() + factory()がすでに取っていた方向性をさらに拡張するものです。これは本番環境に関するドキュメントの両方の軸にも適合します。
ウォームアップの原則の下では、実際の環境がすでに存在するためこの問題は発生せず、プリコンパイルの例外の下では、ビルドアーティファクトにはDIスクリプト、プリロード、オートロードのみを含めるべきであり（インジェクタキャッシュは含めない）、コールドスタート時には実際の環境が再び利用可能になるため、その部分をその場でビルドできるからです。