Support Laravel Package

Getting Started

The v3.0.0-alpha.0 release is the very first alpha, so treat the assessment below as a process for adopting it rather than a map of a stable API. There is no prior assessment to diff against, which means everything you learn about this package you will learn from the source.

Minimal steps:

1. Install on a throwaway branch, pinned to the exact pre-release. Pre-release versions will not satisfy ^3.0 constraints, so Composer needs an explicit stability flag or an exact constraint:

   composer require vendor/package:"3.0.0-alpha.0" --prefer-stable
   

   Do not add minimum-stability: dev globally; scope the stability to the single package with an inline @alpha flag if you need a range later.
2. Commit composer.lock immediately. In an alpha, the lockfile is the only thing that makes your build reproducible.
3. Look at these files, in this order, before writing any code:
   • README.md — usually the only usage documentation that exists at alpha 0.
   • composer.json — the real contract: PHP version, Laravel/Illuminate constraints, and every transitive dependency you are inheriting.
   • src/*ServiceProvider.php (and any *Facade.php) — the public surface: what is bound in the container, what is registered, what is auto-discovered.
   • config/*.php — the intended configuration shape and default values.
   • tests/ — the most reliable specification at this stage; the tests show which behaviour the author actually asserts.
   • CHANGELOG.md / UPGRADE.md — likely absent or one line ("First alpha release"); note the absence, because it means alpha.1 will arrive with no migration guide either.

First use case: build one spike, on one branch, that exercises a single happy-path scenario end-to-end as a Laravel feature test. Prove the package boots, resolves from the container, and does its one core job inside your app's real service provider stack — before you design anything around it.

Implementation Patterns

Isolate the alpha behind a seam. Do not let the package namespace leak across your codebase. Define your own interface (or a thin adapter class) that expresses what your domain needs, implement it with the package, and bind it in a service provider. When alpha.1 renames a method — and it will — you change one file, not forty.

Prefer constructor injection over facades. Facades are convenient but they couple call sites to the package's static surface and are awkward to substitute. Constructor-injected contracts are trivially swappable in tests and let you keep the package out of your domain layer entirely.

Publish config into version control. Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" and commit the result. At alpha stage the published stub can change between releases; committing it gives you a diffable record of what you actually shipped, rather than whatever the next install happens to write.

Pin and gate the rollout. Wrap the call site in a feature flag. Ship the code dark, enable it for internal users, then roll forward. An alpha is a dependency you want to be able to turn off without a deploy.

Keep the upgrade diff small. Because you have isolated the package, upgrading is: bump the exact version, run composer update vendor/package --with-dependencies, run your feature tests, then diff the newly published config against the committed one (publish to a temp directory with --force on a scratch branch and diff, rather than overwriting in place).

Test at the boundary, not through it. Assert your adapter's behaviour with feature tests that hit the real container. Stub the package only where it reaches outside the process (HTTP, queue, storage) so you catch wiring regressions, which are the most common alpha breakage.

Keep a CI lane on the pinned version and a second, non-blocking lane on 3.0.x@alpha. The first protects your main branch; the second tells you what alpha.1 will break before you are forced to find out.

Gotchas and Tips

• Composer will refuse pre-releases quietly. If composer require reports it cannot find a matching version, the constraint is the problem, not the package. Use composer why-not vendor/package 3.0.0-alpha.0 to see exactly which constraint is blocking it.
• ^3.0 does not include 3.0.0-alpha.0 unless stability is explicitly allowed. An exact pin is the least surprising choice in an alpha.
• composer update can silently pull a newer alpha if you used a range. Check composer show vendor/package after every update and assert the version in CI.
• Service provider caching and discovery. After any install/upgrade run php artisan package:discover and php artisan config:clear. A stale bootstrap/cache/ is the single most common "the package is broken" false alarm. php artisan about shows what is actually registered.
• Transitive dependency conflicts surface as Laravel version errors, not as package errors. Read composer.json before blaming a runtime failure on the alpha.
• No upgrade guide exists, and none is promised. Compensate by making your own: keep your feature tests green and treat each alpha bump as a small, isolated diff. Tests are your changelog.
• Config keys drift between alphas. Publishing with --force in place will silently overwrite local edits. Publish to a temp path and diff, every time.
• Debugging order: php artisan about → container resolution in php artisan tinker → check the package's own exception messages in storage/logs/laravel.log with APP_DEBUG=true → read the package's tests/ for the intended calling convention.
• Extension points to prefer, in order: published config → container binding override → package events → macros. Do not patch vendor/. If you find yourself needing to, that is the signal to write the adapter you skipped in week one.
• Plan the exit. Before adopting, note what you would need to rebuild if the alpha is abandoned: the core behaviour, the config surface, and the data it writes. If that list is short, the risk is acceptable.