Subscriptions Laravel Package

Technical Evaluation

Architecture fit. The first thing to flag is category mismatch: flarum/subscriptions is not a Laravel package, it is a Flarum extension. Flarum is a PHP forum platform that borrows Laravel components (Illuminate container, database, events, queue) but pins its own versions and boots through its own extender/service-provider lifecycle. It cannot be composer required into a Laravel application and used as a billing library. Leveraging it means one of three things: (1) running Flarum as a companion service alongside the Laravel app — the realistic option; (2) extracting the subscription domain model and reimplementing it in Laravel — high effort, low reuse; or (3) not using it at all if Flarum isn't already in the estate.

Integration feasibility. Moderate-to-low as a standalone dependency. The extension provides subscription state, plan definitions, and recurring-payment hooks on top of Flarum's payment abstraction, but it is designed to be consumed by Flarum's frontend and other Flarum extensions, not by an external API. Any Laravel-side entitlement checks would require a shared datastore or a thin API we build and own. Realistically this is a "we already run Flarum, do we add paid memberships?" decision, not an "adopt this package" decision.

Technical risk.

• [READ ONLY] Subtree split is the dominant signal. The canonical source lives in Flarum's monorepo; this repo is a generated mirror. Issues and PRs are not accepted here, patches require forking upstream, and the release history is an artifact of core releases rather than an independently versioned library.
• 13 stars / score 20 reflects the split, not necessarily quality — but it also means no independent docs, no independent issue tracker, and effectively zero community surface to lean on.
• Version coupling: the extension tracks Flarum core majors. A Flarum upgrade is a coordinated, potentially breaking change to the subscription extension and any gateway extensions it depends on.
• Correctness surface: recurring billing is a state machine where bugs are financial. Renewal boundaries, proration, dunning, refunds, and webhook idempotency all need independent verification — we should not assume the extension's defaults match our accounting requirements.
• Payment provider coupling: gateway support is delegated to sibling extensions; the real dependency graph is larger than this one package.
• License: MIT, clean. Low legal risk.

Key questions. Which Flarum major version(s) does the current release target, and what is the upgrade cadence? Which payment gateways have first-party extension support, and do they cover our processor? Is subscription/entitlement data readable from an external service without forking? How are webhooks received and are they idempotent? Does it handle tax, multi-currency, proration, refunds, and failed-payment dunning, or do we own those? Who is the maintainer of the canonical monorepo package, and what is the bus factor? What is the migration story if we later move billing in-house?

Integration Approach

Stack fit. Only viable if Flarum is already (or is planned to be) part of the product. The supported topology is: Laravel remains the system of record for identity and entitlements; Flarum runs as a separate PHP service with its own vendor tree; flarum/subscriptions manages plan purchase and renewal inside Flarum; the two are joined by shared user identity and a synchronization contract we own.

Do not attempt to share a single vendor/ directory or a single Composer project between Laravel and Flarum. Their Illuminate version pins will conflict. Treat Flarum as a bounded-context service with its own deploy unit, its own database, and a documented API/event boundary.

Migration path. Do not vendor this read-only mirror. Either consume the published flarum/subscriptions release through Composer at a pinned version, or — if any customization is required — fork the canonical monorepo extension, not this split, and maintain the fork as a path repository. Record explicitly that we are diverging from upstream at that point and budget for rebasing.

Compatibility. Verify against a specific Flarum major (1.x vs 2.x are materially different extension APIs), the PHP version Flarum supports, and MySQL vs PostgreSQL. Validate the gateway extension's supported currencies and regions before committing. Confirm that Flarum's pinned Illuminate components do not collide with our Laravel version at the HTTP/SSO boundary (they won't at the dependency level if services are separated, but they will at the shared-session level if we try to share cookies — don't).

Sequencing.

1. Confirm Flarum is a strategic part of the product; if not, stop here.
2. Stand up Flarum in a sandbox at the target version and install the extension plus the gateway extension.
3. Model the entitlement contract: what a "subscriber" means to the Laravel app, and how it is read (shared DB read replica, webhook, or polling API).
4. Build the webhook receiver and idempotency layer on the Laravel side first — before any real money moves.
5. Wire SSO so a single identity spans both services.
6. Run a full renewal cycle in sandbox against the gateway's test clocks, including failure, retry, cancel, and refund paths.
7. Backfill or grandfather existing subscribers, then cut over.

Operational Impact

Maintenance. Upgrades arrive on Flarum's release cadence, not ours. Because this repo is a generated split, there is no changelog, no issue history, and no PR review trail visible here — the team must track the canonical monorepo to understand what changed and why. Any local patch becomes a permanent rebase obligation. Budget for one engineer to own the Flarum surface, not a fraction of one.

Support. Community forum and upstream maintainers only; no commercial SLA. The low star count and mirror status mean we should assume we will be our own first line of support. Escalation paths for a billing outage are effectively "read the upstream source."

Scaling. Subscription checks on the request path will become a hot read — cache entitlements with an explicit TTL and invalidation on webhook. Webhook ingestion must be queue-backed and horizontally scalable; renewal bursts (month-start, annual cohorts) are spiky. Subscription and payment-attempt tables grow monotonically; plan for retention and archival of historical attempts. Do not put the entitlement check inline in a page-render path without a cache.

Failure modes.

• Missed or duplicated webhooks → entitlement drift: paying users locked out or cancelled users retaining access. Needs reconciliation job, not just webhook handling.
• Renewal boundary bugs (timezone, month-end, leap day) → incorrect charge dates or double charges.
• Flarum core upgrade disables the extension → checkout and renewal both stop; renewals may silently fail.
• Gateway extension abandonment → no path to rotate processors without a fork.
• Refund/chargeback not propagated → access retained after reversal; a finance and audit finding, not just a bug.
• Silent cron failure for renewal jobs — the worst case, because it looks like normal operation until revenue is missing.

Ramp-up. A Laravel developer will not be productive in this codebase on day one. Flarum's extender pattern, its frontend (Mithril/JS), its migration and settings conventions, and its permission model are all distinct from standard Laravel idioms. Expect roughly one to two weeks to first meaningful contribution, plus additional time for whoever owns the payment gateway integration to understand its reconciliation semantics. The billing correctness knowledge — not the PHP — is the actual ramp-up cost, and it should sit with whoever owns revenue operations, not solely with engineering.