Purchases For Laravel Laravel Package

Getting Started

The package ships an opt-in API that is disabled unless you explicitly enable it. That switch is the first thing to understand before anything else works.

1. Install the package (composer require <vendor>/<package>) and confirm the package-toolkit constraint resolves to ^1.4.0 or newer — the 1.1.9 release tightened this requirement.
2. Publish the config file (php artisan vendor:publish --tag=<package>-config) so the opt-in switch actually exists in your app.
3. Set the corresponding environment variable in .env and mirror it in .env.example.
4. Clear cached config (php artisan config:clear) and verify the flag is live.

Where to look first: the published config file, for the opt-in key and the env var it reads. That single value determines whether the API routes/services are even registered — every other question about behaviour is downstream of it.

First use case: enable the API in a single non-production environment, boot the app, and confirm the endpoints/services are registered. If they are, wire up your first consumer; if not, you are almost certainly looking at a config-cache or missing-key problem rather than a code problem (see Gotchas).

Upgrading to 1.1.9: no breaking changes. The only behavioural change is a fix — the opt-in API now correctly stays off when the switch is unset, rather than loading. If you were already relying on the API, verify your env var is explicitly set; environments that were silently working because of the old fallback behaviour will now be dark.

Implementation Patterns

Treat the opt-in flag as the single source of truth. Gate route registration, service provider bindings, and middleware on the same config value rather than re-reading env() in multiple places. A thin accessor or config helper keeps this consistent:

if (config('<package>.api.enabled')) {
    // register routes / bindings
}

Per-environment enablement. The natural workflow is off in local and testing unless a test explicitly needs it, on in the environments where the API is consumed. Keep the env var in .env.example with an explicit false so new clones don't inherit "unset" ambiguity.

Test the flag itself. Because the switch changed behaviour in 1.1.9, asserting that the API is absent when the flag is off is as valuable as asserting it's present when on:

config()->set('<package>.api.enabled', false);
$this->get('/api/...')->assertNotFound();

config()->set('<package>.api.enabled', true);
$this->get('/api/...')->assertOk();

Integration tip: if you deploy behind config caching, the flag is frozen at config:cache time. Any change to the switch is a deploy step, not a runtime toggle — plan for that rather than expecting a .env edit to take effect on a running instance.

Dependency pinning: since 1.1.9 requires package-toolkit ^1.4.0, keep that constraint aligned in your own composer.json if you depend on the toolkit directly. Divergent constraints are the most likely source of an upgrade conflict.

Gotchas and Tips

The 1.1.9 fix is the headline gotcha. Before this release, the opt-in API would load when the switch was missing from a published config, was null, or came from an unset env var. Now it stays off. Concretely, this means:

• A published config file that predates the switch (you published, then upgraded) no longer enables the API by accident. Re-publish or merge the config.
• An env var present in .env but absent from the server's actual environment leaves the flag null → API off. This is the classic "works locally, 404s in staging" scenario.
• Any test that assumed implicit enabling will now fail — correctly. Fix the test by setting the flag, not by working around the default.

Watch for env() semantics. env('X') returns null when unset, and the package now treats that as off, not as "fall back to default". If you need a default, express it in the config file ('enabled' => env('X', false)), not by relying on absence.

Config caching. Always config:clear after touching the flag or the config file. A stale cache is indistinguishable from a bug and wastes disproportionate debugging time.

Debugging checklist, in order: (1) is the key present in config/<package>.php? (2) is the env var set in the running process, not just .env? (3) is config cached? (4) did a composer update drag package-toolkit to a conflicting version?

Extension point: the config file is the intended extension surface. Prefer overriding config values in config/<package>.php or via environment overrides over subclassing package internals — the 1.1.9 change is a reminder that implicit, undocumented fallback behaviour is not part of the contract.

Maintenance note: the release is a dependency bump plus a safety fix. Low upgrade risk if your flag is explicitly set; higher risk — but in a good way — if it wasn't, because you may discover environments that were never intentionally configured.