Statamic Toasty Laravel Package

Getting Started

This is a 0.0.1 initial release. There is no changelog beyond "Initial release", so treat the package as unproven and start by mapping its surface area rather than assuming an API.

1. Install into a scratch app, not your main project.

   composer require <vendor>/<package>:0.0.1
   

   Pin the exact version. Under SemVer, 0.x means any minor bump can break you, and ^0.0.1 will only ever resolve 0.0.1 anyway — but pin explicitly so a composer update doesn't surprise you.

2. Find out what the package actually registers. Read the package's composer.json first:

   • extra.laravel.providers — auto-discovered service providers.
   • extra.laravel.aliases — facades.
   • require — which Laravel/framework versions and PHP version it targets.
   • autoload.psr-4 — namespace root so you know where to look.

3. Inspect the source before the docs. With no documentation, the contract is the code:

   ls vendor/<vendor>/<package>/src
   cat vendor/<vendor>/<package>/composer.json
   

   Look for *ServiceProvider.php, *Facade.php, config/*.php, routes/, database/migrations/, src/Console/, and src/Http/. Those five locations tell you almost everything about how the package expects to be used.

4. Publish anything publishable, then diff it.

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

   Every published config key and migration is part of the package's effective API. Commit the published files so upgrades show up as diffs.

5. First use case: pick the narrowest thing the package claims to do and prove it end-to-end in a feature test before wiring it into application code. For a 0.0.1, that test is your regression harness for the next release.

Implementation Patterns

Wrap it in your own boundary. This is the single most valuable pattern for a 0.x dependency. Don't let Vendor\Package\... types leak across your codebase; resolve the package behind one interface or one small service class you own.

namespace App\Support;

use Vendor\Package\Client;

final class ThingGateway
{
    public function __construct(private Client $client) {}

    public function doTheThing(array $payload): mixed
    {
        return $this->client->send($payload);
    }
}

Bind it once in a service provider, then inject ThingGateway. When 0.0.2 renames Client::send(), you change one file.

Bind config through your own config file. Don't call config('package.key') from twenty places. Have your config/thing.php read from the package config with sane defaults, so you control the fallback when the package changes a default.

// config/thing.php
return [
    'driver' => env('THING_DRIVER', config('package.default_driver', 'null')),
    'timeout' => (int) env('THING_TIMEOUT', 5),
];

Integration tips by package shape (check which applies after step 2 above):

• Service provider + facade: prefer constructor injection over the facade in your own classes; the facade is convenient in Blade and quick scripts, but hides the dependency in tests.
• Publishes migrations: copy them into database/migrations with a timestamp after any existing migration they depend on, and never edit vendor migrations in place — you'll lose the edits on update.
• Registers commands: verify with php artisan list | grep <package> before documenting them to your team.
• Registers routes: check php artisan route:list for the prefix/middleware and make sure nothing is exposed publicly that shouldn't be.

Test at the seam, not the package. Assert on your ThingGateway contract with the real package in a feature test and a fake in unit tests. That way an upgrade that breaks internals fails in exactly one place.

it('round-trips through the gateway', function () {
    $this->app->instance(ThingGateway::class, new FakeThingGateway());
    // ...
});

Version discipline. For day-to-day work, pin 0.0.1 in composer.json, keep a short note in the PR description of what you verified, and schedule a re-read of the source on every bump. Use composer outdated in CI to surface the next release rather than discovering it mid-sprint.

Gotchas and Tips

• 0.0.1 means the API is not stable. Under SemVer, 0.x releases may break on minor bumps. Anything you build against it should sit behind the wrapper described above. Don't put it in a shared foundation package that other teams depend on until it reaches 1.0 or has a track record.
• Auto-discovery hides wiring. If the provider is in extra.laravel.providers, you'll never see it in config/app.php. When behaviour looks magical, run php artisan about and check the package list, or use php artisan tinker to inspect app()->getLoadedProviders().
• Missing config after install. Most "it does nothing" reports on a fresh 0.x package are an unpublished config file or an unset env var. Run vendor:publish first, then php artisan config:clear — a cached config will mask new keys.
• Config caching swallows env(). If the package calls env() outside its own config file, it returns null in production once config:cache runs. Read the package's config file to confirm; if it does this, set the values explicitly and don't rely on env at runtime.
• Migrations that don't run. Check php artisan migrate:status — if the package's migration is registered under a non-standard path, it may not be picked up. Publishing it into your app is the reliable fix.
• Debugging internals. dump()/dd() inside vendor code is fine on a branch; just remember to revert. Better: composer show -P <vendor>/<package> to confirm the installed version, and git diff the vendor directory only if you're tracking it (you shouldn't be).
• Extension points to look for while it's small. Events dispatched, contracts/interfaces, and any Manager-style driver pattern. If the package offers none, that's a signal to keep it at arm's length — you have no supported way to customise behaviour other than forking.
• Watch the upgrade path. Before adopting, skim whether the package has tests of its own (vendor/.../tests or the repo). A 0.0.1 with no tests will be slow to stabilise; budget for reading the diff on each release rather than trusting the changelog.
• Exit criteria for adoption. Promote the package out of "experimental" once (a) it reaches a stable release, (b) its public API has survived at least one bump unchanged, and (c) you have a passing test at your integration seam. Until then, keep the wrapper and the pinned version.