Nova Json Schema Field Laravel Package

Getting Started

This is an initial RC — treat day one as an evaluation spike, not an integration.

Install into a sandbox first, not your app.

laravel new pkg-sandbox && cd pkg-sandbox
composer require vendor/package:1.0.0-RC1 --with-all-dependencies

RC tags are not picked up by normal stability rules. If the package isn't tagged @beta/@RC in its own composer.json, you'll need either an exact version constraint (as above) or "minimum-stability": "RC" with "prefer-stable": true in the root composer.json. Pin exactly — never a caret range on an RC.

Where to look first, in this order:

1. composer.json — PHP and illuminate/* constraints. This is the single most common RC failure point; a package built against Laravel 10 will silently install on 11 and misbehave at runtime.
2. src/*ServiceProvider.php — is register()/boot() present, is the provider in extra.laravel.providers for auto-discovery, or do you have to add it to bootstrap/providers.php manually?
3. Config/route/migration publish tags — run php artisan vendor:publish with no arguments and read the list before publishing anything.
4. The package's own test suite (vendor/bin/phpunit inside the package, or composer test).

First use case: get the package's own tests green in your sandbox app, then exercise the single happy-path call the README documents. If the README's example doesn't run verbatim, stop there and file an issue — that's your first packaging bug and it won't be the last.

Implementation Patterns

Isolate behind your own boundary. Even in a spike, put every call to the package inside one class in your app:

namespace App\Support;

use Vendor\Package\Client;

final class ThingGateway
{
    public function __construct(private Client $client) {}

    public function doTheThing(array $payload): mixed
    {
        return $this->client->handle($payload);
    }
}

Bind it in a service provider and inject the interface, not the package class. When 1.0.0 stable lands (and it will rename things), you change one file.

Feature-flag it. Wire the binding to a config toggle so the package can be disabled with an env var without a deploy:

$this->app->bind(ThingGateway::class, fn () =>
    config('features.new_thing')
        ? new PackageThingGateway(app(\Vendor\Package\Client::class))
        : new LegacyThingGateway()
);

Keep the install on a branch. composer require on a throwaway branch, PR it as draft, and keep composer.lock in the diff so reviewers can see exactly what was pulled in transitively.

Config discipline. Publish config (php artisan vendor:publish --tag=package-config) and commit it, rather than relying on the package's defaults, so an RC2 default change can't silently alter your runtime behaviour. Same for any migrations — read them before running; RC-era migrations are frequently missing indexes or have non-nullable columns without defaults on existing tables.

Contract tests around your wrapper. Write a handful of tests against ThingGateway, not against the package. They'll pass unchanged when you swap implementations and they'll catch behavioural drift on RC2.

Pin and document. Add "vendor/package": "1.0.0-RC1" to composer.json with a sibling comment in your README or an ADR noting why the pre-release is present and what the exit criteria are.

Gotchas and Tips

• "Expect packaging bugs" is a specific warning. Verify the dist archive, not just the source: composer install --prefer-dist in a clean clone. Classic RC packaging failures are .gitattributes export-ignore stripping config/, resources/, or tests/ from the archive, and autoload PSR-4 paths that resolve on the author's machine but not from a tarball. If --prefer-dist breaks but --prefer-source works, that's the bug — report it with both commands.
• Auto-discovery is silent. If the provider isn't in extra.laravel.providers, nothing errors — you just get "class not found" or an unregistered facade alias later. Check php artisan about / php artisan package:discover -v to confirm registration.
• Facade aliases. RC packages often register aliases that collide with an existing package or a Laravel built-in. Check config/app.php aliases after install.
• No upgrade guarantees between RC and stable. Assume 1.0.0 stable renames public methods, changes config keys, and bumps minimum PHP. Don't build anything on top of it that you can't delete in an afternoon.
• composer update will not move you to RC2. With an exact pin, you must bump it explicitly. Good — that's the behaviour you want, and it's the reason to pin rather than use a range.
• Version matrix. Cross-check the package's CI matrix (if published) against your PHP and Laravel minor. RC-era composer.json constraints are usually looser than the code actually supports.
• Debugging runtime errors: because there's no ecosystem of StackOverflow answers for a brand-new package, go straight to vendor/vendor/package/src — read the actual method. Don't guess at behaviour from the README; in an RC the README and the code routinely disagree.
• Extension points are the stable surface. Prefer packages' events, interfaces, and config over subclassing concrete classes. RC code reshuffles internals freely but is slightly more careful with anything documented as extension surface.
• Do not put this in production. The release note is unambiguous. If you must demo it, do it behind a feature flag defaulted off, on a non-critical path, with the wrapper in place so removal is a one-line change plus composer remove.
• Report bugs upstream immediately with a minimal reproduction and your composer show vendor/package output — RC1 is precisely the window where an issue report shapes the stable API, and you get a say in naming before it's frozen.
• Set an exit criterion now: e.g. "only promote past the spike once 1.0.0 stable ships and the package's tests pass on our PHP/Laravel matrix." Otherwise an RC quietly becomes load-bearing.