Core Architecture

The RudderStack PHP SDK is designed with a layered architecture that separates the public API surface from the message processing pipeline and the underlying network transport. It utilizes a facade pattern for ease of use, a central client for message orchestration, and an abstract consumer layer for flexible data delivery.

High-Level Component Interaction

The following diagram illustrates the flow of an event from the application code through the SDK layers to the RudderStack Data Plane.

SDK Data Flow

Sources: lib/Rudder.php7-9 lib/Client.php14-16 lib/Client.php29-34

---

1. Rudder Static Facade

The Rudder class serves as the primary entry point for developers. It is a static facade that manages a singleton instance of the Client lib/Rudder.php9

Its primary responsibilities include:

• Initialization: Handling the Rudder::init() lifecycle, which includes normalizing the Data Plane URL and ensuring the environment supports JSON encoding lib/Rudder.php19-42
• Validation: Performing basic sanity checks on incoming payloads, such as ensuring a userId or anonymousId is present before passing the data deeper into the SDK lib/Rudder.php99-104
• Delegation: Mapping static method calls like Rudder::identify() or Rudder::track() to the underlying Client instance lib/Rudder.php114-121

For details on initialization logic and URL normalization, see Rudder Static Facade.

Sources: lib/Rudder.php19-42 lib/Rudder.php67-75 lib/Rudder.php99-104

---

2. Client Class

The Client class is the engine of the SDK. While the Facade handles validation, the Client handles the enrichment and routing of messages.

Key behaviors of the Client include:

• Consumer Selection: Based on the options provided during initialization, the Client instantiates the appropriate transport implementation (e.g., LibCurl, ForkCurl) lib/Client.php26-50
• Message Enrichment: The internal message() method injects critical metadata, including a unique messageId (UUID v4), a standardized ISO 8601 timestamp, and the library context (SDK version and consumer type) lib/Client.php79-105
• Pipeline Execution: Every event type (track, identify, etc.) passes through a pipeline that formats the payload before handing it to the Consumer lib/Client.php63-69

For a deep dive into the message pipeline and context injection, see Client Class.

Sources: lib/Client.php29-50 lib/Client.php79-105 lib/Client.php175-179

---

3. Consumer Abstraction

The SDK abstracts the actual delivery of data via the Consumer interface. This allows the SDK to support different performance profiles and environment constraints.

Consumer	Strategy	Best Use Case
LibCurl	Synchronous / Batched	Standard web requests where reliability is key.
ForkCurl	Asynchronous (Exec)	High-volume scripts where you don't want to wait for a network response.
Socket	Low-level TCP	Environments where curl is unavailable.
File	Local Logging	Offline processing or maximum performance with zero network overhead.

The Client maintains a mapping of these types and ensures the selected consumer implements the required Consumer base class lib/Client.php29-45

For details on transport implementations and batching logic, see Consumer Transport Layer.

Sources: lib/Client.php29-34 lib/Client.php38-41 examples/App.php52

---

4. Event Processing Lifecycle

The relationship between these entities during a standard track call is detailed below:

Sequence: Rudder::track() Lifecycle

For more information on the specific fields and payload structures for each event type, see Event Types and Payloads.

Sources: lib/Rudder.php67-75 lib/Client.php63-69 lib/Client.php79-105