Errors And Exceptions Basics

Failure is part of a program's behavior. The important question is not whether something can go wrong, but whether the code detects the failure at the right boundary and responds without hiding the cause or exposing sensitive details.

PHP reports different kinds of problems. A syntax error means the file cannot be parsed. A warning reports a suspicious runtime condition but may allow execution to continue. An Error object represents serious engine-level failures such as many type errors. An exception is a Throwable object deliberately thrown by code when normal execution cannot continue along the current path.

Do not use these terms interchangeably. A warning is not automatically catchable with try and catch, and an expected business state is not automatically exceptional.

Validate Before Performing Risky Work

Prevent avoidable warnings by checking data before reading or operating on it:

<?php

$customer = ['email' => 'ada@example.com'];

if (!isset($customer['name'])) {
    echo "Name is missing\n";
    return;
}

echo $customer['name'], PHP_EOL;

The script chooses the missing-key path deliberately instead of reading an absent key and relying on PHP's warning output.

Validation and exceptions solve different parts of the problem. Validation identifies an invalid value. Throwing an exception communicates that the current function cannot fulfill its contract with that value.

Throw When A Function Cannot Return Its Promised Result

This normalizer promises a non-empty string:

<?php

function normaliseName(string $name): string
{
    $name = trim($name);

    if ($name === '') {
        throw new InvalidArgumentException('Name must not be empty.');
    }

    return $name;
}

Returning '' would violate the intended contract. Printing an error inside the function would not give the caller a usable string. throw stops the current path and sends a typed failure outward.

Use a specific built-in exception when its meaning fits. InvalidArgumentException communicates that a caller supplied an unacceptable argument. RuntimeException is often used when valid input cannot be processed because of a runtime condition. Custom exception classes become useful when callers need to distinguish application-specific failures; they are covered later with object-oriented PHP.

Catch At A Boundary That Can Respond

The caller can translate the exception into a controlled response:

<?php

try {
    $name = normaliseName('   ');
    echo "Customer: $name\n";
} catch (InvalidArgumentException $exception) {
    echo "Please enter a customer name.\n";
}

Output:

Please enter a customer name.

When normaliseName() throws, PHP stops the remaining statements in the try block and searches for the first compatible catch. The echo after the function call does not run.

Catch where you can make a real decision: show a safe validation message, retry an operation under a defined policy, translate the failure for another layer, add context and rethrow, or terminate a command with an appropriate exit code.

Do not catch an exception merely to ignore it. Silent failure leaves the program in an unexplained state.

Exceptions Bubble Through Function Calls

A catch does not need to be in the function that throws:

<?php

function parsePositiveQuantity(string $input): int
{
    if (!ctype_digit($input)) {
        throw new InvalidArgumentException('Quantity must contain digits only.');
    }

    $quantity = (int) $input;

    if ($quantity < 1) {
        throw new InvalidArgumentException('Quantity must be positive.');
    }

    return $quantity;
}

function buildQuantityLabel(string $input): string
{
    $quantity = parsePositiveQuantity($input);

    return "Quantity: $quantity";
}

try {
    echo buildQuantityLabel('0'), PHP_EOL;
} catch (InvalidArgumentException $exception) {
    echo "Invalid quantity\n";
}

The exception leaves parsePositiveQuantity(), then leaves buildQuantityLabel(), and reaches the matching catch. This movement up the call stack is often called bubbling.

If no compatible catch or global exception handler is found, the program terminates with an uncaught exception error. That is preferable to pretending the operation succeeded, but applications should establish controlled top-level handling.

Catch Specific Types Before Broad Types

A catch handles objects compatible with its declared type:

<?php

try {
    echo parsePositiveQuantity('two'), PHP_EOL;
} catch (InvalidArgumentException $exception) {
    echo "The quantity input is invalid.\n";
} catch (RuntimeException $exception) {
    echo "The quantity could not be processed.\n";
}

Place specific catches before broader parent types. Catching Throwable can intercept both exceptions and engine Error objects, but doing so deep in application code can conceal programming defects such as a TypeError.

A top-level framework or command runner may catch Throwable to log the failure and produce one safe response. That is different from claiming every failure is recoverable.

Preserve The Original Failure When Adding Context

Sometimes a lower-level exception needs a more useful application meaning. Catch it, create a new exception with context, and pass the original as the previous exception rather than discarding it:

try {
    $quantity = parsePositiveQuantity($input);
} catch (InvalidArgumentException $exception) {
    throw new RuntimeException("Could not build the order.", 0, $exception);
}

The outer message describes the failed operation, while the exception chain preserves the original validation cause for logs and debugging. Only add this layer when the new context helps a caller. Catching and immediately rethrowing the same exception without context usually adds no value.

Use finally For Cleanup That Must Be Attempted

A finally block runs after try and any matching catch, whether or not an exception was thrown:

<?php

function demonstrateCleanup(bool $fail): void
{
    try {
        echo "Start\n";

        if ($fail) {
            throw new RuntimeException('Operation failed.');
        }

        echo "Complete\n";
    } catch (RuntimeException $exception) {
        echo "Handled failure\n";
    } finally {
        echo "Cleanup\n";
    }
}

demonstrateCleanup(true);

Output:

Start
Handled failure
Cleanup

Real cleanup includes releasing locks, restoring a temporary handler, or closing a manually managed resource. Avoid returning or throwing a new exception from finally; it can replace the result or obscure an earlier failure.

Do Not Confuse Expected Outcomes With Exceptions

An order being pending is an ordinary business state:

<?php

function canShip(string $status): bool
{
    return $status === 'paid';
}

The caller can branch on false. No contract was broken.

An empty value passed to a function that promises a required name is different: the function cannot produce its promised result. That can justify an exception.

Use normal return values for expected alternatives that callers routinely inspect. Use exceptions for failures that interrupt the requested operation and should travel to a handling boundary.

Keep Internal Details Away From Users

An exception object can expose its message, code, file, line, and stack trace. Those details help developers, but raw output can reveal filesystem paths, configuration, queries, or other internals.

At a boundary, separate developer diagnostics from the public response:

<?php

try {
    $quantity = parsePositiveQuantity('abc');
    echo "Accepted: $quantity\n";
} catch (InvalidArgumentException $exception) {
    error_log($exception->getMessage());
    echo "Please provide a positive whole number.\n";
}

In a real application, use its configured logger rather than scattered error_log() calls. The principle is stable: record enough context privately and return a safe, actionable message publicly.

Never place passwords, access tokens, or complete sensitive payloads in exception messages or logs.

Warnings Are A Separate Mechanism

Many PHP operations report warnings rather than throwing exceptions. A surrounding try block does not automatically convert those warnings into exceptions.

PHP provides set_error_handler() and ErrorException for controlled conversion of certain non-fatal errors, but that is application infrastructure, not a substitute for checking expected conditions. It also cannot handle every fatal error category.

For beginner code, prefer APIs and validation that make failure explicit. Check array keys, validate input types and ranges, and test operation results where the API documents a failure return value.

CLI Programs Need Failure Exit Codes

A command-line entry point should report failure and exit non-zero:

<?php

try {
    $quantity = parsePositiveQuantity($argv[1] ?? '');
    echo "Quantity: $quantity\n";
} catch (InvalidArgumentException $exception) {
    fwrite(STDERR, "Invalid quantity\n");
    exit(1);
}

Standard output is for the normal result. Standard error is for diagnostics. Exit code 0 means success; a non-zero code lets shell scripts and deployment tools detect failure.

Keep exit() at the application boundary. Reusable functions should throw or return a result rather than terminating the entire process themselves.

Common Error-Handling Mistakes

What You Should Be Able To Do

After this lesson, you should be able to distinguish validation, warnings, Error objects, and exceptions; throw InvalidArgumentException when a function cannot satisfy its input contract; trace how an exception bubbles; catch a specific type at a useful boundary; explain why later try statements are skipped; use finally for cleanup; keep expected business alternatives as return values; separate internal diagnostics from safe user messages; and return a non-zero CLI exit code on failure.

Official references: PHP's manual pages for exceptions, Throwable, and set_error_handler().