Annotation Warmer Laravel Package

Product Decisions This Supports

• Deployment-time performance tuning. This package exists to pre-parse (warm) Doctrine annotation metadata into a cache during a build/deploy step, so production requests don't pay the docblock-parsing cost on a cold cache. It directly supports the decision of whether cold-start annotation parsing is worth engineering time — and gives you a cheap way to test that hypothesis before investing in a bigger change.
• Build artifact slimming. Because annotations are resolved from the warmed cache, production installs can run with composer install --no-dev and an optimized/authoritative autoloader without shipping annotation classes that are only needed for parsing. That's a supply-chain and image-size decision, not just a latency one.
• Build vs. buy vs. skip. The actual capability is a single console command plus a compiler-pass-level integration. This package is best treated as a reference implementation for an internal ~100-line deploy task rather than a dependency decision. The 0.3.0 release reinforces this: the interesting change is a config-wiring fix, not a capability, which is exactly the kind of maintenance you'd otherwise absorb yourself.
• Roadmap signal on metadata strategy. Adoption implicitly commits you to Doctrine annotations, which are deprecated in favor of PHP 8 attributes. This package informs the "when do we migrate to attributes" question more than it informs "what do we build next."

When to Consider This Package

Consider it only when all of these hold:

• You are on a legacy Symfony + Doctrine stack (roughly PHP 7.x era) still using Doctrine\Common\Annotations\CachedReader / PsrCachedReader.
• Profiling shows measurable cold-cache annotation parsing cost — e.g., after every deploy, cache clear, or autoscale event.
• Your deploy pipeline can run a console command (deployer, Capistrano, CI/CD step) and you can warm the cache in the target environment.
• You need to strip annotation classes from the production vendor tree and want the safety net that makes it work.

Look elsewhere — or skip entirely — when:

• You are on PHP 8.1+ and Doctrine ORM 2.9+/3.x, where attributes are first-class and this problem largely disappears.
• Symfony's cache:warmup and container compilation already cover your hot path.
• You need support. Maintenance is sporadic at best: effectively dormant since 2019, 2 stars, 0 dependents, then a single 0.3.0 release in 2026 that removes the default config values without a major-version bump. There is still no visible PHP 8.2+/8.3+ compatibility guarantee, no security-response path, and no guarantee it tracks doctrine/annotations deprecations. The runtime risk surface is small (no network or I/O at request time), but the maintenance risk is real, and 0.3.0 shows the package will make small breaking config changes on a 0.x line without migration notes — pin it, fork it, or reimplement it.
• Your team cannot absorb a bespoke deploy step. The win is only realized if the warm command runs reliably on every deploy — and since 0.3.0 removes the default config, that means you now own a published config file and its upgrade path across every future bump.

How to Pitch It (Stakeholders)

To executives: A small, MIT-licensed deploy-time optimization. It pre-parses PHP docblock annotations once during deployment so production servers don't repeat that work on every cold start, and it lets us ship leaner production builds. The catch: it was dormant from 2019 until a single 0.3.0 housekeeping release, has effectively zero community, and is built on Doctrine annotations — a technology the ecosystem is actively sunsetting in favor of PHP 8 attributes. The 0.3.0 change removes default configuration, so adopting it now means owning a config file we must validate on every upgrade. Recommendation: do not adopt as a new dependency. If we have a measured cold-start problem, budget half a day to reimplement the equivalent deploy step internally, or fold the work into the attributes migration we'll need anyway.

To engineering: One console command that fills the annotation cache at deploy time. 0.3.0 removed the config defaults and added a service-definition existence check — a robustness fix, but it means 0.3.0 is not a drop-in for anyone already on 0.2.x: you must publish/supply the config explicitly, and you should diff the new expected keys against whatever your warm command reads. Nothing here adds PHP 8.2+/8.3+ support or a test matrix, so do not read this release as the project coming back to life. Before adopting, measure: cold-cache request latency and deploy-time cache rebuild cost, with and without warming. If the number is real and we're staying on annotations short-term, the source is small enough to vendor and own — which also insulates us from the next 0.x config break.