PHPackages                             ospp/protocol - 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. ospp/protocol

ActiveLibrary

ospp/protocol
=============

PHP SDK for the OSPP (Open Self-Service Point Protocol) — enums, envelope, crypto, state machines

v0.3.0(yesterday)0123—0%MITPHPPHP ^8.3CI passing

Since Feb 24Pushed todayCompare

[ Source](https://github.com/ospp-org/ospp-sdk-php)[ Packagist](https://packagist.org/packages/ospp/protocol)[ RSS](/packages/ospp-protocol/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (2)Versions (5)Used By (0)

OSPP SDK PHP
============

[](#ospp-sdk-php)

PHP SDK for the **Open Self-Service Point Protocol (OSPP)** — a communication protocol for self-service station management systems.

This package provides the shared protocol layer used by CSMS servers, station simulators, and testing tools.

Requirements
------------

[](#requirements)

- PHP 8.3+
- ext-json
- ext-openssl (optional — required only for ECDSA offline pass signing)

Installation
------------

[](#installation)

```
composer require ospp/protocol

For private repositories, add the VCS source first:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@github.com:ospp-org/ospp-sdk-php.git"
        }
    ]
}

What's Included

┌──────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│    Module    │                                                  Description                                                   │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Enums        │ MessageType, SessionSource, BayStatus, SessionStatus, Severity, SigningMode, OsppErrorCode (102 codes),        │
│              │ FirmwareUpdateStatus, DiagnosticsStatus, ReservationStatus, BootNotificationStatus, BootReason,               │
│              │ NetworkConnectionType, TransactionEventStatus, ChangeConfigResultStatus, DataTransferStatus,                  │
│              │ TriggerMessageStatus, CertificateType, ResetType, SecurityEventType, StationConnectivity,                    │
│              │ BleServiceStatus, PricingType, LogLevel, SessionEndReason, ConfigurationKey (41 keys with metadata)            │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ State        │ Transition tables for Bay (7 states), Session (6 states), Firmware (10 states), Diagnostics (5 states),        │
│ Machines     │ Reservation (5 states)                                                                                         │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Envelope     │ MessageEnvelope, MessageBuilder — wire-format message construction with correlation support                    │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Crypto       │ HMAC-SHA256 message signing (MacSigner), ECDSA P-256 offline pass signing, canonical JSON serialization,       │
│              │ critical message registry (19 actions), SessionProofCalculator (BLE session proof)                            │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Value        │ MessageId (UUID v4), ProtocolVersion (semver)                                                                  │
│ Objects      │                                                                                                                │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Actions      │ OsppAction — all 30 protocol actions (27 MQTT + 3 API-only) with validation                                   │
├──────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ JSON         │ 77 schema files (ble, common, mqtt) accessible via SchemaPath::directory()                                    │
│ Schemas      │                                                                                                                │
└──────────────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Quick Start

Build and sign a message

use Ospp\Protocol\Envelope\MessageBuilder;
use Ospp\Protocol\Crypto\MacSigner;

$envelope = MessageBuilder::request('StartService')
    ->withPayload(['bayId' => 'bay-1', 'userId' => 'user-123'])
    ->build();

$signer = new MacSigner($sessionKey);
$signed = $envelope->withMac($signer->sign($envelope->payload));

$json = $signed->toJson();

Check state transitions

use Ospp\Protocol\Enums\SessionStatus;
use Ospp\Protocol\StateMachines\SessionTransitions;

$allowed = SessionTransitions::canTransition('pending', 'authorized'); // true
$timeout = SessionTransitions::timeout('active'); // 3600

Wire format conversion

use Ospp\Protocol\Enums\BayStatus;

$status = BayStatus::fromOspp('Available'); // BayStatus::AVAILABLE
$wire = BayStatus::OCCUPIED->toOspp();      // 'Occupied'

Access JSON Schemas

use Ospp\Protocol\SchemaPath;

$schemasDir = SchemaPath::directory();
$bootSchema = json_decode(file_get_contents($schemasDir . '/mqtt/boot-notification-request.schema.json'), true);

Architecture

- Zero external dependencies — only PHP extensions (json, openssl)
- Pure PHP 8.3 — readonly classes, enums, match expressions, named arguments
- Immutable — all DTOs and value objects are final readonly
- Framework-agnostic — no Laravel, Symfony, or other framework dependency
- PSR-4 autoloading — Ospp\Protocol\ namespace

Testing

composer install
vendor/bin/phpunit

646 tests across 4 test suites:

┌─────────────┬───────┬───────────────────────────────────────┐
│    Suite    │ Tests │                Purpose                │
├─────────────┼───────┼───────────────────────────────────────┤
│ Unit        │ 457   │ Individual class behavior             │
├─────────────┼───────┼───────────────────────────────────────┤
│ Regression  │ 10    │ Pins previously found bugs            │
├─────────────┼───────┼───────────────────────────────────────┤
│ Contract    │ 148   │ Behavioral alignment with CSMS server │
├─────────────┼───────┼───────────────────────────────────────┤
│ Integration │ 27    │ Cross-component workflows             │
└─────────────┴───────┴───────────────────────────────────────┘

Static analysis:

vendor/bin/phpstan analyse --level=9 src/

License

MIT
```

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance100

Actively maintained with recent releases

Popularity14

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

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 ~8 days

Total

4

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/103e277154d485dba3232d0c41a517b805437840e1b2f52cd27040cb3683ea68?d=identicon)[gabriel.marinescu](/maintainers/gabriel.marinescu)

---

Top Contributors

[![g-marinescu](https://avatars.githubusercontent.com/u/203068987?v=4)](https://github.com/g-marinescu "g-marinescu (10 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ospp-protocol/health.svg)

```
[![Health](https://phpackages.com/badges/ospp-protocol/health.svg)](https://phpackages.com/packages/ospp-protocol)
```

PHPackages © 2026

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