Getting Started

Minimal Setup

Installation:

composer require --dev kwn/php-rdkafka-stubs

Add to your composer.json under autoload-dev:

"autoload-dev": {
    "files": ["vendor/kwn/php-rdkafka-stubs/stubs/rdkafka.php"]
}

Run composer dump-autoload.

Verify Compatibility: Check your php-rdkafka version with:
```
php -m | grep rdkafka
```
Ensure the stubs match your installed version (check composer.json of the stubs package).

First Use Case: Use the stubs with a simple Kafka producer/consumer:

$conf = new \RdKafka\Conf();
$conf->set('metadata.broker.list', 'localhost:9092');
$producer = new \RdKafka\Producer($conf);
$topic = $producer->newTopic('test-topic');
$topic->produce(0, 0, "Hello Kafka!");
$producer->flush(10000);

Your IDE (PHPStorm/VSCode) should now provide autocompletion and type hints for \RdKafka\* classes.

Implementation Patterns

Common Workflows

Producer Workflow:

Topic Creation: Use newTopic() with error handling:

try {
    $topic = $producer->newTopic('events');
} catch (\RdKafka\Exception $e) {
    log::error("Topic creation failed: " . $e->getMessage());
}

Async Producing: Leverage callbacks for non-blocking operations:

$producer->on('event.log', function (\RdKafka\Event $event) {
    if ($event->err) {
        error_log("Producer error: " . $event->errstr());
    }
});

Consumer Workflow:

Group Management: Use newConsumer() with consumer groups:

$conf->set('group.id', 'my-group');
$consumer = new \RdKafka\Consumer($conf);
$consumer->subscribe(['test-topic']);

Polling Loop: Implement a robust polling loop with timeout:

while ($message = $consumer->consume(1000)) {
    switch ($message->err) {
        case RD_KAFKA_RESP_ERR_NO_ERROR: /* Valid message */
            break;
        case RD_KAFKA_RESP_ERR__PARTITION_EOF:
            $consumer->close();
            break;
        default:
            throw new \Exception($message->errstr(), $message->err);
    }
}

Error Handling:

Global Error Listeners: Attach listeners to the producer/consumer:

$producer->on('error', function (\RdKafka\Event $event) {
    Sentry\captureException(new \Exception($event->errstr()));
});

Integration Tips

Laravel Service Providers: Bind the producer/consumer to the container for dependency injection:

$this->app->singleton(\RdKafka\Producer::class, function ($app) {
    $conf = new \RdKafka\Conf();
    $conf->set('metadata.broker.list', config('kafka.brokers'));
    return new \RdKafka\Producer($conf);
});

Configuration Management: Store Kafka configs in config/kafka.php and load them dynamically:

$conf = new \RdKafka\Conf();
foreach (config('kafka.producer') as $key => $value) {
    $conf->set($key, $value);
}

Testing: Use php-rdkafka-mock for unit testing:

composer require --dev php-rdkafka-mock

Mock producers/consumers in tests:

$mockProducer = new \RdKafka\Mock\Producer();
$this->app->instance(\RdKafka\Producer::class, $mockProducer);

Gotchas and Tips

Pitfalls

Stub Version Mismatch:
- Issue: Stubs may not align with your php-rdkafka version, causing IDE errors.
- Fix: Pin the stubs version to match your php-rdkafka version in composer.json:
```
"kwn/php-rdkafka-stubs": "dev-main#0.0.0-20260401"
```
- Debug: Run php -r "var_dump(\RdKafka\Producer::class);" to verify stubs are loaded.
IDE-Specific Quirks:
- PHPStorm: Enable "Strict typing" in Settings > PHP > Strict types for better stub utilization.
- VSCode: Ensure php.intellisense.stubs is enabled in settings.json:
```
"php.intellisense.stubs": ["vendor/kwn/php-rdkafka-stubs/stubs/rdkafka.php"]
```
Memory Leaks:
- Issue: Unclosed producers/consumers can leak resources.
- Fix: Always call close() or use __destruct():
```
public function __destruct() {
    if ($this->producer) {
        $this->producer->close();
    }
}
```
Async Callback Delays:
- Issue: Callbacks may execute after the script ends, causing silent failures.
- Fix: Use a loop to keep the script alive:
```
while (true) {
    $producer->flush(1000);
    sleep(1);
}
```

Debugging Tips

Enable Debugging: Set Kafka config for verbose output:

$conf->set('debug', 'all');
$conf->set('log_level', LOG_DEBUG);

Log Events: Attach a logger to capture all events:

$producer->on('event', function (\RdKafka\Event $event) {
    file_put_contents(
        'kafka_debug.log',
        sprintf("[%s] %s\n", $event->type, $event->str()),
        FILE_APPEND
    );
});

Check Broker Metadata: Use getMetadata() to diagnose connection issues:

$metadata = $producer->getMetadata();
if ($metadata->err) {
    throw new \Exception("Metadata error: " . $metadata->errstr());
}

Extension Points

Custom Stubs: Extend stubs for internal classes by creating a stubs/rdkafka-extended.php:

<?php
// Extend RdKafka\Producer with custom methods
class_alias(\RdKafka\Producer, \RdKafka\ProducerExtended);
class RdKafka\ProducerExtended extends \RdKafka\Producer {
    public function customMethod() {
        return "Extended!";
    }
}

Add to autoload-dev in composer.json.

Type-Safe Config: Create a wrapper class for type-safe configuration:

class KafkaConfig {
    public static function producer(array $overrides = []): \RdKafka\Conf {
        $conf = new \RdKafka\Conf();
        $defaults = [
            'metadata.broker.list' => 'localhost:9092',
            'queue.buffering.max.messages' => 100000,
        ];
        foreach (array_merge($defaults, $overrides) as $key => $value) {
            $conf->set($key, $value);
        }
        return $conf;
    }
}

Retry Logic: Implement exponential backoff for transient failures:

function produceWithRetry(\RdKafka\Producer $producer, string $topic, string $message, int $maxRetries = 3) {
    $retries = 0;
    while ($retries < $maxRetries) {
        try {
            $producer->newTopic($topic)->produce(0, 0, $message);
            return true;
        } catch (\Exception $e) {
            $retries++;
            if ($retries === $maxRetries) throw $e;
            usleep(100 * pow(2, $retries));
        }
    }
    return false;
}

Php Rdkafka Stubs Laravel Package