Task Bundle Laravel Package

Getting Started

• Install with composer require php-task/task-bundle. Version 4.1.0 only widens the Symfony constraint to allow ^8.0 alongside the existing 4.x-supported versions — no install steps changed.
• Register PhpTask\TaskBundle\PhpTaskBundle (or TaskBundle, check the class name in vendor/php-task/task-bundle/src) in config/bundles.php. Note: this is a Symfony bundle, not a Laravel package — there is no service provider or facade.
• Verify the runtime first: php bin/console list and look for the bundle's task command (naming varies by major version — grep vendor/php-task/task-bundle/src/Command if it isn't obvious). That command is the fastest way to confirm the bundle is wired up and discoverable.
• First use case: a single idempotent job — "reindex products", "prune stale uploads" — implemented as a service and executed from the console. Do not start with batches or nested tasks.
• Check composer show php-task/task-bundle and your PHP version before upgrading: Symfony 8 requires PHP 8.4+, so 4.1.0 is a no-op on older runtimes and only becomes relevant when you move the framework forward.

Implementation Patterns

Task as a container-managed service. Implement the task interface (PhpTask\Task\TaskInterface, or extend the provided base Task), inject your repositories/clients normally, and rely on autoconfiguration to tag it. If you disable autoconfigure, add the tag explicitly:

App\Task\ReindexProductsTask:
    tags: ['php_task.task']   # confirm the exact tag in the bundle's DI extension

Compose, don't inherit. Prefer TaskFactory to build tasks from callables for one-offs, and CollectionRunner when you need to run a set of tasks in sequence with shared progress reporting. This keeps task classes small and avoids deep inheritance trees.

Invoke from a console command. The common production pattern is your own command that pulls the runner from the container, attaches tasks, and runs them — giving you a place to add --dry-run, tenant filters, and locking:

protected function execute(InputInterface $input, OutputInterface $output): int
{
    $collection = $this->collectionRunner;
    $collection->addTask($this->taskFactory->create($this->reindexTask));
    $collection->run();
    return self::SUCCESS;
}

Progress and output. Wire the console-output progress adapter into the runner so long jobs report incrementally rather than appearing hung. Keep task-level logging inside the task, and let the runner own the bar.

Laravel-side integration. Without a Laravel provider, the practical pattern is to use the underlying php-task/task library directly and wrap the runner in an Artisan command or a queued job; bind the runner as a singleton in a service provider so tasks compose the same way they do in Symfony.

Gotchas and Tips

• Framework mismatch is the big one. This is Symfony-only. Laravel developers get value from php-task/task itself, not this bundle — plan for a thin adapter, not a drop-in.
• 4.1.0 is additive, not breaking. Symfony 8 support means the constraint moved from ^6|^7 to include ^8. Upgrading is safe, but composer update may also pull the Symfony 8 line on PHP 8.4 projects — pin framework packages if you are not ready.
• Event loop semantics. php-task is built on ReactPHP. Blocking I/O inside a task (sync HTTP, sleep, large DB loops) stalls the loop and freezes progress output. Batch your blocking work or push it into child processes.
• Task construction cost. Tasks are services; keep constructors cheap and side-effect free. Doing work in __construct gets executed on container resolution, not on run.
• Don't share mutable state across a collection. Tasks in a CollectionRunner should be independent; carrying state between them turns retries into a debugging nightmare.
• Debugging checklist: run the command with -vvv, confirm the task appears in the bundle's list command before debugging execution, and check debug:container --tag=<task-tag> to verify the service is tagged. In dev, the Symfony profiler shows the runner timeline.
• Extension points worth knowing: decorate the runner service rather than subclassing it; supply a custom progress reporter if the console bar doesn't fit (e.g. structured JSON logs for a queue worker); and keep the DI tag as the single registration mechanism so debug:container remains the source of truth.
• Locking. Nothing in the bundle prevents two overlapping runs. Add Symfony Lock (or a DB advisory lock) around anything that mutates shared state.