# Introduction

The PHP package provides a **Queue client** that allows you to add jobs to BullMQ queues from your PHP applications. These jobs can then be processed by workers written in Node.js, Python, or Elixir.

{% hint style="info" %}
The PHP package only implements the Queue class (producer side). Workers are not included as PHP's execution model is not well-suited for long-running worker processes. Use Node.js, Python, or Elixir workers to process the jobs.
{% endhint %}

### Installation

#### Option 1: Download Release (Recommended)

Download the latest release from the [releases page](https://github.com/taskforcesh/bullmq/releases) (look for `bullmq-php-X.X.X.zip`), extract it to your project, and configure Composer:

```json
{
  "repositories": [
    {
      "type": "path",
      "url": "./bullmq-php-X.X.X"
    }
  ],
  "require": {
    "taskforcesh/bullmq-php": "*"
  }
}
```

Then run:

```bash
composer install
```

#### Option 2: Install from GitHub (Development)

For development or the latest changes, install directly from the repository:

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/taskforcesh/bullmq"
    }
  ],
  "require": {
    "taskforcesh/bullmq-php": "dev-master"
  },
  "minimum-stability": "dev",
  "prefer-stable": true
}
```

{% hint style="warning" %}
Installing from VCS requires building the Lua scripts. After `composer install`, run from the monorepo root:

```bash
yarn install && yarn build && yarn copy:lua:php
```

{% endhint %}

### Requirements

* PHP 8.1 or higher
* Redis 5.0 or higher (6.2+ recommended)
* Composer

### Get started

You can add jobs to a queue like this:

```php
<?php

use BullMQ\Queue;

$queue = new Queue('myQueue');

// Add a job with data to the queue
$job = $queue->add('myJob', ['foo' => 'bar']);

echo "Added job with ID: " . $job->id . "\n";

// Close when done
$queue->close();
```

### Job Options

You can pass various options when adding jobs:

```php
<?php

use BullMQ\Queue;

$queue = new Queue('myQueue');

// Delayed job (delay in milliseconds)
$job = $queue->add('sendEmail', $emailData, [
    'delay' => 60000, // Process after 60 seconds
]);

// Priority job (lower number = higher priority)
$job = $queue->add('urgent', $data, [
    'priority' => 1,
]);

// Job with custom ID
$job = $queue->add('processOrder', $orderData, [
    'jobId' => 'order-' . $orderId,
]);

// Job with retry settings
$job = $queue->add('flakyOperation', $data, [
    'attempts' => 3,
    'backoff' => [
        'type' => 'exponential',
        'delay' => 1000,
    ],
]);

// LIFO (Last In, First Out) - process newest jobs first
$job = $queue->add('task', $data, [
    'lifo' => true,
]);
```

### Adding Multiple Jobs

```php
<?php

$jobs = $queue->addBulk([
    ['name' => 'email', 'data' => ['to' => 'user1@example.com']],
    ['name' => 'email', 'data' => ['to' => 'user2@example.com']],
    ['name' => 'email', 'data' => ['to' => 'user3@example.com']],
]);
```

### Queue Management

```php
<?php

// Get job counts
$counts = $queue->getJobCounts();
echo "Waiting: " . $counts['waiting'] . "\n";
echo "Active: " . $counts['active'] . "\n";

// Get a specific job
$job = $queue->getJob('job-id');

// Pause/Resume the queue
$queue->pause();
$queue->resume();

// Clean old jobs
$cleaned = $queue->clean(3600000, 100, 'completed'); // 1 hour grace period
```

### Interoperability

Jobs added with the PHP client are fully compatible with BullMQ workers in:

* **Node.js** - Using the official [BullMQ](https://www.npmjs.com/package/bullmq) package
* **Python** - Using the [BullMQ Python](https://pypi.org/project/bullmq/) package
* **Elixir** - Using the [BullMQ Elixir](https://hex.pm/packages/bullmq) package

Example Node.js worker that processes jobs added from PHP:

```javascript
import { Worker } from 'bullmq';

const worker = new Worker('myQueue', async job => {
  console.log(`Processing job ${job.id} with data:`, job.data);
  // Process the job...
  return { success: true };
});
```

### Connection Options

```php
<?php

use BullMQ\Queue;

// Custom Redis connection
$queue = new Queue('myQueue', [
    'connection' => [
        'host' => 'redis.example.com',
        'port' => 6379,
        'password' => 'your-password',
    ],
]);

// Using a Redis URI
$queue = new Queue('myQueue', [
    'connection' => 'redis://user:password@localhost:6379/0',
]);

// Custom prefix
$queue = new Queue('myQueue', [
    'prefix' => 'myapp',
]);
```

### Retry and Promote Jobs

```php
<?php

// Retry all failed jobs
$queue->retryJobs([
    'count' => 100,      // Max jobs to retry per iteration (default: 1000)
    'state' => 'failed', // State to retry from: 'failed' or 'completed'
]);

// Promote all delayed jobs to waiting
$queue->promoteJobs(['count' => 100]);

// Get counts by priority
$counts = $queue->getCountsPerPriority([0, 1, 2, 3]);
```

{% hint style="warning" %}
**Note on Job Schedulers**: Repeatable/scheduled jobs (cron patterns) should be created from the Node.js side using `JobScheduler`. The PHP client is designed for adding individual jobs, not managing schedulers.
{% endhint %}

### More Information

For more details, see the [PHP README](https://github.com/taskforcesh/bullmq/tree/master/php) on GitHub.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullmq.io/php/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.