Test Suite Laravel Package

Getting Started

This is a v0.1.0 pre-release. The release notes carry an explicit warning that every version below v1.0.0 is not production ready. Treat this release as an evaluation artifact, not a dependency — the useful question right now is "is this worth tracking?", not "how do I ship it?".

Minimal steps:

1. Read the source before the docs. With a 0.1.0 release the README is usually a stub, while src/, composer.json, and the service provider tell you what the package actually registers (bindings, config, migrations, commands, routes, middleware).
2. Install pinned, in a throwaway app. Never in an existing project:

   composer require vendor/package:0.1.0
   

   Commit the lockfile so you can reproduce the exact tree you evaluated.
3. Confirm what gets auto-discovered. Check extra.laravel.providers / aliases in the package's composer.json, then run php artisan about — if it doesn't appear in the provider list, discovery is off and you need manual registration.
4. Look for a config file and a publish tag. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=package-config). The shape of the config array is the closest thing to a public API contract at this stage.
5. First real use case: run the package's own happy path once end-to-end in the scratch app, then again inside a Pest/PHPUnit test. If the happy path can't be reproduced from the README alone, that's a strong signal the package is still mid-design.

Implementation Patterns

Wrap it behind your own boundary. At 0.x, class names, namespaces, and method signatures are all liable to change. Bind the package behind a small interface or adapter of your own so a breaking bump on their side touches one file on yours, not fifty call sites.

// app/Support/Contracts/Thing.php
interface Thing { public function handle(array $payload): Result; }

// app/Support/PackageThing.php  — the only file that imports the vendor namespace
final class PackageThing implements Thing { /* delegates */ }

Pin exactly, and review tag diffs. ^0.1 is not the safety net you think it is in Composer's 0.x rules (see Gotchas). Pin 0.1.0 exactly and, on each new tag, read the diff of src/ before bumping. A pre-1.0 changelog is often incomplete; the diff is the source of truth.

Characterisation tests, not unit tests. Write one test that exercises the package's main entry point end-to-end and assert on observable output, not internal method calls. This survives refactors on their side and immediately tells you when a 0.1.x bump changed behaviour. Run it as part of your bump checklist.

Keep it off the default path. Gate the integration behind a config flag or a feature toggle so the package can be disabled without a deploy:

// config/features.php
'new_thing' => env('FEATURE_NEW_THING', false),

if (config('features.new_thing')) {
    $this->app->register(PackageServiceProvider::class);
}

Isolate anything that touches the database. Publish the migrations into database/migrations and inspect them; expect column names and table shapes to churn before 1.0. Run them against a disposable database, and never let them near a database you can't rebuild.

Track upstream deliberately. Watch the repository's releases and issues rather than relying on Packagist notifications. Read the source of src/ between tags — a silent rename of a config key is the most common pre-1.0 break.

Mirror config into env explicitly. Publish the config file, diff it against the package's config/package.php on every bump, and map the values you care about to .env keys you control. Don't let application code read config('package.*') directly — wrap it.

Gotchas and Tips

• Composer's 0.x caret rules will bite you. ^0.1 means >=0.1.0 <0.2.0, which is roughly what you want — but ^0 means >=0.0.0 <1.0.0, i.e. every 0.x release including breaking ones. Pin the exact version or use 0.1.* at most.
• There is no backwards-compatibility promise. Below 1.0, Semantic Versioning's 0.x clause explicitly allows anything to break in a minor bump: config keys, service provider binding names, namespaces, DB columns, command signatures, event names. Assume all of them are unstable.
• Auto-discovery can silently fail. If extra.laravel.providers is malformed or the namespace changed, the provider just doesn't load — no error, just a "class not found" three layers away from the cause. Verify with php artisan about rather than assuming.
• Config cache is the classic debugging trap. After bumping the package, php artisan config:clear and php artisan cache:clear before debugging anything. A stale cached config from the previous version looks exactly like a code bug.
• Don't edit vendor/. Tempting at 0.x when a signature is wrong, but it's lost on the next composer install. Use an adapter or a subclass in your own namespace instead — and treat that subclass as a shim to be deleted at 1.0.
• Extension points are unstable, not just the API. Filters, hooks, and events added in 0.1.0 may be removed entirely before 1.0 — they were often added to unblock the author's own use case. Don't build a feature on top of a pre-release hook.
• Timebox the evaluation. If the package looks promising, the cheapest path is: pin, run the characterisation test, log the findings, and revisit when 1.0 lands. Adopting a 0.1.0 into a production codebase costs more in churn than waiting almost always saves.