agentleFS
peterfoxpeterfox/agent-skills/laravel-advanced-concepts/SKILL.md

laravel-advanced-concepts

Skill25 starsChanged 9 months agoMITView on GitHub

Advanced Laravel architectural patterns: Feature Flags, State Machines, and Event Sourcing. Use this skill whenever a user asks about: toggling features for users/groups, gradual rollouts, A/B testing, beta access (→ Feature Flags); modeling workflows like order status, subscription lifecycle, booking states, anything with defined transitions (→ State Machines); financial ledgers, credit/wallet systems, audit trails, undo history, GDPR-compliant data deletion, analytics replay (→ Event Sourcing). Also trigger when users mention spatie/laravel-model-states, Laravel Pennant, spatie/laravel-event-sourcing, hirethunk/verbs, or ask "how should I model X in Laravel" for any complex domain. This skill provides library recommendations, code patterns, and decision guidance — use it proactively whenever the user's domain sounds like it fits one of these patterns.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Feature Flags + anything: use Pennant to gate access to new aggregates or state machine variants during a migration.

    line 106

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

SituationPatternWhy
Credit, wallet, points, ledgerEvent SourcingEvery balance change needs an immutable audit trail; balance = sum of events
Order status, booking lifecycleState MachineTransitions are the business rules; illegal transitions must be prevented at the model level
New feature rollout, beta accessFeature FlagsDecouple deploy from release; control who sees what without code changes
GDPR "right to be forgotten"Event SourcingEncrypt events per user; "forget" = destroy the key
Subscription plan managementState Machineactive → paused → cancelled is a classic FSM
A/B testing, experimentsFeature FlagsDefine variant logic once, measure separately
Full audit log / time travelEvent SourcingRebuild 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:

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.