Process Bundle Laravel Package

Getting Started

This is a low-adoption bundle (0 stars, no dependents), so treat the source as the documentation. Start by reading these files in order once installed:

1. README.md — usually the only usage example.
2. src/DependencyInjection/Configuration.php — the real config surface (spipu_process: root key).
3. src/Entity/Process* and src/Manager/ProcessManager* (names vary slightly by version) — the domain model you'll actually touch.
4. src/Command/ — the worker/consumer command that turns queued processes into running ones.

Install and register:

composer require spipu/process-bundle

// config/bundles.php
return [
    // ...
    Spipu\ProcessBundle\SpipuProcessBundle::class => ['all' => true],
];

If the bundle ships Doctrine entities (likely — a "process" needs persisted state), check src/Resources/config/doctrine/ and run migrations before anything else:

php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

First use case: enqueue a slow shell command (report generation, data import, PDF batch) from a controller instead of blocking the request. Create a process record through the bundle's manager, return a 202/redirect to a status page, and let the bundle's worker command pick it up.

public function startExport(ProcessManager $manager): Response
{
    $process = $manager->create('app:export', ['--since' => '2026-01-01']);
    $manager->queue($process);

    return $this->redirectToRoute('process_status', ['id' => $process->getId()]);
}

Then run the worker in a terminal (and later under Supervisor/systemd):

php bin/console spipu:process:run   # verify the exact command name in src/Command/

Implementation Patterns

Enqueue/dequeue decoupling. Don't execute a process inline in a controller. Persist the request as a process row with a status (queued/in_progress/done/error — check the actual enum/constants), then let a CLI worker own execution. This keeps HTTP fast and makes retries trivial.

Status polling. The most common integration is a status endpoint the frontend polls. Poll the process record, not the OS process:

#[Route('/process/{id}/status')]
public function status(Process $process): JsonResponse
{
    return $this->json([
        'status' => $process->getStatus(),
        'output' => $process->getOutput(),   // or a truncated tail
        'exitCode' => $process->getExitCode(),
    ]);
}

One worker, many queues. If the bundle supports prioritization or named queues in config, use them rather than adding arbitrary sleep logic. If not, tag processes with your own type column via a custom entity extension and filter in a forked worker.

Progress reporting. For long jobs, have your underlying command write progress to stdout in a parseable format (e.g. [25%]) and have the bundle's output handler pick it up. Avoid dumping megabytes into a DB TEXT column — cap the retained output and stream full logs to a file.

Symfony Messenger as a complement. If you're already on Messenger, use Messenger for scheduling/retries and this bundle only for the actual OS process lifecycle. Don't run two competing queue systems over the same table.

Admin visibility. A simple ProcessCrudController (EasyAdmin or plain Twig table) listing recent processes with status, duration, exit code, and a "retry" action covers 90% of operational needs.

Gotchas and Tips

No community safety net. With zero stars and zero dependents, there are no StackOverflow answers or third-party tutorials. Pin the version in composer.json ("spipu/process-bundle": "x.y.*"), read CHANGELOG.md, and skim the diff between the release you pin and the next one before upgrading. The 2026-10-08 release date is encouraging for maintenance but doesn't imply stability.

Process output deadlock. Classic Symfony Process pitfall: if a child writes more than the OS pipe buffer (~64 KB) and you call wait() without reading stdout/stderr, the process hangs forever. Make sure the bundle's runner uses start() + getIncrementalOutput() or sets a callback; if it doesn't, this is the first extension point you'll patch.

Timeouts are the most common support ticket. The default Symfony Process timeout is 60s. Set it explicitly per process type in your config — either the bundle exposes a timeout option or you override the Process factory. Also set the worker's own max runtime so Supervisor can recycle it.

Doctrine entity conflicts. If the bundle's mapping uses annotations/attributes and your app runs PHP 8.3+ with strict ORM versions, check for deprecation warnings. Run doctrine:schema:validate and prefer extending the bundle's repository rather than adding columns directly — otherwise a bundle update can drift your schema.

Debugging stuck workers. Add --verbose -vvv to the worker command and log the PID. ps aux | grep <pid> plus kill -QUIT on Symfony Process children (if signal support is compiled in) is often the fastest way to see where a job is blocked. If the bundle stores the PID, check whether that column is populated — if it's null, you've lost the only handle to the child.

Extension points to check early: bundle events (look for EventDispatcher calls in src/), the process factory/service you can decorate, and whether the status constants are class constants you can reference instead of hardcoded strings. Decorating the manager service is usually safer than forking the bundle.

Failure modes to guard against: unhandled exceptions leaving rows stuck in in_progress forever. Add a watchdog command that finds processes older than N minutes still in_progress whose PID is gone, and mark them error. This is a ~20-line query and it will save you a weekend.