Compilex Laravel Package

Getting Started

• Read composer.json first. Before composer require, confirm the php and illuminate/* constraints match your app's Laravel version. A brand-new 1.0.0 package often supports a narrower version matrix than you assume, and Composer will happily resolve an older release instead of telling you.
• Treat 1.0.0 as an API promise. The jump to 1.0.0 means the maintainer is declaring the public surface stable under semver. Pin with ^1.0 for libraries and internal packages; use ~1.0.0 for anything on a critical path until a few patch releases have landed.
• Open the service provider before the README. register() shows what goes into the container and whether the provider is deferred; boot() shows what gets registered globally (middleware, observers, migrations, routes, commands). That single file tells you more about day-to-day impact than the marketing section of the docs.
• Publish and commit the config. php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" (check for --tag variants) and commit the result. Committed config is your record of the defaults you're relying on when a future release changes them.
• First use case: get the smallest README example running in a throwaway route or a php artisan tinker session. Resolve the package's main class from the container and hit one method end to end before wiring anything into domain code.

Implementation Patterns

• Resolve from the container, never new. Constructor injection in your own services, app()/the facade only at the edges (controllers, Blade, Artisan commands, tests). Instantiating directly bypasses config, singleton bindings, and any fake you register in tests.
• Config, not env(). Read settings via config('package.key') in your code. env() calls outside config/*.php return null the moment php artisan config:cache runs in production.
• Put an adapter in front of it. Even a 20-line interface of your own around the package's entry points means a 1.x → 2.x breaking change touches one file instead of thirty. This matters most for a first release, where "public API" is a statement of intent more than a proven contract.
• Test at your boundary, not theirs. Feature tests against the HTTP endpoint, job, or command that triggers the package, asserting the observable outcome. Avoid asserting internal class names or log lines — those are the first things to change in a patch release.
• Fake the seams. If the package dispatches events, calls HTTP, or pushes jobs, use Event::fake(), Http::fake(), Queue::fake() in your tests so you're testing your integration rather than the package's network behaviour.
• Migrations: if the package ships them, run php artisan migrate --pretend first to see the actual SQL and confirm table naming doesn't collide with yours. Use RefreshDatabase and let the package's migrations run rather than hand-creating tables in test setup.
• Isolate tooling packages. Dev-only packages (debugging, generators, static analysis) go in require-dev so they never land in a production image. For a local patch while waiting on an upstream fix, a path repository entry is cleaner than editing vendor/.

Gotchas and Tips

• The first few 1.0.x patches are where the defaults get fixed. Watch the changelog for the first month; a 1.0.1 that changes a config default can silently alter production behaviour if you haven't committed your published config.
• "Stable" does not mean "frozen." A 1.0.0 is a promise about breaking changes, not about bug-free behaviour. Read the diffs of patch releases — they should be fixes only, and if they aren't, that's worth an issue.
• vendor:publish --force overwrites your edits. Always diff your published config against the new stub before forcing; git diff after publishing is the cheapest safety net you have.
• Auto-discovery conflicts. If two packages register similar bindings or middleware, use the extra.laravel.dont-discover array in your composer.json and register manually in AppServiceProvider — you get an explicit, debuggable order.
• Deferred providers hide from casual inspection. app()->getLoadedProviders() only lists what has actually been resolved. If a binding "doesn't exist" in tinker, resolve it once and re-check before assuming it's broken.
• Check boot() for global side effects. Middleware, model observers, and global scopes registered there apply to every request in the app. If you see unexpected query constraints or headers, that's the first place to look.
• Debugging checklist: php artisan about (environment + cache state), config('package') in tinker, php artisan route:list --path=package, php artisan vendor:publish with no flags to list available tags, and composer show vendor/package to confirm which version actually installed.
• Extension points before forking. Look for a contract or binding you can override in your own provider ($this->app->bind(PackageContract::class, MyImpl::class)) and for config-driven class names. A package that reads a class name out of config is usually telling you exactly where it expects to be extended.