Licensing Laravel Package

Technical Evaluation

Architecture fit

• This is not a general-purpose licensing library; it is a capability plugin for Lunar. The decisive fit question is therefore prior to any code review: are we running Lunar, and do we intend to keep running it? If the answer is no, the package is out of scope regardless of quality. Its value is entirely contingent on Lunar's order model being our order model.
• Where it does fit, the shape is correct for the domain: license keys as Eloquent models tied to order lines, with a separate activation entity. That is the right normalization — a licence (the entitlement) and an activation (a machine/instance consuming a seat) are distinct lifecycles, and collapsing them is the mistake most homegrown implementations make. The stated "extensible validation and activation hooks" is the seam that matters: validation policy (seat counts, expiry, revocation, offline grace) is business logic and should not be hard-coded.
• The "READ ONLY — subtree split" banner is an architectural signal, not a defect. Canonical development happens in lunarphp/lunar; this repository is a published artifact. It means the service provider and composer.json are generated from the monorepo, that tags mirror monorepo tags, and that this repo cannot accept the fixes we might need. Intake must target the monorepo.

Integration feasibility

• Feasible in principle for a Lunar shop: Composer install, Eloquent models, order-flow integration, Laravel-native config/migrations. No exotic infrastructure implied.
• The binding constraint is version lockstep with Lunar core. A subtree split's version is only meaningful relative to the monorepo tag it was cut from. lunarphp/licensing and lunarphp/lunar must be resolved together, from the same release train. Treating licensing as an independently versioned dependency is the most likely integration error.
• The published release date (2023-01-19) is the material finding. It either indicates the component was folded into Lunar core, deprecated, or has simply been stable and untouched. These are very different outcomes and cannot be distinguished from this repository alone — it carries no changelog, no issues, and no PR history by design.

Technical risk

• Staleness / status ambiguity (high). A two-year-old subtree split is not automatically abandoned, but we cannot tell from here whether the package is current, superseded by core, or unmaintained. This must be resolved before any code is read. Check the monorepo's current packages/ layout and whether licensing is still a standalone installable.
• Version-coupling to Lunar (high). The package is only useful inside a narrow band of Lunar versions. If our Lunar install is older or newer than the licensing component's supported range, we are either upgrading Lunar or forking. That is a project, not a composer require.
• Security surface (high, domain-specific). License keys are bearer secrets. The questions that matter are concrete and checkable: are keys stored hashed or in plaintext, is comparison timing-safe, is key entropy sufficient (no sequential IDs, no Str::random misuse), is there a rate limit on any public validation endpoint, and does activation enforce a seat cap atomically rather than via read-then-write. A licensing bug is a revenue and trust bug, not a cosmetic one.
• Fork cost (medium). Because the repo is read-only, any patch means forking the monorepo or vendoring the package. Price that in at adoption, not at the first incident.

Key questions (blocking)

1. Is lunarphp/licensing still a supported package in the current Lunar release, or has it been merged into core or deprecated? What is the canonical install instruction today?
2. Which Lunar core versions does it support, and does that range include ours and our planned upgrade?
3. Do we actually need to sell or validate licences? Is there an incumbent (Keygen, LicenseSpring, Cryptlex, custom table) and why is a self-hosted package better than a hosted licensing service?
4. How are keys generated and stored? Hashed at rest, sufficient entropy, timing-safe comparison?
5. Is activation seat-limited atomically, and is validation rate-limited if exposed publicly?
6. Does it support revocation on refund/chargeback, and does it hook Lunar's order status transitions?
7. What is the offline-validation story, if any? (Determines whether activation can be an occasional call or must be on every app start.)
8. Licensing and maintainer commitment for the monorepo, not this split.

Integration Approach

Stack fit

• Binary precondition: Laravel + Lunar. If we are on Lunar, the fit is good — the package speaks the platform's order model natively, which is precisely the integration we would otherwise hand-roll. If we are not on Lunar, stop; do not attempt to port the models into a non-Lunar application. The coupling to order flow is the value and the lock-in simultaneously.
• Confirm the service provider auto-discovers and that published config/migrations are namespaced and reversible. Check for collisions in config keys, facade aliases, and Artisan signatures against our existing packages.

Migration path

• Greenfield (no licensing today): the clean case. Install, publish config and migrations, wire the order hook, define validation policy. Low migration risk; the risk is design, not transition.
• Replacement (replacing a hosted service or in-house table): do not big-bang. Run both issuers in parallel — issue from the new package, keep the old validator authoritative — until activation parity is proven. Licence-key migrations are one-way in practice; customers hold keys we cannot re-issue without support load.
• Review the published migrations before running anywhere non-ephemeral. A migration that creates licensing tables is low risk; one that alters orders or order_lines is a different conversation.

Compatibility

• Pin licensing and Lunar core to the same release train, explicitly — exact versions or matched tilde constraints. Never allow an independent float on either.
• Verify the PHP/Laravel support matrix from the monorepo CI, not from this repository, and check it against our runtime and our next upgrade target.

Sequencing

1. Status check (blocking). Confirm in the monorepo that licensing is a current, supported, installable package and identify the supported Lunar range. If superseded or deprecated, stop.
2. Domain fit. Confirm the business actually issues licences and agree the policy: seats, expiry, revocation, offline grace. This drives what we need to extend.
3. Static review. Provider, models, key generation/storage, activation transaction semantics, migrations. Security review of the key path specifically.
4. Isolated spike. Fresh Lunar app at our version; issue a licence against a test order, activate, revoke, over-activate. Timebox one to two days.
5. Pilot in one product line behind a config flag, with a documented rollback to the previous issuer.
6. Adoption decision with a named owner, pinned versions, and an upgrade cadence tied to Lunar upgrades.

Steps 1 and 2 are cheap and decide the outcome; do not compress them.

Operational Impact

Maintenance

• Upgrades to this package are Lunar upgrades, not independent dependency bumps. Budget the licensing component into every Lunar upgrade rather than treating it as a separate maintenance line. That is simpler than it sounds and more disciplined than it sounds.
• Because the repo is read-only, record explicitly where patches go (monorepo fork or vendored copy) and who owns the fork. Do not let a dependency bot bump it independently of Lunar core.

Support

• Support flows through the Lunar project and its commercial entity, not through this repository. Establish what the monorepo's stated support posture is — community-only versus commercial — and whether licensing sits inside that commitment. A 2023-dated split with no activity is a signal to verify, not a verdict.
• Mitigation: the pilot team must be able to read the models and validation hooks. If we cannot reason about key issuance and activation, we cannot operate a licensing system, upstream support or not.

Scaling

• Licensing has an unusual load profile: writes are rare (issue, activate), but validation can be hot and public. If licence checks are exposed to client applications, that endpoint is internet-facing and must be rate-limited, cached, and indexed on the key column. Treat a plaintext-key lookup without an index as a production incident waiting to happen.
• Activation must be transactional and seat-checked atomically; concurrent activations against a read-then-write check will oversubscribe seats under even modest concurrency.
• Standard Laravel risks apply: N+1 through package-provided order/licence relations, and service-provider boot cost on every request. Measure provider boot overhead in the pilot if licensing is loaded in a high-throughput service.

Failure modes

• Package superseded or removed from Lunar (highest impact). We build on it, then find the capability moved into core with a different schema. Detectable at step 1; catastrophic at step 5.
• Version skew with Lunar core. Licensing lags or leads our core version; upgrade becomes blocked or forced. Mitigated by lockstep pinning.
• Key compromise or weak generation. Plaintext storage, low entropy, or non-constant-time comparison turns a licence system into a data breach. Security review at step 3, not after launch.
• Activation over-subscription. Non-atomic seat checks let one licence serve unlimited installs. Revenue loss, discovered late.
• Fork drift. We patch locally, upstream moves, and we carry a divergent licensing implementation through every Lunar upgrade.
• The first two are cheap to detect during intake and expensive to detect in production. That asymmetry is the argument for the gated sequence above.

Ramp-up

• Two knowledge domains, not one: Lunar's order lifecycle and licensing semantics (entitlement vs activation, revocation, offline grace). Assume two to three days to first productive use including the spike, more if the team is new to Lunar.
• Documentation will largely come from the monorepo and from us. If more than one product line adopts, write a short internal note: pinned versions, chosen validation policy, issuer-of-record, revocation procedure, and the named owner. That note is what prevents the next engineer from inheriting an unexplained licensing dependency.

Recommendation: Conditional proceed to intake, not adoption. The package is architecturally well-shaped for its narrow purpose and the licensing domain model is sound, but its value is entirely contingent on our being a Lunar shop, and its 2023-01-19 release date leaves its current status unresolved. Resolve two things before writing any code: whether licensing is still a supported, installable component in the current Lunar monorepo, and whether we genuinely need to issue licences rather than buy a hosted licensing service. If both resolve favourably and the key-handling review is clean, this moves to pilot. If licensing has been folded into core, follow core; if it is unmaintained, the fork cost is the real price and should be quoted before the decision, not after.