Skip to main content

Connection Parameters

The RabbitMQ connector supports various connection parameters that can be configured via the connection URI query string. These parameters control connection behavior, timeouts, reconnection logic, and message consumption patterns.

Overview​

Connection parameters are passed as query string arguments in the connection URI:

$uri = "amqp://user:pass@host:port/vhost?param1=value1&param2=value2";

All parameters are optional and have sensible defaults for most use cases.

Available Parameters​

heartbeat​

Type: Integer Default: 30 seconds Description: Interval in seconds to send heartbeat frames to keep the connection alive during periods of inactivity.

$uri = "amqp://guest:guest@localhost:5672/?heartbeat=30";

Heartbeats are critical for detecting dead connections, especially when:

  • The network has a long idle timeout
  • The connection goes through firewalls or load balancers
  • You need to detect connection failures quickly
Recommendation

Keep the default of 30 seconds unless you have specific requirements. Lower values increase network traffic but provide faster failure detection.

connection_timeout​

Type: Integer Default: 40 seconds (fixed; it does not follow the heartbeat parameter) Description: Timeout in seconds when establishing a new connection to the RabbitMQ server.

$uri = "amqp://guest:guest@localhost:5672/?connection_timeout=10";

This parameter controls how long the client will wait when initially connecting to RabbitMQ. Set it lower if you want to fail fast, or higher if connecting over slow networks.

max_attempts​

Type: Integer Default: 10 attempts Description: Maximum number of reconnection attempts before giving up when the connection is lost.

$uri = "amqp://guest:guest@localhost:5672/?max_attempts=5";

The connector implements exponential backoff when reconnecting, with jitter:

AttemptComputed delayActual wait
11 second1s
22 seconds1–2s
34 seconds2–4s
48 seconds4–8s
516 seconds8–16s
6+30 seconds (capped)15–30s

The actual wait is randomised between half the computed delay and all of it. Without that, every consumer that lost the same broker reconnects on an identical schedule and the whole fleet arrives together on a server that has only just come back up. Half the delay is always guaranteed, so the backoff can never collapse into a tight retry loop.

Only genuine connection failures count towards this limit. A timeout elapsing without a message is not a failure and does not consume an attempt — see timeout.

warning

Setting this too low may cause the consumer to give up during temporary network issues. Setting it too high may cause excessive wait times during permanent failures.

pre_fetch​

Type: Integer Default: 0 (no limit) Description: Controls how many messages the server will deliver before requiring acknowledgements (QoS prefetch count).

$uri = "amqp://guest:guest@localhost:5672/?pre_fetch=10";

This parameter is crucial for load balancing:

  • 0: No limit - server will deliver as many messages as possible (default)
  • 1: Fair dispatch - one message at a time, ideal for even load distribution
  • N: Batch processing - deliver N messages before requiring acknowledgement

Common use cases:

// Fair dispatch: ideal when messages have variable processing time
$uri = "amqp://guest:guest@localhost:5672/?pre_fetch=1";

// Batch processing: good for consistent, fast processing
$uri = "amqp://guest:guest@localhost:5672/?pre_fetch=50";
Load Balancing

When using multiple consumers, set pre_fetch=1 to ensure even distribution of work. Without this, RabbitMQ may send all messages to one consumer.

timeout​

Type: Integer Default: 600 seconds (10 minutes) Description: Timeout in seconds for waiting for messages when consuming.

$uri = "amqp://guest:guest@localhost:5672/?timeout=60";

This parameter controls how long the wait() method will block when waiting for new messages. After the timeout elapses with no message:

  • The connection is closed and, after one second, reopened, and the consumer continues waiting
  • The reconnection does not count towards max_attempts
  • With single_run=true, consume() returns instead
Long-running Consumers

For long-running consumers, keep this at a reasonable value (60-600 seconds) to allow periodic connection health checks.

single_run​

Type: String (true/false) Default: "false" Description: When set to "true", consume() returns after the first consumption cycle ends instead of reconnecting. The cycle ends when timeout elapses with no message, when a handler returns Message::EXIT, or after a connection error (once its backoff delay has passed).

$uri = "amqp://guest:guest@localhost:5672/?single_run=true";

This is useful for:

  • Testing: Process a few messages and exit
  • Scheduled Jobs: Run the consumer via cron or scheduled tasks
  • Batch Processing: Process available messages and exit
// Continuously consume messages (default behavior)
$uri = "amqp://guest:guest@localhost:5672/?single_run=false";

// Process available messages and exit
$uri = "amqp://guest:guest@localhost:5672/?single_run=true&pre_fetch=100";

Configuration Examples​

Development Environment​

For local development with fast failure detection:

<?php
use ByJG\MessageQueueClient\Connector\ConnectorFactory;
use ByJG\Util\Uri;

$uri = "amqp://guest:guest@localhost:5672/?heartbeat=10&connection_timeout=5&timeout=30";
$connector = ConnectorFactory::create(new Uri($uri));

Production Environment​

For production with robust connection handling:

<?php
$uri = "amqp://user:[email protected]:5672/production" .
       "?heartbeat=30" .
       "&connection_timeout=10" .
       "&max_attempts=10" .
       "&timeout=60" .
       "&pre_fetch=1";

$connector = ConnectorFactory::create(new Uri($uri));

High-Throughput Consumer​

For processing large volumes of messages efficiently:

<?php
$uri = "amqp://user:[email protected]:5672/production" .
       "?heartbeat=30" .
       "&pre_fetch=100" .        // Batch processing
       "&timeout=300";           // Longer timeout for steady flow

$connector = ConnectorFactory::create(new Uri($uri));

Fair Load Balancing​

For even distribution across multiple consumers:

<?php
$uri = "amqp://user:[email protected]:5672/production" .
       "?heartbeat=30" .
       "&pre_fetch=1";           // One message at a time for fair dispatch

$connector = ConnectorFactory::create(new Uri($uri));

Scheduled/Cron Consumer​

For periodic processing via cron:

<?php
$uri = "amqp://user:[email protected]:5672/production" .
       "?single_run=true" .      // Exit after one batch
       "&pre_fetch=100" .        // Process up to 100 messages
       "&timeout=5";             // Short timeout if queue is empty

$connector = ConnectorFactory::create(new Uri($uri));

Connection Testing​

You can test the connection before starting to consume:

<?php
use ByJG\MessageQueueClient\RabbitMQ\RabbitMQConnector;
use ByJG\Util\Uri;

$connectionUri = "amqp://user:pass@host:5672/?heartbeat=30&connection_timeout=10";

$connector = new RabbitMQConnector();
$connector->setUp(new Uri($connectionUri));

if (!$connector->testConnection()) {
    die("Failed to connect to RabbitMQ server.\n");
}

echo "Connection successful!\n";

Performance Considerations​

CPU vs. I/O Bound Tasks​

CPU-bound tasks (heavy computation):

?pre_fetch=1  // Process one at a time

I/O-bound tasks (API calls, database queries):

?pre_fetch=10-50  // Process multiple in parallel

Memory Constraints​

If your messages are large or consume significant memory during processing:

?pre_fetch=1  // Prevent memory exhaustion

Network Stability​

Stable network:

?heartbeat=60&timeout=600&max_attempts=5

Unstable network:

?heartbeat=15&timeout=120&max_attempts=20

Troubleshooting​

Connection Keeps Timing Out​

// Increase connection timeout
?connection_timeout=30

Consumer Exits Unexpectedly​

// Increase max_attempts and add better reconnection handling
?max_attempts=20

Uneven Load Distribution​

// Enable fair dispatch
?pre_fetch=1

High Memory Usage​

// Reduce pre_fetch to limit in-flight messages
?pre_fetch=1

See Also​