Template Laravel Package

Getting Started

This is the initial assessment for the package at 0.1.0 — "First Release". There is no prior assessment and no upgrade guide yet, so treat everything below as an adoption baseline for a pre-1.0 Laravel package rather than a settled API contract. The notes here are deliberately framed around how you actually put a 0.x package to work, not around the (as-yet undocumented) surface area.

Minimal steps to get productive:

1. Install and pin. composer require <vendor>/<package>:^0.1. Under semver, 0.x releases may break on minor bumps, so commit composer.lock and treat every 0.1.x → 0.2.0 as a potentially breaking upgrade.
2. Confirm framework fit. Open vendor/<vendor>/<package>/composer.json and read the require block for PHP and illuminate/* constraints. A first release often targets a narrower Laravel range than your app — check this before anything else.
3. Check auto-discovery. Look for extra.laravel.providers (and aliases) in that same composer.json. If present, the provider is registered automatically. If absent, register it manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
4. Publish configuration. php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" — or list tags first with --tag omitted if you want to see what's on offer. Review the published config file before changing values.
5. Read the source, not just the README. At 0.1.0 the README is usually thin. The src/ directory is the real documentation: start at the service provider (what it binds, what it registers), then config/, routes/, migrations/, and any Contracts/ directory.

First use case: pick the single smallest place in your app where the package earns its keep — one controller action, one queued job, one Artisan command. Wire it there behind your own thin wrapper (see below), write a feature test that exercises it end to end, and only then consider spreading it across the codebase. A 0.1.0 package should prove itself in one seam before it touches ten.

Implementation Patterns

Wrap it before you spread it. The highest-leverage pattern for any pre-1.0 dependency is a one-class adapter: your own App\Services\X that resolves the package's service from the container and exposes the two or three operations you actually need. When 0.2.0 renames a method or changes a return type, you edit one file instead of grepping the application.

final class ShippingEstimator
{
    public function __construct(private \Vendor\Package\EstimatorContract $estimator) {}

    public function forOrder(Order $order): Money
    {
        return $this->estimator->quote($order->toQuotePayload());
    }
}

Resolve from the container, prefer constructor injection. Facades are convenient for one-off calls in a controller, but injected contracts are trivially swappable in tests via $this->app->instance(...). If the package ships a facade and a binding, use the binding in application code and the facade only in tinker/Artisan.

Keep configuration in config/, not in code. Publish the config file and reference it via config('package-name.key'). Anything environment-specific (endpoints, credentials, timeouts, feature toggles) belongs there so it survives config:cache and differs cleanly between local, staging, and production.

Stage adoption with a flag. For anything user-facing, gate the new code path behind a config boolean or a feature flag. You get a fast rollback that doesn't require a deploy, which matters a great deal when the dependency is at 0.1.0 and you have no changelog history to reason about.

Own the migrations. If the package publishes migrations, publish them into database/migrations and review the schema before running. Once published they are yours to modify — and yours to reconcile when the package later changes its own copy. Never let a package run migrations you haven't read.

Test with the package's fakes if they exist; otherwise swap the container. Grep src/ for Fake, fake(), or a testing namespace. If there's nothing, bind a hand-rolled stub through the container in your setUp() and assert against your adapter, not against the package's internals — testing a third party's behaviour is a good way to get red builds on their release day rather than yours.

Wire it into queues and commands as a second step. Once the synchronous path is proven, the package usually slots naturally into a job's handle() or a scheduled command. Because jobs are resolved through the container, constructor injection of the package's contract works there without extra ceremony.

Gotchas and Tips

• 0.1.0 means the API is not stable. There is no upgrade guide, no deprecation policy, and no backwards-compatibility promise. Pin the version, watch the repository's releases, and read the diff before bumping. Budget for one painful upgrade; if that's unacceptable, don't adopt yet.
• Auto-discovery is cached. After composer require, if the provider "isn't registering", run php artisan package:discover — and if things are still odd, php artisan optimize:clear. Discovery failures are almost always a stale bootstrap cache rather than a broken package.
• config:cache breaks closures. If the published config file contains anything other than scalars and arrays (closures, objects), php artisan config:cache will fail or silently misbehave in production. Check the config file early; this bites at deploy time, not at development time.
• vendor:publish can overwrite your edits. Publishing with --force after an upgrade will clobber local changes to config, views, or migrations. On every version bump, re-publish into a scratch directory and diff against what you have rather than forcing in place.
• Debugging registration problems. php artisan about shows discovered providers and package versions; a BindingResolutionException naming the package's contract usually means a missing provider registration or a typo'd config key. php artisan tinker with app()->bound(...) is the fastest confirmation that the container knows about it.
• Look for extension points before forking. Custom drivers registered via a manager's extend() method, publishable views, macros on the facade, and dispatched events are all preferable to editing vendor/. If 0.1.0 offers none of these and you find yourself needing to patch behaviour, that is a signal to wait for a later release rather than maintain a fork.
• Add a compatibility guard to CI. One test that boots the package's provider and exercises your adapter against the current version turns upgrade day into a normal pull request. It's cheap insurance and it's the single best habit to establish while the package is still at 0.1.0.