Enqueue Fs Laravel Package

Getting Started

Minimal steps:

composer require micro-module/enqueue-fs enqueue/enqueue

1. Create a spool directory that your PHP process can read/write (e.g. var/queue). This directory is your queue — messages are persisted as files.
2. Look first at the package's Context / TransportFactory classes (namespace MicroModule\EnqueueFs\...). Like every Enqueue transport, the integration surface is a trio: createContext(), createTransport(), createDestination().
3. First use case: local dev queue. Wire it wherever you'd normally put AMQP/Redis so you can run producers and workers on a laptop with zero broker install:

use Enqueue\Fs\FsConnectionFactory;

$context = (new FsConnectionFactory('file://'.__DIR__.'/var/queue'))->createContext();
$queue   = $context->createQueue('emails');

$context->createProducer()->send($queue, $context->createMessage('hello'));

⚠️ Before relying on it: this package has 0 stars, 0 dependents, and no visible release cadence beyond Oct 2024. Treat the README/source as the only authority; there is no community to lean on. Verify the exact namespace and factory signature from vendor/micro-module/enqueue-fs/src after install — do not assume from Enqueue's own enqueue/fs package, which this mirrors but is not identical to.

As of 0.10.21 the package no longer depends on enqueue/dsn; DSN parsing now comes from micro-module/dsn. Run composer show micro-module/dsn enqueue/dsn after install and confirm which DSN classes are actually autoloaded before type-hinting or extending anything DSN-related (see Gotchas).

Implementation Patterns

1. Producer/consumer split Producers write message files into the spool; consumers poll and ack() to remove them. Typical worker loop:

$consumer = $context->createConsumer($queue);
while (true) {
    if ($message = $consumer->receive(5000)) { // ms timeout
        try {
            handle($message->getBody());
            $consumer->acknowledge($message);
        } catch (\Throwable $e) {
            $consumer->reject($message, true); // requeue
        }
    }
}

2. Laravel integration Bind the Context as a singleton in a service provider; register a FsConnector alongside Laravel's queue connectors so Queue::push()/queue:work use the filesystem transport. Store the spool under storage/app/queue and add it to .gitignore and to your deploy cleanup script.

3. Symfony integration Register the transport factory as a service and expose it via enqueue.transport.fs config. Use messenger:consume-style workers or Enqueue's Client command.

4. Test isolation For unit/integration tests, point the factory at a sys_get_temp_dir() path per test case and delete it in tearDown(). This gives you realistic async behaviour (serialization, worker loop) without mocking the transport.

5. Cron-driven workers Because there's no long-lived broker connection, a one-shot worker (receive until empty, then exit) invoked by cron/systemd timer is a natural fit. Keep jobs idempotent — see gotchas.

6. Keep DSN construction in one place Now that the DSN parser is a separate MicroModule dependency (0.10.21+), centralise DSN strings in config (config/queue.php, .env) rather than building them inline across the codebase. If you later swap transports or the DSN library shifts namespaces again, you change one string instead of grepping for new FsConnectionFactory(.

Gotchas and Tips

• Concurrency and file locking. Multiple workers polling the same directory can race. Confirm the package uses atomic rename()/flock() on message files before running more than one worker. When in doubt, run a single worker per spool directory.
• Not a production broker. Filesystem queues are fine for dev, tests, and low-volume single-host jobs. You lose visibility timeouts, priorities, dead-letter semantics, and horizontal scaling. If you need any of those, use enqueue/redis or AMQP instead — the Enqueue abstractions let you swap transports without touching handler code.
• NFS / network mounts. flock, atomic renames, and file mtime behave inconsistently over NFS. Keep the spool on local disk.
• Reject/requeue loops. A poisoned message rejected with requeue=true will spin forever. Add a retry counter in the message headers or move failures to a dead/ subdirectory yourself.
• Cleanup and disk growth. Abandoned or unacked messages stay as files. Monitor the spool directory size and add a sweeper for orphans older than N times your max retry window.
• Permissions. The PHP-FPM/cli user and any cron worker must share ownership of the spool directory. A root-owned file from a misconfigured cron job will silently stall consumers.
• Debugging is genuinely nice. ls -la var/queue and cat a message file to inspect the payload — far easier than rabbitmqctl. Use this to triage stuck jobs when first integrating.
• Serialization contract. Enqueue serializes message body + properties (headers, content_type, message_id). Keep payloads JSON-serializable; avoid closures/resources. Verify round-trip in a test before wiring into business logic.
• DSN dependency swap (0.10.21). enqueue/dsn was replaced by micro-module/dsn. Two things can bite you:
  • If anything else in your tree (or your own code) pulls in enqueue/dsn, you may end up with two DSN implementations installed — different class names, same conceptual role. Don't rely on transitive enqueue/dsn being absent just because this package dropped it; check composer why enqueue/dsn.
  • Any code that type-hints Enqueue\Dsn\Dsn or catches its exception classes is now decoupled from this package's DSN parsing. Confirm whether micro-module/dsn ships a compatible/aliased type or a distinct one — a mismatch surfaces at runtime (argument type errors), not at composer install.
  • If you only pass plain DSN strings to FsConnectionFactory you're unaffected; the risk is concentrated in code that touches DSN objects directly.
• Maintenance risk. Zero dependents means no upstream bug reports to learn from. Pin the version in composer.json (e.g. "micro-module/enqueue-fs": "0.10.21" or a tight ~0.10.21 range), and if you extend it, prefer writing a thin wrapper (your own MessageBus service) rather than calling the transport directly everywhere — that gives you an escape hatch to swap to Redis/AMQP later. Given the enqueue/dsn → micro-module/dsn swap landed in a patch release, assume other dependency-level changes may arrive the same way; a loose ^0.10 constraint is riskier than it looks.
• Extension points. Enqueue's Context interface is the seam: you can decorate the transport (logging, metrics, retries) in a wrapper class without touching the package.
• Check compatibility. Confirm the package's enqueue/* version constraint matches your project's Enqueue version; the transport interface has moved between major versions and a mismatch fails at runtime, not install time. After upgrading to 0.10.21+, also run composer update --dry-run and a smoke test of FsConnectionFactory DSN parsing — that's the exact code path the dependency swap touches.