Errors & Debugging

PHP reports problems in four ways, and the first word of the message tells you which one you have. A parse error means the file is not valid PHP, so nothing in it runs — not even the lines above the mistake. A fatal error stops the script at that point. A warning, notice or deprecation is reported and the script keeps going, usually with a null where a value should be — which is why a warning often causes a wrong result or a fatal error a few lines later. An uncaught exception is printed as Fatal error: Uncaught ..., but unlike the others it could have been caught (Module 08).

Warnings are easy to miss in a busy page. A custom error handler can collect them instead of printing them — the same hook frameworks use to turn them into exceptions or send them to a log:

<?php
$problems = [];
set_error_handler(function (int $level, string $msg, string $file, int $line) use (&$problems): bool {
    $name = match ($level) {
        E_WARNING => 'Warning',
        E_NOTICE => 'Notice',
        E_DEPRECATED => 'Deprecated',
        default => "Level $level",
    };
    $problems[] = "$name: $msg (line $line)";
    return true;                        // true = handled, do not print it
});

$cart = ['pen' => 20];
$total = $cart['pen'] + $cart['ink'];   // missing key
$name = strtoupper($undefinedName);     // missing variable
$price = trim(null);                    // null to a string parameter

echo "total = $total, name = '$name'\n";
echo count($problems), " problems:\n", implode("\n", $problems), "\n";

total = 20, name = ''
4 problems:
Warning: Undefined array key "ink" (line 15)
Warning: Undefined variable $undefinedName (line 16)
Deprecated: strtoupper(): Passing null to parameter #1 ($string) of type string is deprecated (line 16)
Deprecated: trim(): Passing null to parameter #1 ($string) of type string is deprecated (line 17)

Every PHP error message has the same shape: type, message, file and line. For an uncaught exception the location is in main.php:12 — the line where it was thrown — followed by a stack trace: the chain of calls that led there, innermost first (#0) down to {main}, the top-level script. Each frame reads "this file and line called this function with these arguments". Since PHP 8.5 even engine fatal errors (out of memory, redeclared function) print a stack trace.

<?php
declare(strict_types=1);

function loadPrice(array $product): float
{
    return $product['price'];              // line 6: price is a string here
}

function cartTotal(array $cart): float
{
    $sum = 0.0;
    foreach ($cart as $product) {
        $sum += loadPrice($product);       // line 13
    }
    return $sum;
}

try {
    echo cartTotal([['price' => 9.5], ['price' => '12.00']]);   // line 19
} catch (TypeError $e) {
    echo get_class($e), ": ", $e->getMessage(), "\n";
    echo "thrown at line ", $e->getLine(), "\n";
    echo str_replace(__DIR__ . DIRECTORY_SEPARATOR, '', $e->getTraceAsString()), "\n";
}

TypeError: loadPrice(): Return value must be of type float, string returned
thrown at line 6
#0 main.php(13): loadPrice(Array)
#1 main.php(19): cartTotal(Array)
#2 {main}

1. 1
   Read the first line

   Type and message: TypeError, "return value must be float, string returned". That is what went wrong.

2. 2
   Go to the reported line

   Line 6, the return in loadPrice(). That is where PHP noticed.

3. 3
   Walk down the trace

   #0: line 13 in cartTotal() called loadPrice. #1: line 19 called cartTotal. Stop at the first frame whose data you control.

4. 4
   Find where the bad value was born

   The string '12.00' came from the cart built on line 19 — that is the real bug, two frames away from the reported line.

The first group of errors is about the shape of your code and the names in it: a missing operator, a variable that was never set, a function or class PHP cannot find, a function declared twice. Most of them are caught before you run by an editor with PHP support or by a static analyser (last lesson).

<?php
$total = 250;
echo "Total: " $total;

Parse error: syntax error, unexpected variable "$total", expecting "," or ";" in main.php on line 3

<?php
$total = 250;
echo "Total: " . $total;     // or: echo "Total: $total";

<?php
$items = ['pen', 'ink', 'paper'];
foreach ($items as $item) {
    $count++;
}
echo "Items: $count\n";

Warning: Undefined variable $count in main.php on line 4
Items: 3

<?php
$items = ['pen', 'ink', 'paper'];
$count = 0;
foreach ($items as $item) {
    $count++;
}
echo "Items: $count\n";   // or simply count($items)

<?php
$words = ['php', 'is', 'fun'];
echo str_join(' ', $words);

Fatal error: Uncaught Error: Call to undefined function str_join() in main.php:3
Stack trace:
#0 {main}
  thrown in main.php on line 3

<?php
$words = ['php', 'is', 'fun'];
echo implode(' ', $words);   // php is fun

<?php
function formatPrice(float $p): string
{
    return number_format($p, 2);
}

echo formatPrice(9.5), "\n";

function formatPrice(float $p): string
{
    return '$' . number_format($p, 2);
}

Fatal error: Cannot redeclare function formatPrice() (previously declared in main.php:2) in main.php on line 9
Stack trace:
#0 {main}

<?php
function formatPrice(float $p): string
{
    return number_format($p, 2);
}

function formatPriceWithSymbol(float $p): string
{
    return '$' . formatPrice($p);
}

echo formatPriceWithSymbol(9.5), "\n";   // $9.50

<?php
namespace App\Controllers;

$date = new DateTimeImmutable('2026-01-01');
echo $date->format('Y');

Fatal error: Uncaught Error: Class "App\Controllers\DateTimeImmutable" not found in main.php:4
Stack trace:
#0 {main}
  thrown in main.php on line 4

<?php
namespace App\Controllers;

use DateTimeImmutable;

$date = new DateTimeImmutable('2026-01-01');
echo $date->format('Y');   // 2026

The most common PHP bugs are about data that is not there: a key missing from an array, an index one past the end, a function that returned null instead of the array or object you expected. PHP 8 made most of these louder (older versions called them "notices" and "undefined index/offset"), but the array ones are still only warnings, so the script continues with null.

<?php
$user = ['name' => 'Asha', 'email' => '[email protected]'];
echo "Phone: " . $user['phone'] . "\n";
echo "Done\n";

Warning: Undefined array key "phone" in main.php on line 3
Phone:
Done

<?php
$user = ['name' => 'Asha', 'email' => '[email protected]'];
echo "Phone: " . ($user['phone'] ?? 'not given') . "\n";
echo "Done\n";

<?php
$scores = [90, 72, 85];
for ($i = 0; $i <= count($scores); $i++) {
    echo "Score $i: {$scores[$i]}\n";
}

Score 0: 90
Score 1: 72
Score 2: 85

Warning: Undefined array key 3 in main.php on line 4
Score 3: 

<?php
$scores = [90, 72, 85];
foreach ($scores as $i => $score) {
    echo "Score $i: $score\n";
}

<?php
function findUser(int $id): ?array
{
    $users = [1 => ['name' => 'Asha']];
    return $users[$id] ?? null;
}

$user = findUser(2);
echo "Hello, " . $user['name'] . "\n";

Warning: Trying to access array offset on null in main.php on line 9
Hello, 

<?php
function findUser(int $id): ?array
{
    $users = [1 => ['name' => 'Asha']];
    return $users[$id] ?? null;
}

$user = findUser(2);
if ($user === null) {
    echo "No such user\n";
} else {
    echo "Hello, " . $user['name'] . "\n";
}

<?php
class Order
{
    public function __construct(public ?Customer $customer = null) {}
}
class Customer
{
    public function getEmail(): string { return '[email protected]'; }
}

$order = new Order();
echo $order->customer->getEmail();

Fatal error: Uncaught Error: Call to a member function getEmail() on null in main.php:12
Stack trace:
#0 {main}
  thrown in main.php on line 12

<?php
class Order
{
    public function __construct(public ?Customer $customer = null) {}
}
class Customer
{
    public function getEmail(): string { return '[email protected]'; }
}

$order = new Order();
echo $order->customer?->getEmail() ?? 'guest checkout';

These are all Error subclasses PHP throws when a function gets something it cannot work with: the wrong type (TypeError), the wrong number of arguments (ArgumentCountError), a value that is the right type but impossible (ValueError), or a zero divisor (DivisionByZeroError). Their messages are precise — they name the function, the argument number and name, what was expected and what was given.

<?php
declare(strict_types=1);

function applyDiscount(float $price, int $percent): float
{
    return $price * (100 - $percent) / 100;
}

$percent = $_GET['discount'] ?? '10';
echo applyDiscount(200.0, $percent);

Fatal error: Uncaught TypeError: applyDiscount(): Argument #2 ($percent) must be of type int, string given, called in main.php on line 10 and defined in main.php:4
Stack trace:
#0 main.php(10): applyDiscount(200.0, '10')
#1 {main}
  thrown in main.php on line 4

<?php
declare(strict_types=1);

function applyDiscount(float $price, int $percent): float
{
    return $price * (100 - $percent) / 100;
}

$percent = filter_var($_GET['discount'] ?? '10', FILTER_VALIDATE_INT) ?: 0;
echo applyDiscount(200.0, $percent);   // 180

<?php
function sendEmail(string $to, string $subject, string $body): string
{
    return "To: $to | $subject";
}

echo sendEmail('[email protected]', 'Welcome');

Fatal error: Uncaught ArgumentCountError: Too few arguments to function sendEmail(), 2 passed in main.php on line 7 and exactly 3 expected in main.php:2
Stack trace:
#0 main.php(7): sendEmail('[email protected]...', 'Welcome')
#1 {main}
  thrown in main.php on line 2

<?php
function sendEmail(string $to, string $subject, string $body = ''): string
{
    return "To: $to | $subject";
}

echo sendEmail('[email protected]', 'Welcome');

<?php
$orders = [];
$revenue = 0;
$average = $revenue / count($orders);
echo "Average order: $average\n";

Fatal error: Uncaught DivisionByZeroError: Division by zero in main.php:4
Stack trace:
#0 {main}
  thrown in main.php on line 4

<?php
$orders = [];
$revenue = 0;
$average = count($orders) > 0 ? $revenue / count($orders) : 0;
echo "Average order: $average\n";

<?php
$header = ['id', 'name', 'email'];
$row = ['7', 'Asha'];
$record = array_combine($header, $row);
print_r($record);

Fatal error: Uncaught ValueError: array_combine(): Argument #1 ($keys) and argument #2 ($values) must have the same number of elements in main.php:4
Stack trace:
#0 main.php(4): array_combine(Array, Array)
#1 {main}
  thrown in main.php on line 4

<?php
$header = ['id', 'name', 'email'];
$row = ['7', 'Asha'];
if (count($row) !== count($header)) {
    echo "Skipping row with ", count($row), " columns, expected ", count($header), "\n";
} else {
    print_r(array_combine($header, $row));
}

Two last errors come from the environment rather than your logic: HTTP headers sent too late, and running out of memory or time. Both are controlled by settings you can change, but raising a limit is rarely the right fix.

<?php
session_start();
$_SESSION['user_id'] = 7;
header('Location: /dashboard');
exit;

Warning: session_start(): Session cannot be started after headers have already been sent (sent from main.php on line 1) in main.php on line 3

Warning: Cannot modify header information - headers already sent by (output started at main.php:1) in main.php on line 5

<?php
session_start();
$_SESSION['user_id'] = 7;
header('Location: /dashboard');
exit;

<?php
ini_set('memory_limit', '16M');

$rows = [];
for ($i = 0; $i < 1_000_000; $i++) {
    $rows[] = ['id' => $i, 'name' => "user$i", 'email' => "[email protected]"];
}
echo count($rows);

Fatal error: Allowed memory size of 16777216 bytes exhausted (tried to allocate 1052672 bytes) in main.php on line 6
Stack trace:
#0 {main}

<?php
ini_set('memory_limit', '16M');

function users(int $n): Generator
{
    for ($i = 0; $i < $n; $i++) {
        yield ['id' => $i, 'name' => "user$i", 'email' => "[email protected]"];
    }
}

$count = 0;
foreach (users(1_000_000) as $row) {   // one row in memory at a time
    $count++;
}
echo $count;   // 1000000

The quickest debugger is a well-placed dump. var_dump() shows types and lengths (and tells "1", 1 and true apart), print_r() is shorter and easier to read for nested arrays, var_export() prints valid PHP you can paste back into a test, and json_encode() gives a one-line view that suits logs. In a web page, wrap dumps in <pre>; better still, write them to the log so users never see them.

<?php
$order = ['id' => 7, 'paid' => true, 'total' => '19.90', 'items' => ['pen', null]];

var_dump($order['paid'], $order['total']);
print_r($order);
echo "\n";
var_export($order);
echo "\n", json_encode($order), "\n";

// error_log type 3 appends to a file of your choice (default: the server log / stderr)
$log = tempnam(sys_get_temp_dir(), 'log');
error_log("order 7 total=" . $order['total'] . "\n", 3, $log);
error_log("order 7 items=" . json_encode($order['items']) . "\n", 3, $log);
echo file_get_contents($log);
unlink($log);

bool(true)
string(5) "19.90"
Array
(
    [id] => 7
    [paid] => 1
    [total] => 19.90
    [items] => Array
        (
            [0] => pen
            [1] =>
        )

)

array (
  'id' => 7,
  'paid' => true,
  'total' => '19.90',
  'items' =>
  array (
    0 => 'pen',
    1 => NULL,
  ),
)
{"id":7,"paid":true,"total":"19.90","items":["pen",null]}
order 7 total=19.90
order 7 items=["pen",null]

display_errors, error_reporting and log_errors

php --ini                       # which php.ini files are loaded
php -i | grep -E 'display_errors|error_reporting|log_errors'
php -d display_errors=1 -d error_reporting=-1 script.php   # override for one run
php -l script.php               # syntax check only (finds parse errors without running)

Xdebug: step debugging

Xdebug is the PHP debugger extension. With it, your editor (PhpStorm, or VS Code with the "PHP Debug" extension) can pause on a breakpoint, show every variable, and step line by line — far faster than adding dumps for anything non-trivial. It also improves var_dump output and can profile slow code. Install it only in development: it slows PHP down noticeably.

pecl install xdebug             # or: apt install php-xdebug / brew + pecl
php -v                           # should now say "with Xdebug v3..."

zend_extension=xdebug
xdebug.mode=debug,develop
xdebug.start_with_request=trigger   ; debug only when asked (XDEBUG_TRIGGER cookie/param)
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

{
  "version": "0.2.0",
  "configurations": [
    { "name": "Listen for Xdebug", "type": "php", "request": "launch", "port": 9003 }
  ]
}

Start "Listen for Xdebug" in VS Code, set a breakpoint, then run XDEBUG_TRIGGER=1 php main.php (or add ?XDEBUG_TRIGGER=1 to a URL). Execution stops on your breakpoint.

Catch errors before running: PHPStan

A static analyser reads your code without running it and reports most errors in this module — undefined variables, wrong argument types and counts, calling methods on something that may be null, unknown classes. PHPStan and Psalm are the standard tools; many teams run PHPStan in CI and fail the build on new errors. Start at a low level and raise it as you fix things.

composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src --level 6

#  ------ ------------------------------------------------------------
#   Line   src/Checkout.php
#  ------ ------------------------------------------------------------
#   14     Cannot call method getEmail() on Customer|null.
#   22     Parameter #2 $percent of function applyDiscount expects int,
#          string given.
#  ------ ------------------------------------------------------------

Illustrative report. PHPStan and Psalm are Composer packages, so they are shown as commands rather than runnable examples.

Parse error

The file is not valid PHP syntax; nothing in it runs.

Fatal error

An error that stops the script. "Uncaught ..." fatal errors are exceptions nobody caught; the others (memory, redeclare) cannot be caught.

Warning

A reported problem after which the script continues, usually with null in place of a value.

Deprecated

Code that still works but will stop working in a future PHP version.

Stack trace

The list of active calls when an error happened, innermost (#0) first, ending at {main}.

display_errors

php.ini setting: print errors into the output. On in development, Off in production.

error_log

Function and setting for writing messages to the server log, stderr or a file.

Xdebug

The PHP debugging extension: breakpoints, stepping, variable inspection and profiling.

Static analysis

Checking code for errors without running it; PHPStan and Psalm for PHP.

Null-safe operator

?-> — calls a method or reads a property only if the left side is not null; otherwise gives null.