Client Class

The Client class is the central engine of the RudderStack PHP SDK. It manages the lifecycle of event data from the moment a tracking method is called until the data is handed off to a specific consumer for transport. It is responsible for consumer instantiation, payload normalization, and enriching messages with metadata such as UUIDs and timestamps.

Consumer Instantiation

The Client constructor determines which transport mechanism to use based on the provided configuration. By default, it uses the LibCurl consumer.

Supported Consumer Mapping

The following mapping is defined in the constructor lib/Client.php29-34:

Key	Class	Description
lib_curl	Rudder\Consumer\LibCurl	Standard synchronous cURL (Default).
fork_curl	Rudder\Consumer\ForkCurl	Asynchronous via shell execution.
socket	Rudder\Consumer\Socket	Raw TCP socket connection.
file	Rudder\Consumer\File	Local log file buffering.

Resolution Logic

The client resolves the consumer using these steps:

1. Check Options: Looks for the consumer key in the $options array lib/Client.php36
2. Custom Class Support: If the provided string is not a built-in key but is a valid class name extending Rudder\Consumer\Consumer, it instantiates that class lib/Client.php38-45
3. Default Fallback: If no consumer is specified, it defaults to lib_curl lib/Client.php36

Sources: lib/Client.php26-50 test/ClientTest.php15-35

---

The Message Pipeline

Every event-specific method (like track or identify) passes its payload through the internal message() pipeline. This method ensures consistency across all event types.

Implementation Flow: message()

The message() function performs the following transformations lib/Client.php79-105:

1. Default Field Initialization: Ensures the primary data container (e.g., properties or traits) exists as an object lib/Client.php81-86
2. Context Injection: Merges user-provided context with SDK-generated context lib/Client.php88-91
3. Timestamp Normalization: Formats the event time into ISO 8601 lib/Client.php93-96
4. UUID Generation: Assigns a unique messageId using ramsey/uuid lib/Client.php98-100
5. Channel Tagging: Hardcodes the channel to server lib/Client.php102

Context Injection

The SDK automatically injects a library object into the context of every message. This includes the SDK name, the current version from Version.php, and the identifier of the active consumer lib/Client.php111-123

Message ID Generation

The SDK uses the ramsey/uuid library to generate Version 4 (random) UUIDs for the messageId field, ensuring global uniqueness for every event sent to the data plane lib/Client.php175-179

Sources: lib/Client.php79-123 lib/Client.php175-179 lib/Version.php8

---

Event-Type Methods

The Client provides public methods for the six core RudderStack event types. Each method wraps the message() pipeline and delegates the final payload to the Consumer.

Method	Default Data Key	Description
track()	properties	Records actions performed by a user lib/Client.php63-69
identify()	traits	Associates a user with specific traits lib/Client.php187-193
group()	traits	Associates a user with a group/organization lib/Client.php201-207
page()	properties	Records a page view lib/Client.php215-221
screen()	properties	Records a mobile screen view lib/Client.php229-235
alias()	(None)	Re-identifies a user or merges identities lib/Client.php243-249

Diagram: Data Flow from Method to Consumer

This diagram illustrates how a call to track() moves through the Client logic into the Consumer layer.

Sources: lib/Client.php63-249

---

Timestamp Formatting

The formatTime method handles various input formats to ensure the data plane receives a valid ISO 8601 string. It specifically addresses PHP's date('u') limitation, which often fails to capture microseconds from floats lib/Client.php132-134

1. Integer Inputs: Treated as Unix timestamps (seconds) and formatted via date('c') lib/Client.php143-145
2. Float Inputs: Split into seconds and microseconds to manually construct a precise ISO 8601 string (e.g., Y-m-d\TH:i:s.uP) lib/Client.php157-164
3. String/Null: Strings are processed via strtotime(), while null values default to the current time() lib/Client.php140-153

Diagram: Timestamp Processing Logic

Sources: lib/Client.php138-165

---

Destruction and Flushing

The Client implements a __destruct magic method that triggers the consumer's destructor lib/Client.php52-55 This is critical for consumers that buffer events in memory (like LibCurl or Socket), as it ensures any remaining events in the queue are flushed before the PHP process exits.

Sources: lib/Client.php52-55 lib/Client.php255-261