Gears Laravel Package

Getting Started

Minimal Setup

1. Installation Add via Composer:

   composer require cosmologist/gears
   

   No Laravel-specific setup is required—it’s a standalone library.

2. First Use Case Use the Gear class to create a simple state machine or workflow:

   use Cosmologist\Gears\Gear;
   
   $gear = new Gear('my_gear');
   $gear->addState('pending')
        ->addState('processing')
        ->addState('completed')
        ->addTransition('pending', 'processing')
        ->addTransition('processing', 'completed');
   
   $gear->setState('pending');
   $gear->transition('processing'); // Returns true/false
   

3. Where to Look First

   • Documentation: Check the GitHub README (if available) for core concepts.
   • Source: Browse src/Gear.php for state/transition logic.
   • Symfony Integration: If using Symfony, explore GearsBundle for DI/routing helpers.

Implementation Patterns

Common Workflows

1. State Machines Model business processes (e.g., order lifecycle):

   $orderGear = new Gear('order');
   $orderGear->addStates(['draft', 'submitted', 'paid', 'shipped']);
   $orderGear->addTransitions([
       ['from' => 'draft', 'to' => 'submitted'],
       ['from' => 'submitted', 'to' => 'paid'],
   ]);
   

2. Workflow Validation Enforce rules in transitions:

   $gear->addTransition('pending', 'processing', function () {
       return auth()->user()->can('process_items');
   });
   

3. Event Hooks Trigger actions on state changes:

   $gear->onStateChange(function ($oldState, $newState) {
       event(new StateChanged($oldState, $newState));
   });
   

4. Laravel Integration Store gears in a database (e.g., gears table) and hydrate them:

   $gear = Gear::fromArray($storedData);
   

5. Dependency Injection Bind Gear to Laravel’s container:

   $app->bind('gear.my_workflow', function () {
       return new Gear('my_workflow')->configure(...);
   });
   

Gotchas and Tips

Pitfalls

1. State/Transition Mismatches

   • Issue: Calling transition() with invalid states silently fails (returns false).
   • Fix: Validate transitions explicitly:

     if (!$gear->canTransition('pending', 'processing')) {
         throw new \InvalidArgumentException("Invalid transition");
     }
     

2. Circular Dependencies

   • Issue: Infinite loops if transitions reference each other.
   • Fix: Use addTransition() with guards or external validation.

3. Symfony vs. Laravel

   • Issue: GearsBundle may not work out-of-the-box in Laravel.
   • Fix: Use the standalone library or adapt Symfony components manually.

4. Serialization

   • Issue: Gears aren’t natively JSON-serializable.
   • Fix: Implement JsonSerializable or use toArray():

     $gear->toArray(); // Returns state/transitions as associative array
     

Debugging Tips

• Log State Changes:

  $gear->onStateChange(function ($old, $new) {
      \Log::debug("State changed from {$old} to {$new}");
  });
  

• Inspect Gear State:

  $gear->getState(); // Current state
  $gear->getTransitions(); // All allowed transitions
  

Extension Points

1. Custom Guards Override canTransition() to add logic:

   class CustomGear extends Gear {
       protected function canTransition($from, $to) {
           if ($from === 'pending' && $to === 'processing') {
               return $this->hasEnoughStock();
           }
           return parent::canTransition($from, $to);
       }
   }
   

2. Database Backend Extend Gear to persist to Eloquent models:

   class DatabaseGear extends Gear {
       public function save() {
           $this->model->state = $this->state;
           $this->model->save();
       }
   }
   

3. Event Dispatching Use Laravel events for broader integration:

   $gear->onStateChange(function ($old, $new) {
       event(new GearStateChanged($old, $new, $gear->getName()));
   });