Nova Image Laravel Package

Getting Started

1.0.0 is the initial release, so there is no upgrade path or deprecation surface to worry about — but it also means the public API is at its least proven. Treat the first integration as a spike, not a commitment.

Install and confirm discovery

composer require <vendor>/<package>:^1.0
php artisan about          # confirms the provider registered
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"

Look at these in order before writing any application code:

1. composer.json — PHP and Laravel version constraints, plus extra.laravel.providers / aliases. If the provider isn't auto-discovered, you'll be registering it manually in bootstrap/providers.php.
2. The service provider's register() and boot() — this is where config merging, singletons, and publishing tags are declared. It tells you more about the package's real shape than the README does.
3. The config/ file after publishing — every knob the author intended you to touch.
4. The test suite — the most reliable documentation of intended usage at a 1.0.

First use case: reach for the package on a single, low-risk code path — one controller, one job, one Artisan command — rather than threading it through your domain layer. If it's a data-access or integration package, point it at a throwaway or staging connection first and confirm behaviour before it touches production data.

Implementation Patterns

Resolve from the container, don't instantiate. If the provider binds a singleton or interface, inject it through the constructor and let Laravel resolve it. Hard-coding new PackageClient(...) bypasses config merging and makes tests painful.

final class SyncOrders
{
    public function __construct(private readonly PackageContract $package) {}

    public function __invoke(): void { /* ... */ }
}

Bind the contract in a service provider if the package ships an interface. That gives you a one-line swap for a fake in tests and a seam for wrapping the package behind your own adapter — worth doing on day one for anything that talks to a third party.

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

Wrap it in your own thin adapter if the surface is broad. A single App\Support\... class that exposes only the three or four methods you actually call means a 1.x → 2.x breaking change lands in one file instead of forty. This is cheap insurance on any package still in its first major version.

Drive it from queues and commands, not request cycles. Long-running calls belong in a job with $tries/$backoff set explicitly, or behind a scheduled command. This also isolates failures from user-facing latency while you learn the package's behaviour.

Config over code. Anything the package exposes in config/ should be set via env() in your .env and referenced in the config file, not mutated at runtime with config()->set(). Cache the config (php artisan config:cache) and re-test — a surprising number of packages read env vars directly and break under caching.

Test with fakes at the boundary. Use Http::fake() for HTTP-backed packages, Queue::fake()/Bus::fake() for dispatch-driven ones, and RefreshDatabase if it ships migrations. Assert on your adapter's output, not on the package's internals — internal assertions turn every patch release into a test rewrite.

Gotchas and Tips

• Publishing is not idempotent by default. vendor:publish --force overwrites your edits. Publish once, commit the config, and diff against the vendor copy when you upgrade.
• Migrations and tags. If the package ships migrations, check whether they're loaded automatically or require a --tag. Duplicate table creation on a fresh DB is the classic first-run failure.
• Config cache vs. runtime reads. If something works locally and not in CI or production, suspect config:cache combined with a package that calls env() outside a config file. That's the author's bug, but it's your outage.
• Version constraints. ^1.0 on a first release means you'll absorb every 1.x patch. Pin tighter (1.0.*) for anything on a critical path until the package has a few releases behind it. Watch for caret ranges that allow a Laravel major you don't run yet.
• Facades hide the dependency. A facade alias is convenient but invisible to static analysis and to readers of your constructor. Prefer injection; if you must use the facade, add @see/@method annotations.
• Debugging: php artisan tinker to poke at the resolved instance, php artisan about to confirm registration, and Log::debug() inside a wrapper rather than inside vendor code so your instrumentation survives composer update.
• Extension points, in order of preference: config values → binding overrides in your own provider → decorating the package's contract with your own implementation → extending a base class the package exposes. Only fork as a last resort; if you do, pin the version and record why in the repo.
• Read the changelog before every minor bump. At 1.0 there's no track record of semantic-versioning discipline. Skim git diff on the config/ directory and the service provider between tags — that's where breaking changes hide.
• Upstream feedback. On a first release, missing config, unclear exceptions, and absent pagination/retry handling are common. If you hit one, note it early — the maintainer is likely still shaping the API, and your use case may influence it.