CLI Tools and Examples

The RudderStack PHP SDK includes a set of command-line utilities and example applications designed to help developers test their integration, replay logged events, and understand the SDK's lifecycle in various environments. These tools range from a standalone binary for sending one-off events to full-scale demonstration scripts.

Overview of Included Tools

The SDK provides three primary entry points for manual testing and utility operations:

1. bin/analytics: A CLI binary for executing tracking calls directly from the terminal bin/analytics1-4
2. examples/App.php: A comprehensive demonstration of all supported event types (track, identify, group, page, alias, screen) using environment-based configuration examples/App.php1-113
3. examples/sanity-test/Sanity.php: An integration validation script used to ensure the SDK is correctly communicating with the RudderStack Data Plane examples/sanity-test/Sanity.php1-117

System Architecture: CLI to SDK Flow

The following diagram illustrates how CLI tools and example scripts interface with the core Rudder facade and the underlying Client to dispatch events.

CLI and Example Execution Flow

Sources: bin/analytics39-84 examples/App.php45-109 examples/sanity-test/Sanity.php45-111 lib/Client.php14-16

---

bin/analytics CLI (#4.1)

The bin/analytics script is a standalone PHP executable that allows developers to send events without writing any PHP code. It utilizes getopt to parse command-line arguments and maps them to Rudder static methods bin/analytics15-29

Key Functionalities

• JSON Parsing: Includes a parse_json helper to handle complex properties or traits passed as strings bin/analytics97-104
• Short-lived Process Handling: Explicitly calls Rudder::flush() at the end of the script to ensure all events are dispatched before the process terminates bin/analytics84
• Support for All Types: Supports track, identify, page, group, and alias via the --type flag bin/analytics41-82

For detailed usage instructions and a full list of supported flags, see bin/analytics CLI.

Sources: bin/analytics1-113

---

Example Applications (#4.2)

The SDK includes several scripts in the examples/ directory that serve as both documentation and functional tests for the library's features.

Application Lifecycle and Sanity Testing

The example applications demonstrate the "Best Practice" lifecycle for the SDK:

1. Environment Loading: Using vlucas/phpdotenv to manage credentials examples/App.php11-12
2. Configuration: Tuning flush_at and selecting specific consumers (e.g., lib_curl, fork_curl) examples/App.php45-56
3. Context Injection: Manually defining dummyContext to simulate device and OS metadata examples/App.php19-34

Specialized Utilities

• SendBatchFromFile.php: A utility designed to work with the File consumer. It reads line-delimited JSON from a log file, re-constructs the payloads, and replays them to the data plane examples/SendBatchFromFile.php84-113

CLI Entity Mapping

Entity	File Path	Role
CLI Binary	bin/analytics	Quick terminal-based event dispatching.
Demo App	examples/App.php	Full lifecycle demonstration.
Sanity Check	examples/sanity-test/Sanity.php	Integration validation script.
Batch Replayer	examples/SendBatchFromFile.php	Replays events logged by the File consumer.

For a walkthrough of setting up and running these examples, see Example Applications.

Sources: examples/App.php1-113 examples/sanity-test/Sanity.php1-117 examples/SendBatchFromFile.php1-140