SDK Configuration Reference

The RudderStack PHP SDK is initialized using the Rudder::init() static method. This method configures the global SDK behavior by passing a writeKey and an optional $options array. These configurations determine how data is batched, compressed, and transported to the RudderStack Data Plane.

Initialization Flow

When Rudder::init() is called, it performs URL normalization, handles SSL/TLS preferences, and instantiates a Client object which serves as the primary engine for event processing.

Initialization Logic Overview

Sources: lib/Rudder.php19-42 lib/Rudder.php212-232

---

Configuration Options Reference

The following table details all available keys for the $options array passed to Rudder::init(string $writeKey, array $options = []).

Name	Type	Default	Description
consumer	string	lib_curl	The transport strategy: lib_curl, fork_curl, socket, or file.
data_plane_url	string	hosted.rudderlabs.com	The destination URL for your RudderStack Data Plane.
debug	bool	false	If true, the SDK blocks for server responses and logs errors to error_log.
ssl	bool	true	Whether to use HTTPS. If false, http:// is used.
tls	bool	false	Specifically for Socket consumer: uses tls:// instead of ssl://.
compress_request	bool	true	Whether to Gzip payloads before transmission.
max_queue_size	int	10000	Maximum number of events allowed in the in-memory queue.
flush_at	int	100	Number of events to buffer before triggering an automatic flush.
flush_interval	int	10000	Milliseconds to wait between batch transmissions if the queue isn't empty.
timeout	float	0.5	Connection timeout for Socket consumer (seconds).
curl_timeout	int	0	Total timeout for lib_curl requests (0 for infinite).
curl_connecttimeout	int	300	Connect timeout for lib_curl (milliseconds).
max_item_size_bytes	int	32000	Max size for a single event (32KB).
max_queue_size_bytes	int	33554432	Max total size of the queue (32MB).
error_handler	callable	null	A function ($code, $msg) called when a request fails.
filename	string	/tmp/analytics.log	Path for the File consumer log.
filepermissions	int	0644	Octal file permissions for the log file.

Sources: README.md35-53 lib/Consumer/QueueConsumer.php16-26 lib/Consumer/Socket.php23-30

---

Consumer Transport Selection

The consumer option determines which class is instantiated by the Client. Each consumer has unique performance characteristics.

1. LibCurl (Default)

Uses the PHP ext-curl extension for synchronous HTTP requests. It supports exponential backoff and Gzip compression.

• Implementation: Rudder\Consumer\LibCurl
• Key Methods: flushBatch(array $messages) lib/Consumer/LibCurl.php18-118
• Backoff: Starts at 100ms, doubles on 429 or 5xx errors, up to 10s. lib/Consumer/LibCurl.php32-115

2. ForkCurl

Executes a curl command via exec() to send data in the background (fire-and-forget).

• Implementation: Rudder\Consumer\ForkCurl
• Mechanism: If debug is false, it appends > /dev/null 2>&1 & to the shell command. lib/Consumer/ForkCurl.php82-84
• Compression: Writes the payload to a temporary file via tempnam() and gzip before sending. lib/Consumer/ForkCurl.php33-46

3. Socket

Uses pfsockopen() for low-level TCP/IP communication.

• Implementation: Rudder\Consumer\Socket
• Parsing: Manually parses HTTP responses via parseResponse(). lib/Consumer/Socket.php187-189
• Options: Respects timeout and tls. lib/Consumer/Socket.php64-67

4. File

Logs events to a local file for later processing by a cron job or sidecar.

• Implementation: Rudder\Consumer\File
• Format: Line-delimited JSON. lib/Consumer/File.php74-75

---

Data Flow and Queue Limits

Consumers inheriting from QueueConsumer manage an internal $queue array. When enqueue() is called (via track, identify, etc.), the SDK checks several limits before adding the item.

Queue Validation and Flush Logic

Sources: lib/Consumer/QueueConsumer.php149-178 lib/Consumer/QueueConsumer.php106-131

Error Handling

If an error_handler is provided in the configuration, it is triggered by the handleError method in the base Consumer class.

• Signature: function(int $code, string $message)
• Behavior: If debug is enabled, the error is also sent to the PHP error_log().
• Trigger Sites:
  • LibCurl: On curl_error or non-200 HTTP codes. lib/Consumer/LibCurl.php81-84 lib/Consumer/LibCurl.php101
  • Socket: On pfsockopen failure or write failure. lib/Consumer/Socket.php79-82 lib/Consumer/Socket.php176
  • ForkCurl: On non-zero exec() exit codes. lib/Consumer/ForkCurl.php40-41

Sources: lib/Consumer/Consumer.php92-103