README

PHP client for the Ista energy consumption API at mijn.ista.nl. Framework-agnostic.

Requires PHP 8.4+.

Installation

composer require nieknijland/ista-php

Quick start

use NiekNijland\Ista\Ista;

$ista = new Ista(
    username: 'your@email.com',
    password: 'your-password',
);

// Fetch all consumption data
$userValues = $ista->getUserValues();

$customer = $userValues->customers[0];

foreach ($customer->consumption->services as $service) {
    echo "Current usage: {$service->totalNow}\n";
    echo "Previous year: {$service->totalPrevious}\n";

    foreach ($service->currentMeters as $meter) {
        echo "  {$meter->position}: {$meter->value}\n";
    }
}

Constructor

$ista = new Ista(
    username: 'your@email.com',
    password: 'your-password',
    httpClient: $customGuzzleClient,  // ?ClientInterface, default: new Client()
    cache: $psr16Cache,               // ?CacheInterface (PSR-16), default: null (no caching)
    cacheTtl: 3600,                   // int, cache TTL in seconds, default: 3600
);

API methods

The client provides four methods. All throw IstaException on failure.

See API Methods for full parameter documentation and examples.

Data objects

All API responses are returned as readonly DTOs with typed properties. Every DTO provides fromArray() and toArray() for serialization.

See Data Objects for all properties and types.

Caching

Pass any PSR-16 CacheInterface to cache API responses and the JWT token:

$ista = new Ista(
    username: 'your@email.com',
    password: 'your-password',
    cache: new YourPsr16Cache(),
    cacheTtl: 86400, // 24 hours
);

Cache keys used:

Cache failures are silently ignored -- the client will re-fetch from the API.

Error handling

All errors are wrapped in a single exception class:

use NiekNijland\Ista\Exception\IstaException;

try {
    $result = $ista->getUserValues();
} catch (IstaException $e) {
    // Authentication failures, HTTP errors, malformed responses
    // Original exception is available via $e->getPrevious()
}

Testing

The package ships testing utilities so you can mock the Ista client in your application tests without making real API calls.

use NiekNijland\Ista\Testing\FakeIsta;
use NiekNijland\Ista\Testing\UserValuesResultFactory;

$fake = new FakeIsta();
$fake->seedUserValuesResult(UserValuesResultFactory::make());

$result = $fake->getUserValues();

$fake->assertCalled('getUserValues');
$fake->assertCalledTimes('getUserValues', 1);

See Testing for full documentation of FakeIsta, all factories, and recorded call inspection.

Development

composer test              # Unit tests
composer test-integration  # Integration tests (requires ISTA_USERNAME and ISTA_PASSWORD)
composer test-all          # All test suites
composer analyse           # PHPStan level 8
composer format            # Laravel Pint
composer rector            # Rector automated refactoring
composer codestyle         # Full pipeline: Rector + Pint + PHPStan

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.