Nova Fez Laravel Package

Getting Started

Treat 0.2 as a spike, not a dependency. The release is explicitly flagged experimental, which in a 0.x line means the public surface (namespaces, config keys, method signatures) can move between patch releases. Before you write a single line of application code:

1. Pin hard. composer require vendor/package:0.2.* — not ^0.2. Commit the lock file and note the exact version in your upgrade log.
2. Read the source, not just the README. At this stage the service provider and any contracts/interfaces are the real documentation. Start at src/*ServiceProvider.php to see what is bound into the container, what is publishable, and whether anything is registered by auto-discovery.
3. Publish and diff the config. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (check the tag list first — --tag=package-config is common). Diff the published file against the package's own copy every upgrade; silent config key renames are the most common 0.x breakage.
4. Check the composer.json constraints. PHP version, Laravel illuminate/* ranges, and whether it requires ext-*. A narrow illuminate/support constraint is the usual reason a package installs fine today and blocks a framework upgrade next quarter.

First use case: pick the single smallest thing the package does and do it end-to-end in a throwaway branch — one route or one artisan command, no persistence, no auth. The goal is to learn the failure modes (boot order, config resolution, exception types) cheaply, before it is entangled with your domain.

Implementation Patterns

Adapter boundary. Never let the package's classes appear in your controllers, jobs, or models. Define your own interface, implement it with a thin class that delegates to the package, and bind it in a service provider. When 0.3 renames a method, you edit one file:

// app/Contracts/ThingResolver.php
interface ThingResolver { public function resolve(string $key): Thing; }

// app/Services/PackageThingResolver.php
final class PackageThingResolver implements ThingResolver { /* delegates */ }

// AppServiceProvider::register()
$this->app->bind(ThingResolver::class, PackageThingResolver::class);

Feature-flag the integration. Config-driven, default-off:

// config/features.php
'experimental_things' => env('FEATURE_EXPERIMENTAL_THINGS', false),

Guard the service provider registration and any listeners behind it. This gives you a one-env-var rollback that does not require a deploy revert — the cheapest insurance you can buy against an experimental dependency.

Isolate the config surface. Wrap config('package.key') reads in your own config file that reads the package's values, so a renamed key is a one-line fix and your application code never touches vendor config paths. Cache-bust note: php artisan config:cache will freeze whatever the package resolved at boot — if it reads env at runtime it will silently return null in production.

Test double at the boundary. Bind a fake implementation of your interface in tests, and reserve the real one for a single integration test suite marked @group package-integration. This keeps the majority of your test suite immune to the package's internal churn.

Queue and event integration. If the package dispatches events or exposes jobs, register listeners in a dedicated EventServiceProvider block and map the package's event classes to your own domain events. Do not let package event classes leak into $listen keys throughout the app — one indirection layer keeps the blast radius small.

Upgrade ritual. Because there is no BC promise, treat every release as a major. Before bumping: read the changelog, composer update vendor/package --with-dependencies, run the integration suite, and diff the published config and migrations. Keep a short docs/packages/vendor-package.md in your repo recording the version, the pinned constraint, and any patches you had to apply locally.

Gotchas and Tips

• "Experimental" is a contract, not a disclaimer. Assume no deprecation cycle. Anything you build on a public method is a candidate for silent removal in 0.3. Budget for a rewrite; prefer this package in internal tooling or a bounded feature, not in the payment path.
• Package auto-discovery + conditional registration. If you wrap the provider in a feature flag, add it to dont-discover in composer.json, otherwise it boots regardless of your config.
• Config caching masks env reads. Anything the package reads via env() outside a config file works in local and returns null under config:cache. Test with php artisan optimize before you trust it.
• Boot order matters. If the package reads config or binds into the container in register() versus boot(), and you depend on it from another provider, explicit ordering in bootstrap/providers.php (Laravel 11+) or config/app.php may be required. Prefer lazy resolution via the container over eager reads.
• Migration collisions. Check database/migrations for timestamp prefixes that sort before your own tables if there are foreign keys — a classic 0.x oversight.
• Version constraint hygiene. 0.2.* in require plus composer.lock committed is the safe posture; avoid ^0.2 unless you have the integration suite green in CI.
• Debugging. php artisan about and php artisan package:discover -v confirm registration; Log::debug inside a delegated adapter method is quicker than chasing the package's internals. Laravel Telescope helps if the package touches queries, jobs, or HTTP.
• Extension points. Prefer whatever the package exposes as contracts/interfaces or Laravel macros over subclassing concrete classes — subclassing is the first thing to break when internals are refactored in an experimental release.
• Exit criteria. Write down now what would make you drop the package (no release in 6 months, a breaking change you cannot absorb in a day, Laravel major unsupported). Having that written makes the decision cheap later.