Example Applications

This page provides a detailed walkthrough of the example applications included in the RudderStack PHP SDK. These scripts demonstrate the full event lifecycle, from initialization and environment configuration to complex event tracking and batch processing.

1. Overview of Examples

The SDK includes three primary demonstration scripts:

1. examples/App.php: A comprehensive demonstration of all supported event types (track, identify, group, page, alias, screen) using a centralized configuration examples/App.php1-113
2. examples/sanity-test/Sanity.php: An integration validation script designed to verify the SDK's connectivity with a specific data plane and consumer type examples/sanity-test/Sanity.php1-117
3. examples/SendBatchFromFile.php: A utility script for replaying logged events from the File consumer back to the RudderStack data plane examples/SendBatchFromFile.php1-140

Code Entity Space Mapping

The following diagram maps the high-level application concepts to the specific classes and methods used in the examples.

Diagram: Example Application to SDK Entity Mapping

Sources: examples/App.php45-109 lib/Client.php14-50 lib/Client.php79-105

---

2. Environment Setup and Configuration

Both App.php and Sanity.php utilize vlucas/phpdotenv to manage credentials and SDK behavior. They look for a .env file at the project root examples/App.php10-12 examples/sanity-test/Sanity.php10-12

Required Environment Variables

Variable	Purpose	Example Value
WRITE_KEY	RudderStack Source Write Key	1z...abc
DATAPLANE_URL	Your RudderStack Data Plane URL	https://hubs.rudderstack.com
CONSUMER	The transport type to use	lib_curl, fork_curl, socket, file
SSL	Enable/Disable SSL verification	true

Initialization Pattern

The examples initialize the SDK using Rudder::init(). A key configuration tuned in these examples is flush_at, which determines the batch size before the consumer sends data to the data plane examples/App.php45-56 examples/sanity-test/Sanity.php45-56

Sources: examples/App.php15-18 examples/sanity-test/Sanity.php15-18

---

3. Full Event Lifecycle (App.php)

examples/App.php demonstrates how to structure payloads for various business events. It uses a $dummyContext to show how to inject custom device and library information manually into the context object examples/App.php19-34

Context Injection Patterns

While the SDK automatically injects library metadata via Client::getDefaultContext() lib/Client.php111-123 the examples show how to provide additional telemetry such as:

• Screen details: Density, height, width examples/App.php20-24
• OS details: Name and version examples/App.php25-28
• Locale: Language settings examples/App.php29

Event Flow Logic

The script executes a sequence of calls that simulate a user journey:

1. Anonymous Track: Uses an anonymousId before the user is known examples/App.php58-67
2. Identify: Associates a userId with specific traits like email and plan type examples/App.php69-73
3. Authenticated Track: Subsequent events use the userId examples/App.php77-84
4. Alias: Links the original userId to a new identity examples/App.php99-103

Sources: examples/App.php19-109 lib/Client.php88-91

---

4. Sanity Testing (Sanity.php)

The Sanity.php script is located in examples/sanity-test/ and acts as a standalone integration test. It includes its own composer.json that requires the SDK as a dependency examples/sanity-test/composer.json13-17

Integration Validation Flow

The sanity test follows a strict sequence to ensure the consumer transport is working correctly:

1. Debug Mode: It explicitly sets 'debug' => true to allow for verbose output of transport errors examples/sanity-test/Sanity.php53
2. Flush Tuning: It sets flush_at to 7 examples/sanity-test/Sanity.php54 Since the script sends exactly 7 events (Track, Identify, Track, Group, Page, Alias, Screen), this ensures a single batch is triggered at the end of the script execution examples/sanity-test/Sanity.php60-111

Diagram: Sanity Test Execution Sequence

Sources: examples/sanity-test/Sanity.php45-113 lib/Client.php63-69

---

5. Batch Replay Utility (SendBatchFromFile.php)

This utility demonstrates how to process events stored by the File consumer. It is particularly useful for environments where synchronous network calls are prohibited.

Key Implementation Details

• File Rotation: To prevent duplicate processing, the script renames the log file to a unique name using mt_rand() before reading examples/SendBatchFromFile.php40-52
• Timestamp Reconstruction: It parses the stored timestamp and ensures it is correctly formatted for the RudderStack API examples/SendBatchFromFile.php90-92
• Manual Batching Logic: It manually calculates the byte size of the batch using mb_strlen with 8bit encoding to ensure it does not exceed the 512KB limit examples/SendBatchFromFile.php96
• Explicit Flushing: It calls Rudder::flush() manually when the batch limit is reached or the file ends examples/SendBatchFromFile.php97 examples/SendBatchFromFile.php109

Sources: examples/SendBatchFromFile.php40-113