Rudder Static Facade

The Rudder class serves as the primary entry point for the RudderStack PHP SDK. It implements a static facade (singleton-style) that encapsulates a Client instance, providing a simplified interface for tracking events without requiring the developer to manage object instances manually.

Initialization Lifecycle

Before any tracking calls can be made, the facade must be initialized via Rudder::init(). This method configures the internal Client and performs environment validation.

Data Plane URL Normalization

The SDK handles the transition from the legacy host option to the current data_plane_url. It performs automatic normalization of the URL to ensure it includes the correct protocol based on the SSL configuration.

1. Default Host: If no URL is provided, it defaults to hosted.rudderlabs.com lib/Rudder.php22
2. Legacy Support: If host is provided in the options array, it triggers a deprecation warning but is used as the data plane destination lib/Rudder.php24-28
3. SSL/URL Handling: The handleSSL and handleUrl methods ensure the URL is well-formed.
   • handleSSL checks for a scheme (e.g., https://). If missing, it prepends https:// lib/Rudder.php216-218
   • It validates the URL using FILTER_VALIDATE_URL lib/Rudder.php220
   • It forces the protocol to http if the ssl option is explicitly set to false, otherwise it defaults to https lib/Rudder.php221-224

JSON Extension Check

The SDK requires the PHP JSON extension. Rudder::init() performs a runtime check using function_exists('json_encode') and throws a RudderException if the extension is missing lib/Rudder.php39-41

Initialization Data Flow

The following diagram illustrates the sequence of operations during the init call.

Facade Initialization Sequence

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

---

Validation Logic

The facade performs basic structural validation on payloads before delegating to the Client. This ensures that mandatory fields are present, reducing unnecessary network overhead for invalid events.

Identity Validation

Most tracking methods (track, identify, page, screen, group) require either a userId or an anonymousId. The validate method enforces this requirement lib/Rudder.php99-104

• userId: Validated to ensure it is present and not an empty string lib/Rudder.php101
• anonymousId: Validated to ensure it is not empty lib/Rudder.php102

Method-Specific Assertions

Certain methods have additional requirements:

• track: Must contain an event string lib/Rudder.php70-71
• group: Must contain a groupId lib/Rudder.php134-135
• alias: Must contain both a userId and a previousId lib/Rudder.php184-186

Validation Entity Mapping

Sources: lib/Rudder.php52-57 lib/Rudder.php82-89 lib/Rudder.php99-104

---

Delegation to Client

The Rudder facade maintains a private static instance of the Client class lib/Rudder.php9 Every tracking method follows a strict internal lifecycle:

1. Client Check: Calls checkClient() to ensure init() was previously called lib/Rudder.php82-89
2. Payload Augmentation: In methods like identify, it manually sets the type field in the message array lib/Rudder.php117
3. Validation: Executes the relevant validate or assert logic.
4. Delegation: Calls the corresponding method on the self::$client instance.

Static Interface Methods

Method	Purpose	Key Validations
track	Records actions performed by a user.	event name, userId/anonId
identify	Updates user traits.	userId/anonId
group	Associates a user with a group (e.g., organization).	groupId, userId/anonId
page	Records a page view.	userId/anonId
screen	Records a mobile screen view.	userId/anonId
alias	Links two user identities.	userId AND previousId
flush	Manually triggers the consumer to send queued events.	Client must be initialized

Sources: lib/Rudder.php67-75 lib/Rudder.php114-121 lib/Rudder.php131-139 lib/Rudder.php149-155 lib/Rudder.php165-171 lib/Rudder.php181-189 lib/Rudder.php196-201

---

Error Handling

The facade uses a custom exception class, RudderException, defined in lib/RudderException.php lib/RudderException.php7-9

Exceptions are thrown in the following scenarios:

• Initialization Failure: Missing writeKey or missing JSON extension lib/Rudder.php21 lib/Rudder.php40-41
• State Errors: Calling tracking methods before init() lib/Rudder.php88
• Validation Failures: Missing required fields in event payloads lib/Rudder.php55
• URL Formatting: Providing an invalid data_plane_url that fails filter_var validation lib/Rudder.php230

Sources: lib/Rudder.php52-57 lib/Rudder.php82-89 lib/RudderException.php1-10