License Connector Laravel Package

Getting Started

laravel-ready/license-connector sits between a Laravel application and a remote license server, handling activation, validation, and (typically) update/entitlement checks for commercially licensed code. v2.0.0 is a major release cut from v1.1.2; treat it as a breaking upgrade rather than a drop-in.

Start here, in order:

1. Read the diff, not the release notes. The published notes for v2.0.0 are only a compare link (v1.1.2...v2.0.0). Before anything else, open that compare and scan for renamed config keys, changed method signatures, dropped facade aliases, and bumped PHP/Laravel constraints in composer.json. There is no prose upgrade guide in the announcement, so the diff is the source of truth.
2. Install and publish.

   composer require laravel-ready/license-connector:^2.0
   php artisan vendor:publish --tag=license-connector-config
   

3. Configure via env. Set the license key, server endpoint, and product/slug identifiers in .env; keep the config file thin and env-driven so staging and production differ without code changes.
4. First use case: activate a key once during provisioning, then verify status on subsequent boots rather than re-activating. The minimal loop is activate → persist the response → validate later.

If you are upgrading an existing 1.x install, branch first, bump the constraint, run the test suite, and only then resolve the diff. Do not let ^1.1 float into 2.0 accidentally.

Implementation Patterns

Activate on deploy, validate on boot. Activation is a write operation against the license server and should happen in a deploy step or an artisan command, not on a user request. Validation is a read and can be tolerated in the request lifecycle if cached.

// deployment / provisioning
php artisan license:activate {key}

Cache the validation result. The single most important pattern is wrapping validate() behind Cache::remember() with a TTL matched to the license server's polling expectations. Without this you add a remote HTTP round-trip to every request that checks entitlement.

Gate features through Laravel's native primitives. Rather than sprinkling if ($license->isValid()) across controllers, register a Gate::define('use-pro-feature', ...) or a Blade directive so entitlement logic lives in one place and is testable.

Schedule revalidation. A daily or hourly scheduled command that refreshes the cached status keeps long-running apps from serving stale entitlements if a license is revoked or expires. Pair it with a soft-fail policy so a transient network error does not lock users out.

Test with HTTP fakes. Because the package talks to a remote server, stub Http::fake() in your test suite and assert on the activation payloads. Never let CI hit the real license endpoint.

Multi-tenant / multi-domain. If you run per-tenant installs, store the activated license against the tenant record rather than a single global config value, and scope validation to the current tenant's domain.

Gotchas and Tips

• The v2.0.0 notes contain no upgrade guidance. A major bump with only a diff link almost always means renamed config keys or changed contract signatures. Grep the diff for config(, public method names, and facade accessors before deploying.
• Config caching bites on upgrade. After changing env keys for v2, run php artisan config:clear (or config:cache in deploy). Stale cached config is the most common cause of "the package ignores my new settings."
• Don't call the license server on every request. Network latency, rate limits, and license-server outages will surface directly as application latency or hard failures. Cache aggressively and define behaviour when the check fails.
• Distinguish "invalid" from "unreachable." A 500/timeout from the license server is not the same as a 403 "license revoked." Treat them differently — one should retry, the other should degrade. Look for a grace-period or offline-mode option in the config before rolling your own.
• Guard against silent expiry in queues and console commands. Scheduled jobs and queue workers may run outside the request lifecycle where your middleware-based check never fires. Validate explicitly in long-running processes.
• Pin the major version. Use ^2.0 deliberately; if you are mid-migration, pin the exact patch you have tested.
• Extension points to inspect: the HTTP client binding (swap in a client with retries/timeouts or a logging driver for debugging), and any repository/storage contract for persisting license state (useful for swapping file storage for database in clustered deployments).
• Debugging: enable the package's logging/driver config at debug level temporarily to see the raw request/response payload — license failures are usually a payload mismatch (domain, product slug, or key format), not a transport problem. Turn it back off before shipping, since it can log key material.
• Never log or commit the license key. It belongs in .env and a secrets manager, not in config/ defaults, and it should be excluded from any payload dumps you paste into issues.