PHPackages                             virtuallast/surfsight-php-client - 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. virtuallast/surfsight-php-client

ActiveLibrary

virtuallast/surfsight-php-client
================================

A strongly typed PHP client for the Surfsight API.

v1.0.0(today)00MITPHPPHP ^8.3

Since Jul 31Pushed todayCompare

[ Source](https://github.com/virtualLast/surfsight-php-client)[ Packagist](https://packagist.org/packages/virtuallast/surfsight-php-client)[ Docs](https://github.com/VirtualLast/surfsight-php-client)[ RSS](/packages/virtuallast-surfsight-php-client/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (14)Versions (2)Used By (0)

Surfsight PHP Client
====================

[](#surfsight-php-client)

A strongly typed, framework-independent PHP 8.3+ client for the official Surfsight API.

Jane generates endpoint and model code from the committed OpenAPI specification. A small maintained API provides regional configuration, authentication, stable resource groups, pagination, media downloads, PSR dependency discovery, and package exceptions.

Features
--------

[](#features)

- Official Surfsight API 2.0.0 models and all 129 specification paths
- PSR-18, PSR-17, and PSR-7 compatibility
- Automatic HTTP implementation discovery or explicit dependency injection
- Credential authentication, 24-hour token reuse, and one controlled re-authentication after HTTP 401
- Explicit Europe or North America selection
- Lazy offset pagination for device events
- Streaming media downloads without forwarding Surfsight credentials to media hosts
- No Symfony FrameworkBundle dependency

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

[](#installation)

```
composer require virtuallast/surfsight-php-client symfony/http-client nyholm/psr7
```

Quick start
-----------

[](#quick-start)

```
use VirtualLast\Surfsight\Configuration;
use VirtualLast\Surfsight\Region;
use VirtualLast\Surfsight\SurfsightClient;

$client = SurfsightClient::create(
    new Configuration(
        region: Region::Europe,
        email: $_ENV['SURFSIGHT_EMAIL'],
        password: $_ENV['SURFSIGHT_PASSWORD'],
    ),
);

$device = $client->devices()->getDeviceByImei($imei);
echo $device->getData()->getName();
```

`Region::Europe` uses `https://api.de.surfsight.net/v2`; `Region::NorthAmerica` uses `https://api-prod.surfsight.net/v2`. A region is always required.

Authentication
--------------

[](#authentication)

The client calls the documented `POST /authenticate` operation on first use, reuses the returned token for its documented 24-hour user-token lifetime, and adds `Authorization: Bearer …` to API calls. An HTTP 401 invalidates the token and permits exactly one re-authentication and retry.

Authentication failures throw `AuthenticationException`. Passwords and tokens are redacted from debug output and are never included in package exception messages.

Dependency injection
--------------------

[](#dependency-injection)

```
$client = SurfsightClient::create(
    $configuration,
    $psr18Client,
    $psr17RequestFactory,
    $psr17StreamFactory,
);
```

When omitted, `php-http/discovery` locates the implementations.

Events and pagination
---------------------

[](#events-and-pagination)

```
$page = $client->events()->getEvents($imei, [
    'start' => '2026-07-01T00:00:00Z',
    'end' => '2026-07-02T00:00:00Z',
    'limit' => '100',
]);

foreach ($client->events()->iterateEvents($imei, [
    'start' => '2026-07-01T00:00:00Z',
    'end' => '2026-07-02T00:00:00Z',
    'limit' => '100',
]) as $event) {
    // $event is VirtualLast\Surfsight\Generated\Model\Event
}
```

The iterator follows the API's `limit`/`offset` metadata lazily and rejects repeated offsets.

Event media
-----------

[](#event-media)

```
$link = $client->media()->getEventFileLink($imei, [
    'fileId' => $fileId,
    'fileType' => 'video',
]);

$stream = $client->media()->download($link);
```

Media links are temporary. Downloads require a valid HTTPS URL and return a PSR-7 stream. The Surfsight bearer token is never attached to the returned external URL.

Recording ranges
----------------

[](#recording-ranges)

```
$ranges = $client->recordings()->getRecordingRanges($imei, [
    'start' => '2026-07-01T00:00:00Z',
    'end' => '2026-07-01T01:00:00Z',
]);
```

API coverage
------------

[](#api-coverage)

Maintained high-level APIs currently cover authentication, device retrieval/update, device events/details, event file links/downloads, and recording ranges.

Every other generated operation remains deliberately available through `$client->generated()`, including alarms, audit logs, calibration, device operations, drivers, geofences, groups, health, OAuth, organizations, partners, streaming, telemetry, users, virtual events, webhooks, and organization albums. This low-level surface follows upstream naming and is less stable.

Errors
------

[](#errors)

- `ConfigurationException` reports invalid local configuration.
- `AuthenticationException` reports safe authentication failures.
- `ApiException` carries the operation, HTTP status, headers, safe decoded details, and previous generated exception.
- `TransportException` wraps PSR transport failures.

No general-purpose retry policy is applied. Configure retries in the injected transport if desired.

Specification and generation
----------------------------

[](#specification-and-generation)

The original official specification is committed at `openapi/surfsight.yaml` (JSON syntax, which is valid YAML). Generated files live only in `generated/` and must never be edited.

```
composer update-spec
composer generate
composer test
composer analyse
composer run validate
```

The update command downloads the official portal's page-data representation, validates its identity, and atomically replaces the file. Generation applies one documented temporary preprocessing fix; the committed upstream file is unchanged.

Current limitations
-------------------

[](#current-limitations)

Only the priority resource groups have polished wrappers in this initial release. Other API groups use `generated()` until maintained wrappers are added. No live integration tests run by default, and no claim is made here that requests have been verified with real Surfsight credentials.

License
-------

[](#license)

MIT

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

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

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/6ad19b55308041d797f054247db4eb1b32f370cb6869edb14e7e4934614fd618?d=identicon)[virtualLast](/maintainers/virtualLast)

---

Top Contributors

[![virtualLast](https://avatars.githubusercontent.com/u/2872439?v=4)](https://github.com/virtualLast "virtualLast (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/virtuallast-surfsight-php-client/health.svg)

```
[![Health](https://phpackages.com/badges/virtuallast-surfsight-php-client/health.svg)](https://phpackages.com/packages/virtuallast-surfsight-php-client)
```

###  Alternatives

[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36826.2k2](/packages/telnyx-telnyx-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

86337.5k](/packages/flow-php-flow)[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k18](/packages/tempest-framework)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k6.0M760](/packages/sylius-sylius)[getbrevo/brevo-php

Official PHP SDK for the Brevo API.

1004.1M53](/packages/getbrevo-brevo-php)[gotenberg/gotenberg-php

A PHP client for interacting with Gotenberg, a developer-friendly API for converting numerous document formats into PDF files, and more!

3906.6M32](/packages/gotenberg-gotenberg-php)

PHPackages © 2026

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