Getting Started

This page provides a step-by-step guide for integrating the RudderStack PHP SDK into your application. It covers installation via Composer, environment configuration, SDK initialization, and executing your first tracking call.

The rudder-php-sdk is designed to collect customer data from PHP applications and route it to the RudderStack data plane. It utilizes a pluggable "Consumer" architecture to handle data transmission either synchronously or asynchronously.

Installation

The SDK is distributed as a Composer package. It requires PHP 7.4 or higher composer.json20

1. Install via Composer

Run the following command in your project root:

Alternatively, if you are developing the SDK or using the provided examples, you can clone the repository and install dependencies README.md12:

2. System Requirements

The SDK relies on the following internal and external dependencies:

• ext-json: Required for payload serialization composer.json21
• ramsey/uuid: Used for generating unique messageId values for every event composer.json23
• vlucas/phpdotenv: Used for loading configuration from .env files composer.json22
• ext-curl (Suggested): Highly recommended for using the lib_curl or fork_curl consumers composer.json36
• ext-zlib (Suggested): Required if compress_request is enabled (default is true) composer.json37 README.md47

---

Configuration

The SDK requires a WRITE_KEY (to identify the source) and a DATA_PLANE_URL (the destination where events are sent).

Setting up the .env file

For security and flexibility, it is recommended to store credentials in a .env file at the root of your project. The SDK provides a template for this .env.sample1-4

Initialization Data Flow

The following diagram illustrates how configuration flows from the environment through the Rudder facade into the underlying Client.

Configuration and Initialization Flow

Sources: examples/sanity-test/Sanity.php11-56 README.md22-29

---

SDK Initialization

To start using the SDK, call the Rudder::init method. This method configures a singleton instance of the Client README.md22-28

Key Initialization Options

Option	Description	Default
data_plane_url	The URL of your RudderStack data plane.	hosted.rudderlabs.com
consumer	The transport mechanism (lib_curl, fork_curl, socket, file).	lib_curl
debug	If true, the SDK blocks until the API responds. Useful for testing.	false
ssl	Whether to use HTTPS for connections.	true
compress_request	Whether to Gzip the request payload.	true

Sources: README.md35-53

---

Making the First Tracking Call

Once initialized, you can use the Rudder static methods to send events. The most common call is track, which records an action performed by a user README.md59-65

Example: Tracking a "Signed Up" Event

Data Flow: From Call to Data Plane

This diagram shows the internal transition from a high-level track call to the serialized JSON sent by the consumer.

Event Pipeline

Sources: lib/Client.php lib/Consumer/QueueConsumer.php README.md59-65

---

Full Example (Sanity Test Pattern)

For a complete implementation reference, including Dotenv loading and multiple event types, see the logic used in the SDK's sanity test examples/sanity-test/Sanity.php44-113

Sources: examples/sanity-test/Sanity.php44-113 README.md59-65