Nova Trust Laravel Package

Getting Started

This is a pre-1.0 package (0.3.0) with a very small change history — the entire release surface so far is a handful of merged pull requests. Treat the source as the documentation until a README with usage examples exists.

First steps, in order:

1. Read composer.json — check the require constraints against your Laravel/PHP versions. At 0.x, the package may pin illuminate/* tightly enough to block an upgrade.
2. Read the service provider — src/*ServiceProvider.php tells you what is actually registered: bindings, singletons, config merges, publishable assets, console commands, migrations. This is the fastest map of the package's public surface.
3. Check config/ — if mergeConfigFrom is called, run php artisan vendor:publish --provider="Vendor\\Package\\PackageServiceProvider" before touching anything. Never edit files inside vendor/.
4. Find the entry point — a facade, a helper function, an injectable class, or a trait. That single class is your day-to-day interface; everything else is plumbing.

First use case: wire the package into one non-critical path (a single controller or a queued job), confirm the happy path, then widen usage. At 0.3.x the API is not stable, so keep the blast radius small while you learn the shape.

Implementation Patterns

Inject, don't resolve. Prefer constructor injection of the package's concrete class or interface over app()/facade calls in application code. When a 0.4.0 rename lands, you change one binding, not thirty call sites.

Wrap it. Put a thin adapter (App\Services\...) between your domain and the package. Laravel packages at this maturity level churn on method signatures and config keys; an adapter converts a breaking change into a one-file edit and gives you a seam to fake in tests.

Bind the interface in a service provider. If the package ships an interface plus a default implementation, re-bind it in AppServiceProvider or a dedicated provider rather than reaching for config flags. This is the cleanest extension point most Laravel packages offer and it survives minor releases.

Config-as-code. Publish the config file and commit it. Add the keys you depend on to your deploy checklist, and assert critical values in a boot-time check or a test — silently defaulting is the most common way these packages misbehave in production.

Test with the real container. Package tests usually lean on orchestra/testbench; mirror that with your own RefreshDatabase-style feature test that boots the provider and exercises one integration point. Mock at your adapter boundary, not at the package's internals.

Version-pin deliberately. In composer.json, pin "vendor/package": "0.3.*" rather than ^0.3. Read the diff of every 0.x bump before merging — with this few merged PRs, each release can carry an outsized share of behavioural change.

Gotchas and Tips

Pre-1.0 means no BC promise. SemVer's stability rules only apply from 1.0.0. Any 0.x minor release may rename classes, change config keys, or alter return types. Budget for reading source on upgrade, not just changelogs.

The changelog is not a changelog. Release 0.3.0 carries only an auto-generated "Merged into request #6" note — no description of what changed. Until release notes describe intent, diff the tagged versions directly (git diff 0.2.0..0.3.0 -- src/ config/) before upgrading.

Single-maintainer risk. With roughly six pull requests of history, bus factor is one and issue response times are unknown. Evaluate against composer show -a vendor/package for last-commit recency, and have a fallback plan (the adapter above) for anything on a critical path.

Config caching bites first. If the package reads env() directly in application code rather than through config/, php artisan config:cache will blank those values in production while local dev works fine. Grep the source for env( outside config/ — it's the classic Laravel package defect.

Double-registration. Laravel's package auto-discovery (the extra.laravel.providers block in composer.json) plus a manual entry in config/app.php produces duplicate bindings and doubled event listeners. Pick one; if you must register manually, add "dont-discover" to your root composer.json.

Asset and migration publishing is one-way. vendor:publish overwrites without asking. Commit published config and migrations, and re-publish with --force only after diffing against the new stub.

Debugging checklist when nothing happens: confirm the provider is actually loaded (php artisan about), confirm the facade alias is registered, check that config:cache isn't stale (php artisan config:clear), and verify the package isn't silently swallowing an exception in a try/catch during boot.

Extension points worth checking before you fork: container bindings, Macroable traits, published config, and events dispatched by the package. If none exist for the behaviour you need, prefer decorating the package class in your own provider over patching vendor/ — forking at 0.3.x means owning every future security fix.