bin/analytics CLI

The bin/analytics script is a command-line utility provided by the RudderStack PHP SDK to facilitate sending events to a RudderStack Data Plane directly from the terminal. It serves as both a functional tool for testing integrations and a reference implementation for using the SDK in short-lived PHP processes bin/analytics1-113

Overview and Purpose

The CLI tool acts as a wrapper around the Rudder static facade bin/analytics4 It allows developers to trigger various event types (track, identify, page, group, alias) by passing arguments via the command line. Because CLI executions are short-lived, the script demonstrates the critical pattern of calling flush() before the process exits to ensure all buffered events are transmitted bin/analytics84

Data Flow Diagram: CLI to Data Plane

The following diagram illustrates how command-line arguments are parsed and transformed into SDK calls.

Title: bin/analytics Execution Flow

Sources: bin/analytics15-84

Command-line Arguments

The script utilizes the PHP getopt function to handle long-form flags bin/analytics15-29

Configuration Flags

These flags are mandatory for initializing the SDK connection.

Flag	Description	Code Reference
--writeKey	The source write key from your RudderStack dashboard.	bin/analytics18
--data_plane_url	The URL of your RudderStack Data Plane.	bin/analytics19
--type	The event type: track, identify, page, group, or alias.	bin/analytics20

Event Payload Flags

These flags map to the specific fields required by different event types.

Flag	Description	Used In
--userId	The unique identifier for the user.	All types bin/analytics44-75
--event	The name of the event being tracked.	track bin/analytics45
--properties	JSON string of event properties.	track, page bin/analytics46-61
--traits	JSON string of user traits.	identify, group bin/analytics53-69
--name	The name of the page.	page bin/analytics60
--groupId	The unique ID of the group.	group bin/analytics68
--previousId	The previous identifier for aliasing.	alias bin/analytics76

Sources: bin/analytics15-29 bin/analytics41-82

Implementation Details

JSON Parsing Helper

The script includes a parse_json helper function to handle complex data structures passed via the CLI bin/analytics97-104

This function is applied to the --properties and --traits flags, allowing users to pass JSON objects from the shell (e.g., --properties '{"plan": "premium"}') which are then converted into PHP associative arrays before being passed to the SDK methods bin/analytics46-69

Lifecycle and Flushing

A critical aspect of the bin/analytics implementation is the explicit call to Rudder::flush() at the end of the script bin/analytics84

In a standard web request, the SDK might rely on the consumer's internal batching or destructors. However, in a CLI environment, the script terminates immediately after the event method is called. Without Rudder::flush(), the process might exit before the Consumer (e.g., LibCurl or Socket) has finished the network transmission.

Code Entity Map: CLI Interface to SDK Core

This diagram maps the CLI flags and logic to the underlying SDK classes and methods.

Title: CLI to SDK Entity Mapping

Sources: bin/analytics4-84 lib/Rudder.php1-180

Usage Example

To send a track event with properties:

The script will:

1. Initialize the SDK via Rudder::init bin/analytics39
2. Parse the --properties JSON string into a PHP array bin/analytics46
3. Invoke Rudder::track bin/analytics43
4. Call Rudder::flush to ensure the HTTP request is completed before the script ends bin/analytics84

Sources: bin/analytics39-84