Twig Collector Extension Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^1.1 and confirm the constraint resolves against your PHP and Laravel versions before touching code. composer why-not is the fastest way to diagnose a conflict.
• Read in this order: the README install block → the service provider (register()/boot()) → the published config file → CHANGELOG.md. The provider tells you what is bound into the container and under which keys; that is the contract everything else depends on.
• Check whether the package relies on Laravel package auto-discovery (extra.laravel.providers in its composer.json). If it does, do not also register it in config/app.php — you will get double registration and duplicated listeners.
• Publish only what you need: php artisan vendor:publish --tag=<package>-config (and -migrations / -assets if present). Review the config diff before committing; published config becomes your code and will not receive upstream default changes.
• First use case: wire the package into one feature behind your own thin wrapper class, not app-wide. Resolve it from the container (app(Contract::class)) rather than instantiating directly so tests can swap it.
• Sanity check in php artisan tinker that the class resolves and the config keys are visible (config('package.key')). If resolution fails, you have a provider or discovery problem, not an API problem.

Implementation Patterns

• Adapter/wrapper boundary. Inject the package's contract into a small first-party service (e.g. App\Services\XService) and let the rest of the app depend on that. It keeps the package out of your domain code, makes fakes trivial, and makes a future major-version upgrade a one-file change.
• Container over facades. Prefer constructor injection for testability; use the facade only in Blade/global helpers where injection isn't practical.
• Config-driven behaviour. Drive environment-specific behaviour (endpoints, queue names, drivers, timeouts) through config/<package>.php + .env, never by editing vendor code. Keep your defaults in the published config under version control and document overrides in .env.example.
• Queued/async paths. If the package dispatches jobs or listeners, set its queue connection explicitly in config rather than inheriting default — otherwise a sync local setup masks production behaviour.
• Migrations. Publish and run migrations in an isolated deploy step; if the package's tables are shared with existing data, add an explicit rollback plan before running migrate.
• Testing. Use the package's own fake/swap helpers in setUp() where offered; otherwise $this->swap(Contract::class, $fake). Add one integration test (real binding) alongside the unit tests so you catch binding regressions on upgrade.
• CI matrix. Test against the lowest Laravel version in your composer.json range plus current — packages at 1.1.x frequently ship minor-version fixes that only surface on older framework releases.
• Upgrade workflow. Pin ^1.1, read the changelog on every composer update, run the suite, and only then bump the lockfile on main. Batch dependency updates separately from feature work so a bisect is possible.

Gotchas and Tips

• Config caching. After editing published config or .env, run php artisan config:clear. Most "my config change is ignored" reports are a stale bootstrap/cache/config.php — especially in Docker images where config is cached at build time.
• vendor:publish runs once per tag. Re-publishing requires --force, which silently overwrites your local edits. Diff before forcing, and consider keeping the published config out of the publish path once customised.
• Auto-discovery caching. php artisan package:discover runs on composer install; in CI with --no-scripts the provider may never be registered. Add an explicit package:discover step if you disable scripts.
• Facade alias collisions. If two packages register the same alias in config/app.php, the later one wins silently. Check aliases after adding any package that ships a facade.
• Version pinning. ^1.1 allows 1.9.x; if you need patch-level reproducibility, rely on composer.lock in the app and commit it. Don't pin exact patch versions in a library's composer.json.
• Queued workers must be restarted after deploying a package upgrade (php artisan queue:restart) — long-running workers hold the old class definitions in memory, which produces confusing "method does not exist" errors.
• Debugging. Log at the package's own channel if it defines one; otherwise wrap calls in a try/catch that logs the input payload before rethrowing. Telescope's "Exceptions" and "Jobs" tabs usually pinpoint whether the failure is binding, config, or transport.
• Extension points to look for before forking: published contracts/interfaces for your own implementations, events dispatched on lifecycle boundaries (listen instead of overriding), and Macroable traits on the main classes. Forking the package should be the last resort — a wrapper plus an event listener covers most customisation.
• Minor versions are not risk-free. At 1.1.x, treat patch releases as safe, minor releases as "read the changelog and run the suite," and keep an eye on deprecation notices in the upgrade guide — they are the cheapest early warning you get before a 2.0.