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
);

Parameter	Type	Default	Description
`$username`	`string`	(required)	Your mijn.ista.nl username
`$password`	`string`	(required)	Your mijn.ista.nl password (marked `#[SensitiveParameter]`)
`$httpClient`	`?ClientInterface`	`null`	Custom Guzzle HTTP client; `null` creates a default one
`$cache`	`?CacheInterface`	`null`	Any PSR-16 cache implementation; `null` disables caching
`$cacheTtl`	`int`	`3600`	Cache time-to-live in seconds

API methods

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

Method	Description
`getUserValues()`	Fetch all customers, meters, and billing data
`getConsumptionAverages()`	Fetch building average consumption
`getMonthlyConsumption()`	Fetch month-by-month consumption history
`getConsumptionValues()`	Fetch consumption for a specific billing period

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.

Class	Description
`UserValuesResult`	Top-level response with customers
`Customer`	A customer with address and consumption data
`ConsumptionPeriod`	A billing period with services, meters, and temperatures
`ServiceComparison`	Current vs. previous year totals for a service type
`Meter`	A single meter reading with all technical fields
`BillingService`	Service type definition (e.g. Heating, Hot Water)
`BillingPeriod`	A billing year with start/end dates
`ConsumptionAverageResult`	Building average consumption
`ConsumptionValuesResult`	Consumption data for a specific billing period
`MonthlyConsumptionResult`	Monthly consumption history
`MonthlyConsumption`	A single month's consumption
`MonthlyServiceConsumption`	Per-service totals for a month
`MonthlyDeviceConsumption`	Per-device readings for a month

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:

Key pattern	Data
`ista:jwt`	Authentication token
`ista:user-values`	`getUserValues()` response
`ista:consumption-averages:{cuid}:{start}:{end}`	`getConsumptionAverages()` response
`ista:monthly-consumption:{cuid}`	`getMonthlyConsumption()` response
`ista:consumption-values:{cuid}:{year}:{start}:{end}`	`getConsumptionValues()` response

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.

nieknijland / ista-php

Maintainers

Package info

Fund package maintenance!

Statistics

Security