Gearman Bundle Laravel Package

Getting Started

This is a Symfony2 bundle, not a Laravel package. A Laravel developer cannot composer require it and expect it to work in a laravel app without a bridge. Before anything else, decide whether you actually need Gearman (see Gotchas), and if so, plan to run this bundle inside a small standalone Symfony kernel that your Laravel app talks to over HTTP/CLI/Redis.

Minimal steps if you go that route:

1. Install the PHP Gearman extension — this is a hard requirement:

   pecl install gearman   # verify with: php -m | grep gearman
   

   Then require the bundle in the Symfony shim:

   composer require xeops/gearman-bundle
   

2. Register it in the shim's AppKernel:

   new Xeops\GearmanBundle\XeopsGearmanBundle(),
   

3. Configure servers in config.yml:

   xeops_gearman:
       servers:
           localhost:
               host: 127.0.0.1
               port: 4730
   

4. Look first at the bundle's Console commands (gearman:worker:run, plus any gearman:job:* / status commands) — those are the main entry point. Then read the Job/Worker service definitions and the config tree.
5. First use case: define a single Job class that resizes a thumbnail or sends a transactional email, expose it as a Gearman function, and start a worker that persists it in a queue. Submit from Laravel via a tiny HTTP endpoint that calls the bundle's Gearman client service.

If you only need to submit work from Laravel, you do not need this bundle — call GearmanClient::doBackground() directly.

Implementation Patterns

Worker-per-concern. Give each job type its own worker process (image ops, mail, PDF generation). The bundle is essentially a DI + console wrapper around GearmanWorker; keep job classes single-responsibility and inject services rather than making them grab the container.

Job registration via the bundle. Jobs are registered through the bundle's config/services (historically via annotations on Job classes). Treat the job class as a thin adapter: deserialize the payload, hand off to an application service, return a status. That keeps the unit-testable logic out of the Symfony/Gearman layer.

Submit async from Laravel. Have your Laravel code push to Gearman over a bridge:

• Preferred: a small Symfony CLI/HTTP shim that owns job classes; Laravel POSTs {job, payload} to it, which calls the bundle's client service with doBackground/addTaskBackground.
• Or skip the shim and use ext-gearman directly in a Laravel service — much less coupling, since the bundle adds little beyond DI and commands.

Synchronous path for tests. Use doNormal during local development (with a gearman binary running in Docker) so you get immediate results and stack traces; switch to doBackground in production.

Deployment shape. Run workers as long-lived processes under Supervisor/systemd, one process group per job name, with graceful restart on deploy. The bundle's worker command typically loops until stopped — do not run it inside a request cycle.

Gotchas and Tips

• It's Symfony2, not Laravel. No service provider, no facades, no config/gearman.php. Expect container wiring, YAML config, and AppKernel-era Symfony assumptions. Bundling it into a Laravel app is usually more work than writing a 40-line GearmanClient wrapper.
• ext-gearman is the real dependency risk. The PECL extension has not had a stable, maintained release for modern PHP (8.x support is spotty at best). Verify php -m | grep gearman compiles against your PHP version and your base image before committing. If it doesn't build, the whole approach collapses — the bundle is a thin layer over it.
• Zero stars, zero dependents, score 0.06. Treat this as unmaintained reference code. Pin a commit or fork it. Do not expect upstream bug fixes.
• Annotation-based job config (if present in your version) pulls in doctrine/annotations and can silently not register a job if the annotation isn't picked up. Prefer explicit service/config registration where the bundle allows it.
• Worker memory. Long-running GearmanWorker loops leak memory (Doctrine connections, log handlers). Set --max-jobs (or a manual counter) and let Supervisor restart the worker; also ensure DB connections are reconnected between jobs.
• Dead payloads and JSON. Gearman sends raw strings. Standardize on JSON with a version field, and always json_decode(..., true, 512, JSON_THROW_ON_ERROR) inside a try/catch — a bad payload should return WORK_FAIL/WORK_EXCEPTION, not crash the loop.
• No built-in monitoring. Gearman has gearadmin --status/--workers; wire that into your health checks. The bundle does not give you a Horizon-style dashboard.
• Prefer Laravel-native queues. For a Laravel app, Redis + Horizon, database, or SQS gives you retries, backoff, failed-job handling, and a UI that this bundle does not. Use Gearman only if you must integrate with an existing Gearman infrastructure.
• Extension points: the client/worker services and the job base classes are the seams to subclass if you need custom serialization or retry logic — but budget time to read the bundle source, because documentation for a 0-star Symfony2 bundle is effectively the code itself.