Laravel Parallel

Simple parallel processing for Laravel - Powered by AMPHP with automatic CPU detection.

Laravel Parallel provides an intuitive, Laravel-style API for true parallel processing in your applications. Built on the battle-tested amphp/parallel library, it enables you to execute CPU-intensive tasks concurrently with automatic CPU core detection and comprehensive error handling.

Features

• Intuitive API - Fluent, Laravel-style interface with method chaining
• Automatic Optimization - Detects CPU cores for optimal parallelization
• True Parallelism - Real multi-process execution, not just async/concurrent
• Rich Result Handling - Comprehensive result collection with metrics and filtering
• Laravel Integration - Works seamlessly with Octane, Horizon, and other Laravel features
• Type-Safe - PHPStan Level 8 compliant with full type coverage
• Extensible Architecture - Built on SOLID principles with clear extension points
• Production Ready - Comprehensive error handling, logging, and monitoring
• Event-Driven - Task lifecycle events for observability and monitoring

Installation

You can install the package via Composer:

Requirements

• PHP 8.2 or higher
• Laravel 11.0 or higher

Configuration (Optional)

Publish the configuration file:

This will create a config/parallel.php file where you can customize default settings.

Quick Start

Execute tasks in parallel with a simple, fluent API:

That's it! Laravel Parallel automatically detects your CPU cores and distributes work efficiently.

Usage Examples

Basic Parallel Execution

Execute multiple tasks concurrently:

Parallel Map Operation

Process collections in parallel:

Configuration

Customize worker count and timeout:

Real-World Example: Parallel API Requests

Fetch multiple API endpoints simultaneously:

Configuration

The package works out-of-the-box with sensible defaults. You can customize behavior via the config file or environment variables:

See the full configuration file for all options and detailed descriptions.

Advanced Usage

Working with Results

The result collection provides powerful methods for handling parallel execution outcomes:

Execution Metrics

Track performance with built-in metrics:

Error Handling

Handle failures gracefully:

Event Listeners

Listen to task lifecycle events:

Integrations

Laravel Parallel integrates seamlessly with popular Laravel ecosystem tools to enhance monitoring, observability, and developer experience.

Laravel Horizon Integration

Monitor your parallel tasks in real-time through Laravel Horizon's dashboard. The Horizon integration provides:

• Automatic metrics recording for all parallel tasks
• Real-time statistics via REST API endpoints
• Dashboard tagging for easy filtering and monitoring
• Event-driven architecture with zero configuration required

The integration is included with the package and activates automatically when Laravel Horizon is detected. Simply install Horizon and start using Laravel Parallel - metrics will appear in your Horizon dashboard immediately.

Quick Start:

For detailed setup instructions, API documentation, and advanced configuration options, see the Horizon Integration Guide.

Laravel Telescope Integration

Debug and profile your parallel tasks with Laravel Telescope's powerful inspection tools. The Telescope integration provides:

• Task lifecycle tracking - Monitor when tasks start, complete, or fail
• Execution metrics - View execution times, results, and performance data
• Smart filtering - Filter tasks by status, exception type, or execution duration
• Exception debugging - Detailed stack traces and error information for failed tasks

The integration is included with the package and activates automatically when Laravel Telescope is detected. Task details appear in a dedicated "Parallel Task" section within your Telescope dashboard.

Quick Start:

For detailed setup instructions, configuration options, and debugging workflows, see the Telescope Integration Guide.

Future Integrations

Planned integrations for upcoming releases:

• Laravel Pulse - Real-time performance monitoring and alerting
• Sentry - Advanced error tracking and performance monitoring

Extending the Package

Laravel Parallel is built with extensibility in mind. You can create:

• Custom Tasks: Implement TaskContract for specialized task types
• Custom Executors: Implement ExecutorContract for alternative execution strategies
• Custom Result Handlers: Extend ResultCollection for domain-specific operations
• Middleware: Intercept task execution for logging, monitoring, etc.

Creating a Custom Task

Best Practices

1. Keep Tasks Self-Contained: Tasks should contain all data needed for execution
2. Handle Serialization: Ensure all task data is serializable
3. Resource Management: Recreate database connections and resources in worker processes
4. Error Handling: Always handle exceptions and return meaningful error information

Architecture

Laravel Parallel follows Hexagonal Architecture (Ports & Adapters) and SOLID principles for maximum maintainability and extensibility.

Key Components

• Core: Domain logic (ParallelManager, Executor, ResultCollector)
• Contracts: Interfaces for extensibility (TaskContract, ExecutorContract, etc.)
• Tasks: Executable work units with serialization support
• Workers: Worker pool management and lifecycle
• Results: Result handling with rich metrics

The package wraps the powerful amphp/parallel library with a Laravel-friendly interface.

Design Patterns

• Facade Pattern: Static access via Parallel facade
• Factory Pattern: Worker pool creation with dependency injection
• Value Object Pattern: Immutable configuration objects
• Strategy Pattern: Different task types via TaskContract
• Dependency Injection: Constructor injection throughout

Testing

Run the test suite:

Run tests with coverage:

Run static analysis:

The package maintains:

• PHPStan Level 8 compliance
• 77.5% test coverage (251 tests, 672 assertions)
• Comprehensive unit and feature tests

Performance

When to Use Laravel Parallel

Ideal For:

• CPU-bound tasks (data processing, transformations, calculations)
• Task sets with 10 or more tasks
• Tasks taking 100ms or longer each
• Immediate results needed (not background processing)
• Laravel applications prioritizing developer experience

Better Alternatives:

• Micro-tasks (<100ms): Use sequential processing
• I/O-bound operations: Use Laravel Queues or async HTTP
• Background jobs: Use Laravel Queues with horizon
• Large data payloads (>1MB): Consider streaming or chunking

Overhead Analysis

• Setup overhead: ~2-5ms per execution
• Per-task overhead: ~0.5-1ms (serialization + IPC)
• Break-even point: 10 tasks × 100ms = 1 second total work

Example Performance

Performance Tips

1. Optimal Worker Count

2. Chunk Large Datasets

3. Balance Task Size

Frequently Asked Questions

Can I use this with Laravel Octane/Swoole?

Yes! Laravel Parallel v2.0+ is fully compatible with Laravel Octane and Swoole. The package uses non-singleton bindings to prevent state leakage between requests.

How is this different from Laravel Queues?

Laravel Queues are designed for background processing with delayed execution, while Laravel Parallel is for immediate parallel execution:

• Queues: Background processing, persistent storage, delayed execution, job retries
• Parallel: Immediate execution, in-memory processing, real-time results, CPU-intensive tasks

Use queues for background jobs, use parallel processing for immediate CPU-intensive operations.

How many workers should I use?

The optimal number depends on your task type:

• CPU-bound tasks: Number of CPU cores (auto-detected by default)
• I/O-bound tasks: 2-3x CPU cores
• Mixed workloads: Start with CPU count and adjust based on monitoring

What happens if a task throws an exception?

Exceptions are caught and wrapped in a ParallelResult with isFailure() === true. Other tasks continue executing independently. You can handle failures gracefully:

Can I use database connections in parallel tasks?

Yes, but you need to be aware that each worker process has its own memory space. Database connections should be recreated within each task:

How do I retry failed tasks?

Extract failed task keys and rerun them:

Is this package production-ready?

Yes! Laravel Parallel v2.0+ is built with production in mind:

• PHPStan Level 8 compliance (maximum type safety)
• Comprehensive test coverage (77.5% with 251 tests and 672 assertions)
• Battle-tested amphp/parallel foundation
• Used in production Laravel applications
• Octane/Swoole compatible

Changelog

Please see CHANGELOG for recent changes and version history.

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Security Vulnerabilities

If you discover a security vulnerability, please email [email protected]. All security vulnerabilities will be promptly addressed.

Credits

• Giorgos Patelis
• Powered by amphp/parallel
• All contributors

License

The MIT License (MIT). Please see License File for more information.