sentinelphp/drift

API schema drift detection and classification library

v1.0.1 2026-04-27 12:16 UTC

Requires

• php: >=8.2

Requires (Dev)

• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0 || ^12.0

GPL-3.0-or-later

• SentinelPHP Contributors

• api
• schema
• monitoring
• detection
• drift

README

API schema drift detection and classification library.

Installation

composer require sentinelphp/drift

Features

• Detect differences between expected and actual API responses
• Classify drift severity (Info, Warning, Critical)
• Compare JSON structures with detailed diff output

Usage

Drift Detection

use SentinelPHP\Drift\Detector;
use SentinelPHP\Schema\Validator;

$detector = new Detector(new Validator());

$schema = [
    'type' => 'object',
    'properties' => [
        'id' => ['type' => 'integer'],
        'name' => ['type' => 'string'],
    ],
    'required' => ['id', 'name'],
];

$actualResponse = [
    'id' => '123',  // Type changed: integer → string
    'name' => 'John',
    'extra' => true, // New field added
];

$result = $detector->detect($schema, $actualResponse);

foreach ($result->getDrifts() as $drift) {
    echo sprintf(
        "[%s] %s at %s\n",
        $drift->severity->value,
        $drift->type->value,
        $drift->path
    );
}

Severity Classification

use SentinelPHP\Drift\Classifier;
use SentinelPHP\Drift\Enum\DriftType;
use SentinelPHP\Drift\Enum\DriftSeverity;

$classifier = new Classifier();

// Field removed = Critical
$severity = $classifier->classify(DriftType::FieldRemoved, 'email', null);
// Returns: DriftSeverity::Critical

// Field added = Info
$severity = $classifier->classify(DriftType::FieldAdded, null, 'extra_field');
// Returns: DriftSeverity::Info

// Type changed (object → primitive) = Critical
$severity = $classifier->classify(DriftType::TypeChanged, 'object', 'string');
// Returns: DriftSeverity::Critical

Alert Threshold

$classifier = new Classifier(defaultThreshold: DriftSeverity::Warning);

// Check if drift should trigger an alert
if ($classifier->shouldAlert($drift->severity)) {
    // Send notification
}

// Override threshold per-check
$classifier->shouldAlert($drift->severity, DriftSeverity::Critical);

JSON Diff

use SentinelPHP\Drift\Diff\JsonDiff;

$diff = new JsonDiff();

$expected = ['id' => 1, 'name' => 'John', 'email' => '[e-mail]'];
$actual = ['id' => 1, 'name' => 'Jane', 'phone' => '555-1234'];

$result = $diff->generateDiff($expected, $actual);

echo "Added: " . count($result->added);     // phone
echo "Removed: " . count($result->removed); // email
echo "Changed: " . count($result->changed); // name

Drift Types

Type	Description	Default Severity
FieldRemoved	Required field missing	Critical
FieldAdded	New unexpected field	Info
TypeChanged	Data type mismatch	Warning/Critical
StructureChanged	Array/object structure changed	Warning

License

GPL v3 — see LICENSE for details