Execution Cache Bundle Laravel Package

Getting Started

The 0.2.0 release is the first version with a usable on-ramp: bundle configuration, annotation support, and documentation all landed together. Start with the docs rather than the source — this package is pre-1.0 and the README is now the most reliable description of intended usage.

Minimal steps:

1. composer require <vendor>/<package>:0.2.0 — pin the exact version. At 0.x a minor bump can be breaking, and 0.2.0 already reshapes how configuration is expressed.
2. Publish the new bundle configuration:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Expect a config/<package>.php file. This is the main artefact of the "bundle configuration" feature — bundles are declared there rather than being hardcoded or auto-discovered implicitly.
3. Register a first bundle in that config file and confirm it resolves:

   // config/<package>.php
   return [
       'bundles' => [
           'app' => [
               'path' => app_path(),
               // package-specific options
           ],
       ],
   ];
   

4. Use the new annotation on one class and verify it is picked up. This is the smallest end-to-end use case: config declares the bundle, the annotation marks the class inside it, the package wires the two together.

If the annotation syntax is attribute-based (PHP 8 #[...]) rather than docblock, prefer attributes — they are refactor-safe and IDE-navigable, and docblock scanning is the more expensive of the two.

Implementation Patterns

Config-first bundle definition. Treat config/<package>.php as the single source of truth for what the package knows about. Per-environment overrides belong in .env values read inside the config file, not in conditional logic scattered through service providers. This keeps config:cache viable in production, which is the whole point of a config-driven bundle registry.

One bundle per domain, not per directory. Because bundles are now an explicit configuration concept, the natural mistake is mapping them 1:1 to folders. Map them to cohesive units instead (e.g. billing, catalog), so annotation-driven resolution has a meaningful scope to search within.

Annotations as declarative glue. The intended pattern is: annotate a class to mark it as belonging to a bundle or exposing some behaviour, and let the package resolve it at boot rather than registering each one by hand. Keep annotated classes side-effect free in their constructors — they may be instantiated during discovery before you expect it.

Integration tip. Register the package service provider normally, then do your own customisation in a small app-level provider that runs after it. Because bundle resolution happens during boot, anything that mutates the bundle list must be registered before the package's own boot() completes — listen for a package-provided event or manipulate the config before container boot rather than reaching into internals.

Testing. Add one smoke test that boots the application with your real config and asserts the expected bundles resolve — this catches the config-cache class of bug before deploy. For unit tests, construct the bundle registry directly with an inline array rather than booting the full app; it is much faster and avoids the annotation scanning cost.

Caching in CI. If annotations are scanned, wire the scan into your deploy pipeline (or warm it in a test) so that CI exercises the cached path, not only the uncached one.

Gotchas and Tips

• Config cache is the number-one tripwire. After editing the bundle configuration you must re-run php artisan config:cache (or config:clear) in any cached environment. A stale bundle list presents as "my new bundle simply doesn't exist," with no error.
• Annotation scanning staleness. Scanned annotations are typically memoised or written to a cache file. In local development, if a newly annotated class is ignored, clear the compiled/cache directory before debugging the annotation itself. Keep an artisan clear command handy.
• Docblock vs. attribute syntax is worth confirming early. If both are supported, standardise on one across the codebase; mixing them makes scanning results order-dependent and confusing to debug.
• Pre-1.0 churn. 0.2.0 added three features at once with no deprecation cycle promised. Pin 0.2.* in composer.json, read the changelog on every bump, and avoid depending on internal classes (registries, resolvers, loaders) — the stable surface is the config file and the annotation, not the machinery behind them.
• Duplicate bundle aliases fail quietly or loudly depending on version. Two bundles claiming the same key may resolve last-wins. Assert uniqueness in your own config test rather than trusting the package to complain.
• Publish tag names drift. vendor:publish without a --tag may now publish more than you expect (config plus stubs). Use explicit tags so upgrades don't silently overwrite your edited config.
• Debugging move. When resolution misbehaves, dump the resolved bundle list from php artisan tinker against the registry object before touching the annotation side — it separates "config not loaded" from "annotation not found" in one step, which are the two distinct failure modes this feature introduces.
• Extension points. The likely customisation seams are a custom bundle loader and a custom annotation resolver, bound in the container. Prefer overriding via the container binding or a published config key over extending package classes; the latter will break on 0.3.0.