Pokio Laravel Package

Product Decisions This Supports

• CLI Performance Optimization: Enables non-blocking parallel execution for I/O-bound Laravel Artisan commands, migrations, and scripts, reducing runtime bottlenecks (e.g., API calls, database operations) by 30–70% in local and CI environments. Ideal for data pipelines, batch processing, and testing suites.
• Debuggable Async Workflows: Allows Xdebug compatibility for parallelized CLI tools, eliminating the need to disable debugging during async development—a critical feature for teams relying on iterative CLI debugging (e.g., migrations, batch jobs).
• Incremental Async Adoption: Provides a low-risk sandbox to experiment with async patterns in Laravel <11 or monolithic applications before committing to full architecture changes (e.g., queues, Swoole). Simplifies migration to Laravel’s native async features later.
• Internal Tooling Modernization: Replaces custom scripts, Python parallelization tools, or over-engineered queues for short-lived, high-throughput tasks (e.g., CI/CD pipelines, local development scripts). The Xdebug fix reduces friction for debugging-heavy workflows.
• Use Cases:
  • Parallel Migrations: Safely run database-heavy migrations in parallel while debugging with Xdebug (e.g., schema updates, data seeding).
  • CI/CD Acceleration: Parallelize test suites (Pest, PHPUnit) or build steps (asset compilation) without Xdebug conflicts, improving pipeline reliability and speed.
  • Local Development Workflows: Run parallelized scripts locally with Xdebug enabled (e.g., API integration tests, data validation scripts).
  • Legacy Codebase Optimization: Introduce async patterns incrementally in older Laravel versions or monolithic apps without full refactoring.

When to Consider This Package

Adopt Pokio if:

• You’re optimizing CLI tools (Artisan commands, scripts) where I/O-bound operations (API calls, file I/O, database queries) are the primary bottleneck, especially in Xdebug-enabled environments.
• You need lightweight parallelism without the complexity of message queues (Redis, SQS) or process managers (Supervisor), and now with debugging support.
• Your team uses Xdebug for CLI debugging and requires parallelism without disabling debug tools (e.g., for migrations, batch jobs, or testing).
• You’re targeting PHP 8.3+ and cannot use Laravel’s native async features (e.g., in older versions or custom codebases).
• You’re okay with no production-grade guarantees (e.g., not for user-facing async APIs) and can test fallback behavior (sequential execution when PCNTL/FFI are missing or Xdebug is active).
• You need short-lived concurrency (e.g., batch processing, one-off scripts) rather than long-running processes.

Look elsewhere if:

• You require long-running processes (Pokio is designed for short-lived tasks; child processes may be killed by OS limits or memory constraints).
• You need cross-language support (Pokio is PHP-only; consider Python’s asyncio or Node.js for multi-language workflows).
• You’re building a public API or user-facing async system (use queues, Swoole, or dedicated async frameworks).
• Your environment disallows PCNTL/FFI (e.g., shared hosting, restricted servers) and you cannot tolerate sequential fallbacks.
• You need advanced features like priority queues, retries, distributed task scheduling, or stateful processes (use Laravel Queues, Symfony Messenger, or Swoole).
• You’re working with stateful processes (e.g., WebSockets, persistent connections) where forking is unsafe or unreliable.

How to Pitch It (Stakeholders)

For Executives: "Pokio enables 30–70% faster execution of CLI tools like migrations and batch jobs by leveraging parallel processing—without sacrificing debugging capabilities. For example, a 10-minute data import script could run in under 2 minutes while still allowing developers to debug with Xdebug. This directly improves developer productivity and tooling reliability, aligning with our goals to streamline workflows and reduce manual effort in data pipelines. The solution is low-risk, integrates seamlessly with existing Laravel environments, and requires no infrastructure changes."

Key Outcomes:

• Faster CLI tools: Parallelize I/O-bound tasks (e.g., API calls, DB queries) in Artisan commands.
• Debugging preserved: Use Xdebug without conflicts, reducing debugging overhead.
• No infrastructure changes: Works within existing Laravel/PHP environments.
• Low risk: Fallback to sequential execution if needed (e.g., missing PCNTL or Xdebug active).

For Engineering Teams: *"Pokio now automatically disables forking when Xdebug is in debug mode, so you can:

• Debug parallelized Artisan commands without conflicts (e.g., migrations, batch jobs).
• Use async/await in CLI tools while stepping through code with Xdebug.
• Fall back to sequential execution only when needed (e.g., missing PCNTL or Xdebug active).

Why Use It?

• Simple API: Familiar async/await syntax, similar to JavaScript promises.
• Xdebug compatibility: No more disabling debug tools to use parallelism.
• Graceful degradation: Works in all environments (local, CI, production fallbacks).
• Laravel-native: Integrates seamlessly with Artisan and Pest.

Example (Debugging a Parallel Migration):

// Runs in parallel, but Xdebug can still step through each task.
[$result1, $result2] = await([
    async(fn() => updateUserProfiles()),
    async(fn() => generateReports()),
]);

Gotchas:

• Child processes are isolated (no shared state; use shared memory or DB for coordination).
• Test fallbacks in environments without PCNTL/FFI or with Xdebug active.
• Use finally() to clean up resources (DB connections, files, locks).
• Avoid for long-running tasks (e.g., >5 minutes); use queues instead.

For Developers: *"Pokio now plays nicely with Xdebug—no more disabling debug tools to parallelize CLI work! Key changes:

• Auto-disables forking in Xdebug debug mode: Safe to debug parallelized tasks.
• Seamless fallback: If PCNTL/FFI are missing, it defaults to sequential execution.
• Promise chaining: Use then(), catch(), and finally() for async workflows.
• Invokable promises: Call promises directly with $promise() for simplicity.

Quick Start:

composer require nunomaduro/pokio

Example Use Cases:

1. Parallel Migrations:

   await([
       async(fn() => Schema::create('users')),
       async(fn() => Schema::create('posts')),
   ]);
   

2. Debuggable Batch Jobs:

   $promise = async(fn() => processLargeDataset())
       ->then(fn($result) => logResult($result))
       ->catch(fn($e) => reportError($e));
   await($promise); // Debug with Xdebug!
   

3. CI/CD Optimization:

   await([
       async(fn() => runTests('unit')),
       async(fn() => runTests('integration')),
   ]);
   

Limitations to Note:

• Not for production async APIs (use queues instead).
• Child processes are ephemeral (no persistent state).
• Requires PHP 8.3+ and may need PCNTL/FFI extensions enabled.