Download the PHP package graystackit/laravel-testo-api without Composer

graystackit/laravel-testo-cloud

A Laravel package for the Testo Smart Connect API, built on Saloon 4.

Retrieve historical measurements, alarm events, HACCP task records, device properties, device health status, measuring object configurations, and location hierarchies from Testo Smart Connect — all with a clean, Laravel-native interface.

Requirements

• PHP 8.3+
• Laravel 11, 12, or 13

Installation

Laravel auto-discovers the service provider. Then publish the config file:

Configuration

Add the following to your .env file:

Generate your API key from the Smart Connect home page. Keys are valid for up to one year.

Async Workflow

All data-export endpoints use the same two-step async pattern:

1. Submit a POST request → receive a request_uuid
2. Poll a GET request with that UUID until status is Completed
3. Download each URL in dataUrls using downloadDataFile()

An unrecognized status string from Testo (e.g. a future state not listed above) maps to AsyncRequestStatus::Unknown rather than being silently treated as still-processing — check $response->rawStatus for the exact string Testo returned in that case.

Usage

Resolve TestoCloudClient from the container or inject via constructor.

Measurements POST /v2/measurements • GET /v2/measurements/{uuid}

$from must be strictly before $to — an \InvalidArgumentException is thrown otherwise.

Parse NDJSON measurement data

physical_extension disambiguates rows that share the same physical_property_name (e.g. an external-probe temperature reading vs. the logger's own internal sensor) — read temperature_extension/humidity_extension when a logger reports more than one of each.

The optional $deviceUuid filter assumes measurement rows carry a device_uuid field. Testo's migration guide instead documents serial_no as the sensor identifier on measurement values — this is unconfirmed against a live payload either way. Rows with no device_uuid key are never filtered out, so an incorrect assumption here degrades safely (passes everything through) rather than silently dropping data.

Alarms POST /v3/alarms • GET /v3/alarms/{uuid}

Retrieve historical alarm events for the configured account.

Tasks POST /v3/tasks • GET /v3/tasks/{uuid}

Retrieve quality-management / HACCP activity records executed by staff.

⚠️ Unverified (2026-09-28): this path does not appear anywhere in Testo's current Smart Connect API reference — checked the endpoint-examples overview, the OData filtering page, and the changelog, all of which enumerate the same fixed set of six endpoint pairs (device properties, device status, measurements, alarms, locations, measuring objects) with no tasks entry. A separate "Task Execution API" concept is referenced elsewhere but its actual endpoint path could not be confirmed. Verify against a live API key (or with Testo) before relying on this — it may 404, live under a different path, or belong to a different API family entirely.

Device Properties POST /v3/devices/properties • GET /v3/devices/properties/{uuid}

Retrieve device metadata including serial numbers, model codes, firmware versions, calibration status, and equipment relationships.

No date range required — returns current configuration.

Device Status POST /v3/devices/status • GET /v3/devices/status/{uuid}

Retrieve battery level, signal strength, last communication timestamp, firmware version, and serial numbers for all devices.

No date range required — returns current status snapshot.

⚠️ Needs verification (2026-09-28): Testo's changelog records /v4/devices/status being added on top of this v3 path, renaming last_communication/next_communication to ..._time, removing fw_code/fw_version (now under /v3/devices/properties, used by Device Properties above), and adding production_date/battery_temperature/status_time. The changelog never states v3 is deprecated, but the docs' own endpoint-overview page still only lists v3 — the two sources disagree, so the version wasn't changed pending confirmation of which is actually current. This package doesn't parse any device-status-specific fields into a typed DTO today (only the generic async wrapper below), so the version gap is lower-risk than it looks, but should move to v4 once confirmed live.

Measuring Objects POST /v1/measuring-objects • GET /v1/measuring-objects/{uuid}

Retrieve measuring-object configurations including customer_uuid, customer_site, product_family_id, measurement settings, and channel assignments.

No date range required — returns current configuration.

Locations POST /v1/locations • GET /v1/locations/{uuid}

Retrieve the location hierarchy (sites, zones, rooms) associated with the account.

No date range required — returns current location structure.

Data Objects

Submission response — AsyncSubmitResponse

Returned by every submit*() method.

Status response — AsyncStatusResponse

Returned by every check*Status() method.

Helper methods: isCompleted(), isProcessing(), isFailed()

AsyncRequestStatus enum

The enum normalises all API status strings, including "In Progress" → Processing. An unrecognized string never falls back to Processing — it maps to Unknown instead, so a future new terminal status can't get stuck looking like it's still in progress. Read $response->rawStatus to see the original string in that case.

Measurement-specific objects

Used by submitMeasurementRequest()/checkRequestStatus() (measurements only — kept as their own classes since measurements has its own endpoint/status vocabulary separate from the shared Alarms/Tasks/Equipment/Sensors/Measuring-Objects modules, but shaped the same way):

Error Handling

All client methods throw GraystackIT\TestoCloud\Exceptions\TestoApiException on failure.

submit*Request() methods that accept a date range additionally throw \InvalidArgumentException when $from >= $to.

If TESTO_API_KEY is not configured, a \RuntimeException is thrown on container resolution.

API Endpoint Reference

Base URL: https://data-api.{region}.smartconnect.testo.com

Database Storage

Migration

Run the migration to create the testo_measurements table:

To customise the migration before running it, publish it first:

testo_measurements schema

Model

Disabling automatic storage

Set TESTO_STORE_MEASUREMENTS=false in your .env (or store_measurements => false in config/testo.php) to fetch and parse data without writing to the database.

Artisan Command

Fetches historical measurements from the Testo API, parses the NDJSON response, and — when storage is enabled — persists every row to testo_measurements.

Options

Examples

Console output

Testing

Tests use Saloon's MockClient — no real API calls are made.

License

MIT