PHPackages                             androlax2/laravel-model-state-graph - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Validation & Sanitization](/categories/validation)
4. /
5. androlax2/laravel-model-state-graph

ActiveLibrary[Validation & Sanitization](/categories/validation)

androlax2/laravel-model-state-graph
===================================

A powerful state transition system for Laravel Eloquent models that provides field-level validation and business rule enforcement.

v0.1.0-alpha.0(7mo ago)11[1 PRs](https://github.com/Androlax2/laravel-model-state-graph/pulls)MITPHPPHP ^8.2CI passing

Since Oct 11Pushed 4mo agoCompare

[ Source](https://github.com/Androlax2/laravel-model-state-graph)[ Packagist](https://packagist.org/packages/androlax2/laravel-model-state-graph)[ Docs](https://github.com/androlax2/laravel-model-state-graph)[ GitHub Sponsors]()[ RSS](/packages/androlax2-laravel-model-state-graph/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (17)Versions (3)Used By (0)

Laravel Model State Graph
=========================

[](#laravel-model-state-graph)

[![Latest Version on Packagist](https://camo.githubusercontent.com/4a7251c5288b603602c8f3ea4a68f3ed369978bea266cfdb0914776198d87790/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616e64726f6c6178322f6c61726176656c2d6d6f64656c2d73746174652d67726170682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/androlax2/laravel-model-state-graph)[![GitHub Tests Action Status](https://camo.githubusercontent.com/9ee171b5527ca2e9221ebe378be0870a91da149ec6ec5be39196104175788499/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616e64726f6c6178322f6c61726176656c2d6d6f64656c2d73746174652d67726170682f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/Androlax2/laravel-model-state-graph/actions?query=workflow%3Atests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/3b2d0995785a3d4f67c3bda639a3fde3f2143336e0a96c381aa3bdf64961a2fa/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f616e64726f6c6178322f6c61726176656c2d6d6f64656c2d73746174652d67726170682f666f726d6174732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/Androlax2/laravel-model-state-graph/actions?query=workflow%3AFormats+branch%3Amain++)[![Total Downloads](https://camo.githubusercontent.com/244f2d60fb7db9a6911db8336e1dc0cbe18cae515436a4f4f87ba534aca8a346/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616e64726f6c6178322f6c61726176656c2d6d6f64656c2d73746174652d67726170682e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/androlax2/laravel-model-state-graph)

About
-----

[](#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
-----------

[](#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

[](#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
------------

[](#requirements)

- PHP 8.2 or higher
- Laravel 10.0 or higher

Installation
------------

[](#installation)

Install the package via composer:

```
composer require androlax2/laravel-model-state-graph
```

Core Concepts
-------------

[](#core-concepts)

The package is built around three main interfaces:

### BusinessRule Interface

[](#businessrule-interface)

Individual validation rules that can be conditionally applied:

```
interface BusinessRule
{
    /**
     * Determine if this rule applies to the current model state
     */
    public function supports(Model $model): bool;

    /**
     * Validate the model against this rule
     * @throws BusinessRuleViolationException
     */
    public function validate(Model $model): void;
}
```

### FieldRuleSet Interface

[](#fieldruleset-interface)

Groups related business rules for a specific model field:

```
interface FieldRuleSet
{
    /**
     * The field name this rule set validates
     */
    public function getField(): string;

    /**
     * All business rules for this field
     * @return BusinessRule[]
     */
    public function getRules(): array;

    /**
     * Determine if this rule set should run for the current model state
     */
    public function supports(Model $model): bool;
}
```

### ModelStateGraph

[](#modelstategraph)

Coordinates rule execution:

```
$graph = ModelStateGraph::for(Product::class)
    ->addFieldRuleSet(new QuantityRuleSet())
    ->addFieldRuleSet(new PriceRuleSet());

if ($graph->isValid($model)) {
    // All rules passed
} else {
    $violations = $graph->getViolations($model);
    // Handle violations
}
```

Quick Start
-----------

[](#quick-start)

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

### Step 1: Create a Business Rule

[](#step-1-create-a-business-rule)

```