Queue Bundle Laravel Package

Getting Started

This is a Symfony 2-era bundle (pre-Flex), so expect manual registration rather than Composer auto-discovery.

1. Install it and pin the version — the last release was 2020-11-05:

   composer require treehouselabs/queue-bundle
   

2. Read the source before the README. With 1 star and 0 dependents, the README is thin. Open DependencyInjection/Configuration.php first — that file is the actual contract for every config key the bundle accepts (connection, driver, queue names). Then look at Resources/config/services.xml to learn the real service IDs you will inject.
3. Register the bundle in app/AppKernel.php (not bundles.php — this predates Flex):

   new TreeHouseLabs\QueueBundle\TreeHouseQueueBundle(),
   

4. Configure a driver under treehouse_queue: in config.yml. Start with the simplest available driver (in-memory or Doctrine) so you can prove the wiring before adding a real broker.
5. First end-to-end use case: from a controller, inject the producer/queue service and push a small job payload; then consume it from the console. Verify the message round-trips before wiring it into anything important.

Implementation Patterns

• Producer/consumer split. Treat the bundle as a thin transport. Keep the "what happens" in your own handler classes, and let the bundle only move serialized payloads. This makes it cheap to swap or abandon the bundle later — important given its maintenance state.
• Inject the queue service, not the container. Grab the service ID from services.xml and type-hint against the library's queue/producer interface. This keeps your code testable and decoupled from the bundle.
• Job payloads as arrays or small DTOs, JSON-serialized, with an explicit type key. Consumers then dispatch to a handler map. Avoid serializing full entities — you get stale state on consume.
• Long-running workers under Supervisor. The bundle exposes consumer console commands; run them as daemons managed by Supervisor or systemd, never from a web request. Set a sane --limit/--time-limit so workers recycle and don't leak memory.
• Fan-out for side effects. Use it for email sending, webhook retries, image processing and report generation — the classic "move slow work off the request" cases. It is not a good fit for transactional ordering or high-throughput pipelines.
• Retry with backoff in your handler, not the bundle. Most Symfony2 queue bundles lack robust dead-letter/RBAC tooling; wrap your handler in a try/catch that re-publishes with an incremented attempt counter and gives up after N tries.
• Integration tip: register an event subscriber that pushes jobs from domain events. Your application code emits an event and never imports the queue bundle directly, so if you migrate to Symfony Messenger later the change is localized.

Gotchas and Tips

• This is effectively unmaintained. 1 star, 0 dependents, last release in 2020, and a Symfony 2 target. Budget for forking it (MIT, so you can) or replacing it. Do not build a critical path on it without a migration plan.
• No Flex recipe and no auto-discovery. Composer won't register the bundle, won't create config, and won't set up a config/packages/*.yaml file. Everything is manual, which is fine but easy to get half-wired.
• PHP/Symfony version mismatch is the first failure. The 2020 release predates modern PHP typed properties and Symfony 5/6 autowiring. If you're on a modern stack, expect to either pin old Symfony or maintain the fork yourself.
• Service ID guesswork wastes hours. The README may reference services that the XML names differently. Always confirm against Resources/config/services.xml and php bin/console debug:container treehouse.
• Config quirks around driver selection. Most queue bundles silently fall back to a default driver when the named one is misspelled. If messages vanish, log the resolved driver at boot and assert it matches what you configured.
• Serialization is the silent killer. Payloads with closures, resources, or full ORM entities will fail or produce dead jobs. Restrict to scalars/arrays and add a single serialization boundary you control — don't rely on the bundle's default serializer.
• Debugging consumers is awkward. Add structured logging with a correlation/job ID at publish time and log the same ID at consume time. When a job hangs, the log is your only breadcrumb since the bundle has no monitoring UI.
• Extension points to know: custom driver registration and service decoration. If you need retries, metrics, or dead-letter handling, decorate the producer/consumer service in services.yml rather than patching vendor code — that keeps your fork small and upgrades (if any ever land) viable.
• Watch for duplicate delivery. Without idempotency keys on the consumer side, a retry after a partial failure will double-fire side effects (duplicate emails, double charges). Make every handler idempotent before you scale workers.