AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-product-analytics

Add PostHog product analytics events to track user behavior. Use after implementing new features or reviewing PRs to ensure meaningful user actions are captured. Also handles initial PostHog SDK setup if not yet installed.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-product-analytics at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 62

references/EXAMPLE-php.md

PostHog php Example Project

Repository: https://github.com/PostHog/context-mill Path: example-apps/php


README.md

PostHog PHP Example - CLI Todo App

A simple command-line todo application built with plain PHP (no framework) demonstrating PostHog integration for CLIs, scripts, data pipelines, and non-web PHP applications.

Purpose

This example serves as:

  • Verification that the context-mill wizard works for plain PHP projects
  • Reference implementation of PostHog best practices for non-framework PHP code
  • Working example you can run and modify

Features Demonstrated

  • SDK initialization - Uses PostHog::init(...) once with environment-based configuration
  • Event tracking - Captures user actions with distinctId and properties
  • User identification - Associates properties with users via PostHog::identify(...)
  • Error tracking - Enables automatic PHP error tracking and manually captures handled exceptions
  • Proper flushing - Calls PostHog::flush() before CLI exit

Quick Start

1. Install Dependencies

composer install

2. Configure PostHog

# Copy environment template
cp .env.example .env

# Edit .env and add your PostHog project token
# POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
# POSTHOG_HOST=https://us.i.posthog.com

3. Run the App

# Add a todo
php todo.php add "Buy groceries"

# List all todos
php todo.php list

# Complete a todo
php todo.php complete 1

# Delete a todo
php todo.php delete 1

# Show statistics
php todo.php stats

What Gets Tracked

The app tracks these events in PostHog:

| Event | Properties | Purpose | |-------|-----------|---------| | todo_added | todo_id, todo_length, total_todos | When user adds a new todo | | todos_viewed | total_todos, completed_todos | When user lists todos | | todo_completed | todo_id, time_to_complete_hours | When user completes a todo | | todo_deleted | todo_id, was_completed | When user deletes a todo | | stats_viewed | total_todos, completed_todos, pending_todos | When user views stats | | $exception | exception details and command context | When handled errors occur |

Code Structure

example-apps/php/
├── todo.php             # Main CLI application
├── composer.json        # PHP dependencies
├── .env.example         # Environment variable template
├── .gitignore           # Git ignore rules
└── README.md            # This file

Key Implementation Patterns

1. Initialize Once

PostHog::init($projectToken, [
    'host' => $host,
    'error_tracking' => [
        'enabled' => true,
    ],
]);

2. Event Tracking Pattern

PostHog::capture([
    'distinctId' => 'user_123',
    'event' => 'event_name',
    'properties' => ['key' => 'value'],
]);

3. Identifying Users

PostHog::identify([
    'distinctId' => 'user_123',
    'properties' => ['app_language' => 'php'],
]);

4. Exception Tracking

try {
    riskyOperation();
} catch (Throwable $e) {
    PostHog::captureException($e, 'user_123', [
        'command' => 'example_command',
    ]);
}

5. Flush Before CLI Exit

PostHog::flush();

Running Without PostHog

The app works fine without PostHog configured - it simply won't track analytics. You'll see a warning message but the app continues to function normally.

Next Steps

  • Modify todo.php to experiment with PostHog tracking
  • Add new commands and track their usage
  • Explore feature flags: PostHog::isFeatureEnabled('flag-name', 'user_id')
  • Check your PostHog dashboard to see tracked events

Learn More


.env.example

# PostHog configuration
POSTHOG_PROJECT_TOKEN=phc_your_project_token_here
POSTHOG_HOST=https://us.i.posthog.com


todo.php

<?php

declare(strict_types=1);

// Simple CLI Todo App with PostHog Analytics
//
// A minimal plain PHP CLI application demonstrating PostHog integration
// for non-framework PHP projects (CLIs, scripts, data pipelines, etc.).

require __DIR__ . '/vendor/autoload.php';

use PostHog\PostHog;

const DATA_FILE = '.todo_app_php.json';

function loadEnvFile(string $path): void
{
    if (!file_exists($path)) {
        return;
    }

    foreach (file($path, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES) ?: [] as $line) {
        $line = trim($line);
        if ($line === '' || str_starts_with($line, '#') || !str_contains($line, '=')) {
            continue;
        }

        [$key, $value] = explode('=', $line, 2);
        $key = trim($key);
        $value = trim($value, " \t\n\r\0\x0B\"'");

        if ($key !== '' && getenv($key) === false) {
            putenv($key . '=' . $value);
            $_ENV[$key] = $value;
        }
    }
}

function dataFilePath(): string
{
    $home = getenv('HOME') ?: sys_get_temp_dir();
    return rtrim($home, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . DATA_FILE;
}

function initializePostHog(): bool
{
    loadEnvFile(__DIR__ . '/.env');

    $projectToken = getenv('POSTHOG_PROJECT_TOKEN');
    if (!$projectToken || str_starts_with($projectToken, 'phc_your_')) {
        echo "WARNING: PostHog not configured (POSTHOG_PROJECT_TOKEN not set)\n";
        echo "         App will work but analytics won't be tracked\n";
        return false;
    }

    PostHog::init($projectToken, [
        'host' => getenv('POSTHOG_HOST') ?: 'https://us.i.posthog.com',
        'error_tracking' => [
            'enabled' => true,
            'context_provider' => static function (array $payload): array {
                return [
                    'distinctId' => getUserId(),
                    'properties' => [
                        'app' => 'php_todo_cli',
                        'runtime' => PHP_VERSION,
                        '$exception_source' => $payload['source'] ?? null,
                    ],
                ];
            },
        ],
    ]);

    return true;
}

function getUserId(): string
{
    $path = dataFilePath();
    if (file_exists($path)) {
        $data = json_decode((string) file_get_contents($path), true);
        if (is_array($data) && isset($data['user_id'])) {
            return (string) $data['user_id'];
        }
    }

    return 'user_' . bin2hex(random_bytes(4));
}

function loadTodos(): array
{
    $path = dataFilePath();
    if (!file_exists($path)) {
        return ['user_id' => getUserId(), 'todos' => []];
    }

    $data = json_decode((string) file_get_contents($path), true);
    if (!is_array($data)) {
        return ['user_id' => getUserId(), 'todos' => []];
    }

    $data['todos'] = $data['todos'] ?? [];
    $data['user_id'] = $data['user_id'] ?? getUserId();
    return $data;
}

function saveTodos(array $data): void
{
    file_put_contents(dataFilePath(), json_encode($data, JSON_PRETTY_PRINT) . PHP_EOL);
}

function identifyUser(bool $posthogEnabled): void
{
    if (!$posthogEnabled) {
        return;
    }

    PostHog::identify([
        'distinctId' => getUserId(),
        'properties' => [
            'app_language' => 'php',
            'app_type' => 'cli',
        ],
    ]);
}

function trackEvent(bool $posthogEnabled, string $eventName, array $properties = []): void
{
    if (!$posthogEnabled) {
        return;
    }

    PostHog::capture([
        'distinctId' => getUserId(),
        'event' => $eventName,
        'properties' => $properties,
    ]);
}

function cmdAdd(string $text, bool $posthogEnabled): void
{
    $data = loadTodos();

    $todo = [
        'id' => count($data['todos']) + 1,
        'text' => $text,
        'completed' => false,
        'created_at' => date(DATE_ATOM),
    ];

    $data['todos'][] = $todo;
    saveTodos($data);

    echo "Added todo #{$todo['id']}: {$todo['text']}\n";

    trackEvent($posthogEnabled, 'todo_added', [
        'todo_id' => $todo['id'],
        'todo_length' => strlen($todo['text']),
        'total_todos' => count($data['todos']),
    ]);
}

function cmdList(bool $posthogEnabled): void
{
    $data = loadTodos();

    if (count($data['todos']) === 0) {
        echo "No todos yet! Add one with: php todo.php add 'Your task'\n";
        return;
    }

    echo "\nYour Todos (" . count($data['todos']) . " total):\n\n";

    foreach ($data['todos'] as $todo) {
        $status = $todo['completed'] ? 'X' : ' ';
        echo "  [{$status}] #{$todo['id']}: {$todo['text']}\n";
    }

    echo "\n";

    trackEvent($posthogEnabled, 'todos_viewed', [
        'total_todos' => count($data['todos']),
        'completed_todos' => count(array_filter($data['todos'], static fn (array $todo): bool => (bool) $todo['completed'])),
    ]);
}

function cmdComplete(int $id, bool $posthogEnabled): void
{
    $data = loadTodos();

    foreach ($data['todos'] as &$todo) {
        if ((int) $todo['id'] !== $id) {
            continue;
        }

        if ($todo['completed']) {
            echo "Todo #{$id} is already completed\n";
            return;
        }

        $todo['completed'] = true;
        $todo['completed_at'] = date(DATE_ATOM);
        saveTodos($data);

        echo "Completed todo #{$todo['id']}: {$todo['text']}\n";

        $timeToComplete = (strtotime($todo['completed_at']) - strtotime($todo['created_at'])) / 3600;
        trackEvent($posthogEnabled, 'todo_completed', [
            'todo_id' => $todo['id'],
            'time_to_complete_hours' => $timeToComplete,
        ]);
        return;
    }

    echo "ERROR: Todo #{$id} not found\n";
}

function cmdDelete(int $id, bool $posthogEnabled): void
{
    $data = loadTodos();

    foreach ($data['todos'] as $index => $todo) {
        if ((int) $todo['id'] !== $id) {
            continue;
        }

        unset($data['todos'][$index]);
        $data['todos'] = array_values($data['todos']);
        saveTodos($data);

        echo "Deleted todo #{$id}\n";

        trackEvent($posthogEnabled, 'todo_deleted', [
            'todo_id' => $todo['id'],
            'was_completed' => $todo['completed'],
        ]);
        return;
    }

    echo "ERROR: Todo #{$id} not found\n";
}

function cmdStats(bool $posthogEnabled): void
{
    $data = loadTodos();

    $total = count($data['todos']);
    $completed = count(array_filter($data['todos'], static fn (array $todo): bool => (bool) $todo['completed']));
    $pending = $total - $completed;
    $rate = $total > 0 ? number_format($completed / $total * 100, 1) : '0.0';

    echo "\nStats:\n\n";
    echo "  Total todos:     {$total}\n";
    echo "  Completed:       {$completed}\n";
    echo "  Pending:         {$pending}\n";
    echo "  Completion rate: {$rate}%\n\n";

    trackEvent($posthogEnabled, 'stats_viewed', [
        'total_todos' => $total,
        'completed_todos' => $completed,
        'pending_todos' => $pending,
    ]);
}

function printUsage(): void
{
    echo <<<USAGE
Simple todo app with PostHog analytics

Usage:
  php todo.php add "Todo text"    Add a new todo
  php todo.php list               List all todos
  php todo.php complete <id>      Mark todo as completed
  php todo.php delete <id>        Delete a todo
  php todo.php stats              Show statistics
USAGE;
}

$posthogEnabled = false;

try {
    $posthogEnabled = initializePostHog();
    identifyUser($posthogEnabled);

    $command = $argv[1] ?? null;
    if (!$command) {
        printUsage();
        exit(0);
    }

    switch ($command) {
        case 'add':
            $text = $argv[2] ?? null;
            if (!$text) {
                echo "ERROR: Please provide todo text\n";
                echo "Usage: php todo.php add \"Your task\"\n";
                exit(1);
            }
            cmdAdd($text, $posthogEnabled);
            break;

        case 'list':
            cmdList($posthogEnabled);
            break;

        case 'complete':
            $id = (int) ($argv[2] ?? 0);
            if ($id <= 0) {
                echo "ERROR: Please provide a valid todo ID\n";
                echo "Usage: php todo.php complete <id>\n";
                exit(1);
            }
            cmdComplete($id, $posthogEnabled);
            break;

        case 'delete':
            $id = (int) ($argv[2] ?? 0);
            if ($id <= 0) {
                echo "ERROR: Please provide a valid todo ID\n";
                echo "Usage: php todo.php delete <id>\n";
                exit(1);
            }
            cmdDelete($id, $posthogEnabled);
            break;

        case 'stats':
            cmdStats($posthogEnabled);
            break;

        default:
            echo "ERROR: Unknown command '{$command}'\n";
            printUsage();
            exit(1);
    }
} catch (Throwable $e) {
    echo "ERROR: {$e->getMessage()}\n";

    if ($posthogEnabled) {
        PostHog::captureException($e, getUserId(), [
            'command' => $argv[1] ?? null,
            'app' => 'php_todo_cli',
        ]);
    }

    exit(1);
} finally {
    if ($posthogEnabled) {
        PostHog::flush();
    }
}