Simple Workflow Bundle Laravel Package

Getting Started

• Establish what you're actually installing. Despite the Composer name, this is a Symfony bundle, not a Laravel package. There is no ServiceProvider, no auto-discovery, no config/ publishing, no facade. composer require xcentric/simple-workflow-bundle in a Laravel app will pull in Symfony DI/FrameworkBundle constraints (circa 2019, so likely Symfony 4.x era) and register nothing the Laravel container understands. The 0-star/0-dependent/no-release-since-2019 signals should be treated as a hard stop before you add it to composer.json.
• Look at the underlying library first, not the bundle. The bundle is glue around dulejankovic/simple-workflow. Read that repo's README and source before anything else — the workflow/state-machine semantics live there. In the bundle, the interesting files are:
  • SimpleWorkflowBundle.php — what, if anything, is registered/booted
  • DependencyInjection/Configuration.php and ...Extension.php — the config tree (this tells you the shape of a workflow definition)
  • Resources/config/services.* — service IDs and constructor arguments Those three tell you 90% of what the bundle does. If the extension is trivial, the bundle adds little over the library.
• Decide the integration path before writing code. Three realistic options for a Laravel team:
  1. Use symfony/workflow directly (the maintained Symfony component, works standalone in Laravel with a thin wrapper). Recommended.
  2. Use the standalone dulejankovic/simple-workflow library and wire it manually into a service provider — smaller surface, no Symfony bundle machinery.
  3. Reimplement the ~200 lines you actually need (states, transitions, guard callbacks, registry) as a Laravel-native service. Given the abandoned state of this package, this is often cheaper than maintaining a bridge.
• First use case to validate the idea: an order lifecycle — draft -> pending_payment -> paid -> shipped -> refunded, with a guard (only shipping if paid) and a side effect (send email on paid). If your need is this simple, you don't need this package; if it's more complex (parallel states, sub-workflows, marking stores), you need symfony/workflow, not this.

Implementation Patterns

• Config-as-definition, registry-as-lookup. The typical shape (in the underlying library, mirrored by the bundle's config tree) is a named workflow with places/states, transitions, and optional guards. In Laravel, model this as a config/workflows.php array and a small WorkflowManager that resolves a definition by name and applies transitions. Keep transitions pure (validate then apply) so they're testable without the framework.
• Wrap the model, don't annotate it. With no Eloquent/Doctrine listener in the bundle, drive transitions from an explicit service rather than model magic:

  $workflow->apply($order, 'ship'); // throws if guard fails
  

  This keeps the state column (status) the single source of truth and makes auditing trivial.
• Events are your integration seam. Whether you use the library's event dispatcher or Laravel's, emit workflow.transition.before/after style events (Transitioning, Transitioned) and hang side effects (mail, ledger entries, webhook dispatch) off listeners. This is the pattern that survives a library swap.
• Audit trail as a separate table. Every transition writes (subject_type, subject_id, from, to, transition, actor_id, created_at). Don't rely on the package for this; do it in your Transitioned listener. This is the part that's hard to retrofit and cheap to build up front.
• Guards as invokable classes, not closures in config. Config-file closures can't be cached/serialized reliably and are miserable to test. Use TransitionGuard classes resolved from the container, referenced by class-string in config.
• Queued work goes through the same entry point. If a job advances a workflow, it calls the same apply() service — never mutates status directly. Otherwise you'll have two code paths and the audit trail lies.
• Integration tip if you insist on the bundle: don't try to boot a Symfony DI container inside Laravel. Isolate it in a standalone bridge script/test harness only if you're evaluating the library; for production, depend on the underlying library, not the bundle.

Gotchas and Tips

• License is GPL-3.0. For a Laravel app this isn't automatically fatal (GPL obligations trigger on distribution, not SaaS use), but it is a legal review item and is a different posture from the MIT packages a Laravel team is used to. If you redistribute the product (on-prem, packaged, or a public repo), copyleft applies. Get sign-off before adopting, or choose a permissively-licensed alternative.
• Abandonware risk is the dominant risk. Last release 2019-12-23, zero stars, zero dependents. Expect PHP 8.x incompatibilities (typed properties, deprecations), Symfony version constraints that block composer update, and no fixes for anything you find. Check composer why-not output before assuming it installs on a current Laravel skeleton. A 0-dependent package also means no one has hit your edge cases for you.
• No Laravel integration means no convention support. No php artisan vendor:publish, no config caching story, no container bindings, no Octane safety guarantees. Anything stateful in the library (e.g. a registry cached per request) needs scrutiny under long-running workers.
• Config quirks are Symfony-flavored. Bundle config lives under a simple_workflow: root key, is validated by a TreeBuilder, and is cached by the Symfony kernel. Translating that to Laravel means dropping the tree builder and losing its validation — replicate validation yourself or malformed definitions fail at runtime, mid-transition.
• Debugging is print-and-pray. No Telescope integration, no structured logging hooks. Instrument the transition service yourself (log from, to, guard, actor) or you'll be grepping opaque library exceptions.
• Extension points are thin. Realistically you get: custom guards, transition listeners, and a registry of named workflows. If you need parallel states, sub-workflows, or persistence of the marking store, confirm the underlying library actually supports it before committing — don't assume the bundle's age reflects a mature feature set.
• Pin, vendor, or fork if you adopt. If after all of the above you still want it, pin an exact version, add a fork or Composer patch under your org, and write characterization tests around the transitions you rely on so a future PHP upgrade doesn't silently change semantics.