Weave Code
Camunda Laravel Package
laravolt/camunda
Laravel wrapper for the Camunda BPMN workflow engine. Start and manage process instances, query and complete user tasks, handle external tasks and incidents, and call the Camunda REST API through a fluent, config-driven client integrated with Laravel's service container.
Convenience Laravel HTTP client wrapper to interact with Camunda REST API.
Frequently asked questions about Camunda
- How do I install and configure laravolt/camunda in a Laravel app?
- Install it with composer require laravolt/camunda. The service provider is auto-discovered through Laravel package discovery, then you publish the config file with php artisan vendor:publish and set your Camunda REST base URL (typically http://your-host:8080/engine-rest) plus credentials in your .env file. Resolve the client from the service container or inject it into your classes. Because documentation is thin, confirm the exact config keys against the published config file and the package source before wiring it into a real application.
- Which Laravel and PHP versions does laravolt/camunda support?
- The package targets Laravel 9, 10 and 11 according to its README. Check the require block in composer.json for the exact PHP constraint before adopting it, since community packages sometimes raise minimum versions in minor releases without a written changelog. The 2.7.0 release ships no compatibility statement, so treat its supported matrix as unverified until you read the diff.
- Does laravolt/camunda work with Camunda 8 or Zeebe?
- No. This package is a wrapper around the Camunda 7 REST API under /engine-rest, which is the external task and process API of Camunda Platform 7. Camunda 8 runs on the Zeebe engine using gRPC job workers, a different protocol with different semantics, so external task code written against this package will not transfer directly. Moving to Camunda 8 means rewriting your workers, not just swapping a config value.
- How do I fetch and lock external tasks with laravolt/camunda?
- You register a worker that calls the external task fetch-and-lock endpoint with a worker id, maxTasks batch size and an async response timeout, which returns tasks locked for a fixed duration. For each task you run your PHP business logic and then report completion or failure with retry count, retry timeout and an error message. Long-running handlers are the tricky part: either keep lock duration short and extend the lock periodically or size the lock to your worst-case handler time. Verify in source which of these parameters the wrapper actually exposes.
- How should I report a BPMN business error versus a technical failure from a Laravel worker?
- These are different paths and you must keep them separate. A BPMN error signals a business exception the model handles, so the engine routes the token to an error boundary event; a technical failure reports retries and a retry timeout so the job is retried or eventually creates an incident. Mixing them either burns retries on legitimate business rejections or skips compensation paths on infrastructure problems. Check the source to confirm the wrapper exposes both the BPMN error and the failure calls before you commit a revenue-critical process.
- Are external task handlers idempotent, and what happens if a task is retried?
- External tasks are at-least-once by construction. If a lock expires while your handler is still running, another worker can pick up the same task, and any failure path with retries can re-execute your code. The wrapper cannot give you exactly-once delivery, so handlers with side effects must be idempotent using a business key, a dedupe table or an upsert. Design for this up front rather than relying on package guarantees.
- How do I configure authentication and multiple Camunda environments or tenants?
- Basic authentication against the REST API is the common setup, with credentials supplied through the published config and your .env file. Multiple connections or config entries let you point at different engines per environment, which you want for dev, staging and production rather than a single mutable base URL. If you need multi-tenancy, check the source for tenant-id support on fetch and start calls, since that is a frequent gap in community Camunda clients.
- How can I test Camunda integration code without running a real Camunda engine?
- Unit tests can bind a fake client in the container or use Laravel's HTTP fake to assert that the correct payloads go to the correct endpoints. Keep your task handler logic in plain classes so it can be tested without any engine at all. For lifecycle behavior such as lock expiry, retries and BPMN error routing, run a small integration suite against a Dockerized Camunda 7 instance. Budget one to two sprints for a proof of concept that covers these semantics.
- Is laravolt/camunda safe to run in production given Camunda 7 maintenance status?
- Camunda 7 is in end-of-maintenance, so this adapter carries implicit migration liability. It is also a single-vendor community package with a low star count, so name an internal owner and decide in advance whether you would fork it if upstream stalled. Review commit cadence, open-issue age and CI coverage across Laravel and PHP versions. Also be honest about scope: the operational cost of running the engine dwarfs the cost of the package, and a three-state status column is better served by Laravel queues plus a state machine library.
- What changed in laravolt/camunda 2.7.0, and should I upgrade?
- The 2.7.0 release publishes only a compare link between 2.6.0 and 2.7.0, with no feature list, no fix list, no breaking-change note and no compatibility statement. Treat it as an unverified minor bump until an engineer reads the actual diff and writes a short impact note. Pay particular attention to minimum PHP and Laravel bumps, renamed config keys and changed default lock or timeout values, because those alter runtime behavior without failing a build.
Weaver
How can I help you explore Laravel packages today?