State Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require bastsys/state-bundle
   

   Register the bundle in config/app.php under providers:

   Bastsys\StateBundle\StateBundle::class,
   

2. Basic Usage Define a state machine for an entity (e.g., Order):

   use Bastsys\StateBundle\StateMachine;
   
   class Order
   {
       private $stateMachine;
   
       public function __construct()
       {
           $this->stateMachine = new StateMachine([
               'draft' => ['next' => 'pending'],
               'pending' => ['next' => 'processing', 'prev' => 'draft'],
               'processing' => ['next' => 'completed', 'prev' => 'pending'],
               'completed' => ['prev' => 'processing'],
           ]);
       }
   
       public function transitionToNext()
       {
           $this->stateMachine->transitionToNext();
       }
   
       public function getCurrentState()
       {
           return $this->stateMachine->getCurrentState();
       }
   }
   

3. First Use Case Validate state transitions in a controller:

   public function processOrder(Order $order)
   {
       if ($order->getCurrentState() === 'pending') {
           $order->transitionToNext(); // Moves to 'processing'
       }
   }
   

Implementation Patterns

Workflows

1. State-Driven Logic Use state checks to gate features:

   if ($order->getCurrentState() === 'completed') {
       $this->generateInvoice($order);
   }
   

2. Event-Based Transitions Trigger transitions via events (e.g., OrderProcessed):

   event(new OrderProcessed($order));
   $order->transitionToNext(); // 'processing' → 'completed'
   

3. Validation Rules Integrate with Laravel validation:

   $validator = Validator::make($request->all(), [
       'status' => Rule::in($order->stateMachine->getAllowedTransitions()),
   ]);
   

Integration Tips

• Eloquent Models Store state in a database column (e.g., status) and hydrate the StateMachine on model boot:

  protected static function boot()
  {
      parent::boot();
      static::created(function ($model) {
          $model->stateMachine = new StateMachine($model->getStates());
      });
  }
  

• API Responses Return state metadata in JSON:

  return response()->json([
      'state' => $order->getCurrentState(),
      'allowed_transitions' => $order->stateMachine->getAllowedTransitions(),
  ]);
  

• Testing Mock state transitions in unit tests:

  $order->stateMachine->setCurrentState('processing');
  $this->assertEquals('processing', $order->getCurrentState());
  

Gotchas and Tips

Pitfalls

1. State Machine Initialization

   • Issue: Forgetting to initialize the StateMachine with valid states.
   • Fix: Use a factory or model observer to ensure it’s always bootstrapped.

2. Circular Dependencies

   • Issue: States with bidirectional transitions (e.g., A ↔ B) can cause infinite loops if not handled.
   • Fix: Explicitly define next/prev without mutual recursion.

3. Database Sync

   • Issue: State changes in memory aren’t persisted.
   • Fix: Override transitionToNext() to save the model:

     public function transitionToNext()
     {
         $this->stateMachine->transitionToNext();
         $this->save(); // Persist state
     }
     

Debugging

• State Dump Log the current state machine for debugging:

  \Log::debug('State Machine:', $order->stateMachine->toArray());
  

• Transition Errors Catch InvalidTransitionException for invalid moves:

  try {
      $order->transitionToNext();
  } catch (InvalidTransitionException $e) {
      \Log::error($e->getMessage());
  }
  

Extension Points

1. Custom Transitions Extend the StateMachine class to add guards:

   class CustomStateMachine extends StateMachine
   {
       public function transitionToNext()
       {
           if (!$this->canTransition()) {
               throw new InvalidTransitionException('Custom guard failed');
           }
           parent::transitionToNext();
       }
   }
   

2. State Metadata Attach actions or callbacks to states:

   $states = [
       'draft' => [
           'next' => 'pending',
           'actions' => ['notify_admin'],
       ],
   ];
   

3. Localization Use language arrays for state names:

   $states = [
       'draft' => [
           'next' => 'pending',
           'label' => trans('states.draft'),
       ],
   ];