Gearman Bundle Laravel Package

Getting Started

The package is a Symfony2-era bundle, so treat the install as a legacy integration rather than a drop-in Composer dependency. You will likely need "minimum-stability": "dev" in composer.json and a PHP runtime that matches the bundle's constraints (PHP 5.5–7.x territory). Verify that the gearman PECL extension is compiled into the PHP binary that will run your workers — without it, nothing in the bundle will connect.

Minimal path to first success:

1. Register the bundle. Add it to AppKernel::registerBundles() (new Supertag\Bundle\GearmanBundle\SupertagGearmanBundle() or the namespace the repo exposes). Symfony 3+ still tolerates this, Symfony 4+ will require manual services.yaml wiring since the bundle predates Flex.

2. Configure the server. A single config.yml block pointing at your gearmand host/port is enough to get moving:

   supertag_gearman:
       servers:
           default:
               host: 127.0.0.1
               port: 4730
   

3. Read the DI extension first. Before writing code, open DependencyInjection/ in the bundle. That is where server names, service tags, and the worker/client service definitions live — it tells you exactly what tags and arguments the bundle expects.

4. Look at Command/ next. Any gearman:status, gearman:workers, or similar console command is your best debugging window into queue depth and worker registration.

5. First use case: a single background job. Register a worker service (typically tagged, with a run() or job-callback method), start it with the bundle's worker command, then dispatch from a controller using the injected Gearman client service with doBackground().

If the bundle has no README that matches the code you cloned, stop here — the repository's own tests or Resources/config/services.xml are the real documentation.

Implementation Patterns

Worker-as-service, long-running process. The idiomatic flow is: define a Symfony service that does the work, tag it so the bundle recognises it as a gearman worker, and run it under Supervisor or systemd. Never run a worker in the same process as the web request. Keep one Supervisor program per function name so you can scale hot job types independently.

[program:gearman-image-resize]
command=php /var/www/app/console gearman:worker image_resize --env=prod
numprocs=4
autostart=true
autorestart=true

Foreground vs background dispatch. doBackground() for anything I/O-bound or slow (email, thumbnails, PDFs, third-party API calls) so the web response returns immediately. Reserve foreground/doNormal() calls for cases where the user is genuinely waiting and the latency budget is tight — otherwise a stalled queue becomes a stalled request.

Payload discipline. Send scalars or small arrays. The bundle (like most Gearman wrappers) will hand your worker whatever was serialised; large Doctrine entities with lazy associations will blow up on unserialize because the entity manager in the worker doesn't have the same session. Pass IDs, then re-fetch inside the worker.

Worker loop hygiene. Anything that mutates state — Doctrine, Monolog buffers, caches — needs to be reset between jobs. The standard pattern inside the worker's job handler is:

$em = $this->getContainer()->get('doctrine')->getManager();
// ... work ...
$em->clear();          // drop identity map between jobs
gc_collect_cycles();   // long-running processes accumulate cycles

Monitoring. Use the bundle's console commands (queue status, worker list) as the source of truth in your ops dashboard. Pair them with gearman-top or the raw gearadmin --status when you suspect the bundle's reporting is stale. If you add custom metrics, hook them into your worker loop rather than polling Gearman.

Symfony integration tips. Because the bundle predates autowiring, expect to reference services by string ID ($container->get('gearman.client') or whatever the DI alias is). If you are on Symfony 4+, copy the bundle's service definitions into your own services.yaml and drop the bundle registration entirely — you'll save yourself the legacy config loader headaches.

Testing. Wrap the client in your own thin interface so unit tests can stub dispatch without a running gearmand. Integration-test workers by calling the job handler directly with a fixture payload; don't try to spin up gearmand in CI unless you already have a containerised harness.

Gotchas and Tips

• Abandonment risk. Zero stars and a Symfony2 lineage mean you are on your own for bugs and security issues. Fork it into your org (composer.json repositories block with a VCS entry) before your first production deploy. Pin the commit SHA, not a dev branch.
• gearman PECL extension is a hard dependency. apt install php-gearman or pecl install gearman. Mismatched extension versions between web and worker hosts cause silent dispatch failures — doBackground() returns a handle even when the server rejects the payload.
• Serialization surprises. PHP's default serialisation is used by the underlying extension; if you pass objects across PHP versions (e.g. local dev PHP 7.4, prod PHP 7.2), unserialize will fail inside the worker with a cryptic __PHP_Incomplete_Class result. Stick to arrays and scalars.
• Worker crashes are invisible. gearmand will happily accept jobs with no worker attached and queue them forever. Alert on queue depth, not just on worker count. A numprocs=4 Supervisor config where all four crashed looks healthy from the supervisor side until autorestart kicks in.
• Reconnect after gearmand restart. Long-lived workers hold a socket to gearmand; when it restarts (deploys, OOM, upgrades), the worker's next work() call hangs or errors. Either let Supervisor restart the worker on any connection error, or implement an explicit reconnect with backoff.
• Memory is the classic footgun. A worker that runs for days will leak through the container, Doctrine, and Monolog. Cap the number of jobs per worker process (maxRequests-style limit) and let Supervisor recycle — this is more reliable than hoping gc_collect_cycles() catches everything.
• Config quirk: server aliases. Most bundles of this vintage let you name servers in config (default, batch, etc.) and select one per client. The alias is resolved at container compile time — if you add a server in production via env vars, clear the cache or the alias won't exist.
• Console command environment. Worker commands must run with --env=prod explicitly under Supervisor. Without it they boot in dev, where the profiler and debug toolbar middleware will slowly fill the disk and distort memory profiling.
• Extension point to favour: if the bundle's worker command is too rigid, subclass it or write your own 40-line while (true) loop around the raw GearmanWorker class. The bundle's value is the config and monitoring glue, not the loop itself — you can keep the former and replace the latter.
• Symfony version ceiling. If you've migrated to Symfony 5/6, this bundle will fight you on AppKernel-style registration and the old services.xml loader. At that point the honest move is to drop the bundle and write the two services you actually need (GearmanClient, GearmanWorker factory) against the PECL extension directly.