Rating Laravel Package

Getting Started

This is the initial 0.1.0 release, so the assessment below is a baseline rather than a diff against prior behavior — there is no upgrade path to reason about yet, only adoption guidance.

1. Check compatibility before requiring. Open the package's composer.json and confirm illuminate/* constraints, minimum PHP version (8.1+ is the realistic floor for current Laravel), and whether it pulls Guzzle/Symfony versions that could conflict with your app's lockfile. Run composer require vendor/package --dry-run first on a branch.
2. Install and inspect discovery. After composer require vendor/package, check for extra.laravel.providers / extra.laravel.aliases — if present, the service provider and facade are auto-discovered and you should not add them to config/app.php. If absent, register manually.
3. Publish and diff config. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=package-config). Read the published file line by line — that file is the most accurate documentation of the package's actual behavior in 0.1.0.
4. Read the tests as the spec. On a first release the README is usually thinner than the test suite. tests/ shows the intended happy path, expected exception types, and which collaborators get mocked — far more reliable than prose.
5. First use case. Don't wire it into a controller first. Resolve the main entry point from the container in php artisan tinker (or a single throwaway Pest/PHPUnit test) and exercise one call. Confirm the object graph resolves, config is picked up, and credentials/HTTP work before touching application code.

Implementation Patterns

Resolve from the container, never new. Package services almost always read config or take injected collaborators in their constructor. Inject the class (or its contract) into your own constructor and let Laravel build it — a manual new bypasses config, logging, and any custom bindings the package registers.

Put a thin adapter in front of it. Even for a small package, wrap calls in your own App\Services\* class. On a pre-1.0 dependency this is your insurance policy: when a method signature changes in 0.2.0, you edit one file, not thirty call sites.

final class ShippingRates
{
    public function __construct(private \Vendor\Package\Client $client) {}

    public function forOrder(Order $order): array
    {
        return $this->client->rates($order->toPackagePayload());
    }
}

Keep configuration in config/ + .env, mapped through your own config file. Prefer publishing the package config and overriding values in config/services.php-style keys rather than scattering env() calls in application code — env() returns null once config:cache runs.

Push slow or failure-prone operations onto the queue. Anything that calls an external API, parses large files, or sends mail belongs in a job with $tries, $backoff, and failed() handling. The package call becomes one line inside handle().

Feature-test at the boundary. Use Http::fake() / Queue::fake() / Event::fake() and assert the outbound payload, not internal package state. That keeps your tests valid across package upgrades. Assert exception types (expectException) rather than messages.

Listen to events instead of subclassing internals. If the package dispatches events, hook them from an EventServiceProvider — that's a supported extension seam and survives refactors better than extending a concrete class.

Use it from console commands for one-off work. A small artisan command is the cheapest way to run backfills or syncs idempotently, and it composes with --dry-run flags you control.

Extension points to look for, in order of stability: published config → container bindings against shipped contracts → events → driver/resolver registration (often extend() on a manager class) → macros. Anything below "events" is likely to move in a minor release.

Gotchas and Tips

• 0.1.0 means the API is not stable. Pin tightly ("vendor/package": "0.1.*" or exact) and read the changelog before every bump. Semver gives no guarantees below 1.0.0 — a 0.1.1 can legally break you.
• Silent defaults from unpublished config. If you skip vendor:publish, the package runs on its own defaults, which are often null/empty and fail later with a confusing error. Publish on day one even if you change nothing.
• Config cache staleness. After editing the package config or .env, run php artisan config:clear locally. In deploy pipelines, config:cache must run after the publish step or you'll ship stale values.
• Double registration. If discovery is enabled and someone also added the provider to config/app.php, you get the provider booted twice — duplicate migrations, duplicate routes, doubled event listeners. Check php artisan about and the providers list.
• Migrations are publish-only. Look for a --tag=package-migrations publish step. They usually have no timestamp collision protection; if the package later renames a migration, your already-run copy stays behind and creates drift. Consider copying them into your app and owning them.
• Singleton/static state leaks between tests. Managers and clients are often bound as singletons. If state carries across tests, call $this->app->forgetInstance(...) in tearDown() or re-bind, otherwise you get order-dependent failures.
• Facade typing and IDE support. Add the facade to config/app.php aliases if not auto-aliased, then run php artisan ide-helper:generate so static analysis sees the underlying class. Facades resolve at call time, so a typo'd method fails only at runtime — lean on tests here.
• Exception surface is immature on a first release. Catch broadly at your adapter boundary and translate to your own exception types; don't let Vendor\Package\SomeException escape into controllers or jobs' failed() logic.
• Watch the dependency graph. A pre-1.0 package frequently pins a narrow Guzzle or symfony/* range. If composer update starts downgrading unrelated packages, that's the cause — check composer why-not.
• Debugging checklist when a call fails: config('package.key') in tinker → confirm the binding resolves (app()->make(...)) → check storage/logs/laravel.log for package-channel entries → inspect the last request with Http::fake() logging or a debug middleware. Nine times out of ten it's config, credentials, or a missing publish step.
• Don't leak package DTOs into your domain layer. Map to your own value objects at the adapter. On a 0.x dependency, this is the difference between a one-file change and a refactor.