Attach File Bundle Laravel Package

Getting Started

v1.0.0 is the initial release, so there's no migration path to worry about — but there's also no battle-tested documentation trail yet. Treat the first hour as reconnaissance.

1. Confirm the package is installable and discovered. composer require it, then check php artisan about or php artisan package:discover output to confirm the service provider registered via auto-discovery. If the package's composer.json predates Laravel 5.5 conventions, you may need to add it to config/app.php manually.
2. Publish and diff config. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag= if tags are defined). If nothing gets published, that's a signal the package is opinionated with sensible defaults — check config/ in the package source before assuming it's broken.
3. Read the provider, not just the README. On a 1.0.0 with a one-line changelog, src/*ServiceProvider.php is the most reliable source of truth: what's bound in the container, what's registered as a singleton, what events or commands are wired up.
4. First use case. Run the package's primary entry point end-to-end in a scratch app before wiring it into a real project — a fresh laravel new sandbox, install, exercise the main path, and confirm it works against your actual Laravel and PHP versions. Version constraints in composer.json are the fastest way to spot incompatibility.

Where to look first, in order: README.md → composer.json (constraints, autoload, discovery) → service provider → published config → tests directory (an empty or absent test suite on a 1.0.0 is a real risk signal).

Implementation Patterns

Wrap it behind your own binding. Even for an internal package, don't scatter facade calls through controllers. Bind the package's contract to a thin adapter in a dedicated service provider so a future upgrade or swap is a one-file change:

$this->app->bind(YourContract::class, fn ($app) => new PackageAdapter($app->make(PackageClient::class)));

Feature-flag the integration on first adoption. A 1.0.0 in a production app deserves a config toggle (config('features.package_enabled')) or a Laravel Pennant flag so you can disable behaviour without a deploy if something misbehaves.

Isolate side effects into jobs or listeners. If the package dispatches events, hooks into HTTP, or performs IO, consume it from queued listeners rather than inline in the request cycle. This keeps p95 latency predictable and gives you retries for free.

Mirror their config into yours. Copy only the keys you actually change into config/ and leave the rest to the package defaults. When v1.1.0 adds a key, your published config won't be stale-and-missing-it.

Testing pattern. RefreshDatabase plus a fake for whatever the package talks to. If the package ships a fake (Package::fake()), use it; if not, bind a stub implementation of its contract in tests/TestCase.php so the suite never hits the network or a queue.

Deployment. Include the vendor:publish and any migrate step in your deploy script explicitly — don't rely on someone remembering it locally. If the package ships migrations, publish them into database/migrations with a timestamp earlier than your own migrations that reference the table.

Gotchas and Tips

• One-line changelogs mean uncharted behaviour. With nothing but "First version" to go on, pin the exact version ("vendor/package": "1.0.0" or ^1.0 with a committed composer.lock) and let Renovate/Dependabot surface patches for review rather than auto-merging.
• Auto-discovery silently fails. If the package's classes resolve but its migrations or commands don't, check dont-discover in composer.json and whether the provider is listed twice (once by discovery, once manually) — double registration duplicates route and command entries.
• Config caching bites on first install. After publishing config, always php artisan config:clear; a cached config from before publish means your new keys are ignored and the package falls back to defaults, which is confusing to debug.
• Facade/alias timing issues. If you get "class not found" on a facade alias in tinker but not in HTTP, it's almost always a cached bootstrap/cache/packages.php. php artisan optimize:clear resolves it.
• Watch the Laravel/PHP constraint matrix. A fresh 1.0.0 often ships with narrow constraints (^10.0, ^8.1). Verify against your real runtime — composer why-not vendor/package is quicker than reading the constraints by hand.
• Extension points to check early: whether the package resolves its core class from the container (swappable) or news it inline (not swappable), whether config is read via config() at call time or cached in a constructor (the latter won't respect config()->set() in tests), and whether it exposes a Macroable trait or contracts you can decorate.
• Log the versions. Add the package name and version to your php artisan about custom data or /health endpoint. When the first bug report lands, you'll want to know exactly which build produced it without guessing from a deploy timestamp.