Json Form Bundle Laravel Package

Getting Started

Start by pinning the version you actually install — v1.0.1 is a patch release, so ^1.0 is safe, but read composer.json first to confirm the PHP constraint matches your runtime (a deprecation-fix release almost always implies a raised minimum, typically PHP 8.1+).

Where to look first, in order:

1. composer.json — PHP version floor and whether the service provider is auto-discovered (extra.laravel.providers / aliases). If it isn't, you'll register it manually in config/app.php.
2. config/ — publish it before writing any code (php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"). Reading the shipped defaults tells you more about intended behaviour than the README.
3. src/ contracts — resolve against the interface, not the concrete class. This is the single decision that determines how testable your integration is later.
4. README usage block — copy the smallest example verbatim into a throwaway route or php artisan tinker session and confirm it runs before adapting it.

Minimal first use case: install, publish config, set the one or two env-backed values the config references, then call the package's primary entry point once from a route closure and once from a test. Getting it working inside a test at the same time as your first manual call surfaces container-binding problems immediately rather than three features later.

Implementation Patterns

Resolve through the container, not the facade, in application code. Facades are convenient in controllers and Blade; injected contracts are what keep your service classes unit-testable and what survive the package swapping its concrete implementation.

public function __construct(private \Vendor\Package\Contracts\Client $client) {}

Bind once, override in tests. Add a single binding in a dedicated service provider rather than scattering app()->bind() calls. In tests, swap it via $this->app->instance(Client::class, $fake) in setUp() so every test inherits the fake.

Keep the config file as the integration seam. Anything you'd otherwise hardcode — endpoints, queue names, retry counts — belongs in config/package.php reading from env(). Never call env() outside config files: it returns null once php artisan config:cache has run, and that failure mode is silent.

Wrap the package behind one of your own services. Even a thin App\Services\ThingGateway that delegates to the package pays for itself the first time you need to add logging, retries, or a second implementation. It also confines the blast radius when a release like this one changes method signatures.

If you extend the package's classes, this release matters directly: added return types in v1.0.1 mean any subclass overriding those methods must now declare a compatible return type. A child method with no return type where the parent now declares : void or : static produces a fatal error, not a deprecation. Audit your subclasses, decorators, and any anonymous-class test doubles that extend package classes. If you're mocking package classes with PHPUnit, prefer mocking the contract instead — mocks of classes are generated against the current signature and will follow it, but hand-written stubs won't.

Long-running processes (queue workers, Octane, Swoole) should resolve the package per-job rather than capturing it in a constructor that lives across requests, unless you've confirmed the package is stateless.

Gotchas and Tips

• The v1.0.1 change is a patch semver but a potential breaking change for extenders. Adding return types is non-breaking for consumers who only call methods, and breaking for anyone who overrides them. If your codebase subclasses package classes, treat this as a minor-version-style review: grep for extends against the package namespace, and run your full test suite before deploying, not just the package's own tests.
• Covariance rules bite quietly. A subclass may narrow a return type (return a specific implementation where the parent returns an interface) but may not widen it or omit it entirely. If PHP reports "Declaration must be compatible", check the parent signature in the installed version — it changed in this release.
• Deprecation fixes usually ride along with a PHP floor bump. Verify composer why-not php and check CI matrices; a green local build on 8.3 says nothing about the 8.1 box in production.
• Config caching: after publishing or editing the config, run php artisan config:clear in development. Editing config while a cached copy exists is the most common "my change did nothing" report.
• Silent env() failures in cached configs manifest as null connection strings or empty API keys, often as a confusing 401 from the remote service rather than a config error.
• Facade IDE support: if the package ships a @method docblock on its facade, keep it — it's what makes static analysis and autocomplete work. If it doesn't, add your own stub or you'll get "method not found" noise from PHPStan.
• Debugging order: (1) config:clear + cache:clear, (2) confirm the provider registered via php artisan about, (3) check the published config matches the shipped one after upgrades — new keys in a release won't appear in a config file you published months ago. Re-publish to a temp directory and diff.
• Re-publish on minor upgrades, diff on patch upgrades. Patch releases rarely add config keys, but merging a re-published config after every release is how you avoid the missing-key class of bugs entirely.
• Extension points to prefer: contracts and container bindings, the package's published config, and any documented events it dispatches. Avoid extending concrete classes — that's precisely the surface this release just changed, and it will keep changing.