Nova Priority Laravel Package

Getting Started

This is a 0.1.0 / "First Commit" release, which means there is no prior assessment to diff against and no established public API contract. Treat it as an evaluation candidate rather than a dependency.

Minimal path to a first look:

1. Read the package's composer.json first — check require (PHP and illuminate/* constraints), autoload PSR-4 roots, and whether extra.laravel.providers / extra.laravel.aliases are declared. Auto-discovery presence tells you immediately whether zero-config use is intended.
2. Skim src/ for the Service Provider — the register() vs boot() split shows what is container-bound versus what touches the framework (routes, migrations, publishing, commands).
3. Check for config/*.php, database/migrations/, routes/, resources/ — these directories signal whether the package expects to own config, schema, or HTTP surface, which drives most of your integration decisions.
4. Look for a README usage block and any tests — at first commit, the test suite (or its absence) is the single best proxy for how much of the surface is actually exercised.

First use case: install into a throwaway Laravel app at the same major version you run in production, composer require with a pinned constraint ("vendor/package": "0.1.*"), then exercise the happy path from the README once end-to-end. That gives you a realistic read on whether the package is usable before you invest in reading the source.

Implementation Patterns

Because the API is unversioned, wrap it. The dominant pattern for a 0.1.0 dependency is adapter isolation, so an upstream rename in 0.1.1 doesn't ripple through your codebase.

• Facade/contract wrapper. If the package exposes a facade or a bound interface, resolve it behind your own thin service class rather than calling the facade statically in controllers and jobs. Static facade calls are the hardest thing to swap out later.
• Config-first, code-second. If a config file is publishable (php artisan vendor:publish --tag=...), publish it into config/ and commit it. Do not rely on the package's internal defaults in production — at 0.1.x those defaults are the most likely thing to change without a changelog line.
• Publish selectively. Publish migrations and config, but generally not views or assets, unless you need to override them. Published views silently freeze you out of upstream fixes.
• Service provider ordering. If the package's provider must boot after your app's own bindings (common when it reads config or resolves a contract you register), declare it explicitly in bootstrap/providers.php (Laravel 11+) rather than depending on discovery order.
• Queue and test boundaries. If the package performs I/O (HTTP, storage, mail), bind a fake or stub in your TestCase::setUp immediately, and wrap the calls in your own job/action so tests exercise your adapter, not vendor internals.
• Version pinning. Use 0.1.* — not ^0.1, and certainly not *. At first commit, assume any 0.1.x bump may include breaking changes despite semver's letter.

Gotchas and Tips

• Semver is theoretical below 1.0. composer update on a ^0.1 constraint will happily install 0.1.9 with a renamed method. Pin tightly and review diffs, or vendor the package.
• Auto-discovery vs manual registration. If discovery is not declared in composer.json, the package will appear installed but inert. Symptom: "class not found" or silently missing routes/commands. Check extra.laravel before debugging anything else.
• Config caching. After publishing config, php artisan config:cache in deploy will mask later edits. If a value "isn't taking effect," clear the cache before assuming the package ignores it.
• Migration ordering. Package migrations published without timestamps that sort after your existing migrations can fail on foreign keys. Read the published migration filenames and rename if needed.
• No documented extension points yet. At first commit, assume there are no events, contracts, or overridable bindings. Any customization you need is probably a fork or a wrapper — check src/ for interface and dispatch( before committing to a customization strategy.
• Debugging approach. Bind-and-log: resolve the package's main class from the container in tinker, dump get_class(), and inspect the provider's register() with dd() in a local branch. That is faster than reading a README that may not exist.
• Watch the composer.lock diff on every upgrade. At 0.1.x it is the only reliable changelog you will get — compare the installed version's src/ tree between releases.
• Re-assess at 0.2.0 or 1.0.0. This assessment should be treated as provisional; the first meaningful release note beyond "First Commit" is the trigger to revisit it.