Advertise Laravel Package

Getting Started

This is the package's first release (0.1.0) — there is no prior assessment to diff against, so treat everything below as an initial baseline rather than a migration. A first release tells you two things before you read a single line of code: the public API is not yet stabilised (pre-1.0 semver means minor bumps may break you), and the documentation surface is likely thin. Plan your adoption around that.

Minimal steps to first value:

1. Pin the constraint deliberately. composer require vendor/package:^0.1 is the default; 0.1.* is the safer choice if you intend to upgrade frequently. Do not float to *.
2. Read composer.json first, not the README. Check the require block for the Laravel/illuminate/* version range and whether extra.laravel.providers / aliases are declared (auto-discovery). This tells you whether installation is zero-config or manual.
3. Read the service provider under src/. This one file usually reveals the whole integration story: which bindings are singletons, what is publishable, what hooks boot() registers.
4. Publish and diff the config, if one exists:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   The published file is your contract with the package — commit it and diff it on every upgrade.
5. First use case: exercise the package in php artisan tinker with the smallest possible call, then immediately write one feature test that touches it. A 0.1.0 package with no test of your own is an unbounded risk.

Where to look, in priority order: composer.json → service provider → published config → README → src/Contracts/ (if it exists) → tests/ in the package itself.

Implementation Patterns

Wrap it behind your own boundary. At 0.x, the cheapest insurance is a thin adapter or interface in your app that the rest of the codebase depends on, with one class inside it calling the package. When 0.2.0 renames a method or changes a return type, you edit one file. Do this for anything load-bearing; skip it for genuinely peripheral use.

Bind and inject, don't new. If the package registers a singleton, resolve it from the container so your tests can swap it:

// AppServiceProvider::register()
$this->app->bind(MyContract::class, fn ($app) => new MyAdapter($app->make(VendorThing::class)));

Config over code. Map package config values to config/services.php entries backed by env vars where the package allows it. Anything the package exposes as config is a surface you can change without touching call sites — anything it exposes only as constructor args is not.

Fake outbound I/O in tests. Any first-release package doing HTTP, queues, or filesystem work should be exercised with Http::fake(), Queue::fake(), or Storage::fake(). If the package ships its own fake, prefer it; if not, use the container to bind a stub in your test's setUp(). Never let a 0.1.0 package make live calls in CI.

Pin in CI and test against a version matrix. Lock the package to an exact version in composer.lock, and if the package declares support for a range of Laravel majors, run your suite against the edges of that range. First releases frequently overstate compatibility in require.

Treat publishing as a one-way door. Once you vendor:publish config or stubs into your repo, you own them. Record the package version in the commit message when you publish, so future-you can three-way-merge against a newer stub.

Gotchas and Tips

• Pre-1.0 semver is not a promise. By convention, 0.1.x patches should be safe but 0.2.0 may break anything. Pin to ~0.1.0 or 0.1.* and budget for a manual read of the diff on every minor bump.
• There is no upgrade guide yet. Until one exists, the CHANGELOG diff between versions is the upgrade guide. Read it before bumping; a first release often ships with an empty or auto-generated one, which means reading the commit log instead.
• config:cache masks publish mistakes. If you publish a config file and forget to re-run php artisan config:clear in local dev, edits silently do nothing. The same trap applies in reverse in production — a config published after a deploy cache warm-up will not be picked up. Always clear/serialize config as part of the deploy sequence.
• Auto-discovery conflicts. Two packages registering the same facade alias, or a provider discovered twice because it is also listed in config/app.php, produce confusing "already bound" or "class not found" errors. If php artisan package:discover output looks wrong, check bootstrap/cache/packages.php.
• Provider register() vs boot() ordering. Bindings go in register(), everything else in boot(). If the package gets this wrong, you will see unresolved dependencies or config read before it is merged. Diagnose with a dd() in each method and compare against your own providers' order.
• Facade caching bites after config changes. Facade::clearResolvedInstances() in a test's setUp() prevents stale singletons leaking between tests — a very common source of "passes alone, fails in suite".
• Look for extension points before forking. Contracts, macroable classes, events, and publishable stubs are the intended seams. A 0.1.0 package with a Contracts/ directory is signalling stability intent; one without is signalling that you should wrap it. Forking a first release is almost always the wrong first move.
• Don't depend on internals. Anything under a namespace segment like Support, Concerns, Internal, or Concerns\ is not public API regardless of visibility modifiers. Pin behaviour to the documented surface only.
• Report early, report upstream. At 0.1.0 the maintainer is actively shaping the API — a well-written issue now frequently changes the design. This is the cheapest window you will ever get to influence the package.