- What does Laravel FlowGuard actually do?
- FlowGuard adds reliability primitives to Laravel apps: idempotency keys, a durable webhook inbox, a transactional outbox, and explicit reconciliation for uncertain operations. It provides fenced delivery and bounded retries so at-least-once workflows are deduplicated and state changes commit atomically with outbound messages. It is a substrate for event and message-driven apps, not a replacement for domain state machines or saga orchestration.
- How do I install Laravel FlowGuard?
- Install with composer require mykholy/laravel-flowguard:^1.0, then run php artisan migrate to create the inbox, outbox, operation, and reconciliation tables. Run php artisan flowguard:doctor as a pre-flight check before promoting to staging or production. No data migration or fingerprint rewrite is needed for the v1.0.2 documentation and metadata release.
- Which Laravel versions does Laravel FlowGuard support?
- FlowGuard states verified support for Laravel 12 and 13. Composer will resolve the package against those framework versions, so check your app's Laravel constraint before installing. If you are on an older Laravel release, treat FlowGuard as unsupported until you upgrade or confirm compatibility yourself.
- Does FlowGuard guarantee exactly-once delivery?
- No. FlowGuard implements an at-least-once delivery contract, with the inbox deduplicating inbound webhook deliveries and the outbox making state changes and outbound messages commit atomically. Every consumer still needs to be idempotent by design, and provider-side idempotency keys should be mapped into the inbox. Exactly-once end-to-end semantics are not provided by the package.
- What does php artisan flowguard:doctor do, and how do I test a FlowGuard setup?
- The doctor command is a pre-flight gate that checks the package's expected database schema and installation state, making it useful in CI and before staging promotion. For behavior testing, exercise your idempotent handlers against duplicate webhook deliveries and verify that inbox deduplication and outbox dispatch behave as intended. Because the package supplies the durable substrate, your test suite should also cover the host-owned workflow around it.
- How does the webhook inbox deduplicate inbound webhooks?
- The inbox stores verified inbound webhook deliveries so repeated provider sends can be recognized and not reprocessed. You map the provider's idempotency key into the inbox, which makes at-least-once webhook delivery safe for your handlers. The inbox is durable and requires host-owned retention and cleanup policies.
- What is the transactional outbox and when should I use it?
- The outbox lets you commit a state change and the corresponding outbound message in the same database transaction, so the message is not lost if the process fails after the commit. A dispatch worker then publishes outbox records with bounded retries. Use it whenever an inbound webhook or command must produce a downstream side effect exactly once in practice.
- Can I roll back FlowGuard migrations after data exists?
- A populated rollback is rejected by design, and operation, inbox, outbox, and reconciliation identities must be preserved. In practice the data layer is forward-only once records exist, so treat schema decisions as effectively permanent. Plan retention and archival before you deploy to production.
- Does FlowGuard verify provider webhooks or handle tenant authentication?
- No. The integration boundary is explicitly host-owned: tenant authentication, verified webhook acceptance, provider idempotency, timeouts, approvals, downstream deduplication, and retention remain your responsibility. FlowGuard provides the durable inbox, outbox, and reconciliation substrate, not the correctness of the surrounding workflow. You should accept and verify webhooks before writing them into the inbox.
- Is v1.0.2 a safe upgrade from v1.0.1, and how should I verify it?
- v1.0.2 is a documentation and Composer discovery-metadata release with unchanged runtime code, API signatures, dependencies, and schema. Existing installs get zero functional delta, so verification effort should focus on artifact integrity, such as the immutable archive and checksum, rather than behavior. Independent security review and representative production acceptance are still open risks and should be treated as unresolved until satisfied.