Raw Data Laravel Package

Getting Started

• Install with composer require vendor/package — on a 0.1.0 first release, confirm the exact vendor/name against Packagist before running it, since the README is the only source of truth at this stage.
• Laravel package auto-discovery should register the service provider. If the package predates or opts out of discovery, add the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
• Publish any shipped assets before first use: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Check the provider for $this->publishes([...], 'tag') calls so you publish config, migrations, and views selectively.
• Where to look first, in order: README.md → src/*ServiceProvider.php (bindings, singletons, publish paths) → config/*.php (defaults and env keys) → src/ for the primary entry class.
• First use case: resolve the package's main class out of the container (app(Package::class) or the facade, if one is registered) and exercise the single happy-path method the README documents. That confirms wiring, config loading, and any required env vars in one shot.

Implementation Patterns

• Resolve, don't instantiate. Always pull the package from the container rather than new-ing its classes; service providers register singletons and bindings that your code will silently bypass otherwise.
• Config-first wiring. Publish the config file, then drive the package entirely through config + env. Avoid editing vendor files; if a value isn't exposed in config, treat it as a candidate for an upstream PR.
• Wrap it in your own abstraction. Bind the package behind your own interface in a service provider and depend on that interface in your app code. Pre-1.0 packages churn; a thin adapter keeps the blast radius small when the API shifts.
• Bind fakes in tests. If the package ships a fake or an interface, swap it in TestCase::setUp() or a dedicated testing trait. If it doesn't, wrap the package in your own class and mock that instead.
• Queue and job safety. Before using it inside queued jobs, confirm the resolved object is serializable — container-resolved singletons holding clients or connections will fail on unserialize. Resolve inside handle() rather than the constructor.
• Pin conservatively. Use ^0.1 in composer.json and commit the lockfile; on a 0.x line, minor bumps are allowed to break by semver convention.
• Integrate at the edges. Prefer calling the package from a dedicated service or action class rather than scattering calls through controllers and models — it keeps upgrade work localized.

Gotchas and Tips

• 0.1.0 is a stability signal, not a feature signal. Expect breaking changes across 0.x minors. Read the diff or CHANGELOG before every bump; there is no upgrade guide yet.
• Auto-discovery fails quietly. If app(Package::class) throws, check php artisan about for the registered providers and verify the extra.laravel.providers block in the package's composer.json.
• Config caching bites after publishing. Run php artisan config:clear (and config:cache again in prod) after publishing or editing the package config, or your changes won't take effect.
• Publish tags drift between versions. vendor:publish without a --tag can overwrite files you've customised. Publish once, then diff the package's config against yours on upgrade.
• Debug via tinker. php artisan tinker → app(Package::class) and inspect the resolved instance and its config. Most "package doesn't work" reports are a missing env var or an unpublished config defaulting to null.
• Extension points, in order of preference: (1) override config, (2) bind your own implementation of a shipped interface in a provider registered after the package's, (3) listen for the package's events instead of patching behaviour, (4) subclass only as a last resort.
• No migrations or assets yet? A first release often ships config only. Don't assume vendor:publish created anything — verify the target paths exist before chasing a phantom bug.
• Log the version. Record the resolved package version (from composer.lock) in your bug reports; at 0.1.0 the maintainer will need it to reproduce anything.