Laraflow Laravel Package

Getting Started

1. Install the package and confirm Laravel/PHP compatibility before adopting it:

   composer require szana8/laraflow
   

   Check composer.json constraints and the GitHub issues because the last release is from April 2023.

2. Look first at:

   • The package README for the exact trait name, flow base class, and artisan generator signatures.
   • Any publishable config: php artisan vendor:publish --tag=laraflow-config or the tag documented by the package.
   • The generated flow/state/transition classes and the package tests/source if the docs are thin.

3. Add the package trait to the Eloquent model that owns the workflow:

   use Szana8\LaraFlow\Traits\HasFlow; // confirm exact namespace in README
   
   class Order extends Model
   {
       use HasFlow;
   
       protected $fillable = ['status'];
   }
   

4. Ensure the model has a persisted state column, usually a string column:

   Schema::table('orders', function (Blueprint $table) {
       $table->string('status')->default('pending');
   });
   

5. Scaffold a flow with the package generator, then define states and allowed transitions in the generated class. Exact generator names vary, so use the README/source:

   php artisan make:flow OrderFlow
   

6. First use case: an order lifecycle.

   // Illustrative only — confirm exact API in the package source.
   $order->transitionTo('paid');
   $order->canTransitionTo('shipped');
   

   Start with one simple flow: pending -> paid -> shipped -> cancelled, add a guard for payment authorization, and listen to the package’s state-change event for audit logging.

Implementation Patterns

• One flow per model first. Keep the state machine small and explicit. Add a second flow only when the package’s multi-flow support and storage strategy are clear.
• Treat the flow class as the source of truth. Put allowed states, transitions, and guard wiring there. Avoid scattering transition checks across controllers, jobs, and observers.
• Use guards for business rules, not side effects. Guards should answer “may this transition run?”—payment captured, user authorized, stock available. Send emails, charge cards, and dispatch jobs from events/listeners instead.
• Wrap domain actions and transitions together. In a service/action class, perform the business operation and the state transition in one transaction:

  DB::transaction(function () use ($order) {
      $order->lockForUpdate()->find($order->id);
      // domain work
      $order->transitionTo('paid');
  });
  

• Expose transition capability to the UI/API. Use the package’s can/guard check before rendering buttons or accepting requests. Return 409 Conflict or 422 when a transition is not allowed.
• Use events for observability. Listen to state-change events to write audit rows, notify users, or dispatch follow-up jobs. Prefer DB::afterCommit() for side effects so listeners do not run before the state is safely persisted.
• Keep transition classes small and named by intent. Prefer MarkAsPaid, ShipOrder, CancelOrder over generic UpdateStatus when the package supports transition classes.
• Test the state machine explicitly. Assert:
  • initial state
  • allowed transition
  • denied transition
  • guard pass/fail behavior
  • event dispatch
  • persisted state after transition
• Use factories/seeders to create records in known states. This keeps tests and local demos predictable.
• Add query scopes for common state filters. For example, Order::where('status', 'pending') or a model scope if the package exposes state constants.
• Integrate with admin tooling by reading the flow definition. Build status dropdowns from the flow’s allowed transitions rather than duplicating state lists.

Gotchas and Tips

• Verify compatibility early. The package’s last release was 2023-04-17. Check PHP, Laravel, and Eloquent version constraints; run the test suite on your target Laravel version before committing.
• Confirm the exact API from source/tests. Documentation may be sparse. Search the package for the trait, transition methods, event class, and generator commands before writing wrappers.
• State columns are schema contracts. Renaming a state usually requires a data migration. Prefer stable machine names like pending_payment, not display labels.
• Handle null/initial state deliberately. Set a database default, model default, or creation hook. A null state can make guard and transition checks behave unexpectedly.
• Guards should be deterministic and fast. Avoid external API calls or writes inside guards. If a guard needs remote data, fetch it before attempting the transition.
• Check whether events fire before or after persistence. This affects listeners. If the package dispatches before save, use transactions/after-commit patterns carefully to avoid inconsistent audit logs.
• Concurrency is your responsibility unless documented otherwise. Two requests can attempt transitions on the same row. Use transactions plus row locking or an optimistic version column for critical workflows.
• Avoid chaining transitions inside listeners. A listener that immediately triggers another transition can create hidden workflows and recursion. Make follow-up transitions explicit in a service/job.
• Multiple flows need clear storage. If using more than one flow on a model, confirm whether the package supports separate state columns/flow names. Do not overload one status column with unrelated machines.
• Debug by logging transition attempts. Log model ID, from-state, to-state, guard result, and exception class. This makes denied transitions and missing guard registrations obvious.
• Extension points to inspect: custom transition classes, guard definitions, event listeners, publishable config, and any overridable methods on the flow class.
• Do not force LaraFlow into complex orchestration. It is a lightweight state machine. For long-running sagas, compensating actions, or multi-model workflows, use jobs, queues, and an explicit orchestration layer.