PHPackages                             malikad778/php-sentinel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. malikad778/php-sentinel

ActiveLibrary[HTTP & Networking](/categories/http)

malikad778/php-sentinel
=======================

Passive API contract monitor: detects when third-party APIs silently change.

v1.0.3(3mo ago)170MITPHPPHP ^8.3CI passing

Since Feb 22Pushed 3mo agoCompare

[ Source](https://github.com/malikad778/php-sentinel)[ Packagist](https://packagist.org/packages/malikad778/php-sentinel)[ RSS](/packages/malikad778-php-sentinel/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (12)Versions (5)Used By (0)

PHP Sentinel 🛡️
===============

[](#php-sentinel-️)

[![Latest Version on Packagist](https://camo.githubusercontent.com/178c4a3146e77e394589115642c789ff719a139d7e4cf70c6d847561cad572b0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d616c696b61643737382f7068702d73656e74696e656c2e737667)](https://packagist.org/packages/malikad778/php-sentinel)[![Tests](https://github.com/malikad778/php-sentinel/actions/workflows/tests.yml/badge.svg)](https://github.com/malikad778/php-sentinel/actions/workflows/tests.yml)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](https://opensource.org/licenses/MIT)[![PHP Version Require](https://camo.githubusercontent.com/b297cf456c857f8a65af4b472317ee14d106136ce1a6d59ffdf03286659e6e3f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d616c696b61643737382f7068702d73656e74696e656c2e737667)](https://packagist.org/packages/malikad778/php-sentinel)

Passive API Contract Monitoring for strictly typed PHP 8.3+.

Sentinel silently monitors the JSON payloads returning from the third-party APIs you consume, automatically infers their structural JSON Schema, and detects when they change unexpectedly (drift).

❓ What Is It & What Does It Do?
-----------------------------------

[](#-what-is-it--what-does-it-do)

When you integrate with external REST APIs, you build your internal systems, DTOs, and mappings around the structural "contract" of their responses. But APIs change—fields become nullable, new enum values appear, or keys are dropped entirely. Usually, you don't find out until your app crashes in production.

**PHP Sentinel solves this.** It acts as a passive proxy middleware on your HTTP clients (like Guzzle).

1. **Sampling:** It watches the first *N* successful JSON responses from an endpoint and probabilistically infers the underlying JSON Schema (figuring out which fields are required, optional, null, what the enums are, and the exact nesting structure).
2. **Hardening:** After enough samples, it locks in a "Baseline Schema" and stores it.
3. **Drift Detection:** On all future requests, Sentinel compares the live response against your locked baseline. If the API adds, removes, or changes the type of any field, Sentinel instantly detects the drift.
4. **Alerting:** Sentinel logs the drift to your PSR-3 Logger (e.g., Laravel's or Symfony's logger) and dispatches a PSR-14 Event so you can alert your team via Slack, Sentry, or email *before* it breaks your app.

✨ Features
----------

[](#-features)

- **Zero-Touch Inference:** Automatically deduces deep JSON Schemas containing `types`, `nested properties`, `required/optional fields`, `enums`, and string `formats` (like UUIDs, Datetimes) just from looking at data.
- **Smart Drift Detection:** Differentiates between:
    - `BREAKING` changes (fields removed, types changed, previously non-null fields returning null)
    - `ADDITIVE` changes (new fields added)
    - `ADVISORY` changes (formats changed)
- **Framework Native Integrations:** Ships with deep auto-wiring support for **Laravel** (Service Providers & Http Macros) and **Symfony** (Bundles & Dependency Injection Extensions).
- **PSR Standard Compliant:** Integrates directly with PSR-18 (HTTP Clients), PSR-14 (Event Dispatchers), and PSR-3 (Loggers).
- **Multiple Storage Backends:** Store your schemas safely in `Redis`, relational databases via `PDO`, flat `Files`, or `In-Memory Arrays` for testing.
- **CLI Toolkit:** Includes a robust set of `symfony/console` commands to manually profile URLs, inspect baselines, list active tracked endpoints, and compare local schemas.

---

💻 How Developers Can Utilize This
---------------------------------

[](#-how-developers-can-utilize-this)

### Installation

[](#installation)

```
composer require malikad778/php-sentinel
```

### 1. The Laravel Way 🔴

[](#1-the-laravel-way-)

Sentinel natively integrates with Laravel and the `Http::` facade.

Just publish the config:

```
php artisan vendor:publish --tag=sentinel-config
```

Then attach Sentinel to any outgoing API request using the `withSentinel()` macro!

```
use Illuminate\Support\Facades\Http;

$response = Http::withSentinel()
    ->withToken('stripe-key')
    ->get('https://api.stripe.com/v1/payment_intents/pi_123');
```

As traffic flows through, Sentinel will automatically store schemas in your configured database or Redis, and write warnings directly into your Laravel `Log`.

### 2. The Symfony Way 🎹

[](#2-the-symfony-way-)

Enable the `SentinelBundle` in your `config/bundles.php`:

```
return [
    Sentinel\Symfony\SentinelBundle::class => ['all' => true],
];
```

Define your settings in `config/packages/sentinel.yaml`:

```
sentinel:
    store:
        driver: redis # or pdo, file
    sample_threshold: 30
    drift_severity: BREAKING
    reharden: true
```

The bundle automatically wires the `Sentinel` singleton into your Dependency Injection container so you can inject it anywhere.

### 3. The Framework-Agnostic Way (PSR-18)

[](#3-the-framework-agnostic-way-psr-18)

Inject `SchemaWatcher` into any PSR-18 middleware stack (like Guzzle).

```
use Sentinel\Sentinel;
use Sentinel\Store\FileSchemaStore;
use Sentinel\Middleware\SchemaWatcher;
use Sentinel\Drift\DriftReporter;

$sentinel = Sentinel::create()
    ->withStore(new FileSchemaStore('/tmp/schemas'))
    ->withSampleThreshold(20)
    // ->withLogger($myMonologInstance)
    // ->withDispatcher($myPsr14Dispatcher)
    ->build();

// Wrap your HTTP Client
$watcher = new SchemaWatcher($psr18Client, $sentinel, new DriftReporter($sentinel->getDispatcher(), $sentinel->getLogger()));

// Use $watcher exactly like your normal HTTP client!
$response = $watcher->sendRequest($request);
```

---

🛠 Project Architecture & Structure
--------------------------------------

[](#-project-architecture--structure)

The framework was built with strict modularity, targeting PHPStan Level 8.

- **`src/Inference/`**: The deductive engine. Houses `InferenceEngine`, `TypeResolver`, and `EnumCandidateDetector` which convert raw JSON payloads into strict structural schemas.
- **`src/Sampling/`**: Contains the `SampleAccumulator` which pools traffic over time, calculating fractional presences (to map `optional` vs `required` fields) before hardening the schema.
- **`src/Drift/`**: The diffing engine. Contains `DriftDetector` and granular `Changes/*` classes (e.g. `NowNullable`, `TypeChanged`) to calculate exact JSON diffs.
- **`src/Middleware/`**: Wrappers for the `SchemaWatcher` that hook into HTTP lifecycles.
- **`src/Store/`**: Storage drivers implementing `SchemaStoreInterface`.
- **`src/Console/`**: `symfony/console` commands.
- **`src/Laravel/` & `src/Symfony/`**: Adapters to seamlessly bind the library to enterprise frameworks natively.

---

🚨 Responding to Drift Programmatically
--------------------------------------

[](#-responding-to-drift-programmatically)

While Sentinel logs drift warnings out-of-the-box, you probably want to trigger custom actions (like paging an on-call engineer) when a breaking change happens.

Sentinel broadcasts the `Sentinel\Events\SchemaDriftDetected` PSR-14 event. Listen to it in your app:

```
use Sentinel\Events\SchemaDriftDetected;

public function handleAPIChange(SchemaDriftDetected $event): void
{
    if ($event->drift->severity->value === 'BREAKING') {
        // The API broke its contract!
        $endpoint = $event->drift->endpoint;

        foreach ($event->drift->changes as $change) {
            echo "Field: " . $change->getPath() . " -> " . $change->getDescription();
        }

        // PagerDuty::trigger("API Drift on $endpoint");
    }
}
```

🧰 CLI Tools
-----------

[](#-cli-tools)

Sentinel comes with a standalone executable (`bin/sentinel`) and registers identical artisan/console commands into your framework.

```
# Profile an endpoint blindly 5 times to force a schema generation
php vendor/bin/sentinel profile --url="https://api.github.com/users/octocat" --samples=5

# View all actively monitored endpoints and their sampling status
php vendor/bin/sentinel list-schemas

# View the full JSON Schema inferred for an endpoint
php vendor/bin/sentinel inspect "GET /users/{id}"

# Compare two generated JSON schemas manually
php vendor/bin/sentinel diff old_schema.json new_schema.json
```

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance80

Actively maintained with recent releases

Popularity8

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

107d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e4a7f00f437e6ae1436953cf64cd6fa1d55a13da6b9c369340b2cfd8ddd4ef42?d=identicon)[malikad778](/maintainers/malikad778)

---

Top Contributors

[![malikad778](https://avatars.githubusercontent.com/u/86764206?v=4)](https://github.com/malikad778 "malikad778 (2 commits)")

---

Tags

apidrift-detectionjson-schemalaravelmonitoringphppsr-18schema-validationsymfonyapisymfonylaravelmonitoringschemajson-schemarestpsr-18drift-detectionphpstan-level-8

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/malikad778-php-sentinel/health.svg)

```
[![Health](https://phpackages.com/badges/malikad778-php-sentinel/health.svg)](https://phpackages.com/packages/malikad778-php-sentinel)
```

###  Alternatives

[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M395](/packages/drupal-core-recommended)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

585.4M506](/packages/shopware-core)[eliashaeussler/cache-warmup

Composer package to warm up website caches, based on a given XML sitemap

75419.2k9](/packages/eliashaeussler-cache-warmup)[typo3/cms-core

TYPO3 CMS Core

3312.9M4.7k](/packages/typo3-cms-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)