Documentation for larsasub v0.38.2. On an older version? Your release notes ship with the package (CHANGELOG.md).

Database schema#

Every table the package creates, column by column. Use it when you write a report or a query against LarsaSub's tables, or when you need to check a development database against what the current release expects.

There are twenty-seven tables. All of them carry the larsasub.table_prefix (default larsasub_) and live on the larsasub.database.connection connection (default: your application's default connection). The published migrations are the authority — run php artisan vendor:publish --tag=larsasub-migrations to read them.

• Conventions
• Core billing
  • larsasub_billables
  • larsasub_subscriptions
  • larsasub_subscription_change_targets
  • larsasub_billable_subscriptions
  • larsasub_subscription_cost_lines
• Payments
  • larsasub_payment_methods
  • larsasub_tenant_payment_methods
  • larsasub_recurring_charges
  • larsasub_single_payments
  • larsasub_single_payment_entities
  • larsasub_single_payment_lines
  • larsasub_dunning_cases
  • larsasub_dunning_steps
  • larsasub_settlements
• Credit
  • larsasub_billable_credits
  • larsasub_credit_transactions
• Invoicing
  • larsasub_invoices
  • larsasub_invoice_lines
  • larsasub_credit_notes
  • larsasub_invoice_sequences
• Provider (Mollie)
  • larsasub_mollie_customers
  • larsasub_mollie_mandates
  • larsasub_mollie_connected_accounts
  • larsasub_connect_flow_states
• Supporting
  • larsasub_terms_acceptances
  • larsasub_notification_deliveries
  • larsasub_model_logs
• Keeping the schema in step

Conventions#

The column tables below leave out what every table shares, so each row is a column that tells you something.

• id and timestamps. Every table starts with an auto-incrementing unsigned big-integer id and ends with created_at / updated_at (nullable timestamps). The one exception is larsasub_model_logs, which has created_at only.
• Types are the Laravel schema-builder methods the migration calls. string without a length is string(255). Amounts are decimal(10,2) and VAT rates decimal(5,2) (a percentage: 21.00).
• Morph pairs (tenant, provider_mandate, invoiceable, source, entity, loggable) are a {name}_type string plus a {name}_id unsigned big integer, indexed together.
• Tenant columns. tenant_type / tenant_id name the Connect tenant a row belongs to. Null means no tenant: simple mode, or the platform's own account.
• Foreign keys restrict deletion unless the table says otherwise.
• Currency defaults (price_currency, currency) take currency.default as it stands when the migration runs.
• Columns are contract. The model columns are part of the public API: removing one is a breaking change.

Seven tables use soft deletes (deleted_at), so the audit trail survives a cleanup: larsasub_subscriptions, larsasub_billable_subscriptions, larsasub_subscription_cost_lines, larsasub_recurring_charges, larsasub_single_payments, larsasub_mollie_customers and larsasub_mollie_mandates.

These columns are encrypted at rest through model casts, so they hold ciphertext — never query or compare them in SQL:

An encrypted array sits on a longText column, not json: a ciphertext is not valid JSON, and MySQL rejects it in a JSON column.

Core billing#

The registration, the plans and each subscriber's copy of a plan.

larsasub_billables#

The registration linking your owner model (User, Team, Tenant) to everything else. Model: Billable — see Billable models.

The four vat_check_* columns are written by the package only and are not fillable, so a profile form cannot set them.

Indexes:

• Unique (owner_type, owner_id, tenant_key) — one registration per owner per tenant. tenant_key is non-null precisely so this works: NULLs are never equal in a unique index, and customer #1 of two different tenants must be two registrations.
• (tenant_type, tenant_id) and (invoice_type, vat_check_status).

larsasub_subscriptions#

Plan templates. Model: Subscription — see The subscription plan. Soft deletes.

Indexes: (tenant_id, tenant_type).

larsasub_subscription_change_targets#

Which plans a plan may be switched to. A pivot with no model of its own; it backs Subscription::changeTargets().

Indexes: unique (subscription_id, target_subscription_id).

larsasub_billable_subscriptions#

One subscriber's instance of a plan. The price and terms are copied from the plan at creation, so a later plan edit never changes the price a running subscriber pays or how often. The VAT rate is the exception: it is not copied, and follows the plan (see vat_rate). Model: BillableSubscription — see The BillableSubscription instance. Soft deletes.

Indexes: billable_id; (started_processed_at, start_date); the provider_mandate morph pair.

larsasub_subscription_cost_lines#

Recurring add-ons on a subscription instance, prorated per calendar day. Model: SubscriptionCostLine — see Cost lines. Soft deletes.

valued_from and starts_on are not each other's mirror: an opening charge clamps to its own period start and writes the days before it off. Null means "nothing valued yet" on a new line and "predates the column" on an old one, and the accessor answers both with starts_on. Lines marked before the column existed are repaired once with larsasub:backfill-valued-from — see the upgrade guide.

Indexes: (billable_subscription_id, key).

Payments#

Payment methods, the two payment tables and what hangs off them: order lines, attached entities, reminder series and payouts.

larsasub_payment_methods#

The available payment methods. Model: PaymentMethod — see Enabling methods.

Indexes: unique (provider, provider_id).

larsasub_tenant_payment_methods#

Per-tenant enablement of those methods in Connect mode. Model: TenantPaymentMethod — see Tenant availability.

Indexes: unique (tenant_id, tenant_type, payment_method_id).

larsasub_recurring_charges#

One payment in a subscription's billing history — and also every charge without a subscription: standalone charges, the €0.01 mandate setup and chargeback follow-ups. Model: RecurringCharge — see Recurring charges. Soft deletes.

Indexes:

• Unique reference; unique origin_chargeback_id (one follow-up per chargeback).
• billable_id, superseded_by_charge_id, follows_charge_id, settlement_id, the provider_mandate morph pair.
• (provider_payment_id, charged_at), (billable_subscription_id, planned_on) and (charged_at, planned_on) — the webhook lookup, the planner and the executor.

larsasub_single_payments#

One-time payments. Model: SinglePayment — see Single payments. Soft deletes.

Indexes: unique reference; billable_id; provider_payment_id; settlement_id.

settlement_id on both payment tables is written by larsasub:sync-settlements and by nothing else. It is the provider's settlement id, not a foreign key: a payment is attached before, or without, its larsasub_settlements row. See Settlements.

larsasub_single_payment_entities#

Pivot linking a single payment to your IsPayable business objects. Model: SinglePaymentEntity — see Attaching entities.

Indexes: single_payment_id; the entity morph pair.

larsasub_single_payment_lines#

Optional order lines on a single payment. Model: SinglePaymentLine — see Order lines.

Indexes: single_payment_id.

larsasub_dunning_cases#

One reminder series per unpaid charge. Written only through DunningService; no soft deletes — the model log is the trail. Model: DunningCase — see Reminder series, which has a table for every enum value below.

Indexes: unique recurring_charge_id; billable_id; status.

larsasub_dunning_steps#

One row per step of a case's schedule that a run took up. Model: DunningStep.

Indexes: unique (dunning_case_id, step_index) — two overlapping runs cannot both take the same step.

larsasub_settlements#

The provider's payouts, one row per settlement, written by larsasub:sync-settlements. Model: Settlement — see Settlements.

Indexes: unique settlement_id; (tenant_type, tenant_id); reference; status.

Credit#

The credit wallet and its ledger. Mutate them only through CreditService — see Credit.

larsasub_billable_credits#

One credit account per billable. Model: BillableCredit.

Indexes: unique billable_id.

larsasub_credit_transactions#

The ledger: one row per credit mutation. Model: CreditTransaction — see Transaction types.

Indexes: billable_credit_id, billable_id, type, recurring_charge_id, expires_at, expired, performed_by_user_id, the source morph pair.

Invoicing#

Invoice and credit-note snapshots and their numbering. Invoicing is off by default — see Invoicing and VAT.

larsasub_invoices#

Finalized invoice snapshots. Model: Invoice — see The invoice model.

Indexes: unique invoice_number; unique (invoiceable_type, invoiceable_id) — at most one invoice per payment; billable_id; the tenant morph pair.

larsasub_invoice_lines#

Immutable invoice lines, net of VAT, summing exactly to the invoice subtotal. Model: InvoiceLine — see Invoice lines.

Indexes: invoice_id.

larsasub_credit_notes#

Credit notes voiding an invoice after a refund or chargeback. Model: CreditNote — see Credit notes.

Indexes: unique credit_note_number; invoice_id; billable_id; the tenant morph pair.

larsasub_invoice_sequences#

Continuous numbering, one sequence per document type and tenant, never reset. Model: InvoiceSequence — see Numbering.

Indexes: unique (tenant_key, type) — the non-null tenant_key is what makes it bite in simple mode, where a unique over the nullable morph would let two first invoices mint the same number.

Provider (Mollie)#

Customer and mandate references at Mollie, and the Connect tables. See Mollie models.

larsasub_mollie_customers#

Customer references at Mollie, one per billable per tenant. Model: MollieCustomer. Soft deletes.

Indexes: unique (billable_id, tenant_id, tenant_type).

larsasub_mollie_mandates#

Direct debit mandates. Model: MollieMandate — see Mandates. Soft deletes.

The tenant of a mandate is the tenant of its customer.

Indexes: unique (customer_id, mandate_id); (billable_id, payment_method_id); last_validated_at.

larsasub_mollie_connected_accounts#

A tenant's OAuth connection to its own Mollie organization. Model: MollieConnectedAccount — see Mollie Connect.

Indexes: unique (tenant_id, tenant_type) — one connected account per tenant; unique reference_code; disconnected_at.

larsasub_connect_flow_states#

A Connect authorization in progress. It lives in a table rather than the cache because the flow crosses origins — see The OAuth flow. Model: ConnectFlowState.

The rows are transient: a flow that completes or is declined is deleted on the spot, and expired rows are swept by the next authorization. That is why the table has no prune command.

Indexes: unique state_hash; unique ticket_hash; expires_at.

Supporting#

Acceptance evidence, the notification delivery log and the activity trail. None of these tables stores a raw IP address, user agent, email address, subject or body — see Compliance.

larsasub_terms_acceptances#

Append-only acceptance evidence. Model: TermsAcceptance — see The evidence record.

Indexes: (billable_id, terms_identifier).

larsasub_notification_deliveries#

One row per (notification, channel), so an interrupted delivery job does not re-mail a whole list. Model: NotificationDelivery — see Delivery records and duplicates.

Indexes: unique (notification_id, channel) — the deduplication key; (delivery_key, status); (billable_id, created_at); (status, created_at); created_at.

larsasub_model_logs#

The per-model activity trail, written through peters-development/laravel-model-logger. Model: ModelLog — see HasModelLogs. This table has created_at only.

Indexes: user_id; the loggable morph pair.

Three daily prune commands keep the bounded tables bounded:

For the first two, null or 0 disables pruning. Finished reminder series are kept unless you set retention.dunning_days; a series whose charge could still get one is never pruned.

Keeping the schema in step#

Since 0.37.1, existing migrations never change: every schema change ships as a new migration, and php artisan migrate applies it. Up to 0.37.1 the migrations were edited in place, so a database created from an earlier release can have nothing pending while it misses columns: php artisan migrate reports success, and the next scheduled run dies on Unknown column.

php artisan larsasub:doctor

The doctor checks the columns the models expect, not just the tables. On a development database the fix is php artisan migrate:fresh, or a manual ALTER — see the upgrade guide for the per-release notes.