Download the PHP package androlax2/laravel-model-state-graph without Composer

Laravel Model State Graph

About

Laravel Model State Graph provides a powerful, flexible way to enforce complex business rules and state transitions in your Eloquent models. Instead of scattering validation logic across controllers, form requests, and model observers, this package lets you define field-level business rules that are conditionally applied based on your model's current state.

Think of it as a state machine for individual model fields, where you can control what changes are allowed, when they're allowed, and under what conditions.

When to Use

This package is ideal for scenarios where you need to:

• Enforce state transitions: Control valid status workflows (e.g., draft → pending → approved → shipped)
• Manage inventory constraints: Ensure quantity changes respect stock levels, daily limits, and contractual obligations
• Implement approval workflows: Require different validation rules based on user roles or approval states
• Guard critical fields: Prevent invalid updates to prices, quantities, or statuses that could break business logic
• Maintain data integrity: Ensure models maintain valid states throughout their lifecycle

Real-World Examples

• E-commerce order management with complex status transitions
• Inventory systems with minimum/maximum stock rules
• Document approval workflows with role-based validations
• Pricing systems requiring approval for discounts above certain thresholds
• Booking systems where cancellations have state-dependent rules

Requirements

• PHP 8.2 or higher
• Laravel 10.0 or higher

Installation

Install the package via composer:

Core Concepts

The package is built around three main interfaces:

BusinessRule Interface

Individual validation rules that can be conditionally applied:

FieldRuleSet Interface

Groups related business rules for a specific model field:

ModelStateGraph

Coordinates rule execution:

Quick Start

Let's start with the simplest possible example - validating a single field:

Step 1: Create a Business Rule

Step 2: Create a Field Rule Set

Step 3: Validate Your Model

Basic Usage

Multiple Rules for a Single Field

Conditional Business Rules

Rules that only apply in specific scenarios:

Validating Multiple Fields

Advanced Usage

Status Transition Rules

Control complex state machine workflows:

Conditional Rule Sets with Dependencies

Inject services and apply rules based on feature flags, user roles, or other context:

Complex Business Rules with External Dependencies

Integration with Laravel Events

You can integrate the graph into your model lifecycle using Laravel events:

Error Handling

The package provides specific exceptions for different error scenarios:

Testing

Testing Business Rules

Testing Field Rule Sets

Testing Full Validation

Best Practices

1. Keep Rules Focused and Single-Purpose

Each business rule should validate one specific concern:

2. Use supports() Efficiently

Skip expensive validation when rules don't apply:

3. Provide Clear, Actionable Violation Messages

Help users understand what went wrong and how to fix it:

4. Organize Rules by Model

Since RuleSets and Rules are tied to specific models, organize them by model for better clarity and maintainability:

This structure groups related rules by their field/concern, making it easy to find and maintain all rules for a specific field.

5. Leverage Dependency Injection

Use Laravel's container for flexibility and testability:

6. Test Thoroughly

Write tests for:

• Individual rule logic
• Rule support conditions
• Complete validation scenarios
• Edge cases and error conditions

7. Document Your State Machines

When implementing complex status transitions, document them:

Performance Considerations

• The graph only runs rules for fields that have changed (isDirty())
• Use the supports() method to skip expensive validation early
• Rules are evaluated lazily - validation stops at the first violation
• Consider caching expensive lookups within rules for the same request

Comparison with Laravel Validation

Laravel Model State Graph complements Laravel's built-in validation but serves a different purpose:

Use both together: Laravel validation for input sanitization, Model State Graph for business rule enforcement.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Security Vulnerabilities

If you've found a bug regarding security please mail [email protected] instead of using the issue tracker.

Credits

• Théo Benoit
• All Contributors

License

The MIT License (MIT). Please see License File for more information.