Workflow Extension Bundle Laravel Package

Getting Started

1. Install (Composer, no Flex recipe assumed since it has 0 dependents):

   composer require survos/workflow-extension-bundle
   

2. Register the bundle — check whether Flex added it automatically; if not, add the class (see the package's src/*Bundle.php, commonly SurvosWorkflowExtensionBundle) to config/bundles.php for all or dev environments.
3. Import routes — look for a routing file shipped in the bundle (config/routes.yaml in the package or a documented prefix like /workflows). Most admin-style bundles expose attribute-routed controllers, so verify with:

   bin/console debug:router | grep -i workflow
   

4. Look here first: the bundle's src/Controller/, templates/, and DependencyInjection/Configuration.php. These tell you the exposed routes, what data the UI needs, and which config keys exist. Do this before writing any integration code.
5. First use case: configure one workflow in config/packages/workflow.yaml (a marking store and a couple of places/transitions), open the admin route in dev, and confirm the UI reflects your workflow definition. That validates service registration, routing, and marking-store wiring in one pass.

Implementation Patterns

• Treat Symfony's workflow config as the source of truth. This bundle is an interface over framework.workflows, so define workflows, places, transitions, guards, and metadata there first; the admin UI just visualizes/drives them.
• Marking store contract matters more than the UI. Whether you use method (getMarking/setMarking) or property (marking), the subject must implement it correctly. The admin UI is the fastest way to see if state is being read/written as expected.
• Dev/testing harness pattern. Register the bundle and import its routes only in config/bundles.php under when@dev / a dev-only routes file. Use the UI to fire transitions against a real subject while developing, instead of writing throwaway controllers.
• Inspection workflow. After changing workflow config, run bin/console cache:clear (compiled container holds workflow definitions), then refresh the UI. Cross-check with bin/console workflow:dump <name> for the canonical graph.
• Integration with your own controllers. Inject the workflow registry (or WorkflowInterface per workflow) and use can()/apply() in your app code; use the bundle's UI purely for observation and manual transition testing. Keep the two paths separate so admin features don't leak into production flows.
• Subject lookup pattern. Admin UIs typically resolve subjects by class + id from route parameters; be ready to expose a subject type/id or configure a resolver if the bundle provides one.
• CI pattern. If routes/templates are only registered in dev, add a smoke test hitting the admin route in a functional test to catch broken templates after upgrades.

Gotchas and Tips

• Low maturity signal. 4 stars, 0 dependents, "READ ONLY" in the description — treat the public API as unstable. Pin the version ("survos/workflow-extension-bundle": "0.1.*" or the specific tag) and review the diff on every update.
• Package vs bundle naming. The package is workflow-extension-bundle; the bundle class/service IDs may use a different prefix (survos_workflow_extension...). Use bin/console debug:container | grep -i workflow and debug:router rather than guessing.
• Security. An admin UI that can apply transitions is a write surface. Restrict it by firewall/access_control or keep it strictly out of prod. Do not import the routes globally in config/routes.yaml without a guard.
• Cache is the #1 debugging trap. Workflow definitions are compiled into the container; stale UI after a config change almost always means a missing cache:clear.
• Marking store failures look like "no state." If the UI shows subjects in an undefined place, check the marking store type, initial marking, and that the subject is properly persisted/reloaded.
• Container/workflow name collisions. Multiple workflows on the same subject is common; verify the UI is pointed at the right workflow name, and confirm service names in debug:container when it isn't.
• Extension points. Override templates via templates/bundles/<BundleName>/... (standard Symfony bundle override), decorate services for extra behavior, and listen to workflow.<name>.transition / .guard events for hooks — but avoid patching the bundle itself, or you'll lose the change on the next composer update.
• Fallback for debugging. If the UI is too thin or broken, workflow:dump plus a small dev-only controller around the workflow registry gives you 90% of the value with zero dependency risk.