fmohican / iperf3-laravel

dev-master 2026-09-22 09:56 UTC

Requires

• php: ^8.5
• ext-json: *
• illuminate/contracts: ^13.0
• illuminate/support: ^13.0

Requires (Dev)

• laravel/pint: ^1.27
• orchestra/testbench: ^11.2
• phpunit/phpunit: ^12.5

MIT

• performance
• network
• laravel
• iperf3

Published on Packagist.org on 2026-09-22 09:56 UTC

README

A strict, strongly typed iperf3 JSON parser for PHP 8.5 and Laravel 13. It supports TCP and UDP results, including intervals, per-stream metrics, throughput, retransmits, RTT, packet loss, jitter, and host/remote CPU usage.

Installation

composer require fmohican/iperf3-laravel

Laravel discovers the service provider and the Iperf3 facade automatically. The optional input-size configuration can be published with:

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

Usage

use fmohican\Iperf3Laravel\Facades\Iperf3;

$result = Iperf3::parseFile('/path/to/result.json');
$summary = $result->summary();

echo $summary->protocol;             // TCP or UDP
echo $summary->uploadSpeedMbps;      // sender throughput
echo $summary->downloadSpeedMbps;    // receiver throughput
echo $summary->retransmits;
echo $summary->jitterMs;
echo $summary->lostPacketsPercent;
echo $result->end->cpuUtilization->hostTotal;

Raw JSON and open stream resources are accepted too:

$fromJson = Iperf3::parseJson($json);

$stream = fopen('/path/to/result.json', 'rb');

try {
    $fromStream = Iperf3::parseStream($stream);
} finally {
    fclose($stream);
}

Stream input is size-bounded while it is read, but parsing is not constant-memory: the complete JSON document is retained and passed to PHP's native JSON decoder. Caller-owned streams remain open after parsing.

Every returned DTO is immutable. A summary defaults to Mbps; conversion methods return a new summary whose uploadSpeed and downloadSpeed properties use the selected unit:

$mbps = $summary->toMbps();
$gbps = $summary->toGbps();

echo $gbps->uploadSpeed;
echo $gbps->unit->value; // Gbps

For standard TCP output, upload maps to end.sum_sent and download maps to end.sum_received. For a one-way UDP end.sum, the direction is determined by iperf3's reverse flag.

Errors and limits

Malformed JSON, incomplete result structures, unsupported protocols, invalid streams, and iperf3 error documents throw fmohican\Iperf3Laravel\Exceptions\Iperf3ParseException. File and stream input defaults to a 64 MiB limit. iperf3.max_input_bytes must be a positive integer and applies equally to strings, files, and streams.

Filesystem exception messages omit local paths so they are safer to expose in logs or HTTP error responses. When trusted diagnostic code needs the original path, it can explicitly read $exception->sourcePath().

Development

composer install
composer test
composer lint