README

Out-of-band AI API usage metering for PHP. After setup, call your provider’s HTTP API yourself, then record usage with Meter::track() (the PHP SDK does not auto-wrap HTTP clients).

Install

composer require tokentifyai/usagemeter

Optional: load .env in development (recommended):

composer require vlucas/phpdotenv

Setup

1. Environment (API key is global)

Copy .env.example to .env. The API key lives only in .env (or your deployment environment)—never in init() code.

cp .env.example .env

# .env — required
USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=your_bucket_name

2. Initialize

<?php

use UsageMeter\Tokentify;

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

// USAGEMETER_API_KEY from .env; USAGEMETER_BUCKET from argument
Tokentify::init('your_bucket_name', ['account_id', 'user_id']);

// USAGEMETER_API_KEY and USAGEMETER_BUCKET both from .env
Tokentify::init(getenv('USAGEMETER_BUCKET') ?: 'your_bucket_name', ['account_id', 'user_id']);

// Production (skip health checks after first successful setup)
Tokentify::init(getenv('USAGEMETER_BUCKET') ?: 'your_bucket_name', ['account_id', 'user_id'], [
    'verify_connection' => false,
    'verify_api_key' => false,
]);

Init parameters (API key is not accepted):

// Not supported — keep the API key in .env only:
// Tokentify::init(['api_key' => 'secret', 'bucket' => 'x', 'tracking_fields' => ['account_id', 'user_id']]);

Call init() before provider HTTP calls and Meter::track() events.

3. Launch (v0.1.1)

.env (USAGEMETER_API_KEY + USAGEMETER_BUCKET):

USAGEMETER_API_KEY=your_ingest_api_key
USAGEMETER_BUCKET=your_bucket_name

app.php:

<?php

use UsageMeter\Tokentify;
use UsageMeter\Meter;

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

Tokentify::init(getenv('USAGEMETER_BUCKET') ?: 'your_bucket_name', ['account_id', 'user_id']);
// loads .env when phpdotenv is installed; reads USAGEMETER_API_KEY and USAGEMETER_BUCKET

Meter::tag([
    'account_id' => '00000000-0000-4000-8000-000000000001',
    'user_id' => '00000000-0000-4000-8000-000000000002',
]);

$ch = curl_init('https://api.openai.com/v1/chat/completions');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_OPENAI_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'gpt-4o',
        'messages' => [['role' => 'user', 'content' => 'hi']],
    ]),
]);
$response = curl_exec($ch);
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Meter::track([
    'provider' => 'openai',
    'model' => 'gpt-4o',
    'input_tokens' => 10,
    'output_tokens' => 5,
    'http_status' => $status,
    'status' => $status >= 200 && $status < 300 ? 'success' : 'error',
]);

Meter::flush();

php app.php

4. Develop from this repo

cd tokentify-sdk-php
composer install
cp .env.example .env   # set USAGEMETER_API_KEY and USAGEMETER_BUCKET
composer test

Quick init check:

php -r "
require 'vendor/autoload.php';
use UsageMeter\Tokentify;
Tokentify::init(getenv('USAGEMETER_BUCKET') ?: 'your_bucket_name', ['account_id', 'user_id'], [
    'verify_api_key' => false,
    'load_env_file' => false,
]);
echo \"ok\n\";
"