hellojb / foxess-php

dev-main 2026-07-10 18:01 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.0

Requires (Dev)

• mockery/mockery: ^1.6
• phpunit/phpunit: ^10.0

Suggests

• illuminate/support: Required for Laravel integration (^11.0)

MIT

• John Blackmore

Published on Packagist.org on 2026-07-10 18:03 UTC

README

PHP SDK for the FoxESS Cloud Open API with Laravel support.

Features

• OAuth 2.0 Authorization Code Grant authentication
• Automatic token refresh
• Real-time device data (battery SOC, solar generation, grid import/export, load statistics)
• Batch queries for multiple devices
• Typed DTOs with helper methods
• Laravel Service Provider, Facade, and config
• Rate limit exception handling

Requirements

• PHP 8.2+
• GuzzleHTTP 7.0+

Installation

composer require hellojb/foxess-php

Standalone Usage

use Hellojb\Foxess\FoxEss;
use Hellojb\Foxess\Auth\AccessToken;

$token = new AccessToken('your-access-token');

$client = new FoxEss([
    'base_url' => 'https://www.foxesscloud.com/',
    'token' => $token,
]);

$realTime = $client->realTimeData()->query(['YOUR_DEVICE_SN']);

foreach ($realTime as $data) {
    echo "SoC: {$data->soc()}%\n";
    echo "PV Power: {$data->pvPower()} kW\n";
    echo "Charging: " . ($data->isCharging() ? 'Yes' : 'No') . "\n";
}

Laravel Usage

Publish the config:

php artisan vendor:publish --tag=foxess-config

Set .env variables:

FOXESS_CLIENT_ID=your-client-id
FOXESS_CLIENT_SECRET=your-client-secret
FOXESS_REDIRECT_URI=https://your-app.com/auth/foxess/callback

Use the Facade:

use Hellojb\Foxess\Laravel\FoxEssFacade as FoxEss;

$realTime = FoxEss::realTimeData()->query(['SN001']);

Real-Time Data Helpers

The RealTimeData DTO provides convenient accessors:

Method	Description
soc()	Battery state of charge (%)
pvPower()	Solar generation (kW)
loadsPower()	Home load (kW)
batteryPower()	Battery power (negative = charging, positive = discharging)
isCharging()	Is battery currently charging?
isDischarging()	Is battery currently discharging?
isImporting()	Is power being imported from grid?
isExporting()	Is power being exported to grid?

License

MIT