ForkCurl Consumer

The ForkCurl consumer provides a "fire-and-forget" asynchronous transport mechanism for the RudderStack PHP SDK. It achieves non-blocking execution by spawning a background system process using exec to run the curl command-line utility. This approach allows the PHP script to continue execution without waiting for the network round-trip to the RudderStack Data Plane.

Implementation Overview

The ForkCurl class extends QueueConsumer and implements the flushBatch method by constructing a shell command. It leverages system-level features like /dev/null redirection and backgrounding (&) to decouple the HTTP request from the main PHP process.

Data Flow and Command Construction

When flushBatch is called, the consumer performs the following steps:

1. Serialization: The message batch is encoded into a JSON string lib/Consumer/ForkCurl.php19-20
2. Sanitization: To prevent shell injection, the JSON payload and the write key (secret) are wrapped using escapeshellarg lib/Consumer/ForkCurl.php24-25
3. Payload Validation: The consumer verifies that the escaped payload size is below 512KB to ensure it stays within RudderStack's ingestion limits lib/Consumer/ForkCurl.php54-59
4. Header Construction: It adds standard headers including Content-Type, User-Agent, and optionally an AnonymousId header for single-event batches to maintain event ordering lib/Consumer/ForkCurl.php30-78

Async Execution Logic

The core of the "fire-and-forget" behavior is found in the command suffix logic. If the SDK is not in debug mode, the command is appended with > /dev/null 2>&1 & lib/Consumer/ForkCurl.php82-84 This redirects all output (stdout and stderr) to the null device and instructs the shell to run the process in the background.

ForkCurl Execution Flow

The following diagram illustrates how the ForkCurl class interacts with the operating system to dispatch events.

"ForkCurl Execution Flow"

Sources: lib/Consumer/ForkCurl.php17-105

Compression and Temporary Files

Unlike the LibCurl or Socket consumers which perform in-memory compression using gzencode, the ForkCurl consumer utilizes system-level compression when compress_request is enabled.

1. Temporary File Creation: It generates a unique temporary file using tempnam('/tmp', 'forkcurl_') lib/Consumer/ForkCurl.php35
2. Gzip Pipe: It executes a shell command to pipe the payload into gzip and redirect the output to the temporary file: echo [payload] | gzip > [tmpfile] lib/Consumer/ForkCurl.php36-37
3. Binary Data Upload: The curl command is modified to use --data-binary '@[tmpfile]' and the Content-Encoding: gzip header is added lib/Consumer/ForkCurl.php44-46
4. Cleanup: After the exec call returns (which happens immediately in background mode), the temporary file is deleted via unlink lib/Consumer/ForkCurl.php100-102

Code Entity Mapping

This table maps the conceptual "Fire-and-Forget" components to specific code implementations within lib/Consumer/ForkCurl.php.

Concept	Code Entity / Implementation	Line Reference
Batch Processing	ForkCurl::flushBatch(array $messages)	lib/Consumer/ForkCurl.php17
Shell Sanitization	escapeshellarg($payload)	lib/Consumer/ForkCurl.php24
Backgrounding	> /dev/null 2>&1 &	lib/Consumer/ForkCurl.php83
Process Spawning	exec($cmd, $output, $exit)	lib/Consumer/ForkCurl.php86
Compression	tempnam & gzip	lib/Consumer/ForkCurl.php35-36
Event Ordering	AnonymousId header (base64 encoded)	lib/Consumer/ForkCurl.php77-78

Sources: lib/Consumer/ForkCurl.php1-106

Debug Mode Behavior

The behavior of ForkCurl changes significantly when debug mode is enabled:

• Synchronous Execution: The > /dev/null 2>&1 & suffix is omitted lib/Consumer/ForkCurl.php82-84 This causes the exec call to block until the curl process completes.
• Error Capturing: The $output and $exit code from exec are captured. If the exit code is non-zero, the consumer calls handleError($exit, $output) lib/Consumer/ForkCurl.php96-98
• Logging: While the code contains commented-out var_dump statements for local debugging lib/Consumer/ForkCurl.php88-94 standard errors are logged via error_log if the payload exceeds size limits lib/Consumer/ForkCurl.php54-56

"Component Interaction Diagram"

Sources: lib/Consumer/ForkCurl.php17-105 lib/Consumer/QueueConsumer.php (inherited logic)