Laravel Advanced Concepts

Three patterns that solve common but complex problems in Laravel apps. Each has a clear "home turf" — when the problem fits the pattern well, you get enormous benefits; when it doesn't, you're adding accidental complexity.

Quick Pattern Selector

Situation	Pattern	Why
Credit, wallet, points, ledger	Event Sourcing	Every balance change needs an immutable audit trail; balance = sum of events
Order status, booking lifecycle	State Machine	Transitions are the business rules; illegal transitions must be prevented at the model level
New feature rollout, beta access	Feature Flags	Decouple deploy from release; control who sees what without code changes
GDPR "right to be forgotten"	Event Sourcing	Encrypt events per user; "forget" = destroy the key
Subscription plan management	State Machine	active → paused → cancelled is a classic FSM
A/B testing, experiments	Feature Flags	Define variant logic once, measure separately
Full audit log / time travel	Event Sourcing	Rebuild state at any point in time from the event stream

---

Feature Flags

Primary library: Laravel Pennant (official, first-party, Laravel 10.2+)

Pennant is the recommended choice for almost all use cases. It ships with Laravel and has first-class support.

When to use Feature Flags

• Rolling out a new feature to a percentage of users
• Beta programs / early access lists
• A/B testing UI or pricing
• Kill switches for risky features
• Gradual infrastructure migrations (e.g., "10% of traffic uses new payment processor")

Core concepts

• Feature: a named flag that resolves to true/false (or a variant value)
• Scope: what the flag is evaluated against — usually the authenticated user, but can be any model
• Driver: where flag state is stored — database (per-scope state), array (in-memory for tests)

See references/feature-flags.md for installation, full API, and patterns.

---

State Machines

Primary library: spatie/laravel-model-states

The standard choice for Laravel. Tight Eloquent integration, transition validation, custom transition classes.

When to use State Machines

• The entity has a status field that controls what actions are allowed
• Illegal transitions should be rejected (e.g., can't go from cancelled back to active)
• You want the transition itself to carry logic (send email, fire event, update timestamps)
• Multiple places in your code change the same status and you need consistency

When NOT to use State Machines

• The "states" are just labels with no transition logic — a plain enum is simpler
• Transitions are completely unrestricted — just update the field directly

See references/state-machines.md for installation, state/transition classes, and patterns.

---

Event Sourcing

Primary libraries:

• spatie/laravel-event-sourcing — mature, full-featured, well-documented
• hirethunk/verbs — newer, opinionated, simpler API, excellent for new projects

When to use Event Sourcing

• Financial data: credits, debits, wallet balances, points — the canonical use case
• You need a complete audit log that cannot be altered
• You need to replay history to rebuild state (analytics, projections, debugging)
• GDPR compliance: per-user encryption keys let you "forget" a user by deleting their key
• The domain is complex enough that understanding "how did we get here" matters

When NOT to use Event Sourcing

• Simple CRUD with no audit requirements — overhead isn't worth it
• The team is unfamiliar with event sourcing — it's a significant mental model shift
• You just need soft deletes + timestamps — that's usually enough

Choosing between Spatie and Verbs

• Spatie: battle-tested, more users/resources, traditional event sourcing concepts (Aggregates, Projectors, Reactors)
• Verbs: simpler syntax, type-safe state, better for greenfield projects, fewer concepts to learn

See references/event-sourcing.md for installation, aggregates, projectors, and patterns for both libraries.

---

Combining Patterns

These patterns compose well:

• State Machine + Event Sourcing: record each state transition as an event. The state machine enforces valid transitions; the event log gives you full history. Good for order workflows where you need both correctness and auditability.
• Feature Flags + anything: use Pennant to gate access to new aggregates or state machine variants during a migration.