recruiterphp/recruiter

Job Queue Manager: high performance, high volume, persistent, fault tolerant. 100% PHP/MongoDB, 100% Awesome

v5.0.0 2025-08-08 23:00 UTC

README

CI Pipeline Latest Stable Version License

A battle-tested job queue manager for PHP, with billions of jobs processed over the years in production environments.

โœจ Features

  • ๐Ÿš€ Production Ready - Billions of jobs processed over the years with proven reliability
  • ๐Ÿ”„ Advanced Retry Policies - Exponential backoff, custom strategies
  • ๐Ÿท๏ธ Multi-Queue Support - Job tagging and filtering
  • ๐Ÿ“Š Full Job History - Built-in analytics and monitoring
  • ๐Ÿ›ก๏ธ Fault Tolerant - Graceful failure handling and recovery
  • โšก High Performance - Optimized for scale with MongoDB
  • ๐Ÿณ Docker Ready - Complete development environment included
  • ๐Ÿงช Fully Tested - Comprehensive test suite with property-based testing

Requirements

  • PHP 8.4+
  • MongoDB Extension >=1.15
  • MongoDB Server 4.0+

Installation

composer require recruiterphp/recruiter

Quick Start

use Recruiter\Recruiter;
use Recruiter\Workable;
use Recruiter\WorkableBehaviour;
use MongoDB\Client;

// Create a job class
class EmailJob implements Workable
{
    use WorkableBehaviour;

    public function execute(): void
    {
        // Write your logic here
        mail(
            $this->parameters['email'],
            $this->parameters['subject'],
            $this->parameters['body']
        );
    }
}

// Connect to MongoDB
$factory = new Factory();
$db = $factory->getMongoDb(
    MongoURI::fromEnvironment(),
    $options = [],
);

// Set up Recruiter
$recruiter = new Recruiter($db);

// Schedule a job
new EmailJob([
    'email' => 'user@example.com',
    'subject' => 'Welcome!',
    'body' => 'Thanks for joining us!'
])
    ->asJobOf($recruiter)
    ->inBackground()
    ->execute();

๐Ÿข Production Heritage

Recruiter was born at Onebip in 2012, a major mobile payment platform processing millions of jobs daily. After being reengineered and open sourced in 2014, it was later adopted by EasyWelfare in 2018, with billions of jobs processed across both platforms:

  • โœ… Jobs cannot be lost (payments aren't idempotent)
  • ๐Ÿ“‹ Jobs must be traceable (for customer support)
  • โฐ Failed jobs need smart retry logic (respecting rate limits)

After billions of jobs processed in production (2012-2024) and active development until 2020, Recruiter has proven its reliability across diverse production environments. Both original platforms have since been phased out due to corporate acquisitions, but in July 2025 Recruiter received a major modernization, ensuring it continues as a proven, independent solution with over a decade of battle-tested experience.

๐Ÿš€ Development

# Clone and set up development environment
git clone https://github.com/recruiterphp/recruiter.git
cd recruiter

# Start development environment
make build && make up

# Run tests
make test

# Code quality checks
make fix-cs      # Fix code style
make phpstan     # Static analysis
make rector      # Code modernization

๐Ÿ“š Documentation

๐Ÿค Related Projects

Part of the RecruiterPHP ecosystem:

  • concurrency - MongoDB-based distributed locking
  • geezer - Tools for robust long-running processes
  • clock - Testable time handling and MongoDB integration
  • precious - Value object library
  • zeiss - Event sourcing projections