Foundation Laravel Package

Getting Started

• Install the package with composer require fapost-lab/foundation and run the publishable install command (typically php artisan foundation:install). Publish config and migrations, then run php artisan migrate.
• Start by reading the package’s config/foundation.php (or equivalent) and the Quota/Tenant contracts. The new v0.19.0 feature adds an operator-facing usage reporting path — look for a service, facade, or artisan command that lets an operator record per-period usage for a tenant.
• First use case: after a tenant performs a metered action (API call, seat added, storage written), report the usage for the current billing period. For example, an operator back-office job can call the new reporting API to push usage that originated outside the tenant’s own app (manual adjustments, imports, partner systems).

// Illustrative shape — check the actual API in v0.19.0
app(QuotaReporter::class)->report(
    tenant: $tenant,
    metric: 'api_calls',
    amount: 150,
    period: now()->startOfMonth(), // or let the package resolve the active period
);

• If you already use the package’s quota enforcement middleware or policies, the new reporting method complements them: enforcement checks limits, reporting records consumption. Use both together so the operator view stays accurate.

Implementation Patterns

• Event-driven reporting: dispatch a domain event (e.g. ApiCallCompleted) and let a queued listener call the new operator reporting method. This keeps usage writes out of the request cycle and makes retries safe.
• Idempotency: when importing usage from external systems, pass a unique idempotency key (invoice ID, external event ID) so repeated reports for the same period don’t double-count. If the package doesn’t provide this out of the box, wrap reports in your own usage_reports table with a unique constraint.
• Operator dashboards: expose a small admin controller that lists tenants, their current-period usage, and remaining quota. The new v0.19.0 feature is specifically aimed at operators, so build read models around the same service to avoid drift between “reported” and “enforced” numbers.
• Scheduled reconciliation: run a nightly job that compares your source-of-truth usage (logs, Stripe meters, etc.) with the package’s recorded usage and reports any delta. This is especially useful for manual adjustments and corrections.
• Billing integration: after reporting usage, trigger your billing provider’s usage-record API (Stripe, Lago, etc.). Keep the package as the quota ledger; keep the billing provider as the invoicing system.
• Tenant context: when an operator reports usage on behalf of a tenant, ensure the tenant is explicitly resolved rather than relying on the current request’s tenant scope. Use the package’s tenant resolver or pass the tenant model directly.
• Feature flags / rollout: wrap new reporting calls behind a config flag so you can enable metered billing per plan or per tenant cohort without redeploying.

Gotchas and Tips

• Period boundaries: “per-period usage” depends on how the package resolves the billing period (calendar month vs. tenant anniversary vs. custom start day). Confirm the period resolution logic before backfilling data; a mismatch will put usage in the wrong bucket.
• Concurrency: usage reporting from multiple queue workers can race. Prefer atomic increments (increment/upsert) or wrap reports in a transaction with row locks. If the package’s reporter is not atomic, serialize per tenant with a cache lock.
• Operator vs. tenant context: the new feature is operator-facing. Don’t assume it behaves identically to tenant self-reporting — authorization, tenant scoping, and period defaults may differ. Check the release PR (#23) and tests for exact behavior.
• Caching: if you cache quota limits or usage summaries, invalidate or update the cache after every report. Stale dashboards are the most common complaint after enabling metered usage.
• Debugging: log every report with tenant ID, metric, amount, resolved period, and idempotency key. When numbers look wrong, replay the logs against the package’s period resolver. Add an artisan command like foundation:quota:show {tenant} for quick inspection.
• Extension points: look for events such as UsageReported or QuotaExceeded. Hook into them for audit logs, notifications, and billing sync rather than modifying package code.
• Config quirks: check whether the package uses a “soft limit” vs. “hard limit” mode, whether overage is allowed, and how rounding works for fractional usage. These settings often live in config and are easy to overlook during local testing.
• Upgrade note: v0.19.0 is a minor feature addition, not a breaking change. No migration is implied by the release notes, but always run php artisan vendor:publish --tag=foundation-config --force cautiously and diff the config after upgrading.