DEV Community: Roberto B.

GPX Runner's data decoded with PHP

Roberto B. — Sat, 07 Mar 2026 08:06:36 +0000

Every runner with a sports watch carries a small data recorder on their wrist. After every run, it produces a GPX file: a detailed log of GPS positions, timestamps, elevation, and often heart rate. Most runners glance at the summary on their phone: distance, time, average pace, and move on.

But that GPX file holds much more. With the hi-folks/statistics PHP package, you can extract per-kilometer splits and apply real statistical analysis to your running performance, from pacing consistency to elevation impact, cardiac drift to long-term improvement trends.

In this article, we will parse a GPX file, build per-kilometer splits, and analyze a 10K run step by step using descriptive statistics, correlation, regression, outlier detection, and more.

Installing the package

composer require hi-folks/statistics

The package requires PHP 8.2+ and is available on GitHub: https://github.com/Hi-Folks/statistics.

What is inside a GPX file?

A GPX (GPS Exchange Format) file is XML. Every sport watch — Garmin, Polar, Suunto, Apple Watch, Coros — can export one. Each file contains a sequence of trackpoints recorded every 1–5 seconds during your run. A trackpoint looks like this:

<trkpt lat="45.4642" lon="9.1900">
  <ele>122.4</ele>
  <time>2025-03-15T07:30:45Z</time>
  <extensions>
    <gpxtpx:TrackPointExtension>
      <gpxtpx:hr>152</gpxtpx:hr>
    </gpxtpx:TrackPointExtension>
  </extensions>
</trkpt>

From these raw points you can derive:

Distance between consecutive points (using the Haversine formula)
Pace per kilometer (time elapsed over each 1 km segment)
Elevation gain and loss per kilometer
Heart rate averages per kilometer (from the Garmin extension)

Parsing the GPX file

PHP's built-in SimpleXML makes parsing straightforward. Here are the helper functions we use:

function parseGpx(string $filePath): array
{
    $xml = simplexml_load_file($filePath);
    if ($xml === false) {
        throw new RuntimeException("Cannot parse GPX file: {$filePath}");
    }

    $namespaces = $xml->getNamespaces(true);

    $points = [];
    foreach ($xml->trk->trkseg->trkpt as $trkpt) {
        $point = [
            'lat' => (float) $trkpt['lat'],
            'lon' => (float) $trkpt['lon'],
            'ele' => isset($trkpt->ele) ? (float) $trkpt->ele : 0.0,
            'time' => isset($trkpt->time) ? strtotime((string) $trkpt->time) : 0,
            'hr' => null,
        ];

        // Extract heart rate from Garmin TrackPointExtension
        if (isset($namespaces['gpxtpx'])) {
            $extensions = $trkpt->extensions;
            if ($extensions) {
                $gpxtpx = $extensions->children($namespaces['gpxtpx']);
                if (isset($gpxtpx->TrackPointExtension->hr)) {
                    $point['hr'] = (int) $gpxtpx->TrackPointExtension->hr;
                }
            }
        }

        $points[] = $point;
    }

    return $points;
}

To calculate the distance between two GPS coordinates, we use the Haversine formula, the standard method for computing great-circle distance on a sphere:

function haversineDistance(float $lat1, float $lon1, float $lat2, float $lon2): float
{
    $R = 6371000; // Earth radius in meters
    $dLat = deg2rad($lat2 - $lat1);
    $dLon = deg2rad($lon2 - $lon1);
    $a = sin($dLat / 2) ** 2
       + cos(deg2rad($lat1)) * cos(deg2rad($lat2)) * sin($dLon / 2) ** 2;

    return $R * 2 * atan2(sqrt($a), sqrt(1 - $a));
}

Then we walk through the trackpoints, accumulating distance until we hit each kilometer mark, and record the split:

function buildKmSplits(array $trackpoints): array
{
    $splits = [];
    $currentKm = 1;
    $kmDistance = 0;
    $kmStartTime = $trackpoints[0]['time'];
    $kmEleGain = 0;
    $kmEleLoss = 0;
    $kmHrValues = [];

    for ($i = 1; $i < count($trackpoints); $i++) {
        $prev = $trackpoints[$i - 1];
        $curr = $trackpoints[$i];

        $segDist = haversineDistance($prev['lat'], $prev['lon'], $curr['lat'], $curr['lon']);
        $kmDistance += $segDist;

        $eleDiff = $curr['ele'] - $prev['ele'];
        if ($eleDiff > 0) {
            $kmEleGain += $eleDiff;
        } else {
            $kmEleLoss += abs($eleDiff);
        }

        if ($curr['hr'] !== null) {
            $kmHrValues[] = $curr['hr'];
        }

        if ($kmDistance >= 1000) {
            $kmTime = $curr['time'] - $kmStartTime;
            $splits[] = [
                'km' => $currentKm,
                'time' => $kmTime,
                'pace' => $kmTime,
                'eleGain' => round($kmEleGain, 1),
                'eleLoss' => round($kmEleLoss, 1),
                'avgHr' => count($kmHrValues) > 0
                    ? (int) round(Stat::mean($kmHrValues))
                    : null,
            ];

            $currentKm++;
            $kmDistance -= 1000;
            $kmStartTime = $curr['time'];
            $kmEleGain = 0;
            $kmEleLoss = 0;
            $kmHrValues = [];
        }
    }

    return $splits;
}

The data

For this article, we use a simulated 10K run with realistic characteristics: a hilly middle section, slight positive split tendency, and heart rate drifting upward with fatigue. If you have a real GPX file, just swap in parseGpx() and buildKmSplits().

// === Option 1: Parse a real GPX file ===
// $trackpoints = parseGpx('your-run.gpx');
// $splits = buildKmSplits($trackpoints);

// === Option 2: Simulated 10K run ===
$splits = [
    ['km' => 1,  'time' => 322, 'pace' => 322, 'eleGain' => 5,  'eleLoss' => 2,  'avgHr' => 145],
    ['km' => 2,  'time' => 318, 'pace' => 318, 'eleGain' => 8,  'eleLoss' => 3,  'avgHr' => 150],
    ['km' => 3,  'time' => 335, 'pace' => 335, 'eleGain' => 22, 'eleLoss' => 4,  'avgHr' => 158],
    ['km' => 4,  'time' => 348, 'pace' => 348, 'eleGain' => 28, 'eleLoss' => 5,  'avgHr' => 164],
    ['km' => 5,  'time' => 340, 'pace' => 340, 'eleGain' => 15, 'eleLoss' => 18, 'avgHr' => 162],
    ['km' => 6,  'time' => 312, 'pace' => 312, 'eleGain' => 2,  'eleLoss' => 30, 'avgHr' => 155],
    ['km' => 7,  'time' => 325, 'pace' => 325, 'eleGain' => 3,  'eleLoss' => 8,  'avgHr' => 158],
    ['km' => 8,  'time' => 338, 'pace' => 338, 'eleGain' => 12, 'eleLoss' => 5,  'avgHr' => 165],
    ['km' => 9,  'time' => 352, 'pace' => 352, 'eleGain' => 18, 'eleLoss' => 3,  'avgHr' => 170],
    ['km' => 10, 'time' => 330, 'pace' => 330, 'eleGain' => 4,  'eleLoss' => 15, 'avgHr' => 172],
];

The package includes utility classes for column extraction and time formatting:

use HiFolks\Statistics\Stat;
use HiFolks\Statistics\Freq;
use HiFolks\Statistics\Utils\Arr;
use HiFolks\Statistics\Utils\Format;

[$paces, $eleGains, $hrValues, $kmNumbers] = Arr::extract(
    $splits,
    ['pace', 'eleGain', 'avgHr', 'km']
);

The full PHP example with the complete code is here: examples/article-gpx-running-analysis.php

Step 1: Run overview, your run at a glance

Before diving into analysis, let's get the big picture:

$totalTime = array_sum(array_column($splits, 'time'));
$totalEleGain = array_sum(array_column($splits, 'eleGain'));
$totalEleLoss = array_sum(array_column($splits, 'eleLoss'));

echo "Distance:        " . count($splits) . " km" . PHP_EOL;
echo "Total time:      " . Format::secondsToTime($totalTime) . PHP_EOL;
echo "Average pace:    " . Format::secondsToTime(Stat::mean($paces)) . "/km" . PHP_EOL;
echo "Elevation gain:  +" . $totalEleGain . " m" . PHP_EOL;
echo "Elevation loss:  -" . $totalEleLoss . " m" . PHP_EOL;
echo "Average HR:      " . round(Stat::mean($hrValues)) . " bpm" . PHP_EOL;

Output:

Distance:        10 km
Total time:      0:55:20
Average pace:    0:05:32/km
Elevation gain:  +117 m
Elevation loss:  -93 m
Average HR:      160 bpm

This is the summary your watch shows you. Now let's look at what the numbers actually reveal.

Step 2: Pace descriptive statistics, how consistent were you?

The average pace is useful, but it hides the variation. Did you hold a steady 5:32/km throughout, or did you yo-yo between 5:12 and 5:52?

$meanPace = Stat::mean($paces);
$medianPace = Stat::median($paces);
$stdevPace = Stat::stdev($paces);
$quartiles = Stat::quantiles($paces);

echo "Mean pace:       " . Format::secondsToTime($meanPace) . "/km" . PHP_EOL;
echo "Median pace:     " . Format::secondsToTime($medianPace) . "/km" . PHP_EOL;
echo "Std deviation:   " . round($stdevPace, 1) . " sec" . PHP_EOL;
echo "Fastest km:      " . Format::secondsToTime(min($paces)) . "/km" . PHP_EOL;
echo "Slowest km:      " . Format::secondsToTime(max($paces)) . "/km" . PHP_EOL;
echo "Quartiles:       Q1=" . Format::secondsToTime($quartiles[0]) . "/km"
    . "  Q2=" . Format::secondsToTime($quartiles[1]) . "/km"
    . "  Q3=" . Format::secondsToTime($quartiles[2]) . "/km" . PHP_EOL;

Output:

Mean pace:       0:05:32/km
Median pace:     0:05:33/km
Std deviation:   13 sec
Fastest km:      0:05:12/km (km 6)
Slowest km:      0:05:52/km (km 9)
Quartiles:       Q1=0:05:21/km  Q2=0:05:33/km  Q3=0:05:42/km

How to interpret the results:

A standard deviation of 13 seconds means most of your km were within ~13 seconds of the average. That's moderate consistency for a hilly course.
If mean and median are close (5:32 vs 5:33), your pacing was roughly symmetric — no extreme skew toward fast or slow km.
The range (5:12 to 5:52 = 40 seconds) tells you the spread from your best to worst km. Compare this with the IQR (Q1 to Q3 = 21 seconds) — the core of your pacing was much tighter than the extremes suggest.

Step 3: Pacing consistency, did you positive-split or negative-split?

Every coach talks about pacing strategy. A positive split means you slowed down in the second half; a negative split means you got faster. The Coefficient of Variation (CV) puts a single number on your consistency:

$cv = Stat::coefficientOfVariation($paces, 2);

$halfPoint = intdiv(count($splits), 2);
$firstHalfPaces = array_slice($paces, 0, $halfPoint);
$secondHalfPaces = array_slice($paces, $halfPoint);
$meanFirst = Stat::mean($firstHalfPaces);
$meanSecond = Stat::mean($secondHalfPaces);
$splitDiff = $meanSecond - $meanFirst;
$splitPct = round(($splitDiff / $meanFirst) * 100, 1);

echo "Coefficient of Variation: " . $cv . "%" . PHP_EOL;
echo "First half avg pace:  " . Format::secondsToTime($meanFirst) . "/km" . PHP_EOL;
echo "Second half avg pace: " . Format::secondsToTime($meanSecond) . "/km" . PHP_EOL;

Output:

Coefficient of Variation: 3.91%
First half avg pace:  0:05:33/km (km 1-5)
Second half avg pace: 0:05:31/km (km 6-10)
Negative split: 1.2 sec/km faster (0.4% improvement)

How to interpret the results:

A CV below 5% is considered good pacing for a hilly course. Elite runners often achieve CV under 2% on flat courses.
Our runner managed a slight negative split, the second half was marginally faster. This is often the sign of disciplined pacing: holding back on the uphills in km 3–5 and then capitalizing on the downhill at km 6.
Compare your CV across different runs to track whether your pacing discipline is improving over time.

Step 4: Elevation impact, how much do hills slow you down?

This is the question every trail runner wants answered. We have per-km elevation gain and per-km pace. Let's see if hills measurably affect your speed:

$corrEle = Stat::correlation($eleGains, $paces);
$regEle = Stat::linearRegression($eleGains, $paces);
$r2Ele = Stat::rSquared($eleGains, $paces, false, 4);

echo "Correlation (elevation gain vs pace): " . round($corrEle, 4) . PHP_EOL;
echo "Linear regression: pace = " . round($regEle[0], 2)
    . " x eleGain + " . round($regEle[1], 1) . PHP_EOL;
echo "R-squared: " . $r2Ele . PHP_EOL;

Output:

Correlation (elevation gain vs pace): 0.8053
Linear regression: pace = 1.18 x eleGain + 318.2
R-squared: 0.6485

How to interpret the results:

A Pearson correlation of 0.81 is strong, more uphill clearly means slower pace.
The slope (1.18) tells you: each additional meter of elevation gain within that kilometer is associated with roughly 1.2 seconds slower pace. On a km with 28m of climbing (km 4), the model predicts you'd run ~33 seconds slower than on a flat km.
R-squared of 0.65 means elevation gain explains about 65% of the variation in your pace. The remaining 35% comes from other factors — fatigue, wind, terrain surface, mental state.
Track this slope over multiple runs. As your hill fitness improves, this number should decrease, hills will slow you down less.

Step 5: Heart rate analysis, detecting cardiac drift

Heart rate tells a story that pace alone cannot. Even if your pace stays constant, a rising heart rate signals that your body is working harder, this is cardiac drift, caused by dehydration, heat, and accumulated fatigue.

$meanHr = Stat::mean($hrValues);
$stdevHr = Stat::stdev($hrValues);

// Cardiac drift: HR vs km number
$corrHrKm = Stat::correlation($kmNumbers, $hrValues);
$regHrKm = Stat::linearRegression($kmNumbers, $hrValues);
$r2HrKm = Stat::rSquared($kmNumbers, $hrValues, false, 4);

// HR vs pace
$corrHrPace = Stat::correlation($hrValues, $paces);

Output:

Mean HR:    160 bpm
Median HR:  160 bpm
Std dev:    8.5 bpm
Min HR:     145 bpm | Max HR: 172 bpm

Cardiac drift (HR vs km):
  Correlation:      0.8506
  Regression:       HR = 2.38 x km + 146.8
  R-squared:        0.7235
  HR drift per km:  +2.4 bpm/km

HR vs pace correlation: 0.6912

How to interpret the results:

A correlation of 0.85 between km number and heart rate confirms significant cardiac drift, your heart worked progressively harder as the run continued.
The regression slope (+2.4 bpm/km) means your heart rate rose by about 2.4 beats per minute each kilometer. Over 10 km, that's a ~24 bpm increase from start to finish.
The HR vs pace correlation (0.69) is moderate — heart rate is influenced by pace, but also by elevation, fatigue, and heat. A perfect correlation would mean pace alone determines HR, which is never true in real-world conditions.

Heart rate zone distribution

Using Freq::frequencyTableBySize(), we can see how many kilometers were spent in each heart rate zone:

$hrZones = Freq::frequencyTableBySize($hrValues, 10);
foreach ($hrZones as $range => $count) {
    echo "  " . $range . " bpm: "
        . str_repeat("#", $count) . " (" . $count . " km)" . PHP_EOL;
}

Output:

Heart Rate Zone Distribution:
  145 bpm: ## (2 km)
  155 bpm: ##### (5 km)
  165 bpm: ### (3 km)

This tells you that 5 of your 10 km were in the 150–159 bpm zone — your aerobic sweet spot. Only 3 km pushed into the 165+ range (threshold/anaerobic), primarily on the uphill and late-fatigue segments.

Step 6: Outlier detection, which km was your best and worst?

Not every kilometer is created equal. Some are unusually fast (downhill? adrenaline?) or slow (steep hill? red light? cramp?). The z-score tells you exactly how unusual each km was:

$zscores = Stat::zscores($paces, 2);

foreach ($splits as $i => $split) {
    echo "  km " . $split['km'] . ": " . Format::secondsToTime($split['pace']) . "/km"
        . "  z=" . sprintf("%+.2f", $zscores[$i]) . PHP_EOL;
}

Output:

  km  1: 0:05:22/km  z=-0.77
  km  2: 0:05:18/km  z=-1.08
  km  3: 0:05:35/km  z=+0.23
  km  4: 0:05:48/km  z=+1.23
  km  5: 0:05:40/km  z=+0.62
  km  6: 0:05:12/km  z=-1.54
  km  7: 0:05:25/km  z=-0.54
  km  8: 0:05:38/km  z=+0.46
  km  9: 0:05:52/km  z=+1.54
  km 10: 0:05:30/km  z=-0.15

How to interpret the results:

Negative z-scores mean faster than average; positive means slower. The further from zero, the more unusual.
Km 6 (z = -1.54) was the standout fast km — 20 seconds faster than average. Looking at the data, it had only 2m of elevation gain but 30m of loss. Gravity did the work.
Km 9 (z = +1.54) was the slowest — 18m of climbing plus accumulated fatigue in the late stages.
No km exceeded |z| > 2.0, so there are no statistical outliers. This is confirmed by both Stat::outliers() and Stat::iqrOutliers():

$zOutliers = Stat::outliers($paces, 2.0);   // []
$iqrOutliers = Stat::iqrOutliers($paces);    // []

If you had stopped at a traffic light or taken a water break, the affected km would show up as an outlier — and you'd know to exclude it from your pace analysis.

Step 7: Percentile benchmarks, your pace distribution

Percentiles tell you what your pace range actually looks like across this run:

$percentiles = [10, 25, 50, 75, 90];
foreach ($percentiles as $p) {
    echo "  P" . $p . ": "
        . Format::secondsToTime(Stat::percentile($paces, $p, 0)) . "/km" . PHP_EOL;
}

Output:

  P10: 0:05:13/km
  P25: 0:05:21/km
  P50: 0:05:33/km
  P75: 0:05:42/km
  P90: 0:05:52/km

How to interpret the results:

P10 (5:13/km) is the pace you only sustain on your fastest 10% of km — your peak speed on this run.
P50 (5:33/km) is your median pace — the truest single number for "how fast did I run?"
P90 (5:52/km) is your slowest 10% — your weakest km, usually hills or the final push.
The gap between P25 and P75 (21 seconds) is your interquartile range — the "core band" of your pacing. A narrower band means more consistent running.

Step 8: Distribution shape, are your km skewed?

skewness() and kurtosis() reveal the shape of your pace distribution:

$skewness = Stat::skewness($paces, 4);
$kurtosis = Stat::kurtosis($paces, 4);

echo "Skewness: " . $skewness . PHP_EOL;
echo "Kurtosis: " . $kurtosis . PHP_EOL;

Output:

Skewness: 0.0481
Kurtosis: -0.9316

How to interpret the results:

Skewness near zero (0.05) means your pace distribution is approximately symmetric. You did not have a long tail of slow km or fast km — the variation was balanced.
Negative kurtosis (-0.93) means your pace values are more uniformly spread out than a normal distribution, fewer km clustered tightly around the mean, and the extremes are not very extreme. This is typical for a hilly course where terrain forces variation.
If your skewness were strongly positive (> 0.5), it would mean a tail of slow km, possibly from steep climbs or late-run fatigue. A negative skewness would mean a tail of fast km, perhaps starting too fast.

Step 9: Confidence interval, what is your true pace?

Your 10 km give you an average pace, but with more data (more km), that average would stabilize. The confidence interval tells you the range where your "true" comfortable pace likely falls:

$ci = Stat::confidenceInterval($paces, 0.95, 0);
$sem = Stat::sem($paces, 1);

echo "95% CI: " . Format::secondsToTime($ci[0]) . "/km to "
    . Format::secondsToTime($ci[1]) . "/km" . PHP_EOL;
echo "Standard Error of the Mean: " . $sem . " sec" . PHP_EOL;

Output:

95% CI for your true pace: 0:05:24/km to 0:05:40/km
Standard Error of the Mean: 4.1 sec

How to interpret the results:

We are 95% confident that your true comfortable pace for this effort level and course profile is between 5:24/km and 5:40/km.
The SEM of 4.1 seconds is the engine behind this interval. With only 10 km, there's meaningful uncertainty. On a half-marathon (21 km), the SEM would shrink to about 2.8 seconds, and on a marathon (42 km) to about 2 seconds — your confidence interval would become very tight.
This is useful for race planning: instead of saying "I run 5:32/km pace", you can say "my pace is 5:24–5:40/km on this type of terrain" — a more honest and useful estimate.

Step 10: Multi-run trend analysis, are you getting faster?

The most powerful analysis comes from loading multiple GPX files across weeks or months. Each run gives you an average pace, and over time, you can see the trend.

Here we simulate 8 weeks of training data:

$weeks = [1, 2, 3, 4, 5, 6, 7, 8];
$weeklyPaces = [350, 342, 337, 333, 330, 328, 326, 325];

$trendReg = Stat::linearRegression($weeks, $weeklyPaces);
$trendR2 = Stat::rSquared($weeks, $weeklyPaces, false, 4);
$trendCorr = Stat::correlation($weeks, $weeklyPaces);

echo "Trend regression: pace = " . round($trendReg[0], 2)
    . " x week + " . round($trendReg[1], 1) . PHP_EOL;
echo "R-squared: " . $trendR2 . PHP_EOL;
echo "Correlation: " . round($trendCorr, 4) . PHP_EOL;

Output:

Trend regression: pace = -3.39 x week + 349.1
R-squared:        0.9176
Correlation:      -0.9579
Improvement rate:  3.4 seconds/km per week

Predicted pace at week 12: 0:05:08/km
(Extrapolation — use with caution!)

How to interpret the results:

The slope (-3.39) means you're improving by about 3.4 seconds per km per week on average. That's meaningful and measurable progress.
R-squared of 0.92 means the linear model explains most of the variance, but not all of it. The remaining 8% hints that the improvement pattern isn't perfectly linear — there's curvature in the data.
The negative correlation (-0.96) confirms weeks going up while pace goes down — exactly what improvement looks like.
The prediction for week 12 (5:08/km) is an extrapolation. Linear trends don't continue forever — you won't reach 0:00/km eventually. But for short-term planning (next 2–3 weeks), the projection can be a reasonable target.

Why linear regression can be misleading for athletic improvement

The linear model predicts a constant improvement of 3.4 seconds per week, forever. Taken to the extreme, it would eventually predict a pace of 0:00/km, which is obviously impossible. The real issue is more subtle: athletic improvement follows a diminishing returns curve. Early gains come fast (beginner effect, neuromuscular adaptation), but as you get fitter, each additional second of improvement requires more training volume and specificity.

Look at the data closely: the improvements become progressively smaller, from week 1 to week 2 is 8 seconds, but from week 7 to week 8 it's only 1 second. The rate is clearly slowing down, a pattern that linear regression cannot capture because it assumes a constant slope. This is why the linear R² (0.9176) leaves room for improvement.

Logarithmic regression, modeling the plateau

The logarithmicRegression() method fits the model y = a × ln(x) + b, which naturally produces fast initial improvement that gradually flattens:

// Logarithmic model: pace = a * ln(week) + b
$logReg = Stat::logarithmicRegression($weeks, $weeklyPaces);
$logWeeks = array_map(fn($v) => log($v), $weeks);
$logR2 = Stat::rSquared($logWeeks, $weeklyPaces, false, 4);

echo "Logarithmic regression: pace = " . round($logReg[0], 2)
    . " x ln(week) + " . round($logReg[1], 1) . PHP_EOL;
echo "R-squared: " . $logR2 . PHP_EOL;

Output:

Logarithmic regression: pace = -12.33 x ln(week) + 350.2
R-squared:              0.9987

The logarithmic model has a much higher R² (0.9987 vs 0.9176), indicating that it fits the observed data substantially better than the linear model for this dataset.

A note about this simple example: with only 8 points, extremely high R² is easy to obtain.

This suggests that the relationship is likely nonlinear: improvement appears rapid initially and then slows over time, a pattern consistent with diminishing returns. While the linear model already provides a strong fit (R² ≈ 0.92), the much higher R² for the logarithmic model indicates that accounting for curvature captures the structure of the data more accurately.

Comparing the predictions

The difference becomes clear when you project forward:

$linearPrediction = $trendReg[0] * 12 + $trendReg[1];
$logPrediction = $logReg[0] * log(12) + $logReg[1];

echo "Linear prediction week 12:      " . Format::secondsToTime($linearPrediction) . "/km" . PHP_EOL;
echo "Logarithmic prediction week 12:  " . Format::secondsToTime($logPrediction) . "/km" . PHP_EOL;

Output:

Linear prediction week 12:      0:05:08/km
Logarithmic prediction week 12: 0:05:20/km

The logarithmic model predicts 5:20/km, 12 seconds more conservative than the linear model's 5:08/km. At week 20 the gap widens further: the linear model would predict 4:41/km (unlikely for most recreational runners), while the logarithmic model predicts 5:13/km, a more realistic plateau.

Which model should you use?

Aspect	Linear	Logarithmic
Model	`pace = a × week + b`	`pace = a × ln(week) + b`
Assumes	Constant improvement forever	Fast early gains, gradual plateau
Short-term (4 weeks)	Good approximation	Good approximation
Long-term (12+ weeks)	Over-optimistic	More realistic
Best for	Short training blocks, beginners with stable gains	Multi-month planning, experienced runners
R² on this data	0.9176	0.9987

Recommendation: compare R² values for both models on your own data. If the logarithmic R² is higher, your improvement is already following a curve and the logarithmic model will give more trustworthy projections. If R² values are similar, you're still in the early "linear" phase of improvement — but use the logarithmic model for any prediction beyond 4–6 weeks.

All four models compared — letting the numbers decide

Rather than assuming which model fits best, let's run all four regression types on the same data and compare them objectively. The package provides logarithmicRegression(), powerRegression(), and exponentialRegression() alongside linearRegression() — each fits a different curve shape:

// Linear: pace = a * week + b
[$aLin, $bLin] = Stat::linearRegression($weeks, $weeklyPaces);
$r2Lin = Stat::rSquared($weeks, $weeklyPaces, false, 4);

// Logarithmic: pace = a * ln(week) + b
[$aLog, $bLog] = Stat::logarithmicRegression($weeks, $weeklyPaces);
$logWeeks = array_map(fn($v) => log($v), $weeks);
$r2Log = Stat::rSquared($logWeeks, $weeklyPaces, false, 4);

// Power: pace = a * week^b
[$aPow, $bPow] = Stat::powerRegression($weeks, $weeklyPaces);
$logPaces = array_map(fn($v) => log($v), $weeklyPaces);
$r2Pow = Stat::rSquared($logWeeks, $logPaces, false, 4);

// Exponential: pace = a * e^(b * week)
[$aExp, $bExp] = Stat::exponentialRegression($weeks, $weeklyPaces);
$r2Exp = Stat::rSquared($weeks, $logPaces, false, 4);

Output:

Model             R²       Week 12    Week 20    Week 52
─────────────────────────────────────────────────────────
Linear            0.9176   0:05:08    0:04:41    0:02:53
Logarithmic       0.9987   0:05:20    0:05:13    0:05:02
Power             0.9985   0:05:20    0:05:14    0:05:03
Exponential       0.9232   0:05:09    0:04:45    0:03:27

The R² column settles it without any assumptions:

Logarithmic (R² = 0.9987) and Power (R² = 0.9985) are virtually tied and both fit the data near-perfectly. They capture the curvature that the other two models miss.
Linear (R² = 0.9176) and Exponential (R² = 0.9232) leave about 8% of the variance unexplained — they force a shape that doesn't match the data's natural curve.

But R² only measures how well a model fits past data. The prediction columns reveal which models are trustworthy for the future:

At week 20, linear predicts 4:41/km and exponential predicts 4:45/km — both assume improvement keeps accelerating at nearly the same rate. For a recreational runner who started at 5:50/km, breaking 5:00/km in just 20 weeks is ambitious; breaking 4:45 is unrealistic.
At week 52 (one year), linear predicts 2:53/km — faster than the world record marathon pace (2:50/km for Kelvin Kiptum's 2:00:35). Exponential predicts 3:27/km. Both are absurd for the same runner.
Logarithmic and Power predict 5:02/km and 5:03/km at week 52 — a realistic plateau where the runner has improved by about 48 seconds over a year and further gains require significantly more effort.

The logarithmic and power models converge on nearly identical predictions because they both model the same fundamental pattern: fast early gains that asymptotically flatten. For running pace data, either is a sound choice. Logarithmic is slightly simpler to interpret (the coefficient a directly tells you "seconds of improvement per unit of ln(week)"), which is why we recommend it as the default for trend analysis.

Visualizing the models: why the curve matters more than the fit

These charts plot each model's forecast beyond the training data, so you can see at a glance where the predictions stay realistic and where they drift into fantasy.

The chart below shows all four models fitted to the same training data. The actual pace values (blue dots) end at week 8 — everything beyond is a prediction. Notice how the linear and exponential lines keep diving, while the logarithmic and power curves flatten into a realistic plateau.

Linear

The straight line fits the training period reasonably well, but projects an impossible pace of 2:53/km at week 52 — a reminder that constant improvement is a mathematical fiction.

Logarithmic

The curve mirrors how runners actually improve: rapid early gains that gradually flatten, predicting a realistic 5:02/km plateau after one year of training.

Power

Nearly indistinguishable from the logarithmic model, the power curve confirms the diminishing-returns pattern, two different equations arriving at the same truth.

Exponential

Slightly better than linear but still too optimistic, the exponential model bends just enough to look plausible in the short term while still predicting an unrealistic 3:27/km at week 52.

Linear VS Logarithmic

When we isolate the two best-fitting models, the difference becomes subtle over the training period but significant in the projection zone. Both track the actual data closely through week 8, but the linear model keeps promising improvement that will never come.

Loading real GPX files

To implement this with real GPX files, load each file, compute the average pace, and build your arrays:

$gpxFiles = glob('runs/2025-*.gpx');
$weeks = [];
$weeklyPaces = [];

foreach ($gpxFiles as $i => $file) {
    $trackpoints = parseGpx($file);
    $splits = buildKmSplits($trackpoints);
    [$paces] = Arr::extract($splits, ['pace']);
    $weeks[] = $i + 1;
    $weeklyPaces[] = Stat::mean($paces);
}

// Compare both models
$linear = Stat::linearRegression($weeks, $weeklyPaces);
$logarithmic = Stat::logarithmicRegression($weeks, $weeklyPaces);

What to look for when you analyze your own runs

Run the example and then try it with your own GPX files. Here's what to watch for:

CV below 5%: your pacing is disciplined. Above 8%: investigate what's causing the variation (hills? starting too fast?).
Elevation slope: track this number over months. As your hill strength improves, each meter of climb should cost fewer seconds.
Cardiac drift slope: a lower bpm/km slope means better aerobic fitness and hydration. Compare this across similar runs.
Z-scores: any km with |z| > 2 deserves investigation — was it a genuine outlier (stoppage, cramp) or a terrain feature?
Week-over-week trend: a negative slope means improvement. Plateaus are normal; a positive slope (getting slower) may signal overtraining or insufficient recovery.

The complete example

The full script with all helper functions and simulated data is available in the repository. You can run it with:

php examples/article-gpx-running-analysis.php

Source: examples/article-gpx-running-analysis.php

Summary of the package features used

Class	Method	What it does
`Stat`	`mean()`, `median()`, `stdev()`	Basic descriptive statistics on pace, HR, elevation
`Stat`	`quantiles()`, `percentile()`	Pace distribution — where do your km fall?
`Stat`	`coefficientOfVariation()`	Single number for pacing consistency
`Stat`	`correlation()`	Elevation vs pace, HR vs pace, HR vs time
`Stat`	`linearRegression()`	Quantify hill cost, cardiac drift rate, improvement trend
`Stat`	`logarithmicRegression()`	Model diminishing returns (pace improvement plateau)
`Stat`	`powerRegression()`, `exponentialRegression()`	Alternative non-linear trend models
`Stat`	`rSquared()`	How well does elevation/time explain your pace?
`Stat`	`zscores()`	Flag unusual km segments
`Stat`	`outliers()`, `iqrOutliers()`	Detect anomalous km (stops, sprints)
`Stat`	`skewness()`, `kurtosis()`	Distribution shape of your pace
`Stat`	`confidenceInterval()`, `sem()`	Estimate your true pace range
`Freq`	`frequencyTableBySize()`	Heart rate zone distribution
`Arr`	`extract()`	Extract columns from split data
`Format`	`secondsToTime()`	Human-readable pace and time formatting

Install it and start exploring your own runs:

composer require hi-folks/statistics

Exploring Olympic Downhill Results with PHP Statistics

Roberto B. — Fri, 20 Feb 2026 20:57:54 +0000

When Franjo von Allmen crossed the finish line in 111.61 seconds at the 2026 Olympic Downhill, he claimed gold. But the raw leaderboard only tells part of the story. How dominant was his performance? How tightly packed was the field? Were there outliers that skewed the results?

With the hi-folks/statistics PHP package, you can answer these questions using the same statistical tools that data scientists rely on, right from your PHP code.

In this article, we will walk through a real step-by-step analysis of the 2026 Olympic Men's Downhill race results.

Installing the package

composer require hi-folks/statistics

The package requires PHP 8.2+, and you can find the sources here on GitHub: https://github.com/Hi-Folks/statistics.

The data

We start with the official race results, 34 athletes, each with a name and finish time in seconds:

$results = [
    ["name" => "Franjo von ALLMEN", "time" => 111.61],
    ["name" => "Giovanni FRANZONI", "time" => 111.81],
    ["name" => "Dominik PARIS", "time" => 112.11],
    // ... 28 more athletes ...
    ["name" => "Dmytro SHEPIUK", "time" => 120.11],
    ["name" => "Cormac COMERFORD", "time" => 124.4],
];

$times = array_column($results, "time");

I extracted the times into a flat array so we can feed them into the statistical functions.

The full PHP example and the full PHP data array are here: https://github.com/Hi-Folks/statistics/blob/main/examples/article-downhill-ski-analysis.php

Step 1: Descriptive statistics, understanding the shape of the data

Before building any model, we need to understand the raw numbers. The Stat class gives us the essential summary in a few lines:

use HiFolks\Statistics\Stat;

$mean = Stat::mean($times);
$median = Stat::median($times);
$std = Stat::stdev($times);
$quartiles = Stat::quantiles($times);

Output:

echo "Sample size: " . count($times) . PHP_EOL;
echo "Mean time: " . round($mean, 2) . " seconds" . PHP_EOL;
echo "Median time: " . round($median, 2) . " seconds" . PHP_EOL;
echo "Standard deviation: " . round($std, 2) . " seconds" . PHP_EOL;
echo "Min: " .
    $min .
    "s | Max: " .
    $max .
    "s | Range: " .
    round($range, 2) .
    "s" .
    PHP_EOL;
echo "Quartiles (Q1, Q2, Q3): " .
    round($quartiles[0], 2) .
    "s, " .
    round($quartiles[1], 2) .
    "s, " .
    round($quartiles[2], 2) .
    "s" .
    PHP_EOL;
/**
Sample size: 34
Mean time:   114.38 seconds
Median time: 113.60 seconds
Std dev:     2.60 seconds
Min: 111.61s | Max: 124.4s | Range: 12.79s
Quartiles (Q1, Q2, Q3): 112.95s, 113.60s, 114.77s
*/

A few things stand out immediately:

The mean (114.38) is higher than the median (113.60). In a perfectly symmetric distribution, these two values are identical. When the mean is noticeably higher, it signals that the data is right-skewed; a few slow times are pulling the average up.
The range is 12.79 seconds, which is enormous for a downhill race. Most athletes finished within a 3-second window (Q1 to Q3: 112.95 to 114.77), but the tail extends to 124.4 seconds (this kind of data, like timing in a downhill competition, depends on the events that occur during the race).
The standard deviation is 2.60 seconds. This single number summarizes how spread out the results are. We will use it extensively in the next steps.

The Stat::quantiles() method divides the data into four equal groups. The result tells us that 25% of athletes finished under 112.95s (Q1), 50% under 113.60s (Q2/median), and 75% under 114.77s (Q3).

Step 1b: Robust central tendency

The mean (114.38s) is pulled upward by a few slow finishers — Comerford at 124.4s alone adds almost a full second of bias. The trimmed mean solves this by removing a fraction of the extreme values from each end before computing the average:

$trimmedMean10 = Stat::trimmedMean($times, 0.1, 2);
$trimmedMean20 = Stat::trimmedMean($times, 0.2, 2);

echo "Regular mean:       " . round(Stat::mean($times), 2) . "s" . PHP_EOL;
echo "Trimmed mean (10%): " . $trimmedMean10 . "s" . PHP_EOL;
echo "Trimmed mean (20%): " . $trimmedMean20 . "s" . PHP_EOL;
/**
Regular mean:       114.38s
Trimmed mean (10%): 113.91s
Trimmed mean (20%): 113.76s
*/

The trimmedMean() method takes a $proportionToCut parameter, the fraction to remove from each side. With 0.1, we remove the 3 fastest and 3 slowest athletes (10% of 34 from each end), and the result drops by almost half a second. With 0.2, it drops further to 113.76s — much closer to the median (113.60s).

This tells us something important: the "typical" downhill time is closer to 113.8s than to 114.4s. The regular mean overstates it because of the tail. When you want a single number to describe "how fast did most athletes go?", the trimmed mean is a better answer.

Step 1c: Percentile analysis

Quartiles divide the data into 4 groups. But sometimes you want more precision "what time do you need to be in the top 10%?" The percentile() method lets you query any point on the distribution:

echo "P10: " . Stat::percentile($times, 10, 2) . "s — elite threshold" . PHP_EOL;
echo "P25: " . Stat::percentile($times, 25, 2) . "s — top quarter" . PHP_EOL;
echo "P50: " . Stat::percentile($times, 50, 2) . "s — median" . PHP_EOL;
echo "P75: " . Stat::percentile($times, 75, 2) . "s — bottom quarter" . PHP_EOL;
echo "P90: " . Stat::percentile($times, 90, 2) . "s — struggling" . PHP_EOL;
/**
P10: 112.21s — elite threshold
P25: 112.95s — top quarter
P50: 113.6s — median
P75: 114.77s — bottom quarter
P90: 118.2s — struggling
*/

Notice the gap between P75 (114.77s) and P90 (118.2s), over 3 seconds. Compare that to the gap between P10 (112.21s) and P25 (112.95s), less than a second. This asymmetry is the right skew we saw earlier, now quantified: the bottom of the field is much more spread out than the top.

Step 1d: Precision of the mean

How precise is our mean of 114.38s? With only 34 athletes, there is some uncertainty. The "Standard Error of the Mean (SEM)" quantifies this:

$sem = Stat::sem($times, 2);
echo "SEM: " . $sem . "s" . PHP_EOL;
echo "95% confidence interval: "
    . round(Stat::mean($times) - 1.96 * $sem, 2) . "s to "
    . round(Stat::mean($times) + 1.96 * $sem, 2) . "s" . PHP_EOL;
/**
SEM: 0.45s
95% confidence interval: 113.51s to 115.25s
*/

The SEM is the standard deviation divided by the square root of the sample size: stdev / sqrt(n). With 34 athletes, we can estimate that the "true" mean time for this course and field falls within roughly ±0.87s of our calculated mean, at 95% confidence.

Step 2: Fitting a normal distribution

The normal distribution (the classic bell curve) is one of the most widely used models in statistics. It is defined by just two parameters: the mean (mu) and the standard deviation (sigma). The NormalDist class lets you build one directly from your data:

use HiFolks\Statistics\NormalDist;

$normal = NormalDist::fromSamples($times);
echo "mu (mean): " . $normal->getMeanRounded(2);     // 114.38
echo "sigma (std dev): " . $normal->getSigmaRounded(2); // 2.60

The fromSamples() method calculates both parameters from the data and returns a NormalDist object. From this point forward, you can ask probabilistic questions about the distribution.

Checking the fit: model median vs actual median

A quick sanity check: in a perfect normal distribution, the mean, median, and mode are all equal. We can verify this with getMedian():

echo "Model median: " . $normal->getMedianRounded(2); // 114.38
echo "Actual median: " . round($median, 2);            // 113.60

The model median is 114.38 (equal to the mean, as expected), but the actual median is 113.60, a gap of 0.78 seconds. This confirms what we suspected: the data is right-skewed, and the normal distribution is not a perfect fit.

This is an important lesson: a normal distribution assumes symmetry. When your data has a long tail in one direction (as race results often do), the model will be an approximation. It is still useful for insight, but you should be aware of its limitations.

Step 3: Asking probabilistic questions

Once you have a NormalDist object, you can ask questions that would be difficult to answer from raw data alone.

"What percentage of racers finished under 113 seconds?"

The Cumulative Distribution Function (CDF) answers exactly this. It returns the probability that a random value from the distribution falls at or below a given point:

$target = 113.0;
$probUnder = $normal->cdfRounded($target, 4);
echo "Model: P(time <= 113s) = " . round($probUnder * 100, 1) . "%";
// Model: 29.8%

The model predicts 29.8%. The actual count is 9 out of 34 athletes (26.5%). The gap is a direct consequence of the skewness we identified earlier: the inflated mean shifts the entire curve to the right, making the model slightly overestimate the proportion of fast finishers.

"How likely is a time of exactly 113 seconds?"

The Probability Density Function (PDF) gives the relative likelihood of a specific value:

echo "PDF at 113s = " . $normal->pdfRounded(113.0, 6);
// 0.133488

The PDF value is not a probability (it can exceed 1.0 for narrow distributions), but it lets you compare how likely different times are relative to each other. A higher PDF value means that time is more "typical" for this distribution.

Step 4: Performance thresholds with the inverse CDF

The Inverse CDF works backwards: given a probability, it returns the corresponding value. This is perfect for setting performance thresholds:

$eliteThreshold = $normal->invCdfRounded(0.2, 2);
$slowThreshold = $normal->invCdfRounded(0.8, 2);
echo "Top 20% fastest (below): " . $eliteThreshold; // 112.19
echo "Slowest 20% (above): " . $slowThreshold;       // 116.56

According to the model, a time under 112.19 seconds would place an athlete in the top 20%, while a time above 116.56 seconds would place an athlete in the slowest 20%. In practice, only 3 out of 34 athletes (about 9%) broke the 112.19s barrier, another sign that the skewness pushes the model's "elite" threshold to an unrealistically fast time.

Step 5: Z-scores, measuring performance in standard deviations

The z-score expresses a value as the number of standard deviations away from the mean. Negative z-scores mean faster than average, positive means slower:

$z = $normal->zscoreRounded(111.61, 2); // -1.06

Von Allmen's gold-medal time has a z-score of -1.06; he finished about one full standard deviation faster than the average racer. Here is how the z-scores look across the field:

Franjo von ALLMEN     111.61s   z: -1.06   Elite
Giovanni FRANZONI     111.81s   z: -0.99   Elite
Dominik PARIS         112.11s   z: -0.87   Elite
Marco ODERMATT        112.31s   z: -0.80   Strong
...
Jan ZABYSTRAN         114.39s   z: +0.01   Average
...
Cormac COMERFORD      124.40s   z: +3.86   Below avg

Z-scores are powerful because they are universal and comparable. A z-score of -1.06 means the same thing whether you are analyzing ski times, exam scores, or manufacturing tolerances. Comerford's z-score of +3.86 immediately flags him as an extreme outlier, nearly 4 standard deviations from the mean.

Step 5b: Outlier detection

Looking at the z-scores, Comerford's +3.86 stands out dramatically. But how do we systematically identify outliers instead of eyeballing them? The package provides two methods, each with different strengths.

Method 1: Z-score based detection

The outliers() method flags values whose absolute z-score exceeds a threshold. The default is 3.0 (the classic "three sigma rule"), but for a small dataset like ours, 2.5 is more practical:

$zscoreOutliers = Stat::outliers($times, 2.5);
foreach ($zscoreOutliers as $time) {
    echo "  " . $time . "s" . PHP_EOL;
}
/**
  124.4s
*/

Only Comerford is flagged. The z-score method relies on the mean and standard deviation, and here's the catch, "the outliers themselves inflate the stdev", making it harder to detect them. It's a bit like asking a group that includes a giant "is anyone unusually tall?", the giant's height raises the average, making everyone seem more normal.

Method 2: IQR-based detection (box plot whiskers)

The iqrOutliers() method uses the Interquartile Range, which is based on quartiles, not the mean. This makes it robust: outliers don't influence the detection mechanism.

A value is flagged if it falls below Q1 - 1.5 * IQR or above Q3 + 1.5 * IQR:

$iqrOutliers = Stat::iqrOutliers($times);
foreach ($iqrOutliers as $time) {
    echo "  " . $time . "s" . PHP_EOL;
}
/**
  119.24s
  120.11s
  124.4s
*/

The IQR method catches three outliers: Opmanis (119.24s), Shepiuk (120.11s), and Comerford (124.4s). These are the athletes whose times are far enough from the main pack to fall outside the "whiskers" of a box plot.

This is the key difference:

Z-score detection: assumes a roughly normal distribution, sensitive to the outliers themselves
IQR detection: makes no distributional assumptions, robust to extreme values

For skewed data like race results, IQR is generally the better choice.

Step 6: Classifying athletes into tiers

Combining the CDF with custom thresholds, we can classify every athlete into a performance tier:

$tierDefinitions = [
    ["max" => 0.20, "label" => "Elite"],
    ["max" => 0.50, "label" => "Strong"],
    ["max" => 0.80, "label" => "Average"],
    ["max" => 1.00, "label" => "Below avg"],
];

foreach ($results as $r) {
    $percentile = $normal->cdf($r['time']);

    $tier = "Below avg";
    foreach ($tierDefinitions as $def) {
        if ($percentile <= $def['max']) {
            $tier = $def['label'];
            break;
        }
    }

    $z = $normal->zscoreRounded($r['time'], 2);
    echo $r['name'] . " " . $r['time'] . "s  " . $tier . "  z: " . $z;
}

The CDF returns the percentile rank of each athlete within the model. An athlete at the 15th percentile (like Franzoni) has, according to the model, 85% of the distribution above them. Combined with the z-score, you get a complete picture: tier for quick classification, z-score for precise measurement.

Step 7: Visualizing the distribution with a frequency table

A frequency table groups data into classes and counts how many values fall into each class. The Freq class makes this straightforward:

use HiFolks\Statistics\Freq;

$freqTable = Freq::frequencyTableBySize($times, 1);
foreach ($freqTable as $class => $count) {
    echo $class . "s " . str_repeat("*", $count) . " (" . $count . ")";
}

Output:

111s  ** (2)
112s  ****** (6)
113s  ************ (12)
114s  ******** (8)
115s  * (1)
116s   (0)
117s  ** (2)
118s   (0)
119s  * (1)
120s  * (1)
124s  * (1)

The histogram reveals the story: a dense core of athletes between 111-115 seconds, then a gap, then a handful of stragglers trailing off to 124 seconds. This is the right skew in plain sight. A perfect bell curve would be symmetric around the mean; this clearly is not.

Step 8: Measuring the shape of the distribution with skewness and kurtosis

In Step 7 the frequency table hinted at something: the results are not symmetric.
There is a dense core of fast times on the left, and a long tail stretching right toward 124 seconds. But how asymmetric is the distribution, exactly? And how extreme are those outliers?

Two statistics answer these questions: skewness and kurtosis.

Skewness measures asymmetry. A value of 0 means perfectly balanced. Positive means the tail extends to the right; negative means it extends to the left.

Kurtosis (excess) measures tailedness. How much data lives in the extreme tails compared to a normal distribution. A value of 0 means normal-like tails. Positive means heavier tails with more extreme outliers.

use HiFolks\Statistics\Stat;

$skewness = Stat::skewness($times, 4);
// 2.3114

$kurtosis = Stat::kurtosis($times, 4);
// 6.3361

A skewness of 2.31 confirms what the frequency table showed visually: most racers finished with similar times clustered together, but a handful of really slow finishers (119s, 120s, 124s) drag the average up. The results are not balanced around the middle, there is a long tail of slow times on the right side.

A kurtosis of 6.34 tells us something extra that the frequency table alone could not: those slow finishers are not just a little slow, they are very far from the pack. The gap between the main group and the slowest racers is much larger than you would expect in a typical bell curve. The results have extreme outliers.

Together, these two numbers paint a clear picture: the race had a tight competitive group up front, and a few athletes who were significantly off the pace, making the distribution lopsided (skewness) with extreme stragglers (kurtosis).

The skewness() method uses the adjusted Fisher-Pearson formula, the same used by Excel's SKEW() and Python's scipy.stats.skew(bias=False).
The kurtosis() method returns the excess kurtosis, matching Excel's KURT() and Python's scipy.stats.kurtosis(bias=False).

Step 9: Dispersion beyond standard deviation

The standard deviation (2.60s) tells us how spread out the times are, but it's heavily influenced by the slow outliers. Are the times really that spread out, or is it just a few athletes pulling the number up?

Two alternative measures give us a clearer picture:

$stdev    = Stat::stdev($times, 4);
$mad      = Stat::meanAbsoluteDeviation($times, 4);
$medianAD = Stat::medianAbsoluteDeviation($times, 4);

echo "Standard deviation:       " . $stdev . "s" . PHP_EOL;
echo "Mean Absolute Deviation:  " . $mad . "s" . PHP_EOL;
echo "Median Absolute Deviation: " . $medianAD . "s" . PHP_EOL;
/**
Standard deviation:       2.5974s
Mean Absolute Deviation:  1.7056s
Median Absolute Deviation: 0.88s
*/

The Mean Absolute Deviation (1.71s) uses absolute differences instead of squared ones, so it's less sensitive to extreme values. It tells us "on average, athletes finish about 1.7 seconds from the mean."
The Median Absolute Deviation (0.88s) goes further, it measures the median distance from the median, making it highly resistant to outliers. It tells us the "core pack" of athletes is within about 1 second of each other.

The gap between stdev (2.60s) and median absolute deviation (0.88s) is striking. It reveals that the field has two distinct groups: a tightly packed main group separated by less than a second, and a handful of stragglers who inflate the traditional dispersion measures.

Step 10: Coefficient of Variation — comparing race tightness

How tight was this race? Standard deviation alone doesn't answer this, because it depends on the scale. A stdev of 2.6s means something very different in a 2-minute downhill than in a 30-second sprint.

The Coefficient of Variation (CV) expresses dispersion as a percentage of the mean, making it comparable across different events:

$cvFull  = Stat::coefficientOfVariation($times, 2);
$top10   = array_slice($times, 0, 10);
$cvTop10 = Stat::coefficientOfVariation($top10, 2);

echo "Full field CV: " . $cvFull . "%" . PHP_EOL;
echo "Top 10 CV:     " . $cvTop10 . "%" . PHP_EOL;
/**
Full field CV: 2.27%
Top 10 CV:     0.45%
*/

A CV of 2.27% means the times vary by about 2.3% around the mean, a relatively tight field. But the top 10 is five times tighter at just 0.45%. This quantifies what every ski fan knows intuitively: at the top, hundredths of a second matter. The margin between gold and 10th place (1.59s) is tiny compared to the margin between 10th and last (11.2s).

You could use CV to compare across sports or across different race editions: "Was the 2026 downhill tighter than 2022?"

Step 11: Weighted median — focus on the contenders

In a race analysis, not all athletes carry equal weight. The top-seeded racers are the main contenders, their times define the competitive field. The weightedMedian() method lets us give more importance to specific athletes:

$weights = [];
foreach ($results as $i => $r) {
    $weights[] = $i < 15 ? 3.0 : 1.0; // top-15 seeded athletes weighted 3x
}
$wMedian = Stat::weightedMedian($times, $weights, 2);

echo "Regular median:  " . round(Stat::median($times), 2) . "s" . PHP_EOL;
echo "Weighted median: " . $wMedian . "s" . PHP_EOL;
/**
Regular median:  113.6s
Weighted median: 113.28s
*/

The weighted median (113.28s) is lower than the regular median (113.60s) because we're giving triple weight to the top 15 athletes, whose times cluster in the faster range. This answers a different question: "What does a competitive time look like?", as opposed to "What does the typical time look like?"

This is useful for race analysis, but also in any domain where observations have different importance: survey responses with population weights, financial data with volume weights, or sensor readings with reliability weights.

When the normal distribution works (and when it doesn't)

The normal distribution is a great starting point for exploratory analysis, but it assumes symmetry. In our race data:

The mean (114.38s) diverges from the median (113.60s) by 0.78 seconds
The model predicts 29.8% of racers under 113s, while the actual figure is 26.5%
Extreme outliers (Comerford at z = +3.86) have disproportionate influence on the model

This happens because Olympic downhill races have a natural lower bound (you can only ski so fast) but no upper bound (injuries, mistakes, and less experienced athletes create a long right tail).

For data like this, consider:

Using the median and quartiles (from Stat::median() and Stat::quantiles()) for robust summary statistics that are not affected by outliers
Trimming outliers before fitting the distribution, removing the slowest 3-4 finishers, would dramatically improve the normal fit for the competitive core
Exploring other distributions in future analysis (log-normal distributions often fit race times better, as they naturally handle the right-skew)

That said, even an imperfect normal model gave us actionable insights: z-scores, percentile-based tiers, and probability estimates that go far beyond a simple leaderboard.

The complete example

The full script is available in the repository at examples/norm_dist.php. You can run it with:

php examples/norm_dist.php

Summary of the package features used

Class	Method	What it does
`Stat`	`mean()`, `median()`, `stdev()`	Basic descriptive statistics
`Stat`	`quantiles()`	Divide data into equal-probability intervals
`NormalDist`	`fromSamples()`	Build a normal distribution from raw data
`NormalDist`	`getMedian()`	Model median (equals mean for normal dist)
`NormalDist`	`cdf()`	Probability of a value or lower
`NormalDist`	`pdf()`	Relative likelihood of a specific value
`NormalDist`	`invCdf()`	Find the value for a given probability
`NormalDist`	`zscore()`	Standard deviations from the mean
`Freq`	`frequencyTableBySize()`	Group data into classes for histograms
`Stat`	`trimmedMean()`	Mean after removing outliers from each side
`Stat`	`percentile()`	Value at any percentile (0–100)
`Stat`	`weightedMedian()`	Median with weighted observations
`Stat`	`sem()`	Standard error of the mean
`Stat`	`coefficientOfVariation()`	Relative dispersion as a percentage (CV%)
`Stat`	`meanAbsoluteDeviation()`	Average distance from the mean
`Stat`	`medianAbsoluteDeviation()`	Median distance from the median (robust)
`Stat`	`zscores()`	Z-score for each value in the dataset
`Stat`	`outliers()`	Z-score based outlier detection
`Stat`	`iqrOutliers()`	IQR-based outlier detection (box plot whiskers)

Install it and start exploring your own data:

composer require hi-folks/statistics

Programming in the Age of AI: From Code to Intent

Roberto B. — Fri, 13 Feb 2026 22:07:05 +0000

I was building an AI agent in PHP, wiring up tools, feeding it project documentation, defining how it should interact with the codebase, when a thought stopped me mid-keystroke.

I was writing instructions for an AI, in a language designed for humans, using conventions invented so human brains could follow the logic.

And I thought: why are we still doing this?

Programming languages were designed for us humans:

Clear instructions if, while, for.
Indentation for our eyes.
Mnemonics for our memory.
Clean APIs so we can reason about behavior.
Design patterns so we don’t forget how systems are structured.

But now AI is writing the code.

AI doesn’t need mnemonics. It doesn’t get confused by nested brackets. It doesn’t get fatigued by verbosity. It can hold an entire codebase in context.

So the question feels inevitable: "Should we create a programming language optimized for AI instead of for humans?"
I think the answer is yes.

But not in the way most people expect.

The Pattern We Keep Repeating

Look at the history of how we talk to machines:

1950s: Humans write machine code. Raw numbers. Only a handful of experts can do it.
1960s: Assembly arrives. Still low-level, but now we see MOV and ADD instead of opcodes.
1980s–90s: C, Java, Python. We stop thinking about registers and memory addresses. We write for user in users and let the compiler handle the rest.
Today: We write PHP, Python, TypeScript. AI assists us. But we still write code line by line.

Notice the pattern?

Each generation moves humans further from the machine and closer to pure intent.

Nobody writes assembly today. Not because it stopped working, it’s still there under everything you use. We just stopped reading it. It became an intermediate representation.

Code is about to become the next assembly.

The Three Layers of the Future

Here’s what I think is emerging.

Layer 1: Humans Write Intent

I expect we will not have code, but we will have specifications. Constraints. Business rules. Performance requirements. Security guarantees.

Instead of:

if ($user->isAuthenticated()) { ... }

We define something like:

Authenticated users can save preferences.
Maximum 100 preferences per user.
Response time under 200ms.
Backwards compatible with the v2 API.

This looks less like code and more like a contract.

Programming becomes the act of defining what must be true, not how to make it true.

Layer 2: AI Generates Code

PHP, Python, Rust, they don’t disappear.
The ecosystems are too valuable. The runtimes, the libraries, the decades of optimization. AI writes in these languages because that’s where the infrastructure lives.

But humans read this code less and less.

Just like you don’t read the assembly output of your C compiler, you won’t read every line of AI-generated PHP.

Code becomes an implementation detail.

Layer 3: Machines Verify Correctness

This is the critical piece, if humans stop reviewing every line, how do we trust the output?
The answer isn’t “trust the AI more.”

It’s verification.

Strong type systems
Contract checking
Property-based testing
Static analysis
Formal verification tools
Automated proofs that the implementation matches the specification

The AI-optimized “language” isn’t a new syntax for writing loops.

It’s a rigorous way to describe intent, and to mathematically or systematically verify that generated code satisfies it.

The future of programming isn’t about generating code faster. It’s about proving code correct automatically.

Why This Matters Now

We’re in an awkward transition period.

AI writes code, but humans still review it line by line.
That’s like reviewing assembly output in 1995. Technically possible. Not where the value is.

The developers who will thrive aren’t the ones who type the fastest.

They’re the ones who:

Define precise specifications
Express constraints clearly
Build strong verification systems
Design architectures that are easy to validate

The skill is shifting:

From “How do I implement this algorithm?” → to “How do I define what correct means?”
From “Let me debug this code.” → to “Let me define constraints so bugs can’t exist.”
From writing instructions for machines → to writing intent for AI.

What This Means for Junior Developers (and People Starting Today)

There’s an uncomfortable question hidden in all this:

If AI writes most of the code in the future, is learning programming still worth it?

Yes. More than ever.

Understanding programming logic is not about memorizing syntax. It’s about understanding:

Control flow
Data structures
State
Side effects
Performance trade-offs
System design
Failure modes

If you understand how machines think, you can describe intent more precisely.

You know what the machine expects.
You know what can go wrong.
You know where ambiguity hides.

And that makes you dramatically more effective when collaborating with AI.
The abstraction layer may rise. But understanding what’s underneath remains a superpower.

There’s another practical reason this matters today.

If the future depends on verification and coherence, then the habits we adopt now become critical:

Use strict typing.
Write automated tests.
Use static analysis tools.
Enforce consistent architecture.
Keep code uniform and predictable.

Why?

Because coherent, well-structured codebases are easier for AI to understand, extend, and reason about.

If tomorrow AI generates 100% of the code, consistency will reduce:

Errors
Misunderstandings
Hidden edge cases
Bias introduced by unclear patterns

Clean, strictly typed, well-tested systems are not just “good engineering.”
They are AI-ready systems.

Learning programming today is not obsolete. It’s training for a higher level of abstraction tomorrow.

The Real Singularity in Software

The singularity isn’t AI writing code.
That’s already happening.
The real shift is the moment when code becomes an intermediate representation that nobody reads, just like assembly before it.
When that happens, “programming” won’t mean writing PHP or Python.

It will mean writing intent.

The language changes. The skill doesn’t.

It has always been about turning human intent into working machines.

We’re just removing one more layer of translation.

If you’re already using AI tools such as Copilot, Claude, Cursor, or others, have you already noticed the shift?

Less mental energy on syntax. More on defining what you actually want.

And the uncomfortable question:

When was the last time you read every line of AI-generated code before shipping it?

Are we ready to let code become the next assembly?

Or are we holding on because we’re not ready to trust what we can’t read?

State of JS 2025: Popular Syntax Features Explained with PHP Equivalents

Roberto B. — Sat, 07 Feb 2026 19:15:19 +0000

The State of JS is an annual developer survey that captures how thousands of JavaScript developers feel about the language, its ecosystem, and the features they use most, from syntax and tooling to frameworks and testing.

I was reading The State of JS 2025 survey and landed on the Syntax Features section. One question caught my attention:

Which of these syntax features have you used?

It made me curious. Not just why these features are popular in JavaScript, but also:

Do we have something similar in PHP?

So I turned this into a small personal exercise:

Understand the most-used/appreciated JavaScript syntax features
Look for their closest equivalents in PHP
Explain them with some examples

This article is the result of that cozy Saturday exploration.

A JavaScript to PHP walkthrough, written with curiosity rather than comparison wars.

1. Nullish Coalescing

Nullish coalescing allows you to provide a default value that is used only when a variable is truly missing (null or undefined).

JavaScript

Nullish Coalescing operator (??) provides a default value, but only when the original one is truly missing.

const someEmpty = null;
const foo = someEmpty ?? "default string";
console.log(foo); // "default string"

Here, someEmpty is null, so JavaScript falls back to 'default string'.

const zeroValue = 0;
const baz = zeroValue ?? 42;
console.log(baz); // 0

In this case, 0 is a perfectly valid value. Even though it’s falsy, it’s not null or undefined, so JavaScript keeps it.

That’s the real power of nullish coalescing: it lets you distinguish between "no value at all" and "a value that just happens to be falsy".

PHP Equivalent

PHP introduced the null coalescing operator in PHP 7.0, and it behaves almost identically.

$someEmpty = null;
$foo = $someEmpty ?? 'default string';
echo $foo; // "default string"

$zeroValue = 0;
$baz = $zeroValue ?? 42;
echo $baz; // 0

PHP behaves exactly the same way here. The null coalescing operator follows the same rules and the same mental model as JavaScript, making it immediately familiar if you’re coming from a JS background.

2. Dynamic Import

JavaScript

Dynamic imports are especially useful in JavaScript applications because the code itself has to be downloaded. By loading modules only when they are actually needed, dynamic imports help keep the initial download small, improve startup time, and reduce the amount of JavaScript shipped to the browser.

await import('/modules/my-module.js');

This makes features like code splitting and lazy loading first‑class citizens in modern frontend development.

PHP Equivalent (Conceptual)

PHP applications work very differently. The code runs on the server and does not need to be downloaded by the client, which makes dynamic imports far less critical from a performance perspective.

PHP loads files synchronously and doesn’t have a promise‑based model like JavaScript, but it still supports composing functionality at runtime:

require_once __DIR__ . '/modules/my-module.php';

In modern PHP applications, this is usually handled by autoloading. With Composer’s autoloader, classes are loaded automatically when they are referenced without requiring an explicit import via require_once:

$service = new App\Service\MyService();

While this isn’t a direct equivalent of JavaScript’s dynamic import(), PHP’s autoloading mechanism plays an important role in modern applications. It ensures that classes are loaded only when they are actually used, keeping the codebase modular and avoiding unnecessary includes, even though the underlying performance concerns differ from those in JavaScript.

3. Private Properties

JavaScript

Private properties prevents access to class internals from the outside.

class ClassWithPrivateField {
  #privateField = 42;

  getValue() {
    return this.#privateField;
  }
}

Trying to access instance.#privateField will throw an error.

PHP Equivalent

PHP has supported private properties for a long time.

class ClassWithPrivateField {
    private int $privateField = 42;

    public function getValue(): int {
        return $this->privateField;
    }
}

This gives you strong encapsulation that’s enforced at runtime. While JavaScript’s # syntax is relatively new, the idea itself will feel very familiar to PHP developers who have relied on private properties for years.

4. Logical Assignment Operators

JavaScript

Logical assignment operators assign values conditionally using logical operators.

const a = { duration: 50, title: '' };

a.duration ||= 10;
console.log(a.duration); // 50

a.title ||= 'title is empty.';
console.log(a.title); // "title is empty"

In JavaScript, the ||= operator assigns a new value only if the left-hand side is falsy. That means values like false, 0, '', null, or undefined will all trigger the assignment. It’s a convenient shorthand when you want to guarantee a usable value, but it’s important to remember that it doesn’t distinguish between “missing” values and intentionally falsy ones.

PHP Equivalent

PHP doesn’t offer a direct ||= operator, but the underlying pattern is very familiar. A common way to express it is by reassigning the value using the ternary shortcut ?:.

$a = [
    'duration' => 50,
    'title' => ''
];

$a['duration'] = $a['duration'] ?: 10;
echo $a['duration']; // 50

Since 50 is truthy, PHP keeps the original value.

$a['title'] = $a['title'] ?: 'title is empty.';
echo $a['title']; // "title is empty"

Here, the empty string is considered falsy (becasue is a zero length string ''), so PHP falls back to the default.

It’s worth noting that PHP’s ?: behaves like JS’s ||=, it assigns a new value when the current one is falsy, including 0, false, '', or null.
If you want behavior closer to JS’s ??=, where only truly missing values trigger the assignment, the null coalescing operator ??= is the right choice.

Since PHP 7.4 (released in 2019), PHP has had the closest equivalent to JavaScript's ??=: the null coalescing assignment operator ??=. It assigns a value only if the variable is not set or is null, leaving all other values untouched.

$a['title'] ??= 'title is empty.';

This mirrors JS's ??= behavior almost exactly and is usually the best choice when you want to provide a default only for missing values.

5. Iterator Methods

Modern JavaScript makes working with sequences of data super convenient thanks to helper methods like map, filter, and reduce, which can be applied to arrays — and, in some cases, even iterators.

JavaScript Example

const numbers = [1, 2, 3, 4, 5];

// Square the numbers, then keep only the even results, then sum them
const result = numbers
  .map(x => x * x)
  .filter(x => x % 2 === 0)
  .reduce((sum, x) => sum + x, 0);

console.log(result); // 20 -> (4 + 16)

Here’s what happens step by step:

.map squares each number → [1, 4, 9, 16, 25]
.filter keeps only even numbers → [4, 16]
.reduce sums them → 20

PHP Equivalent

While the fluent approach can improve readability, sometimes you can realize that the same logic can be implemented with a single loop, like this:

$result = 0;

foreach ($numbers as $number) {
  if ($number % 2 !== 0) {
    continue;
  }
$result += $number * $number;
}

But if you want to find in PHP something similar to the previous JavaScript example, PHP has the functions for map, filter, and reduce an array:

$numbers = [1, 2, 3, 4, 5];

// Step 1: square the numbers
$squared = array_map(fn($x) => $x * $x, $numbers);

// Step 2: filter the even ones
$evenSquares = array_filter($squared, fn($x) => $x % 2 === 0);

// Step 3: sum them
$result = array_reduce($evenSquares, fn($sum, $x) => $sum + $x, 0);

echo $result; // 20

PHP 8.5 introduced the pipe operator |>, so you can chain those functions:

$numbers = [1, 2, 3, 4, 5];

$result = $numbers
    |> (fn($arr) => array_map(fn($x) => $x * $x, $arr))
    |> (fn($arr) => array_filter($arr, fn($x) => $x % 2 === 0))
    |> (fn($arr) => array_reduce($arr, fn($sum, $x) => $sum + $x, 0));

echo $result; // 20

Same JavaScript concept, slightly different syntax:

array_map = JS .map
array_filter = JS .filter
array_reduce = JS .reduce

The pipe operator in PHP 8.5 passes only one value forward. Since array_map, array_filter, and array_reduce take multiple arguments, they need a small wrapper function to fit into the pipeline (fn($arr) =>).

If you want a fluent approach like JS, you can evaluate using one of the open-source packages (just to say that in PHP, you have a lot of options).

PHP Equivalent with the Open-Source PHP Array Package

Using the PHP Array Package library, we can achieve a similar chainable, fluent syntax in PHP.

To install the package:

composer require hi-folks/array

Once you have installed the package, you can start using it:

<?php

require "./vendor/autoload.php";

use HiFolks\DataType\Arr;


$result = Arr::make([1, 2, 3, 4, 5])
    ->map(fn($x) => $x * $x)
    ->filter(fn($x) => $x % 2 === 0)
    ->reduce(fn($sum, $x) => $sum + $x, 0);

echo $result; // 20 -> (4 + 16)

The PHP Array Package is available here: https://github.com/Hi-Folks/array

This package makes PHP feel almost like JavaScript here, letting you map, filter, and reduce in a single, readable chain.

6. Hashbang Grammar

JavaScript

Hashbang grammar specifies the interpreter for executable scripts.

#!/usr/bin/env node

console.log("Hello world");

This directove #!/usr/bin/env node allows JS files to be executed directly from the CLI.

To make the script executable:

chmod +x script.js
./script.js

If you want to specify bun instead of node:

#!/usr/bin/env bun

console.log("Hello world");

Hashbang grammar is technically a shell feature rather than a JavaScript-specific one. It allows a script to declare which executable should run it by specifying the interpreter (such as node) on the first line of the file.

PHP Equivalent

PHP is supported as well:

#!/usr/bin/env php
<?php

echo "Hello world";

7. `error.cause`

JavaScript

It preserves the original error when rethrowing.

try {
  try {
    throw new Error("EXCEPTION 1");
  } catch (err) {
    throw new Error("EXCEPTION 2", { cause: err });
  }
} catch (err) {
  console.log(err.message); // EXCEPTION 2
  console.log(err.cause.message); // EXCEPTION 1
}

This makes debugging and error tracing much easier.

PHP Equivalent

PHP supports exception chaining natively.

try {
    try {
        throw new Exception("EXCEPTION 1");
    } catch (Exception $err) {
        throw new Exception("EXCEPTION 2", 0, $err);
    }
} catch (Exception $err) {
    echo $err->getMessage(); // EXCEPTION 2
    echo $err->getPrevious()->getMessage(); // EXCEPTION 1
}

You can later access the original exception:

$exception->getPrevious();

This is one area where PHP has been ahead for quite some time.

Final Thoughts

This little exercise wasn’t about proving that one language is better than the other.

It was about:

Exploring the most loved JS features by JavaScript developers (thanks to the survey)
Appreciating how many of these ideas already exist in PHP
Seeing how languages keep learning from each other

Most of the time, the concepts are the same, only the syntax changes.

If you enjoyed this kind of cross-language comparison, feel free to share your thoughts or suggest another feature set to explore next. Happy coding! 🚀

Laravel & Storyblok: Enabling the Real-Time Visual Editor

Roberto B. — Thu, 05 Feb 2026 21:15:52 +0000

This article presents an opinionated yet effective approach to integrating Laravel with Storyblok, focusing on practical decisions that unlock a real-time visual editing experience.

When you think of headless CMS integrations with real-time visual editing, frameworks like React, Vue, or Next.js usually come to mind. But what if I told you that Laravel with Blade templates can deliver the same seamless visual editing experience?

In this article, I'll walk you through how to integrate Storyblok's Visual Editor with Laravel, complete with real-time preview updates and smart DOM diffing to eliminate flickering. No JavaScript framework required.

Why Laravel + Storyblok?

Before diving into the code, let's address the elephant in the room: "Isn't Storyblok designed for JavaScript frameworks?"

Not at all. Storyblok is framework-agnostic. While the most common documentation emphasizes React and Vue, the underlying APIs work with any technology that can:

Fetch JSON from an API
Render HTML
Execute JavaScript in the browser

Laravel excels at all three. Plus, you get:

Server-side rendering out of the box (great for SEO and GEO)
Blade's elegant templating syntax
No hydration issues (a common pain point with SSR frameworks)
Simpler deployment compared to Node.js applications (but this is my opinion based on my personal experience, probably if you are a devop engineer with Node skill, you will think differently)

But here is my opinion. Ready?

There's a reason Laravel keeps winning.

It's not just about elegant syntax or good documentation. It's about the ecosystem. Laravel has become a complete platform for building scalable, production-grade applications, with first-class packages for nearly everything you need.

Specifically, for content-driven frontends, you get Blade components that render fast and deploy anywhere. But here's what most developers miss: Laravel is now a serious platform for AI integration. Libraries like Laravel AI and Neuron AI let you build intelligent agents, connect to LLMs, and add AI-powered features without leaving the ecosystem you already know. And with NativePHP, you can ship native desktop and mobile apps using the same Laravel codebase.

Laravel isn't just for building websites. It's for building channels like kiosks, mobile applications, AI-powered assistants, and everything in between.

This matters for what we're about to build. A headless CMS integration isn't just about rendering pages. It's about creating a content layer that can feed your website today, your mobile app tomorrow, and your AI agent next month. Laravel handles all of it.

Now, let's talk about visual editing.

The Architecture

Here's how the integration works:

┌──────────────────────────────────────────────────────────────────┐
│                         Storyblok CMS                            │
│                    ┌────────────────────┐                        │
│                    │   Visual Editor    │                        │
│                    └─────────┬──────────┘                        │
│                       ┌──────┴──────┐                            │
│              Preview URL            Real-time events             │
│                       │             │                            │
└───────────────────────┼─────────────┼────────────────────────────┘
                        │             │
                        ▼             ▼
┌──────────────────────────────────────────────────────────────────┐
│                      Laravel Application                         │
│                                                                  │
│   ┌───────────────────┐         ┌───────────────────────────┐    │
│   │  StoryController  │         │    Storyblok Bridge       │    │
│   │  POST /api/preview│         │    (JavaScript)           │    │
│   └─────────┬─────────┘         └─────────────┬─────────────┘    │
│             │                                 │                  │
│             │        ┌────────────────────────┘                  │
│             │        │  fetch('/api/preview')                    │
│             │        │  + Idiomorph DOM diffing                  │
│             ▼        ▼                                           │
│   ┌───────────────────────────────────────────────────────────┐  │
│   │                    Blade Components                       │  │
│   │                                                           │  │
│   │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐  │  │
│   │  │hero-section │ │ grid-card   │ │ image (responsive)  │  │  │
│   │  └─────────────┘ └─────────────┘ └─────────────────────┘  │  │
│   │  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐  │  │
│   │  │  richtext   │ │article-page │ │ newsletter-form     │  │  │
│   │  └─────────────┘ └─────────────┘ └─────────────────────┘  │  │
│   │                                                           │  │
│   └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Two flows from the Visual Editor:

Preview URL → When you open a page in the Visual Editor, Storyblok loads your Laravel app via the configured preview URL. The StoryController fetches the story and renders it with Blade components.
Real-time events → As editors make changes, the Storyblok Bridge (JavaScript) receives events, sends the updated story JSON to /api/preview. The Preview controller renders the json with blade components and the JS receive the updated HTML and uses Idiomorph to update only the changed DOM elements.

Step 1: Setting up the Laravel project

Start with a fresh Laravel installation:

laravel new storyblok-laravel
cd storyblok-laravel

Install the Storyblok PHP SDK (for Content Delivery API):

composer require storyblok/php-content-api-client

Add your Storyblok credentials to .env:

STORYBLOK_ACCESS_TOKEN=your_preview_token_here
STORYBLOK_VERSION=draft

In config/serivces.php file add the Storyblok configuration:

    'storyblok' => [
        'access_token' => env('STORYBLOK_ACCESS_TOKEN'),
        'version' => env('STORYBLOK_VERSION', 'published'),
    ],

Step 2: Enable HTTPS for local development

Storyblok's Visual Editor requires your preview URL to be served over HTTPS, even during local development. This is a security requirement because the editor runs inside Storyblok's iframe, and modern browsers block mixed content.

The easiest solution is to use Vite's mkcert plugin with a proxy to your Laravel backend.

Install the mkcert plugin:

bun add -d vite-plugin-mkcert
# or if you prefer to use npm:
# npm install -D vite-plugin-mkcert

Update your vite.config.js:

import { defineConfig } from "vite";
import laravel from "laravel-vite-plugin";
import tailwindcss from "@tailwindcss/vite";
import mkcert from "vite-plugin-mkcert";

const host = "127.0.0.1";
const port = "8000";

export default defineConfig({
    plugins: [
        mkcert(),
        laravel({
            input: ["resources/css/app.css", "resources/js/app.js"],
            refresh: true,
        }),
        tailwindcss(),
    ],
    server: {
        https: true,
        proxy: {
            "^(?!(\/\\@vite|\/resources|\/node_modules))": {
                target: `http://${host}:${port}`,
            },
        },
        host,
        port: 5173,
        hmr: { host },
        watch: {
            ignored: ["**/storage/framework/views/**"],
        },
    },
});

How this works:

Use mkcert 127.0.0.1 to create a proper certificate and key for enabling SSL
Vite serves your frontend at https://127.0.0.1:5173
The proxy forwards all non-Vite requests to Laravel running at http://127.0.0.1:8000
You get HTTPS for the Visual Editor + hot module replacement for development

Start both servers:

composer run dev

Now configure your Storyblok space's Preview URL to:

https://127.0.0.1:5173/story/

Note: The first time you visit the HTTPS URL, your browser will warn about the self-signed certificate. Click "Advanced" → "Proceed" to accept it. You only need to do this once per browser session.

Step 3: Create the Storyblok Service Provider

// app/Providers/StoryblokServiceProvider.php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Storyblok\Api\StoriesApi;
use Storyblok\Api\StoryblokClient;

class StoryblokServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        $this->app->singleton(StoryblokClient::class, function ($app) {
            return new StoryblokClient(
                "https://api.storyblok.com/v2/cdn/",
                config("services.storyblok.access_token"),
            );
        });

        $this->app->singleton(StoriesApi::class, function ($app) {
            return new StoriesApi(
                $app->make(StoryblokClient::class),
                config("services.storyblok.version"),
            );
        });
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        //
    }
}

Step 4: The Story Controller

The controller handles both regular page loads and preview requests:

// app/Http/Controllers/StoryController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Storyblok\Api\StoriesApi;
use Storyblok\Api\Request\StoryRequest;

class StoryController extends Controller
{
    public function __construct(private StoriesApi $storiesApi) {}

    public function show(string $slug = "home")
    {
        $response = $this->storiesApi->bySlug($slug, new StoryRequest());
        return view("story", ["story" => $response->story]);
    }

    public function preview(Request $request)
    {
        $story = $request->input("story");

        if (!$story) {
            return response()->json(["error" => "No story provided"], 400);
        }

        return view("story", ["story" => $story]);
    }
}

The preview method is the key to real-time editing. When editors make changes in Storyblok, the Visual Editor sends the updated story JSON to this endpoint, and we return freshly rendered HTML.

Step 5: Dynamic component rendering

Create a component resolver that maps Storyblok component names to Blade views:

{{-- resources/views/components/storyblok/component.blade.php --}}
@props(['blok'])

@php
    $componentName = str_replace('_', '-', $blok['component'] ?? 'unknown');
@endphp

@if(View::exists('components.storyblok.' . $componentName))
    <x-dynamic-component :component="'storyblok.' . $componentName" :blok="$blok" />
@else
    <div class="alert alert-warning">
        <span>Component "{{ $componentName }}" not found</span>
    </div>
@endif

Now creating components is straightforward. Here's an example hero section:

{{-- resources/views/components/storyblok/hero-section.blade.php --}}
@props(['blok'])

<section {!! \App\Services\StoryblokEditable::attributes($blok) !!}
         class="hero min-h-[500px] bg-base-200">
    <div class="hero-content flex-col lg:flex-row gap-8">
        @if(!empty($blok['image']['filename']))
            <x-storyblok.image
                :image="$blok['image']"
                sizes="(max-width: 640px) 100vw, 384px"
                :widths="[384, 512, 640, 768]"
                :ratio="4/3"
                class="max-w-sm rounded-lg shadow-2xl"
                loading="eager"
                fetchpriority="high"
            />
        @endif

        <div>
            <h1 class="text-5xl font-bold">{{ $blok['headline'] ?? '' }}</h1>
            @if(!empty($blok['text']))
                <p class="py-6">{{ $blok['text'] }}</p>
            @endif
        </div>
    </div>
</section>

Notice the StoryblokEditable::attributes($blok) call. This adds the data-blok-c and data-blok-uid attributes that Storyblok's Visual Editor needs to identify which component you're clicking on.

Step 6: The Storyblok Bridge (where the magic happens)

Here's the JavaScript that enables real-time preview:

{{-- resources/views/components/storyblok/bridge.blade.php --}}
@if(request()->has('_storyblok') || request()->has('_storyblok_tk'))
<script src="https://unpkg.com/idiomorph@0.7.4/dist/idiomorph.min.js"></script>
<script>
    (function() {
        const script = document.createElement('script')
        script.src = 'https://app.storyblok.com/f/storyblok-v2-latest.js'
        script.async = true
        script.onload = function() {
            const storyblokInstance = new window.StoryblokBridge()

            async function updatePreview(story) {
                try {
                    const response = await fetch('/api/preview', {
                        method: 'POST',
                        headers: {
                            'Content-Type': 'application/json',
                        },
                        body: JSON.stringify({ story }),
                    })
                    const html = await response.text()
                    const parser = new DOMParser()
                    const doc = parser.parseFromString(html, 'text/html')
                    const newMain = doc.querySelector('main')
                    const currentMain = document.querySelector('main')

                    if (newMain && currentMain) {
                        Idiomorph.morph(currentMain, newMain, {
                            morphStyle: 'innerHTML',
                            ignoreActiveValue: true,
                            // head: { style: 'merge' }
                        })
                    }
                } catch (error) {
                    console.error('Preview error:', error)
                }
            }

            storyblokInstance.on('input', (event) => {
                if (event.story) {
                    updatePreview(event.story)
                }
            })

            storyblokInstance.on(['published', 'change'], () => {
                window.location.reload()
            })
        }
        document.head.appendChild(script)
    })()
</script>
@endif

Why Idiomorph?

The naive approach would be:

currentMain.innerHTML = newMain.innerHTML

But this causes flickering because every element gets destroyed and recreated, even if nothing changed. Images reload, animations restart, and form inputs lose focus.

Idiomorph (created by the htmx team) performs intelligent DOM diffing. It:

Only updates elements that actually changed
Preserves focus on form inputs
Keeps CSS animations running
Doesn't reload unchanged images

The result? Buttery smooth real-time preview.

Step 7: A responsive image component

Storyblok includes a powerful Image Service that can resize, crop, and optimize images on the fly. Let's create a component that leverages it:

{{-- resources/views/components/storyblok/image.blade.php --}}
@props([
    'image',
    'sizes' => '100vw',
    'widths' => [400, 600, 800, 1200, 1600, 2000],
    'ratio' => null,
    'class' => '',
    'loading' => 'lazy',
    'fetchpriority' => null,
    'quality' => 80,
    'smart' => false,
])

@php
    $filename = $image['filename'] ?? '';
    $alt = $image['alt'] ?? '';
    $title = $image['title'] ?? '';
    $focus = $image['focus'] ?? '';

    if (empty($filename)) {
        return;
    }

    /**
     * Build Storyblok Image Service URL
     * @see https://www.storyblok.com/docs/api/image-service
     *
     * Format: {filename}/m/{width}x{height}/smart/filters:{filter1}:{filter2}
     * - /m/ prefix enables WebP conversion
     * - {width}x{height} for resize (use 0 for auto, e.g., 800x0)
     * - /smart for smart cropping (face detection)
     * - /filters:focal(x,y) for focal point cropping
     * - /filters:quality(0-100) for compression
     */
    $buildUrl = function ($width) use ($filename, $ratio, $focus, $quality, $smart) {
        $height = $ratio ? round($width / $ratio) : 0;
        $dimensions = "{$width}x{$height}";

        $url = "{$filename}/m/{$dimensions}";

        // Add smart cropping if enabled (uses face detection)
        if ($smart && $height > 0) {
            $url .= "/smart";
        }

        // Build filters
        $filters = [];

        // Focal point filter (only applies when cropping, i.e., height > 0)
        // Storyblok focus format: "leftX:leftY:rightX:rightY" or "pointX:pointY"
        if ($focus && $height > 0 && !$smart) {
            $filters[] = "focal({$focus})";
        }

        // Quality filter
        if ($quality && $quality < 100) {
            $filters[] = "quality({$quality})";
        }

        if (!empty($filters)) {
            $url .= "/filters:" . implode(':', $filters);
        }

        return $url;
    };

    // Build srcset with multiple widths
    $srcset = collect($widths)->map(function ($width) use ($buildUrl) {
        return "{$buildUrl($width)} {$width}w";
    })->implode(', ');

    // Default src (medium size fallback)
    $defaultWidth = $widths[2] ?? 800;
    $src = $buildUrl($defaultWidth);
@endphp

@if($filename)
<img
    src="{{ $src }}"
    srcset="{{ $srcset }}"
    sizes="{{ $sizes }}"
    alt="{{ $alt }}"
    @if($title) title="{{ $title }}" @endif
    @if($loading) loading="{{ $loading }}" @endif
    @if($fetchpriority) fetchpriority="{{ $fetchpriority }}" @endif
    decoding="async"
    @class([$class])
/>
@endif

This component:

Generates a srcset with multiple resolutions
Respects Storyblok's focal point for smart cropping
Applies quality optimization
Uses lazy loading by default
Supports fetchpriority="high" for LCP images

💡 Hint: once you understand the dynamics of rendering the image via the Storyblok Image Service with PHP, you can evaluate using this package in your project: https://github.com/storyblok/php-image-service

Step 8: Rich Text Rendering

Storyblok stores rich text as a JSON document structure. Here's a service to convert it to HTML:

// app/Services/StoryblokRichtext.php
<?php

namespace App\Services;

class StoryblokRichtext
{
    public static function render(array|null $content): string
    {
        if (!$content) return '';
        return self::renderNode($content);
    }

    private static function renderNode(array $node): string
    {
        $type = $node['type'] ?? '';
        $content = '';

        foreach ($node['content'] ?? [] as $child) {
            $content .= self::renderNode($child);
        }

        return match ($type) {
            'doc' => $content,
            'paragraph' => "<p>{$content}</p>",
            'heading' => "<h{$node['attrs']['level']}>{$content}</h{$node['attrs']['level']}>",
            'bullet_list' => "<ul>{$content}</ul>",
            'ordered_list' => "<ol>{$content}</ol>",
            'list_item' => "<li>{$content}</li>",
            'blockquote' => "<blockquote>{$content}</blockquote>",
            'text' => self::renderText($node),
            default => $content,
        };
    }

    private static function renderText(array $node): string
    {
        $text = e($node['text'] ?? '');

        foreach ($node['marks'] ?? [] as $mark) {
            $text = match ($mark['type']) {
                'bold' => "<strong>{$text}</strong>",
                'italic' => "<em>{$text}</em>",
                'link' => "<a href=\"{$mark['attrs']['href']}\">{$text}</a>",
                default => $text,
            };
        }

        return $text;
    }
}

You can use the render function in a dedicated component:

{{-- resources/views/components/storyblok/richtext.blade.php --}}
@props(['content'])

{!! \App\Services\StoryblokRichtext::render($content) !!}

Then, in the components where you have the richtext field, you can call the richtext component in this way:

        @if(!empty($blok['text']))
            <div class="prose prose-lg max-w-none">
                <x-storyblok.richtext :content="$blok['text']" />
            </div>
        @endif

💡 Hint: once you understand the dynamics of rendering the richtext editor with PHP, you can evaluate using this package in your project: https://github.com/storyblok/php-tiptap-extension

The Result

With this setup, you get:

Real-time visual editing - Changes appear instantly as editors type
No flickering - Idiomorph ensures smooth updates
Click-to-edit - Click any component to edit it in Storyblok
SEO-friendly - Server-rendered HTML, no client-side hydration
Fast page loads - No JavaScript framework overhead
Optimized images - Responsive images with automatic WebP conversion

An opinionated comparison to React/Vue Implementations

Aspect	React/Vue	Laravel + Blade
Initial page load	Requires hydration	Instant render
Bundle size	50-200KB+	~8KB (idiomorph + bridge)
SEO	Requires SSR setup	Built-in
Deployment	Node.js required	Standard PHP hosting
Learning curve	Framework-specific	Familiar Blade syntax
Real-time preview	Native support	Works great with bridge

Conclusion

You don't need React or Vue to build a first-class Storyblok integration. Laravel's Blade templating, combined with a lightweight JavaScript bridge and smart DOM diffing, delivers an excellent visual editing experience.

The key insights:

The Storyblok Bridge is just JavaScript: it works in any browser, regardless of your backend
Server-rendered HTML is fine: just POST the story JSON and return HTML
Idiomorph eliminates flickering: smart diffing makes updates feel native
Blade components map naturally: Storyblok's component model fits perfectly with Blade

Give it a try. Your content editors will love the real-time preview, and you'll love the simplicity of staying in the Laravel ecosystem.

Resources:

Have questions? Drop a comment below or find me on Twitter/X.

How to deprecate PHP code without breaking your users

Roberto B. — Sun, 25 Jan 2026 10:39:51 +0000

Removing old code from your project or library without breaking existing users is tricky. This guide shows you how to deprecate PHP methods, classes, and parameters the right way.

If you maintain a library, an SDK, or even a shared internal package, you eventually hit this moment:

You realize that something you shipped months (or years) ago is no longer the right API.

The abstraction may be wrong. The constructor should replace a factory. Maybe a “convenience” method turned out to be a long-term design mistake.

Whatever the reason, the uncomfortable truth is:

Good APIs evolve. And evolution means change.

But changing public APIs is dangerous. People build businesses on top of them. Coworkers build systems on top of them. Breaking them casually is how you lose trust.

Over time, I’ve adopted the same approach used by some open-source PHP projects: deprecate first, remove later.

This is how I do it in practice.

What deprecation actually means

When I mark something as deprecated in my code in my projects, I’m not immediately deleting it. I’m saying:

The method still works
The method is still callable
The users are warned that they should stop using it
And I have a proper way to tell users what to use instead

Deprecation is a promise that defines a migration path. In other words, it is a way to say “This still works today, but it won’t forever. Here’s how to migrate.”

This gives your users time. It gives you freedom to evolve. And it makes your API predictable and trustworthy.

This is a good practice, also used in other programming languages. I remember when I used Java (using the @deprecated tag in the JavaDoc comments) or the "deprecated" decorator in Python. Also, in the PHP world, the Symfony ecosystem uses this practice. If you’ve ever upgraded a Symfony or Laravel app across major versions, you’ve benefited from this discipline, whether you noticed it or not.

A real example from an SDK

Let’s say I originally had an API like this:

$client->assetApi($spaceId);

Later, I realize that a more explicit and composable API is better:

new AssetApi($managementApiClient, $spaceId);

I don’t want to break existing users. But I do want to push everyone toward the new design.

So I deprecate the old method.

What a properly deprecated method looks like

Here’s the pattern I use (and yes, this is basically what some other PHP open-source projects do internally):

/**
 * @deprecated since 1.1, use new AssetApi($managementApiClient, $spaceId) instead
 * @codeCoverageIgnore
 */
public function assetApi(string|int $spaceId): AssetApi
{
    trigger_error(
        'Method assetApi() is deprecated since 1.1 and will be removed in 2.0. '
        . 'Use new AssetApi($managementApiClient, $spaceId) instead.',
        E_USER_DEPRECATED
    );

    return new AssetApi($this, $spaceId);
}

This combines three layers:

PHPDoc @deprecated, IDEs and static analysis tools pick this up immediately
trigger_error() with E_USER_DEPRECATED, emits a runtime warning so users see it in logs or test output
@codeCoverageIgnore, optional, but useful if your deprecated code isn't worth covering

Let’s break down why this is such a powerful pattern.

1. The `@deprecated` PHPDoc tag (for humans and tools)

/**
 * @deprecated since 1.1, use ...
 */

This PHPDoc tag is not just documentation:

IDEs will highlight usages
Static analyzers (PHPStan, Psalm) will warn
Code reviewers will see it immediately

This is your "development-time" signal.

2. Triggering a runtime deprecation

trigger_error(..., E_USER_DEPRECATED);

Why it matters:

Users see deprecation warnings in development
CI can fail on deprecations if configured
The tests can raise a warning or fail on deprecation according to the test framework configuration
It makes deprecated usage visible even if nobody reads the docs

3. Always tell people what to use instead

'deprecated since 1.1 and will be removed in 2.0', use new AssetApi(...) instead.'

A deprecation without a migration path is just frustration for users.

A good deprecation message answers:

What is deprecated?
Since when?
When will it be removed?
What should I use instead?

This builds trust and makes upgrades predictable.

4. The deprecated method becomes a thin compatibility layer

When you deprecate a method, the worst thing you can do is copy its old logic in the new refactored method and keep maintaining it in parallel.

Instead, whenever possible, the deprecated method should simply delegate to the new implementation.

In this example, the deprecated method just uses the new initialization logic:

return new AssetApi($this, $spaceId);

This has several significant benefits:

No duplicated logic to maintain
No risk of subtle behavioral differences between old and new code
Any bug fix or improvement automatically applies to both paths

In practice, the old API becomes a thin compatibility layer that forwards to the new one.

This is the strategy used by other PHP open-source projects to preserve backward compatibility without freezing the architecture in time.

PHP 8.4+: the native `#[Deprecated]` attribute

If your project uses PHP 8.4 or later, you can simplify this using the native #[Deprecated] attribute:

/**
 * @deprecated since 1.1, use new AssetApi($managementApiClient, $spaceId) instead
 * @codeCoverageIgnore
 */
#[Deprecated(
    message: 'use new AssetApi($managementApiClient, $spaceId) instead',
    since: '1.1'
)]
public function assetApi(string|int $spaceId): AssetApi
{
    return new AssetApi($this, $spaceId);
}

The benefit? No manual trigger_error(), PHP automatically emits E_USER_DEPRECATED when the method is called. Cleaner code, same result.

Keep the PHPDoc @deprecated tag alongside the attribute for full IDE and documentation support if the IDE you are using does not yet support the PHP Deprecated attribute.

PHPUnit and deprecations: some practical ways to deal with them

When you run your test suite with:

vendor/bin/phpunit

and a deprecated method is executed, PHPUnit will highlight it with a D, usually in yellow instead of green. That’s PHPUnit telling you: “Something here is using a deprecated API.”

Sometimes that’s exactly what you want. But depending on your workflow and your goals, you have a few different options.

Option 1: let PHPUnit show the `D` (the default)

The simplest approach is to do nothing.

Just run:

vendor/bin/phpunit

and let PHPUnit mark every deprecation with a yellow D.

This is useful because:

Deprecations are immediately visible
You can see if they are increasing over time
They act as a constant reminder that some migration is still pending

For many projects, this is already good enough.

Option 2: show exactly where deprecations come from

If you want more details about which code is triggering the deprecation, you can run:

vendor/bin/phpunit --display-deprecations

This will show:

The exact deprecation messages
The file and line number
Which test caused it

This is extremely useful when you’re actively cleaning up deprecated usage or during an upgrade.

Option 3: fail the test suite on deprecations

If you want to treat any usage of deprecated code as a test failure, PHPUnit can do that for you.

Enabling the failOnDeprecation option causes the test suite to fail immediately whenever a deprecation is triggered during the test run. This is a very strict mode, but it’s extremely effective at preventing the accidental use of deprecated APIs.

To enable it, add failOnDeprecation="true" to the <phpunit> element in your phpunit.xml or phpunit.xml.dist file:

<?xml version="1.0" encoding="UTF-8" ?>
<phpunit
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/12.0/phpunit.xsd"
    bootstrap="vendor/autoload.php"
    colors="true"
    cacheDirectory=".phpunit.cache"
    failOnDeprecation="true"
>

This gives you a very strong guarantee:

If the test suite is green, your code is not using any deprecated APIs.

In practice, this is especially useful for application code or libraries that want to enforce the use of new APIs strictly. For projects that still intentionally test deprecated behavior for backward compatibility, this mode can be too strict, but when you want zero tolerance, it's a great tool.
I use this when my goal is to reduce and eventually remove deprecated code from the codebase. Failing tests serve as a guide, highlighting exactly where deprecated code is still being called.

Option 4: remove the tests and ignore coverage for deprecated code

In some cases, especially in libraries and SDKs, tests also serve as documentation.

I know this approach is a bit opinionated, but I also want to share this option with you.

If you don’t want deprecated APIs to appear in your examples anymore, you can:

Remove the tests that exercise the deprecated methods
Keep only tests for the new API

At that point, the deprecated method will naturally show up as uncovered code in your coverage report. If you want to keep coverage clean and honest, you can explicitly mark it as:

/**
 * @codeCoverageIgnore
 */

This is you saying:

“This code exists only for backward compatibility. It’s not part of the active API anymore.”

There’s no single right choice

Sometimes you want visibility. Sometimes you want strictness. Sometimes you want a clean test suite that only shows the modern API.

All these approaches are valid; the critical part is to choose one intentionally, instead of letting deprecations become invisible background noise.

The deprecation lifecycle

Over time, I’ve learned that the most essential quality of a good deprecation policy is predictability. Users don’t want surprises, and they definitely don’t want to discover breaking changes by accident.

That’s why I try to keep the deprecation lifecycle simple, and predictable, for example in my last project I had:

In 1.1, the method is introduced as deprecated
In 1.x, the method still works, but it emits a warning when used
In 2.0, the method is removed entirely

This kind of timeline gives users plenty of time to adapt. It makes upgrades safer, avoids unpleasant surprises, and lets people plan migrations rather than react to sudden breakages. That’s what makes a library or platform feel reliable and professional over the long term.

When I don’t bother deprecating

If a method is new, not public, not documented, and not used by anyone, I just delete it.

Deprecation is a promise you make to users, and if there are no users, there’s no promise to keep.

I reserve deprecation for things that are actually part of a contract: public APIs, libraries, frameworks, SDKs, and shared internal platforms.

Why this matters more than you think

I care a lot about deprecation discipline because it changes the entire dynamic of how a project evolves.

When deprecations are correctly done, I can improve my APIs without fear, and users can upgrade without panic. The architecture doesn’t get stuck in the past, and the project builds long-term trust simply by being predictable.

Good deprecation practices are a quiet signal of engineering maturity. They make upgrades boring (and that’s a compliment), they remove drama from releases, and they let the codebase evolve without constantly worrying about breaking everything.

Bad deprecation practices do the opposite. They create upgrade anxiety, push users into version lock-in, and eventually force big, painful rewrites that nobody enjoys and nobody really has time for.

Additional note: how Symfony manages deprecations at scale

Large frameworks like Symfony face a challenge: as the codebase grows, deprecations multiply, and unmanaged deprecations become noise. Symfony addresses this with the symfony/phpunit-bridge package, which enhances PHPUnit with deprecation-aware behavior:

Captures all E_USER_DEPRECATED notices during test runs
Groups and summarizes them for analysis
Can enforce limits or baselines via the SYMFONY_DEPRECATIONS_HELPER environment variable (e.g., max[direct]=0 to fail on any new direct deprecation)

The guiding principle: existing deprecations are tolerated, but new ones must not slip in unnoticed.

This turns deprecations into measurable technical debt, the count should shrink over time, never grow silently.

You don't need the full PHPUnit bridge for most projects. Simply configuring your tests to fail on deprecations (e.g., failOnDeprecation="true" in PHPUnit 10+) is a practical first step toward disciplined API evolution.

Final Thought

Deprecation is not about the past. It’s about making the future safe.

If you treat deprecation as a first-class design tool, your codebase can grow for years without collapsing under its own history.

And that’s what great libraries do.

Building Real Agentic AI in PHP with Neuron AI, Gemini, and Tools

Roberto B. — Wed, 14 Jan 2026 18:34:57 +0000

Build a real tool-using AI agent that understands YouTube videos and answers questions. In pure PHP

For years, using AI in PHP meant little more than sending prompts to an API and displaying the result. Valuable, yes, but also limited, fragile, and prone to hallucinations.

Today, the industry is moving toward a new paradigm: Agentic AI.

Instead of a single prompt-response interaction, we now build agents: goal-oriented AI programs that can reason, decide when to use tools, call real code, and operate inside well-defined constraints.

And yes: PHP is absolutely ready for this.

Thanks to libraries like Neuron AI, Symfony AI, Prism, and soon Laravel AI, the PHP ecosystem is becoming a first-class platform for building production-grade AI systems.

The PHP ecosystem is becoming a first-class platform for building production-grade AI systems.

To showcase the power and practicality of this approach, we will build a concrete example: an agent that acts as an assistant, capable of answering questions about a YouTube video. To achieve this, we will give our agent the ability to fetch the video’s transcript (and we will see how easy this is to do in PHP) and then use that transcript as its source of context and knowledge.

By the end of this article, you will have an agent that you can interrogate about any specific video. Whether you want to summarize a tutorial, extract key insights, or ask precise questions about a long talk or conference recording, you will be able to do it using an agent you built yourself.

The PHP tools/libraries we are going to use for building the YouTube AI agent:

Neuron AI as the PHP agenting framework https://www.neuron-ai.dev/
Gemini as the LLM provider https://ai.google.dev/gemini-api/docs
The gemini-2.5-flash model, but of course, you can use a richer model https://ai.google.dev/gemini-api/docs/models
The PHP YouTube Transcript open-source library, designed to fetch transcripts for YouTube videos https://github.com/MrMySQL/youtube-transcript.

By the end, you’ll have an agent that can answer questions about a YouTube video using only its transcript.

What is an Agent?

An agent is a goal-driven AI program that can reason, plan, and decide when to use tools to complete a task.

In practice, an agent:

Has clear instructions
Has rules and boundaries
Has tools it can use
Can call real code
Can chain multiple steps
And can operate reliably inside constraints

This is the foundation of modern AI applications.

What is a Tool?

A Tool is a function that the AI is allowed to call.

Instead of guessing or hallucinating data, the model can:

Query your database with your current data
Call external APIs
Read files
Execute business logic
Fetch external resources

The flow becomes:

User asks a question
Agent reasons (following predefined steps and instructions)
Agent decides to call a tool
Tool executes real PHP code
Agent receives the result from the Tool
Agent uses it to answer

This is how you build reliable AI systems.

Agentic AI in the PHP Ecosystem

The PHP ecosystem has always been driven by strong, pragmatic, and highly active communities—and the current wave of AI adoption is no exception. Over the past few months, we’ve seen an increasing number of serious, well-designed libraries emerge, built by people who have a deep understanding of both PHP and real-world production needs.

Rather than treating AI as a gimmick or a thin API wrapper, these projects are focusing on architecture, maintainability, and integration into existing applications. As a result, the PHP ecosystem is evolving extremely fast to support AI more and more, and the number of available tools is growing almost every week, especially thanks to the energy of the Symfony, Laravel, and independent open-source communities.

Today, we already have excellent building blocks, such as Neuron AI, which provides a complete agent framework with tool support and orchestration; Symfony AI, which brings first-class AI integration into the Symfony ecosystem; and Prism, which offers a clean abstraction layer over different LLM providers. And this is only the beginning: a dedicated Laravel AI ecosystem is already on the way.

In this article, we’ll focus on Neuron AI, because it already offers a mature and complete Agent + Tool architecture, making it an ideal foundation for building real-world, production-grade Agentic AI systems in PHP.

Our goal: a YouTube transcript QA agent

We will build an agent that:

Accepts a YouTube video ID
Uses a specific tool to fetch the transcript (we are going to implement the Agent tool)
Answers questions using the transcript

Installation and dependencies

Before we start building our agent, we need to install a few libraries. Each of them plays a very specific role in the architecture of our application, and together they form a clean, modular, and production-ready stack.

You can install everything using Composer:

composer require neuron-core/neuron-ai
composer require mrmysql/youtube-transcript
composer require symfony/http-client nyholm/psr7
composer require vlucas/phpdotenv

Let’s briefly look at why we need each of these packages.

Neuron AI

composer require neuron-core/neuron-ai

This is the core of our system. Neuron AI provides the Agent abstraction, the Tool system, the orchestration layer, and the provider integrations (such as Gemini, OpenAI, Ollama, etc.). It is the framework that allows us to define instructions, expose tools to the model, and let the agent reason about when and how to use them. Without it, we would just be sending prompts to an API; with it, we are building a real Agentic system.

YouTube Transcript fetcher

composer require mrmysql/youtube-transcript

This library is a small but very useful utility that allows us to fetch the transcript of a YouTube video programmatically. Instead of scraping HTML or dealing with undocumented APIs ourselves, we can rely on a clean, tested PHP library. This will be the “real-world data source” that our agent will access through a tool.

Symfony HTTP Client and PSR-7 Implementation

composer require symfony/http-client nyholm/psr7

The YouTube transcript library relies on PSR-18 (HTTP client) and PSR-7 (HTTP messages) interfaces. Here, we use Symfony’s HTTP client as a robust, production-ready implementation, together with Nyholm’s PSR-7 implementation for request and response objects. This keeps everything standards-based and framework-agnostic.

PHP dotenv

composer require vlucas/phpdotenv

Finally, we use phpdotenv to load our Gemini API key from a .env file instead of hardcoding it into the source code. This is a best practice for both security and portability, and it allows us to easily change credentials between environments without touching the code.

This set of dependencies already shows an important aspect of modern PHP: we are building our AI system using small, composable, standards-based components, rather than a single monolithic library.

The complete Agent

<?php

use MrMySQL\YoutubeTranscript\TranscriptListFetcher;
use NeuronAI\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Gemini\Gemini;
use NeuronAI\SystemPrompt;
use NeuronAI\Tools\PropertyType;
use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\Psr18Client;

require "./vendor/autoload.php";

class YouTubeTranscriptQAAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
        $dotenv->load();

        return new Gemini(
            key: $_ENV["GEMINI_API_KEY"],
            model: "gemini-2.5-flash",
        );
    }

    public function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                "You are a helpful assistant that answers questions about a YouTube video using ONLY the provided transcript.",
                "You must use the tool to retrieve the transcript.",
                "If the transcript does not contain the answer, say so clearly and ask for another video id.",
                "Never use external knowledge.",
            ],
            steps: [
                "Ask the user for a YouTube video URL or ID if not provided.",
                "Call the get_transcription tool to retrieve the transcript.",
                "Read the transcript carefully.",
                "Answer the user's question strictly using the transcript.",
            ],
            output: [
                "Be concise and precise.",
                "If the transcript does not contain the answer, reply: 'The transcript does not contain this information.'",
            ],
        );
    }

    protected function tools(): array
    {
        return [
            Tool::make(
                "get_transcription",
                "Retrieve the transcription of a YouTube video.",
            )
                ->addProperty(
                    new ToolProperty(
                        name: "video_id",
                        type: PropertyType::STRING,
                        description: "The YouTube video ID (e.g. wT1lcJ_zn18).",
                        required: true,
                    ),
                )
                ->setCallable(function (?string $video_id): string {
                    if (is_null($video_id)) {
                        return "";
                    }
                    return $this->fetchTranscript($video_id);
                }),
        ];
    }

    private function fetchTranscript(string $videoId, string $language = "en"): string
    {
        $httpClient = HttpClient::create();
        $psr18Client = new Psr18Client($httpClient);
        $psr17Factory = new Psr17Factory();

        $fetcher = new TranscriptListFetcher(
            $psr18Client,
            $psr17Factory,
            $psr17Factory,
        );

        $transcriptList = $fetcher->fetch($videoId);
        $transcript = $transcriptList->findTranscript([$language]);

        $lines = [];

        foreach ($transcript->fetch() as $item) {
            $lines[] = html_entity_decode(
                $item["text"],
                ENT_QUOTES | ENT_HTML5,
                "UTF-8",
            );
        }

        return implode(PHP_EOL, $lines);
    }
}

Understanding the Agent: a guided tour of the code

Now that we’ve seen the complete implementation, let’s walk through the most important parts of the agent step by step. The goal here is not just to understand what the code does, but how the different pieces work together to form a real Agentic AI system.

1. The Agent class

class YouTubeTranscriptQAAgent extends Agent

This is the heart of the application. By extending the Agent class provided by Neuron AI, we are not building a simple wrapper around an LLM, we are defining a full AI agent with:

Its own instructions
Its own tools
Its own model provider
And its own behavior and constraints

From this point forward, Neuron AI will handle orchestration, tool invocation, and conversation flow.

2. Choosing the model provider

protected function provider(): AIProviderInterface

This method instructs Neuron AI which provider (in this case, via the Gemini class provided by Neuron AI, but you can explore other providers, such as Ollama) and which model should power the agent.

return new Gemini(
    key: $_ENV["GEMINI_API_KEY"],
    model: "gemini-2.5-flash",
);

Here, we use Gemini as a provider, but one of the strengths of Neuron AI is that this is easily swappable. The rest of the agent does not care whether you are using Gemini, OpenAI, or Ollama, the architecture stays exactly the same.

We also load the API key from a .env file, which is a best practice for security and configuration management.

3. The system prompt: the Agent’s brain

public function instructions(): string

The instructions() method defines the entire behavioral contract of the agent.

Instead of a single free-form prompt, we build a structured SystemPrompt with:

A background: what the agent is and what it must never do
A set of steps: how to approach the task
An output contract: how it should respond

This is one of the most important parts of the system. These instructions:

Force the agent to use the tool
Forbid it from using external knowledge
Greatly reduce hallucinations
Make the agent more predictable and reliable

In other words, this is where we transform a generic LLM into a specialized, constrained assistant.

4. Defining the Tool

protected function tools(): array

Here we declare what the agent is allowed to do in the real world.

Tool::make("get_transcription", "Retrieve the transcription of a YouTube video.")

This creates a tool named get_transcription. The model can decide to call it whenever it thinks it needs the transcript.

5. Describing the Tool interface

->addProperty(
    new ToolProperty(
        name: "video_id",
        type: PropertyType::STRING,
        required: true,
    ),
)

This is crucial: we are not just exposing a PHP function, we are defining a formal schema for it.

Thanks to this, the model knows:

What arguments are required
What type must they have
How to call the tool correctly

This is what makes tool calling reliable and structured, rather than fragile and heuristic.

6. Connecting the Tool to real PHP code

->setCallable(function (?string $video_id): string {
    return $this->fetchTranscript($video_id);
})

This is the bridge between the AI world and your application.

When the model decides to call the tool, this PHP function is executed. At this point:

The AI stops “imagining”
And your real, deterministic PHP code takes over

This is the exact moment where the agent becomes more than a chatbot.

7. The actual transcript fetching logic

private function fetchTranscript(...)

Everything here is our old, expected, reliable PHP, and that’s a good thing.

We use:

Symfony’s HTTP client
PSR-7 / PSR-18 interfaces
The mrmysql/youtube-transcript library

To fetch the transcript, normalize it, and return it as a simple text variable.

From the agent’s point of view, this is just a tool. From your perspective, this provides full control over data access and behavior.

Using our new Agent

Once the agent is defined, using it in your application is simple.

$agent = new YouTubeTranscriptQAAgent();

$response = $agent->chat(
    new UserMessage("What is the main topic of the video 'wT1lcJ_zn18'?"),
);

echo $response->getContent();

We start by instantiating our agent just like any other PHP object. At this point, we are not dealing with a “model client” or a low-level API wrapper, but with a fully configured AI agent that already knows:

Which model to use
What its instructions are
Which tools it is allowed to call
And how it should behave

When we call the chat() method, we send a UserMessage to the agent. This message becomes part of the agent’s conversation context and triggers the whole reasoning process.

Behind the scenes, Neuron AI orchestrates everything:

The agent analyzes the user’s question.
It follows the rules and steps defined in the system prompt.
It realizes that it needs the video transcript to answer.
It decides to call the get_transcription tool.
Because the get_transcription tool requires the video identifier, the video id is extracted from the question (if it is not present or detected, the answer will be a message about the missing video id)
The Tool PHP code fetches the transcript.
The agent receives the result (a long text with the transcription) from the Tool and uses it as context.
Finally, it generates an answer that strictly respects the defined constraints.

The return value of chat() is a response object. By calling:

echo $response->getContent();

We get and print the final answer produced by the agent as a string.

From the outside, this appears to be a single method call. In reality, it is a full agentic workflow involving reasoning, tool usage, and controlled generation, all hidden behind a clean, idiomatic PHP API.

Why this is real Agentic AI

This approach goes far beyond simply sending prompts to a language model. What we have built here is a real agentic system, where the model is no longer a passive text generator but an active component inside a well-defined software architecture.

The model can autonomously decide when to call a tool, and it can utilize your PHP code as real, concrete capabilities rather than merely as suggestions. At the same time, it operates under strict and explicit rules defined by the system prompt, which constrain its behavior and guide its reasoning.

Thanks to the carefully designed context, background description, step-by-step instructions, and clearly defined output expectations, the agent is firmly grounded in the task it must perform. This dramatically reduces the risk of hallucinations and makes the whole system far more reliable, predictable, and suitable for real-world applications.

Final thoughts

The PHP ecosystem is clearly entering a new era. What only a short time ago looked like an experimental trend is quickly becoming a solid and mature part of everyday application architecture.

With tools like Neuron AI, Symfony AI, Prism, and soon Laravel AI, we can now build reliable, production-grade AI agents entirely in PHP, and, more importantly, integrate them naturally into our existing applications and workflows.

The agent we built in this article is intentionally simple, but it already shows the real power of this approach. From here, you could extend it in many directions: you could add memory to enable reasoning across multiple interactions, introduce multiple tools and let the agent choose between them, connect it to a vector database for semantic search and retrieval-augmented generation, or even orchestrate multiple agents that collaborate on more complex tasks.

This is not about replacing your application logic with an LLM. It is about augmenting your software with reasoning, decision-making, and controlled autonomy, while keeping PHP firmly in charge of execution and structure.

Agentic AI is not a distant future.

It is something you can start building today.

Exploring Real-World APIs with DataBlock

Roberto B. — Tue, 06 Jan 2026 19:57:34 +0000

Comparing Symfony and Laravel using GitHub and Packagist data

In the first article "Handling Nested PHP Arrays Using DataBlock", we explored DataBlock using a simple in-memory dataset to understand its core ideas: safe access, typed getters, and fluent navigation of nested PHP arrays.

That was useful to learn the library's methods, but in real projects, data rarely comes from hardcoded arrays.

More often, it comes from:

HTTP APIs
JSON or YAML configuration files
Tooling metadata (like composer.json)
External services with large, deeply nested responses

In this article, we’ll use real APIs to compare Symfony and Laravel and, at the same time, show how DataBlock shines when dealing with external, untrusted, and deeply nested data.

The setup

We’ll use:

GitHub API for repository statistics
Packagist API for download statistics and popular packages
Raw composer.json files from GitHub

And we’ll fetch everything using Symfony HTTP Client, letting DataBlock wrap the responses.

Installing DataBlock and the HTTP Client

To follow the examples in this article, you’ll need two packages:

DataBlock itself
An implementation of Symfony’s HTTP client

The PHP DataBlock GitHub repository: https://github.com/Hi-Folks/data-block

You can install both via Composer:

composer require hi-folks/data-block symfony/http-client

DataBlock is completely framework-agnostic and works with plain PHP projects, Symfony, or any other setup.

Why DataBlock uses `HttpClientInterface`

In this article, we’ll be calling real APIs. For this, DataBlock provides a convenient helper:

Block::fromHttpJsonUrl(...)

Instead of hard-coding a specific HTTP client, this method accepts any implementation of:

Symfony\Contracts\HttpClient\HttpClientInterface

This design has a few important advantages:

You can use any compatible HTTP client (Symfony HttpClient, mocked clients, or custom implementations)
Your code stays testable (you can inject a fake client)
You stay decoupled from concrete implementations
DataBlock remains framework-agnostic

In our examples, we’ll use the Symfony HTTP Client, but you’re free to swap it with any client that implements the same interface.

Creating the HTTP Client

Here’s how we’ll create the client used in the rest of the article:

use HiFolks\DataType\Block;
use HiFolks\DataType\Enums\Operator;
use Symfony\Component\HttpClient\HttpClient;

$httpClient = HttpClient::create([
    "headers" => [
        "User-Agent" => "PHP DataBlock",
        "Accept" => "application/json",
    ],
]);

And this client will be passed directly to DataBlock via the fromHttpJsonUrl() method:

Block::fromHttpJsonUrl($url, $httpClient);

This keeps responsibilities clean:

The HTTP client handles transport
DataBlock handles data access and exploration

Fetching real data from GitHub and Packagist

To make this example concrete and enjoyable, we’ll work with real, public data from two widely used ecosystems: Symfony and Laravel.

We’ll query two different sources:

GitHub API, to retrieve repository information such as stars, forks, issues, and metadata
Packagist API, to retrieve download statistics for the main framework packages

More specifically, we’ll use:

https://api.github.com/repos/symfony/symfony
https://api.github.com/repos/laravel/framework

And from Packagist:

https://packagist.org/packages/symfony/symfony/stats.json
https://packagist.org/packages/laravel/framework/stats.json

Each of these endpoints returns a large JSON document with many nested fields, exactly the kind of data that is tedious and error-prone to navigate using plain PHP arrays.

With DataBlock, we can fetch and wrap these responses in a single step:

$symfonyGithub = Block::fromHttpJsonUrl(
    "https://api.github.com/repos/symfony/symfony",
    $httpClient,
);
$laravelGithub = Block::fromHttpJsonUrl(
    "https://api.github.com/repos/laravel/framework",
    $httpClient,
);

$symfonyStats = Block::fromHttpJsonUrl(
    "https://packagist.org/packages/symfony/symfony/stats.json",
    $httpClient,
);
$laravelStats = Block::fromHttpJsonUrl(
    "https://packagist.org/packages/laravel/framework/stats.json",
    $httpClient,
);

From this point on, we never touch arrays directly.

Reading GitHub stats safely

GitHub responses are large, nested, and can change over time. We don’t want fragile code.

echo "Symfony GitHub:\n";
echo "Stars: " . $symfonyGithub->getInt("stargazers_count") . "\n";
echo "Forks: " . $symfonyGithub->getInt("forks_count") . "\n";
echo "Open issues: " . $symfonyGithub->getInt("open_issues_count") . "\n";
echo "Main language: " .
    $symfonyGithub->getString("language", "unknown") .
    "\n";

Same for Laravel:

echo "Laravel GitHub:\n";
echo "Stars: " . $laravelGithub->getInt("stargazers_count") . "\n";
echo "Forks: " . $laravelGithub->getInt("forks_count") . "\n";
echo "Open issues: " . $laravelGithub->getInt("open_issues_count") . "\n";
echo "Main language: " .
    $laravelGithub->getString("language", "unknown") .
    "\n";

At no point do we need to worry about whether a field exists or not.
There’s no isset() scattered around, no PHP warnings to silence, and no manual casting to keep track of. We can focus solely on what we want to extract from the data.

Reading Packagist download statistics

Packagist also returns a fairly rich and nested JSON structure. Even for something that sounds simple like “download counts”, the numbers are not at the top level of the response but grouped under a downloads object, with multiple levels and fields.

If you were working with plain arrays, you’d end up writing code like:

$data['downloads']['total']
$data['downloads']['monthly']
$data['downloads']['daily']

... plus all the usual isset() checks to make sure nothing breaks at runtime.

With DataBlock, you can express exactly what you want to read using dot notation:

echo "Symfony downloads:\n";
echo "Total: " . $symfonyStats->getInt("downloads.total") . "\n";
echo "Monthly: " . $symfonyStats->getInt("downloads.monthly") . "\n";
echo "Daily: " . $symfonyStats->getInt("downloads.daily") . "\n";

echo "Laravel downloads:\n";
echo "Total: " . $laravelStats->getInt("downloads.total") . "\n";
echo "Monthly: " . $laravelStats->getInt("downloads.monthly") . "\n";
echo "Daily: " . $laravelStats->getInt("downloads.daily") . "\n";

What’s nice here is that the shape of the JSON almost disappears from the code. You don’t have to care how deeply nested the structure is; you describe the path to the value you want.

Dot notation turns a deeply nested document into something that feels flat, readable, and easy to reason about, while still remaining safe and type-aware.

Parsing composer.json like a data structure

Now let’s fetch the composer.json files directly from GitHub:

$symfonyComposer = Block::fromHttpJsonUrl(
    "https://raw.githubusercontent.com/symfony/symfony/master/composer.json",
    $httpClient,
);
$laravelComposer = Block::fromHttpJsonUrl(
    "https://raw.githubusercontent.com/laravel/framework/master/composer.json",
    $httpClient,
);

Getting nested typed (strin g) values with getString():

echo "Symfony PHP requirement: " .
    $symfonyComposer->getString("require.php") .
    "\n";
echo "Laravel PHP requirement: " .
    $laravelComposer->getString("require.php") .
    "\n";

Exploring dependencies, getting proper blocks data and then accessing to the keys values:

$symfonyRequires = $symfonyComposer->getBlock("require");
$laravelRequires = $laravelComposer->getBlock("require");

print_r($symfonyRequires->keys());
print_r($laravelRequires->keys());

This is structured document exploration, not just array access.

Filtering and sorting real datasets

So far, we’ve only been reading values. But DataBlock can also work with collections of structured items, not just single documents.

The Packagist endpoint we’re using returns a list of the 100 most popular packages. That means we’re no longer dealing with just a nested object, we’re dealing with a nested dataset.

$url = "https://packagist.org/explore/popular.json?per_page=100";
$popularPackages = Block::fromHttpJsonUrl($url, $httpClient)
    ->getBlock("packages");

At this point, DataBlock provides a lightweight query engine for structured arrays.

Let’s start by selecting only the packages related to Symfony and Laravel:

$symfonyPopularPackages = $popularPackages
    ->where("name", Operator::LIKE, "symfony")
    ->orderBy("favers", "desc");

$laravelPopularPackages = $popularPackages
    ->where("name", Operator::LIKE, "laravel")
    ->orderBy("favers", "desc");

Let’s break this down.

The `where()` Method

The where() method filters a dataset based on a condition:

->where(field, operator, value)

In our case:

->where("name", Operator::LIKE, "symfony")

Means:

“Keep only the items where the name field contains the word symfony.”

Each item in $popularPackages is itself a structured object (a package entry), and DataBlock applies this condition to all of them.

The `Operator` Enum

The Operator enum defines how the comparison should be done.

For example:

Operator::EQUAL
Operator::NOT_EQUAL
Operator::GREATER_THAN
Operator::LESS_THAN
Operator::LIKE
…and others

In this example, we use:

Operator::LIKE

Which performs a string contains match.

Using an enum instead of raw strings makes the API:

Safer (no typos)
More explicit
Easier to discover via autocomplete

The `orderBy()` Method

After filtering, we sort the result:

->orderBy("favers", "desc")

This means:

“Sort the remaining items by the favers field, in descending order.”

So now the most starred / favorited packages appear first.

Inspecting the results

After filtering and sorting the datasets, we don’t just want to know that something matched; we want to examine the result and understand what we actually obtained.

Because the result of where() and orderBy() is still a Block, we can keep using all the same tools we’ve seen so far: counting items, accessing nested fields, and safely reading values.

echo "Popular Packages:\n";

echo "Symfony: " . $symfonyPopularPackages->count() . PHP_EOL;
echo " High Favers: " .
    $symfonyPopularPackages->getString("0.name", "") .
    " - " .
    $symfonyPopularPackages->getInt("0.favers", 0) .
    PHP_EOL;

echo "Laravel: " . $laravelPopularPackages->count() . PHP_EOL;
echo " High Favers: " .
    $laravelPopularPackages->getString("0.name", "") .
    " - " .
    $laravelPopularPackages->getInt("0.favers", 0) .
    PHP_EOL;

At this point, we’ve done quite a lot:

Filtered real datasets
Sorted them by meaningful fields
Counted and inspected the results
Navigated deeply nested structures
And all of this without ever touching raw arrays

Conclusion

In this article, we used DataBlock with real HTTP APIs to show that it’s not limited to local arrays or local files. It works just as well with remote JSON and YAML data, such as API responses and external documents.

Once the data is wrapped in a DataBlock, you can:

Access deeply nested values safely
Filter datasets
Sort and inspect results
Extract only the parts you actually care about

All without worrying about missing keys, broken structures, or manual casting.

DataBlock doesn’t try to replace DTOs or business logic. Its job is more straightforward and very focused: make structured data, wherever it comes from, easier and safer to explore, query, and consume.

References

PHP DataBlock GitHub repository: https://github.com/Hi-Folks/data-block
Laravel News mentioned PHP DataBlock in an article: https://laravel-news.com/data-block
Previous article about DataBlock: Handling Nested PHP Arrays Using DataBlock https://dev.to/robertobutti/handling-nested-php-arrays-using-datablock-26d7

Handling Nested PHP Arrays Using DataBlock

Roberto B. — Sun, 04 Jan 2026 18:10:29 +0000

PHP DataBlock is designed to improve the developer experience when working with complex and deeply nested PHP arrays.

If you work with PHP long enough, you will eventually fight an array.

Not because arrays are bad, but because nested, dynamic arrays are everywhere:

API responses
Configuration files
Decoded JSON or YAML
Shared data structures with third-party libraries

And they usually come with the same problems:

Deep isset() chains
Missing keys causing subtle bugs
Manual type casting
Unclear defaults

This is where DataBlock comes in.

GitHub repo & installation:
https://github.com/Hi-Folks/data-block

What is DataBlock?

DataBlock is a small PHP library that wraps arrays into a safer, more expressive object called a Block.

The DataBlock PHP library doesn’t replace arrays; it improves how you access, read, and handle them.

With DataBlock, you get:

Dot-notation access to nested data
Typed getters (getInt(), getString(), etc.)
Safe defaults
Better readability
Easy data inspection and export

Let’s see why that matters.

Installing and using the Block class

To add DataBlock to your projects and start using the Block class with its methods and helpers, you can run the composer require command:

composer require hi-folks/data-block

To support the development, you can "star" ⭐ the repository: https://github.com/Hi-Folks/data-block

Then, in your PHP files, you can import the HiFolks\DataType\Block Namespace:

use HiFolks\DataType\Block;

The simple example dataset

For the examples included in this article, we are going to use a small dataset representing fruits:

use HiFolks\DataType\Block;

$fruitsArray = [
    "avocado" => [
        "name" => "Avocado",
        "fruit" => "🥑",
        "wikipedia" => "https://en.wikipedia.org/wiki/Avocado",
        "color" => "green",
        "rating" => 8,
    ],
    "apple" => [
        "name" => "Apple",
        "fruit" => "🍎",
        "wikipedia" => "https://en.wikipedia.org/wiki/Apple",
        "color" => "red",
        "rating" => 7,
    ],
    "banana" => [
        "name" => "Banana",
        "fruit" => "🍌",
        "wikipedia" => "https://en.wikipedia.org/wiki/Banana",
        "color" => "yellow",
        "rating" => 8.5,
    ],
    "cherry" => [
        "name" => "Cherry",
        "fruit" => "🍒",
        "wikipedia" => "https://en.wikipedia.org/wiki/Cherry",
        "color" => "red",
        "rating" => 9,
    ],
];

$data = Block::make($fruitsArray);

Once the array is wrapped in a Block object, the focus shifts.
Instead of worrying about how the data is structured and whether every key exists, you can concentrate on what you want to read from it.

Safe access without `isset()`

Accessing nested arrays in plain PHP often ends up looking like this:

$color = $array['avocado']['color'] ?? null;

This works, but it doesn’t scale very well.
As soon as the data becomes more complex or dynamic, these checks start spreading across the codebase, making it harder to read and maintain.

With DataBlock, accessing nested values becomes more direct and expressive:

$data->get("avocado.color");

You can safely retrieve values using dot notation, even when the structure is deeply nested:

var_dump(
    $data->get("avocado.color"),
    $data->get("avocado.rating"),
    $data->get("banana.rating"),
    $data->get("apple.notexists"),
);

Output:

string(5) "green"
int(8)
float(8.5)
NULL

Missing keys are handled gracefully, without triggering warnings or notices.
There’s no need for defensive isset() checks or fallback logic scattered throughout the code, just clear, predictable access to the data you need.

Typed getters and defaults

Arrays, by nature, don’t express intent.
When you read a value from an array, it’s not always clear what type that value is supposed to be, or what should happen if it’s missing.

DataBlock makes this explicit.

Instead of retrieving a value and then casting or validating it later, DataBlock allows you to express your expectations directly at the point of access:

var_dump(
    $data->getInt("avocado.rating"),
    $data->getInt("banana.rating"),
    $data->getFloat("banana.rating"),
    $data->get("apple.notexists", "MY_DEFAULT"),
);

Output:

int(8)
int(8)
float(8.5)
string(10) "MY_DEFAULT"

Here, the method name clearly communicates the expected type.
A numeric value is automatically cast to an integer or a float, while missing fields can fall back to a sensible default, all in a single, readable expression.

Why this matters:

getInt() and getFloat() make your intent explicit and self-documenting
Type casting happens consistently and close to the data source
Default values are handled inline, without extra conditional logic

This approach is especially valuable when working with external or untrusted data, such as API responses, configuration files, or decoded JSON, where types and the presence of fields cannot always be guaranteed.

Working with subsets of data

In some cases, you don’t just need a single value; you want to work with an entire section of the dataset.
DataBlock allows you to retrieve a whole branch of the structure in a straightforward way:

$avocado = $data->get("avocado");

In this case, you receive the underlying array:

[
  "name" => "Avocado",
  "fruit" => "🥑",
  "wikipedia" => "...",
  "color" => "green",
  "rating" => 8
]

This is useful when you want to pass the data to existing code that expects a plain PHP array.

Alternatively, if you want to keep working within the DataBlock API, you can retrieve the same branch as a Block instance:

$avocadoBlock = $data->getBlock("avocado");

By using the getBlock() method, you retain all the benefits of DataBlock, dot notation for nested access, typed getters, and the ability to inspect available keys, while focusing only on the portion of the data you’re interested in.

This makes it easy to navigate complex structures step by step, without losing context or switching mental models.

Discovering what’s inside your data

When dealing with dynamic or loosely defined data structures, simply knowing what keys are available can make a big difference.
DataBlock provides a simple way to inspect the structure of your dataset by listing its keys:

$data->keys();

Result:

["avocado", "apple", "banana", "cherry"]

This provides an immediate overview of the top-level elements, which is especially helpful when working with data from external sources.

The same approach also works for nested data. You can inspect the keys of a specific branch by retrieving it as a Block:

$data->getBlock("avocado")->keys();

Result:

["name", "fruit", "wikipedia", "color", "rating"]

Being able to explore the available keys at each level makes DataBlock particularly useful for debugging, data exploration, and building dynamic behaviors such as conditional rendering or automatic mappings.

Exporting data to YAML (and more)

Beyond reading and navigating data, DataBlock can also help with data representation and serialization.

In addition to JSON (method toJson()), DataBlock allows you to serialize your data into YAML, which is often easier to read and reason about, especially for configuration and inspection purposes:

echo $data->toYaml();

Output:

avocado:
  name: Avocado
  fruit: 🥑
  wikipedia: https://en.wikipedia.org/wiki/Avocado
  color: green
  rating: 8
apple:
  name: Apple
  fruit: 🍎
  wikipedia: https://en.wikipedia.org/wiki/Apple
  color: red
  rating: 7
...

Being able to convert a structured dataset into a human-readable or machine-readable format quickly is helpful in many everyday scenarios.
This includes generating configuration files, producing clear debug output, or sharing data with tools and systems that work naturally with YAML.

When should you use PHP DataBlock?

DataBlock is a great fit when:

You consume API responses.
You parse JSON/YAML
You deal with deeply nested arrays.
You want safer, clearer PHP code.

It doesn’t try to replace domain models; it simply makes raw data easier and safer to work with.

Arrays vs DataBlock vs DTOs: which one should you use?

When working with data in PHP, there are usually three common approaches:

Plain PHP arrays
DataBlock
DTOs (Data Transfer Objects)

Each one has a purpose; the key is knowing when to use which.

1) Plain PHP Arrays

The default/first choice.
Arrays are flexible, fast, and built into the language.

$rating = $data['avocado']['rating'] ?? null;

Pros

Native PHP feature
Zero dependencies
Very flexible

Cons

No type safety
Verbose access for nested data
Easy to introduce silent bugs
Hard to understand intent
Defensive code everywhere

Best for

Very small scripts
Simple, flat data
Performance-critical hot paths

Once data becomes nested or dynamic, arrays tend to leak complexity everywhere.

2) DataBlock

A safer abstraction over arrays.
DataBlock keeps the flexibility of arrays while adding structure and intent.

$rating = $data->getInt("avocado.rating");

Pros

Safe nested access (no warnings)
Typed getters
Defaults built in
Highly readable
Great for untrusted or dynamic data

Cons

Still runtime-typed (not compile-time)
Not a domain model
Adds a small dependency

Best for

API responses
Configuration files
JSON / YAML parsing
Boundary layers (input/output)
Rapid prototyping without sacrificing safety

Think of DataBlock as a smart boundary object between raw data and your application logic.

3) DTOs (Data Transfer Objects)

The most explicit and strict option.
DTOs define exactly what your data looks like.

final class FruitDTO
{
    public function __construct(
        public string $name,
        public string $color,
        public float $rating
    ) {}
}

Pros

Strong typing
IDE autocompletion
Self-documenting
Great for domain logic
Easier to refactor safely

Cons

Verbose
Requires mapping
Rigid structure
Overkill for dynamic data

Best for

Domain models
Business logic
Internal application state
Long-lived data structures

DTOs shine inside your application, where structure is stable, and rules matter.

The key difference is where you use them

Layer	My opinionated recommendation
External input (API, JSON, YAML)	DataBlock
Simple scripts	Array
Domain logic	DTO
Configuration	DataBlock
Public interfaces	DTO

Recap: why DataBlock exists

DataBlock doesn’t compete with DTOs; it complements them.

It lives in the uncomfortable middle ground where:

Data is messy
Structure is mostly known
Safety matters
Full modeling would be too heavy.

If arrays are too loose and DTOs are too strict, DataBlock is the pragmatic middle layer.

Final thoughts

PHP arrays are powerful, but they’re also easy to misuse.

DataBlock is designed to improve the developer experience when working with complex, nested, and structured datasets by providing a fluent and expressive way to access and handle data.

Less boilerplate, fewer bugs, more readable code.

Check it out on GitHub:
https://github.com/Hi-Folks/data-block

Essential PHP conferences to attend in 2026

Roberto B. — Thu, 01 Jan 2026 20:25:47 +0000

Here's a curated list of essential developer conferences in 2026, focusing on PHP and its major frameworks, including Laravel and Symfony. These events are ideal for staying up-to-date with the ecosystem, sharpening your skills, and connecting with the global PHP community.

Why should I attend a PHP conference in 2026?

2026 continues the strong momentum of the PHP ecosystem. With modern PHP firmly established, frameworks evolving rapidly, and performance, DX, and tooling improving year after year, it’s an exciting time to be a PHP developer.

Attending PHP conferences allows you to:

Stay current with the latest PHP versions, best practices, and architectural patterns
Learn directly from core contributors, framework maintainers, and industry experts
Discover new tools, libraries, and workflows that can improve your daily work
Network with developers from all over the world and grow your professional opportunities

Beyond the talks, conferences are about people. They’re a place to exchange ideas, share challenges, get inspired, and feel part of a welcoming and passionate community.

In-Person vs Remote

In-person conferences offer something special: human connection. Meeting fellow developers face-to-face, discussing ideas over coffee, and sharing experiences creates a strong sense of community and belonging. These events help strengthen the PHP community and often lead to long-lasting collaborations and friendships.

That said, not everyone can travel. Budget, time, or personal constraints can make in-person attendance difficult. Thankfully, many conferences now offer remote or hybrid options, making high-quality content accessible from anywhere.

In the list below, conferences with a remote option are marked with the 🌐 icon and listed as Online or Hybrid.

Whether you attend in person or online, the most important thing is staying connected and engaged with the PHP ecosystem.

2026 PHP Conferences - The List

🌐 SymfonyOnline – January 2026

Date: January 22 - 23, 2026
Location: Online
More info: https://live.symfony.com/2026-online-january/

🇮🇳 Laracon India 2026

Date: January 31 - February 1, 2026
Location: Ahmedabad, India
More info: https://laracon.in/

🇳🇱 Laracon EU 2026

Date: February 2 - 3, 2026
Location: Amsterdam, Netherlands
More info: https://laracon.eu/

🇬🇧 PHP UK Conference 2026

Date: February 20, 2026
Location: London, UK
More info: https://www.phpconference.co.uk/

🇨🇦 ConFoo 2026

Date: February 25 - 27, 2026
Location: Montreal, Canada
More info: https://confoo.ca/en/2026/track/php

🇳🇱 Dutch PHP Conference 2026

Date: March 10 - 13, 2026
Location: Amsterdam, Netherlands
More info: https://phpconference.nl/

🇫🇷 SymfonyLive Paris 2026

Date: March 26 - 27, 2026
Location: Paris, France
More info: https://live.symfony.com/2026-paris/

🇩🇪 SymfonyLive Berlin 2026

Date: April 23 - 24, 2026
Location: Berlin, Germany
More info: https://live.symfony.com/2026-berlin/

🇮🇹/🌐 phpday 2026

Date: May 14 - 15, 2026
Location: Verona, Italy (also Online)
More info: https://www.phpday.it/

🇺🇸 PHP[TEK] 2026

Date: May 19 - 21, 2026
Location: Chicago Rosemont, IL, USA
More info: https://phptek.io/

🇯🇵 Laravel Live Japan

Date: May 26 - 27, 2026
Location: Tokio, Japan
More info: https://laravellive.jp/en

🇨🇦 SymfonyDay Montreal 2026

Date: June 4, 2026
Location: Montreal, Canada
More info: https://live.symfony.com/2026-montreal/

🇩🇪/🌐 International PHP Conference 2026

Date: June 8 - 12, 2026
Location: Berlin, Germany (also Online)
More info: https://phpconference.com/berlin-en/

🇭🇷 Web Summer Camp 2026

Date: July 2 - 4, 2026
Location: Opatija, Croatia
More info: https://websummercamp.com/2026

🇺🇸 Laracon US 2026

Date: July 28 - 29, 2026
Location: Boston, MA - USA
More info: https://laracon.us/

🇩🇰 Laravel Live Denmark 2026

Date: August 20 - 21, 2026
Location: Copenhagen, Denmark
More info: https://laravellive.dk/

🇫🇷/🌐 API Platform Conference 2026

Date: September 17 - 18, 2026
Location: Lille, France (also Online)
More info: https://api-platform.com/con/2026/

🇮🇹 LaravelDay 2026

Date: November 18, 2026
Location: Verona, Italy
More info: https://www.laravelday.it/

🇵🇱 SymfonyCon Warsaw 2026

Date: November 26 - 27, 2026
Location: Warsaw, Poland
More info: https://live.symfony.com/2026-warsaw-con/

Final Notes

More events will confirm their dates and locations throughout the year. I’ll keep this list updated as soon as new information becomes available.

If you know of any great PHP conferences that should be added, feel free to suggest them in the comments.

And if you’re planning to attend any of these events, online or in person, let me know. Connecting with fellow PHP enthusiasts is always a pleasure!

Happy coding, and see you at a PHP conference in 2026 🚀

Why you should always check licenses in your PHP project

Roberto B. — Wed, 24 Dec 2025 14:00:54 +0000

When we consider dependencies in a PHP project, we typically focus on security, performance, and maintenance. One critical aspect is often overlooked: software licenses.

Whether you are building an open-source library, a commercial SaaS, or a private internal application, the licenses of your dependencies matter. Ignoring them can lead to legal risks, compliance issues, and unexpected obligations.

Composer provides a built-in command to help with this:

composer licenses

In this article, we’ll explore why license checks are essential and how to use Composer’s tooling, especially the summary and JSON output formats, to keep your project compliant and under control.

Why license compliance matters (even for applications)

A common misconception is:

“I’m building an application, not an open source library; licenses don’t matter.”

This is not true.

Checking the licenses used in a project is essential for several important reasons.

Legal obligations : some licenses (e.g. GPL) may require you to:
- Disclose source code
- Use the same license for derivative works.
- Provide attribution or license texts.
Commercial restrictions: certain licenses are incompatible with proprietary software or paid products.
Future-proofing: today’s internal tool might become:
- An open-source project
- A commercial product
- Part of a larger ecosystem
CI/CD & compliance: many companies require license audits as part of:
- Security reviews
- Vendor assessments
- Release pipelines

Knowing what you depend on is not optional; it’s responsible software development.

Getting an overview with `composer licenses -f summary`

The quickest way to understand your project’s license landscape is:

composer licenses -f summary

This command generates an output that lists the licenses used, along with the number of packages that use each license. In the output example, we can see that for my current project, the most used license by the dependencies is the license "MIT".

-------------- ------------------------
 License        Number of dependencies
-------------- ------------------------
 MIT            81
 BSD-3-Clause   33
 BSD-2-Clause   2
 GPL-2.0-only   2
 GPL-3.0-only   2
 proprietary    1
 Apache-2.0     1
-------------- ------------------------

This summary gives a clear picture of how licenses are distributed across your dependencies.

MIT / BSD / Apache These are generally permissive and safe for most projects.
GPL-2.0-only / GPL-3.0-only Strong copyleft licenses that may impose redistribution obligations.
proprietary A red flag that requires manual review.

If you are interested in going deeper into Licenses, you can take a look at: https://opensource.org/licenses

The summary output is perfect for:

Quick audits
Documentation
Team discussions
Deciding whether deeper analysis is needed

However, it doesn’t indicate which packages are responsible for those licenses. For that, we can use the JSON output format.

Going deeper with `composer licenses -f json`

To perform automated checks or detailed analysis, Composer can output machine-readable data:

composer licenses -f json

The JSON output includes:

Project metadata (name, version, license)
A dependencies object where each dependency includes:
- Package name
- Version
- One or more licenses

The JSON output follows a structure similar to the one shown below.

{
  "name": "laravel/laravel",
  "version": "dev-main",
  "license": ["MIT"],
  "dependencies": {
    "brick/math": {
      "version": "0.14.1",
      "license": ["MIT"]
    },
    "some/gpl-package": {
      "version": "1.2.3",
      "license": ["GPL-3.0-only"]
    }
  }
}

This format is ideal for:

CI pipelines
Custom policy enforcement
Reporting tools
Automated alerts

Checking license policies with PHP

Once you have JSON output, you can automatically check your organization’s license policy.

Let’s say your project only allows:

MIT;BSD-2-Clause;BSD-3-Clause;Apache-2.0

Using the JSON output, we can write a small PHP script to automatically detect disallowed licenses.

<?php

$allowedLicenses = explode(';', 'MIT;BSD-2-Clause;BSD-3-Clause;Apache-2.0');

// Execute Composer and capture JSON output
exec('composer licenses -f json 2>/dev/null', $output, $exitCode);

if ($exitCode !== 0) {
    fwrite(STDERR, "Failed to execute composer licenses\n");
    exit(1);
}

$data = json_decode(implode("\n", $output), true);

// Check dependencies
foreach ($data['dependencies'] as $name => $package) {
    $licenses = $package['license'] ?? [];

    if (!array_intersect($licenses, $allowedLicenses)) {
        echo sprintf(
            "%s (%s) -> %s\n",
            $name,
            $package['version'] ?? 'unknown',
            $licenses ? implode(', ', $licenses) : 'NO LICENSE'
        );
    }
}

The scripts:

Runs composer licenses -f json directly
Parses the output safely
Checks each dependency’s license
Reports packages that violate your policy

You can easily extend this to:

Fail a CI build
Generate reports
Send alerts
Whitelist or blacklist specific packages

Why checking licenses matters in practice

Automating license checks:

Prevents accidental license violations
Protects your company and clients
Makes compliance repeatable and auditable
Encourages better dependency hygiene

Most importantly, it shifts license compliance from a manual afterthought to an integrated development practice.

Final thoughts

Composer already gives you the tools, you just need to use them.

Use composer licenses -f summary for a quick overview
Use composer licenses -f json for automation and deep analysis
Integrate license checks early, not after problems arise

Dependency management is not just about code.
It’s also about responsibility.

How to handle API rate limits and HTTP 429 errors in an easy and reliable way

Roberto B. — Sat, 13 Dec 2025 18:13:54 +0000

API rate limits and HTTP 429 (Too Many Requests) errors are common challenges when building applications that integrate with third-party APIs, as they require multiple requests within a short time window.

A typical first approach is to handle 429 responses directly in the application logic by adding custom retry and delay mechanisms; however, this often results in complex, fragile, and difficult-to-maintain code.

When integrating APIs using Symfony HTTP Client, there is no need to reinvent the wheel. Symfony provides a robust, configurable, and production-ready solution through the RetryableHttpClient, allowing you to handle API rate limits automatically and reliably while keeping your code clean and maintainable.

Even if you are not using the Symfony Framework and are working with a standalone PHP script, you can still rely on the Symfony HTTP Client component.

Rate limits and 429 HTTP status/errors

When working with third-party APIs, you may occasionally encounter an HTTP 429 – Too Many Requests response. This status code indicates that the client has exceeded the server’s rate limit, typically the number of allowed requests within a specific period (for example, 10 requests per second).

When a 429 is returned, the API/service is telling the client:

“You are sending requests too fast. Please slow down and try again later.”

To successfully complete the request, you should retry the same API call after waiting the amount of time recommended by the server or, if not provided, after a sensible delay such as one second.

Symfony’s HTTP Client component includes built-in support for retrying failed requests through the RetryableHttpClient class. This allows developers to automatically retry requests that fail due to rate limiting, network issues, or other recoverable errors.

In this article, we will focus on configuring retry mechanisms in Symfony when an HTTP 429 response is received, while keeping in mind that the same approach can also be applied to other recoverable HTTP errors, such as 500-level responses.

Why implement retries for HTTP 429?

APIs enforce rate limits to protect their infrastructure and ensure fair usage among clients. Exceeding these limits results in a temporary block, which is why a 429 response is returned.

Automatically retrying a failed request is helpful because:

The request can succeed shortly after the rate limit resets.
It improves the resiliency of your application.
It avoids manually implementing sleep/delay logic.

Many APIs also include a Retry-After HTTP header indicating how long the client should wait. Symfony’s retry system can detect this and adjust the delay accordingly.

Using `RetryableHttpClient` in Symfony

Symfony provides the RetryableHttpClient wrapper, which adds automatic retry behavior to an existing HTTP client.

To enable retries, you must configure a Retry Strategy, which defines:

how many times to retry,
which HTTP status codes trigger a retry (e.g., 429),
how long to wait between attempts.

Below is a practical example.

Example: retry failed requests after a 429 status

The following example shows how to configure automatic retries for API requests that return an HTTP 429 (Too Many Requests) response using Symfony HTTP Client.
This approach works in both full Symfony applications and standalone PHP scripts, without requiring the Symfony Framework itself.

Step 1: Install the Symfony HTTP Client library

Even if you are not using a Symfony application, you can install the Symfony HTTP Client component via Composer:

composer require symfony/http-client

This installs only the HTTP Client component and its dependencies.
You do not need to install or use the Symfony Framework to take advantage of its retry and networking features.

Step 2: Import required classes

require "./vendor/autoload.php";

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Component\HttpClient\Retry\GenericRetryStrategy;
use Symfony\Component\HttpClient\RetryableHttpClient;

Step 3: Configure a retry strategy

Here we configure a strategy that retries when receiving HTTP 429 responses:

$retryStrategy = new GenericRetryStrategy(
    statusCodes: [429],   // Retry on HTTP 429 Too Many Requests
    delayMs: 1000,        // Wait 1 second between retries
    multiplier: 1.0,      // Do not increase the delay
    maxDelayMs: 2000,     // Maximum delay per retry
);

This strategy says: "If you receive a 429, retry waiting 1 second between attempts."

Step 4: Wrap your HTTP client

$client = HttpClient::create();

$retryingClient = new RetryableHttpClient(
    client: $client,
    strategy: $retryStrategy,
    maxRetries: 3,
);

Step 5: Make the HTTP request and validate the final response

$response = $retryingClient->request(
    "GET",
    "https://dummyjson.com/products/search?q=phone",
);

When using the RetryableHttpClient, Symfony will automatically retry the request if a retryable error occurs, such as an HTTP 429 (Too Many Requests), according to the configured retry strategy.

However, even after all retry attempts are exhausted, the request may still fail. This can happen, for example, if:

the API continues to return 429 responses beyond the maximum number of retries,
the server responds with a different non-retryable error (such as 400 or 401),
a network or timeout error occurs.

For this reason, it is crucial to always validate the final response before using its data.

A safer approach is to check the HTTP status code explicitly:

$statusCode = $response->getStatusCode();

if ($statusCode === 200) {
    $data = $response->toArray();
    print_r($data);
} else {
    // Handle the error (logging, fallback logic, exception, etc.)
    echo $response->getStatusCode();
}

Handling transport exceptions

In addition to HTTP error responses (such as 429 or 500), API requests may fail due to transport-level errors. These errors occur before a valid HTTP response is received and are typically caused by:

network connectivity issues,
DNS resolution failures,
timeouts,
SSL/TLS errors.

When this happens, Symfony HTTP Client throws transport exceptions, which must be handled explicitly to prevent unexpected application failures.

Catching Transport Exceptions Safely

Symfony HTTP Client throws exceptions that implement the TransportExceptionInterface.
You should wrap your request logic in a try/catch block to handle these cases gracefully.

use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;

try {
    $response = $retryingClient->request(
        "GET",
        "https://dummyjson.com/products/search?q=phone",
    );
    $statusCode = $response->getStatusCode();

    if ($statusCode === 200) {
        $data = $response->toArray();
        print_r($data);
    } else {
        // Handle the error (logging, fallback logic, exception, etc.)
        echo $response->getStatusCode();
    }
} catch (TransportExceptionInterface $e) {
    // Handle transport-level errors (network, timeout, DNS, etc.)
    // e.g. log the error, notify monitoring systems, or retry later
    echo $e->getMessage();
}

Why validating responses is important

Even with automatic retries enabled:

a request can still fail due to network issues,
retries only apply when a response is actually received,
transport errors bypass HTTP status codes entirely.

By explicitly catching transport exceptions, you ensure that your application:

remains stable under adverse network conditions,
fails gracefully instead of crashing,
provides meaningful error handling and observability.

Key takeaway about making the HTTP request

A reliable API integration must handle both HTTP-level errors and transport-level exceptions.

Combining RetryableHttpClient, response status validation, and proper exception handling gives you a robust, production-ready solution for interacting with rate-limited APIs.

Handling `Retry-After` Header

Many APIs send a Retry-After header with a value in seconds.

Symfony’s retry system will automatically prioritize the server-provided delay when available.

Example server header:

HTTP/1.1 429 Too Many Requests
Retry-After: 2

In this case, Symfony will wait 2 seconds, even if your strategy says 1 second.

Conclusion

Automatic retries are essential when interacting with rate-limited APIs. Symfony’s RetryableHttpClient makes this process easy and robust by:

automatically handling 429 (Too Many Requests),
supporting server-provided retry delays,
providing configurable retry strategies.

By wrapping your HTTP client with a retry strategy, your application becomes more resilient and better equipped to deal with temporary API throttling.

References

Symfony HTTP Client Documentation Official documentation for the Symfony HTTP Client component, including usage examples and configuration options. https://symfony.com/doc/current/http_client.html
Retry Failed Requests (Symfony Documentation) Detailed explanation of how to retry failed HTTP requests using RetryableHttpClient and retry strategies. https://symfony.com/doc/current/http_client.html#retry-failed-requests
RetryableHttpClient Class source code Source code of the RetryableHttpClient class. https://github.com/symfony/symfony/blob/8.0/src/Symfony/Component/HttpClient/RetryableHttpClient.php
GenericRetryStrategy Class Documentation and source reference for configuring retry logic based on HTTP status codes and delays. https://github.com/symfony/symfony/blob/8.0/src/Symfony/Component/HttpClient/Retry/GenericRetryStrategy.php
Symfony HTTP Client Exceptions Overview of exceptions thrown by the HTTP Client, including transport and HTTP-related exceptions. https://symfony.com/doc/current/http_client.html#handling-exceptions