Understand PHP.
Build systems that hold up.

What to master

• Variables, constants, control flow, functions, scope, includes, and error handling.
• Scalar types, null, coercion, strict comparisons, truthiness, and missing versus null values.
• Arrays, key conversion, destructuring, iterables, closures, arrow functions, and capture by value or reference.
• Typed parameters, returns, properties, union and intersection types, enums, readonly data, and attributes.
• Strings as bytes, Unicode operations, integer limits, float precision, dates, and time zones.

1.1 Think in values, contracts, and boundaries

A variable gives a value a name. A function gives a transformation a name. A type declaration describes a contract at a boundary. Start by asking three questions: what kind of value enters, what valid result leaves, and how invalid input is reported. A request parameter such as a student ID is initially untrusted input, even when a form presents a numeric field. The application must decide which representations it accepts before converting them.

An integer ID, the string "42", a missing parameter, an empty string, and an array parameter are different cases. A cast such as (int) $raw does not tell you whether the original value satisfied your rules. Design that decision explicitly. Keep boundary validation separate from the function that searches already-valid data.

<?php
declare(strict_types=1);

function positiveId(mixed $raw): int
{
    if (!is_string($raw) || !preg_match('/^[1-9][0-9]*$/D', $raw)) {
        throw new InvalidArgumentException('Use a positive decimal ID.');
    }
    $id = filter_var($raw, FILTER_VALIDATE_INT, [
        'options' => ['min_range' => 1],
    ]);
    if ($id === false) {
        throw new InvalidArgumentException('The ID is outside the integer range.');
    }
    return $id;
}

/** @param array<int, array{name: string, department: string}> $students */
function findStudent(array $students, int $id): ?array
{
    return $students[$id] ?? null;
}

$students = [
    1001 => ['name' => 'Rabin', 'department' => 'Computer Science'],
    1002 => ['name' => 'Anish', 'department' => 'Business'],
    1003 => ['name' => 'Anmol', 'department' => 'Computer Science'],
    1004 => ['name' => 'Maya', 'department' => 'Nursing'],
    1005 => ['name' => 'Sita', 'department' => 'Tourism'],
    1006 => ['name' => 'Alex', 'department' => 'Engineering'],
];

try {
    $id = positiveId($argv[1] ?? null);
    $student = findStudent($students, $id);
    echo $student === null
        ? "Student not found.\n"
        : $student['name'] . ' — ' . $student['department'] . "\n";
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, $e->getMessage() . "\n");
    exit(1);
}

php student.php 1001 → Rabin — Computer Science
php student.php 9999 → Student not found.
php student.php abc  → validation error and exit code 1

1.2 Comparisons and truthiness are business decisions

Use === when your rule requires both the value and its type to agree. Loose comparisons involve conversion rules, so they deserve a deliberate reason. Test the exact type returned by a library before choosing a condition: false can represent failure while 0 can be a legitimate result. This is why if (!$result) can discard valid information. A nonempty string such as "false" is not the boolean false.

<?php
declare(strict_types=1);
$row = ['nickname' => null];
var_dump('42' == 42);
var_dump('42' === 42);
var_dump((bool) '0');
var_dump((bool) 'false');
var_dump(isset($row['nickname']));
var_dump(array_key_exists('nickname', $row));

bool(true)
bool(false)
bool(false)
bool(true)
bool(false)
bool(true)

1.3 Scope, closures, and iteration

A local variable belongs to a function call. A closure can capture variables from the surrounding scope. Capture by value preserves the captured value at creation; capture by reference follows the aliased variable. Arrow functions automatically capture used outer variables by value. These differences matter in callbacks and delayed work: a callback can otherwise observe a value you did not expect.

<?php
declare(strict_types=1);
$base = 3;
$doubleBase = fn (): int => $base * 2;
$base = 20;

$counter = 0;
$next = function () use (&$counter): int {
    return ++$counter;
};

echo $doubleBase(), "\n";
echo $next(), ' ', $next(), ' ', $counter, "\n";

6
1 2 2

With foreach ($rows as &$row), the loop variable can remain a reference to the last element after the loop. Use unset($row) when you intentionally iterate by reference, or prefer a transformation that does not leave that alias behind. Avoid modifying a collection while depending on an assumed iteration order unless you have verified the semantics.

1.4 Strings, money, and time

PHP strings store bytes. Byte count, Unicode code-point count, and visible grapheme count are different concepts. strlen() measures bytes; choose mbstring or intl functions when your requirement concerns encoded text or user-perceived characters. Specify the encoding rather than relying on an accidental default.

For currency, represent minor units as integers when the currency and business rules fit that model. Use a decimal library or a carefully specified decimal representation when more precision is required. Avoid letting a floating-point approximation decide a bill, tax, or ledger entry. Date storage, display timezone, business calendar, and elapsed-time measurement also have separate purposes.

<?php
declare(strict_types=1);
function lineTotalCents(int $unitCents, int $quantity): int
{
    if ($unitCents < 0 || $quantity < 0) {
        throw new InvalidArgumentException('Price and quantity must be nonnegative.');
    }
    if ($quantity !== 0 && $unitCents > intdiv(PHP_INT_MAX, $quantity)) {
        throw new OverflowException('The total exceeds the integer range.');
    }
    return $unitCents * $quantity;
}
echo lineTotalCents(1299, 3), "\n";

3897

Read further: PHP language reference^[74] · Type declarations^[75] · Arrays^[76]

What to master

• SAPI, the Zend Engine, the virtual machine, CLI, PHP-FPM, extensions, and configuration.
• Source parsing, compilation into opcodes, OPcache, and the role of optional JIT compilation.
• zval values, reference counting, copy-on-write, object identity, references, cloning, and cyclic garbage collection.
• Request memory versus persistent process resources, and PHP memory accounting versus process RSS.
• Ordinary FPM requests versus a CLI queue worker or persistent application server.

2.1 Source code becomes engine instructions

In a conventional setup, PHP source is parsed and compiled into Zend opcodes, which the engine executes. OPcache retains compiled script representations so subsequent executions can avoid repeating compilation for unchanged scripts. This is a code cache. The application still performs its business logic and external calls. JIT can translate selected execution paths into native code; its usefulness depends on the workload and configuration.

2.2 SAPI connects the runtime to its environment

SAPI means Server API: the integration layer through which PHP receives its execution environment and returns output. CLI executes commands; FPM manages FastCGI workers for a web server. PHP extensions add facilities such as PDO drivers, mbstring, fileinfo, or cURL. Different binaries can load different INI files and extensions, so a successful CLI command does not establish that FPM has the same configuration.

php -v
php --ini
php -m
php -r 'echo PHP_SAPI, " ", PHP_VERSION, PHP_EOL;'

2.3 Values and shared structures

A zval is the engine representation of a PHP value: it carries type information and a value or a reference to an underlying structure. Some structures use reference counts. Array assignment usually avoids copying an entire backing structure immediately; separation can occur when a shared array is modified. Objects have identity, so assigning an object handle creates another way to access the same object.

<?php
declare(strict_types=1);
$original = ['views' => 1];
$copy = $original;
$copy['views'] = 2;
echo $original['views'], "\n";

$alias =& $original;
$alias['views'] = 3;
echo $original['views'], "\n";

$post = new stdClass();
$post->views = 1;
$samePost = $post;
$samePost->views = 4;
echo $post->views, "\n";

$separatePost = clone $post;
$separatePost->views = 9;
echo $post->views, ' ', $separatePost->views, "\n";

1
3
4
4 9

Reference counting handles many lifetimes efficiently, but a cycle can keep its members referenced even when application code no longer reaches them. PHP has a cycle collector for eligible structures. An ever-growing reachable array is a retention problem: the collector cannot discard data your program still keeps alive.

<?php
declare(strict_types=1);
function report(string $label): void
{
    printf("%s: %d bytes\n", $label, memory_get_usage());
}
$a = range(1, 100000);
report('after creation');
$b = $a;
report('after assignment');
$b[0] = 999;
report('after mutation');
unset($b);
report('after unset');
echo $a[0], "\n";

The printed byte counts depend on your environment.
The final value is 1.

2.4 Request lifetime is not process lifetime

The usual FPM model starts and cleans up ordinary request state for each request, while the operating-system worker process can remain alive. The engine also has persistent resources and shared code-cache structures. A CLI queue worker or a persistent application server can execute many jobs or requests without rebuilding all userland state each time. That changes the obligations of application code.

<?php
declare(strict_types=1);
final class RetainedEvents
{
    private static array $events = [];
    public static function record(string $event): void
    {
        self::$events[] = $event;
    }
    public static function count(): int
    {
        return count(self::$events);
    }
}
for ($job = 0; $job < 1000; $job++) {
    RetainedEvents::record(str_repeat('x', 1024));
}
gc_collect_cycles();
echo RetainedEvents::count(), "\n";

1000

Read further: OPcache^[6] · FPM configuration^[58] · zval structure^[7] · Memory management^[8] · Persistent applications^[67]

What to master

• Methods, URLs, headers, content types, bodies, status codes, redirects, and caching headers.
• GET parameters, form POST data, JSON via the request body, uploads, and explicit input parsing.
• Routing, a front controller, middleware, controllers, templates, and response generation.
• Cookies, server-side sessions, login state, session locking, and output buffering.
• Browser behavior around caching, CORS, and the Post/Redirect/Get pattern.

3.1 Follow the request through distinct layers

An HTTP request describes an operation on a resource. The web server chooses how to handle it. A front controller such as public/index.php starts the application, which routes the request, applies middleware, calls an application service, and produces a response. In a common Nginx deployment, the dynamic request reaches FPM through FastCGI. The browser sees response bytes, not the server-side PHP source.

The content type controls interpretation. A successful JSON parse does not establish that the resulting value has your required shape. Likewise, GET versus POST is a protocol and application-design decision; changing the method does not make unvalidated input trustworthy.

3.2 A complete small JSON endpoint

<?php
declare(strict_types=1);

function respond(int $status, array $body): never
{
    http_response_code($status);
    header('Content-Type: application/json; charset=utf-8');
    echo json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
    exit;
}

if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST') {
    header('Allow: POST');
    respond(405, ['error' => 'method_not_allowed']);
}
$type = strtolower(trim(explode(';', $_SERVER['CONTENT_TYPE'] ?? '')[0]));
if ($type !== 'application/json') {
    respond(415, ['error' => 'json_required']);
}
$raw = file_get_contents('php://input', false, null, 0, 8193);
if ($raw === false) {
    respond(500, ['error' => 'body_read_failed']);
}
if (strlen($raw) > 8192) {
    respond(413, ['error' => 'body_too_large']);
}
try {
    $input = json_decode($raw, false, 16, JSON_THROW_ON_ERROR);
} catch (JsonException) {
    respond(400, ['error' => 'invalid_json']);
}
if (!$input instanceof stdClass) {
    respond(422, ['error' => 'object_required']);
}
$input = get_object_vars($input);
if (array_diff(array_keys($input), ['name']) !== []) {
    respond(422, ['error' => 'unexpected_fields']);
}
$name = $input['name'] ?? null;
if (!is_string($name) || trim($name) === '' || mb_strlen($name, 'UTF-8') > 100) {
    respond(422, ['error' => 'invalid_name']);
}
respond(200, ['greeting' => 'Hello, ' . trim($name)]);

php -S 127.0.0.1:8000 -t public

# In a second terminal:
curl -i -X POST http://127.0.0.1:8000/api.php \
  -H 'Content-Type: application/json' \
  --data '{"name":"Rabin"}'

curl -i http://127.0.0.1:8000/api.php

PHP’s built-in development server is useful for learning, but its concurrency and operating model are not the production FPM model. Keep it bound to loopback for local exercises and use the manual to understand platform-specific worker options.

3.3 Cookies and sessions connect separate requests

A cookie is data the browser can send on later eligible requests. With a server-side session, an identifier connects the request to stored session state. Login usually stores an authenticated identity in that state; authorization still needs to evaluate each requested operation. Session storage can impose a lock, so several requests sharing one session can wait for one another even when other workers are idle.

<?php
declare(strict_types=1);
// Local exercise only. Add cookie_secure=true under production HTTPS.
session_start([
    'use_strict_mode' => true,
    'cookie_httponly' => true,
    'cookie_samesite' => 'Lax',
]);
$_SESSION['requests'] = (int) ($_SESSION['requests'] ?? 0) + 1;
$number = $_SESSION['requests'];
session_write_close();

// Artificial delay for observing concurrency in an appropriate runtime.
usleep(1_000_000);
header('Content-Type: text/plain; charset=utf-8');
echo "Request number: $number\n";

3.4 Response semantics and buffering

A safe method is intended for retrieval without requested state changes. Idempotency means repeating an operation has the same intended effect, not that every response is identical. After a form write, a 303 redirect to a GET can reduce accidental resubmission on refresh. These protocol semantics guide your API contract; application code must implement the behavior.

Output buffering can postpone when bytes reach the web server. Web-server, proxy, and client buffering can add further delays. Calling flush() does not force every layer to transmit immediately. Likewise, a stray echo or whitespace before headers can break a redirect or JSON response when buffering is absent. Keep output ownership explicit.

Read further: Session locking^[15] · Request lifecycle^[26] · HTTP middleware standard^[77]

What to master

• Classes, visibility, constructors, interfaces, inheritance, traits, composition, and method contracts.
• Dependency injection: passing collaborators explicitly rather than creating them throughout the code.
• Domain objects, value objects, DTOs, application services, and database or API adapters.
• Business invariants, immutable data where useful, exception boundaries, and transaction ownership.
• SOLID principles and selected patterns as tools for a concrete problem; modular boundaries before distributed services.

4.1 Model responsibilities before choosing patterns

A controller translates HTTP into an application call. An application service coordinates a use case. A domain object expresses a business concept and its invariants. A repository or adapter deals with external persistence. These names are useful when they separate responsibilities that change for different reasons. A small application may not need every layer as a separate class.

For a community platform, title validation is a business rule; extracting a string from JSON is a transport concern; inserting a row is a persistence concern. Keeping those boundaries clear lets a CLI import and an HTTP endpoint share the same use case. A framework can construct the objects, but it does not decide which business rule belongs where.

4.2 Encapsulation protects invariants

<?php
declare(strict_types=1);
final readonly class PostTitle
{
    public string $value;
    public function __construct(string $value)
    {
        $value = trim($value);
    if ($value === ''
        || !mb_check_encoding($value, 'UTF-8')
        || mb_strlen($value, 'UTF-8') > 120) {
        throw new InvalidArgumentException('A title needs valid UTF-8 and 1–120 characters.');
        }
        $this->value = $value;
    }
}
$title = new PostTitle('  First post  ');
echo $title->value, "\n";

First post

Composition gives an object collaborators that perform other responsibilities. Inheritance expresses a substitutable kind of an existing contract. Traits share implementation; they do not create an independent service boundary. Prefer the simplest arrangement that keeps dependencies and business rules understandable.

4.3 Dependency injection makes dependencies visible

<?php
declare(strict_types=1);
interface DemoPostStore
{
    public function insert(int $tenantId, int $authorId, string $title): int;
}

final class DemoMemoryPostStore implements DemoPostStore
{
    private array $rows = [];
    public function insert(int $tenantId, int $authorId, string $title): int
    {
        $id = count($this->rows) + 1;
        $this->rows[$id] = compact('tenantId', 'authorId', 'title');
        return $id;
    }
}

final readonly class DemoCreatePost
{
    public function __construct(private DemoPostStore $posts) {}
    public function execute(int $trustedTenantId, int $authorId, string $title): int
    {
        $title = trim($title);
        if ($trustedTenantId < 1 || $authorId < 1 || $title === '') {
            throw new InvalidArgumentException('Invalid post data.');
        }
        return $this->posts->insert($trustedTenantId, $authorId, $title);
    }
}

$service = new DemoCreatePost(new DemoMemoryPostStore());
echo $service->execute(1, 1001, 'Hello'), "\n";

1

A container can resolve constructor dependencies from bindings or reflection. It is an object-building mechanism. Avoid turning it into a global service locator used everywhere: code that pulls arbitrary dependencies from a container hides its true requirements. Read one container resolution path in your framework to remove the sense of magic.

4.4 Transaction ownership and side effects

If a use case changes several database records atomically, one layer must own the transaction. Repositories that independently commit their own changes can break the use case’s atomicity. External email or payment calls cannot generally be rolled back by a database rollback. Record durable intent in the transaction when a reliable later side effect is required, then process it separately. Pillar 11 develops this design.

4.5 Readability is a maintenance feature

Name operations after the domain outcome: publishPost, reserveSeat, or issueRefund. Keep parsing, authorization, business mutation, and response formatting visible as separate decisions. Use guard clauses for invalid conditions when they make the normal path easier to read. Keep an exception meaningful: callers need to know whether a failure means invalid input, denied access, temporary dependency failure, or a programming defect.

Read further: Objects and references^[78] · Service container^[18]

What to master

• composer.json, version constraints, transitive dependencies, composer.lock, install versus update, and platform requirements.
• Namespaces, PSR-4 autoloading, generated autoload maps, and vendor/autoload.php.
• Relevant PHP-FIG contracts, including logging and HTTP interfaces; consistent coding style.
• One framework in depth: choose Laravel for the capstone, then learn its routes, container, middleware, validation, ORM, events, and queues.
• Reading framework source and stack traces; package maintenance, audits, and upgrade guides.

5.1 Dependencies are part of the application

An application depends on its own source, libraries, extensions, and runtime. Composer records package requirements and resolves compatible versions, including transitive requirements. The application lock file records exact resolved versions. Installing from that file differs from resolving a new set of versions. Treat a dependency change as a code change that deserves review and validation.

For an application, commit composer.lock. Run install against the committed lock in a build or deployment. Run update intentionally in a development branch when changing the resolved dependency set. A library has a different relationship to its consumers: its constraints, rather than its private lock file, govern the dependency versions consumers resolve.

{
  "name": "community/php-learning",
  "type": "project",
  "require": {
    "php": "^8.4",
    "ext-pdo": "*",
    "ext-pdo_mysql": "*",
    "ext-mbstring": "*"
  },
  "autoload": {
    "psr-4": {
      "Community\\": "src/"
    }
  },
  "autoload-dev": {
    "psr-4": {
      "Community\\Tests\\": "tests/"
    }
  }
}

5.2 Autoloading connects class names to files

<?php
declare(strict_types=1);
namespace Community;

final readonly class Title
{
    public function __construct(public string $value)
    {
        if (trim($value) === '') {
            throw new \InvalidArgumentException('A title cannot be blank.');
        }
    }
}

<?php
declare(strict_types=1);
use Community\Title;

require dirname(__DIR__) . '/vendor/autoload.php';
$title = new Title('First post');
echo $title->value, "\n";

composer validate --strict
composer install
composer require --dev "phpunit/phpunit:^12.5" "phpstan/phpstan:^2.0"
composer audit
composer check-platform-reqs
composer dump-autoload --optimize

# Build a production dependency set from the committed lock:
composer install --no-dev --prefer-dist --optimize-autoloader --no-interaction
composer check-platform-reqs --no-dev

5.3 Standards give libraries a shared vocabulary

These standards do not make every implementation identical. Study the contract and the concrete behavior your application relies on. For example, a logger abstraction does not determine your retention policy, and an HTTP client interface does not automatically supply retries or asynchronous I/O.

5.4 Learn one framework through a vertical feature

After one small plain-PHP application, implement one complete Laravel feature: route, middleware, request validation, controller, service, database operation, response, and test. Locate the entry point and watch container construction. Read the SQL emitted by the ORM. Inspect when a queued job is serialized and what the worker reconstructs. This makes framework behavior explainable rather than mysterious.

Learn conventions because they help a team navigate a codebase, but retain the ability to reason about PHP, HTTP, SQL, and process lifetimes underneath. Learn Symfony or another framework later through the same boundaries when a job or project calls for it.

Read further: Composer basic usage^[20] · PSR-4^[21] · Laravel lifecycle^[26]

What to master

• Schema design, normalization, foreign keys, uniqueness, joins, aggregates, migrations, and data retention.
• PDO, parameter binding, driver differences, error modes, and native versus emulated prepares.
• Transactions, isolation, atomic updates, locking, race conditions, deadlocks, and bounded retries.
• Indexes, composite-key order, selectivity, execution plans, stable ordering, and keyset pagination.
• ORM-generated SQL, N+1 queries, result hydration, connection limits, and replication lag.

6.1 Constraints make persistent rules durable

PHP variables disappear or change with runtime lifetimes; the database is a separate source of persistent truth. Put durable relationships and uniqueness rules into the schema. Application validation gives useful error messages, while database constraints protect against concurrent callers and other write paths. Neither should be assumed to replace the other.

CREATE TABLE tenants (
    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(120) NOT NULL
) ENGINE=InnoDB;

CREATE TABLE users (
    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
    email VARCHAR(254) NOT NULL UNIQUE,
    display_name VARCHAR(80) NOT NULL,
    password_hash VARCHAR(255) NOT NULL
) ENGINE=InnoDB;

CREATE TABLE memberships (
    tenant_id BIGINT UNSIGNED NOT NULL,
    user_id BIGINT UNSIGNED NOT NULL,
    role VARCHAR(20) NOT NULL,
    PRIMARY KEY (tenant_id, user_id),
    FOREIGN KEY (tenant_id) REFERENCES tenants(id),
    FOREIGN KEY (user_id) REFERENCES users(id)
) ENGINE=InnoDB;

CREATE TABLE posts (
    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
    tenant_id BIGINT UNSIGNED NOT NULL,
    author_id BIGINT UNSIGNED NOT NULL,
    title VARCHAR(120) NOT NULL,
    body TEXT NOT NULL,
    created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    FOREIGN KEY (tenant_id, author_id)
        REFERENCES memberships(tenant_id, user_id),
    INDEX feed_order (tenant_id, created_at, id)
) ENGINE=InnoDB;

6.2 PDO connects PHP to a specific driver

<?php
declare(strict_types=1);
function connectDatabase(): PDO
{
    $dsn = getenv('APP_DB_DSN');
    $user = getenv('APP_DB_USER');
    $password = getenv('APP_DB_PASSWORD');
    if ($dsn === false || $user === false || $password === false) {
        throw new RuntimeException('Database configuration is missing.');
    }
    $db = new PDO($dsn, $user, $password, [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES => false,
    ]);
    $db->exec("SET time_zone = '+00:00'");
    return $db;
}

<?php
declare(strict_types=1);
function findPost(PDO $db, int $trustedTenantId, int $postId): ?array
{
    $stmt = $db->prepare(
        'SELECT id, author_id, title, body, created_at
         FROM posts WHERE tenant_id = :tenant AND id = :id'
    );
    $stmt->execute(['tenant' => $trustedTenantId, 'id' => $postId]);
    $row = $stmt->fetch();
    return $row === false ? null : $row;
}

Placeholders represent data literals, not column names, table names, directions, or complete SQL fragments. For a submitted sort option, map allowed names to fixed SQL expressions in application code. Native and emulated prepares differ; read the specific driver’s behavior and never build the remaining query structure from arbitrary input.

6.3 Indexes are access paths with tradeoffs

A composite index is ordered by its component keys. The leading columns strongly influence which filtering and ordering patterns it can serve. Indexes can reduce work for selected queries, but they consume storage and add work to writes. Study the query shape, row distribution, and execution plan rather than indexing every column independently.

EXPLAIN
SELECT id, author_id, title, created_at
FROM posts
WHERE tenant_id = 1
ORDER BY created_at DESC, id DESC
LIMIT 50;

-- In a controlled development dataset:
EXPLAIN ANALYZE
SELECT id, author_id, title, created_at
FROM posts
WHERE tenant_id = 1
ORDER BY created_at DESC, id DESC
LIMIT 50;

6.4 Stable pagination needs an ordering contract

SELECT id, author_id, title, created_at
FROM posts
WHERE tenant_id = :tenant
  AND (
    created_at < :before_time_1
    OR (created_at = :before_time_2 AND id < :before_id)
  )
ORDER BY created_at DESC, id DESC
LIMIT 50;

6.5 Transactions and concurrent writes

A transaction groups database changes into a commit-or-rollback boundary. Isolation determines what concurrent transactions observe; locks, atomic statements, and constraints determine how competing changes interact. A transaction alone does not automatically turn “read, check, write” into a correct concurrency design.

<?php
declare(strict_types=1);
function reserveOne(PDO $db, int $trustedTenantId, int $itemId): bool
{
    $stmt = $db->prepare(
        'UPDATE inventory
         SET available = available - 1
         WHERE tenant_id = :tenant AND id = :id AND available >= 1'
    );
    $stmt->execute(['tenant' => $trustedTenantId, 'id' => $itemId]);
    return $stmt->rowCount() === 1;
}

Deadlocks can be a normal consequence of competing transactions. Keep transactions short, acquire resources consistently, and retry the whole failed transaction only under a bounded policy when its operations are safe to repeat. Do not hold a database transaction open around a slow remote network call without understanding the costs and failure model.

6.6 An ORM still issues SQL

Loading 50 posts and then making a separate author query for each post can create an N+1 pattern. Inspect query count and generated SQL. A join, eager load, or bounded batch query can reduce round trips, but blindly loading all relationships can increase the amount of materialized data. The correct fix follows the representation the endpoint actually needs.

Read further: PDO prepare^[27] · Transactions^[30] · MySQL indexes^[79] · InnoDB locking^[32]

What to master

• Authentication, authorization, object ownership, tenant isolation, least privilege, and audit trails.
• SQL injection, context-aware XSS defenses, CSRF, session fixation, secure cookies, and login throttling.
• password_hash(), password_verify(), password reset design, and secret management.
• Upload validation and storage, path traversal, command injection, SSRF, and unsafe deserialization.
• Trust boundaries, allowlists, dependency updates, and avoiding sensitive data in logs.

7.1 Follow the trust boundary

Every request supplies claims: a cookie, an ID, a tenant selector, a filename, a role, or a JSON field. The server decides which claims are authentic and what authority they grant. Authentication identifies a principal; authorization decides whether that principal may perform this operation on this resource now. A valid session does not establish permission for every resource ID.

A useful default is to deny actions unless a rule grants them. Centralize the policy where it can be reviewed and tested, and still keep tenant restrictions in the data access path. Do not trust a client-supplied role or assume that hiding an interface button protects the endpoint.

<?php
declare(strict_types=1);
function deletePermittedPost(
    PDO $db,
    int $authenticatedUserId,
    int $selectedTenantId,
    int $postId
): bool {
    $stmt = $db->prepare(
        "DELETE p FROM posts AS p
         JOIN memberships AS m
           ON m.tenant_id = p.tenant_id AND m.user_id = :actor
         WHERE p.tenant_id = :tenant
           AND p.id = :post
           AND (p.author_id = m.user_id OR m.role = 'admin')"
    );
    $stmt->execute([
        'actor' => $authenticatedUserId,
        'tenant' => $selectedTenantId,
        'post' => $postId,
    ]);
    return $stmt->rowCount() === 1;
}

7.2 Passwords need a password hashing API

<?php
declare(strict_types=1);
$password = 'local-demo-passphrase-only';
$storedHash = password_hash($password, PASSWORD_DEFAULT);

var_dump(password_verify($password, $storedHash));
var_dump(password_verify('wrong passphrase', $storedHash));

if (password_verify($password, $storedHash)
    && password_needs_rehash($storedHash, PASSWORD_DEFAULT)) {
    $newHash = password_hash($password, PASSWORD_DEFAULT);
    // Persist after successful authentication.
}

bool(true)
bool(false)

Do not replace this with fast SHA-256, a fixed salt, reversible encryption, or an invented algorithm. Login also needs abuse controls, secure recovery, session renewal after authentication, and an error policy that does not expose unnecessary account information. A good hash solves one part of the authentication system.

7.3 Encode output for the destination context

<?php
declare(strict_types=1);
$displayName = '<script>alert("demo")</script>';
$safeName = htmlspecialchars(
    $displayName,
    ENT_QUOTES | ENT_SUBSTITUTE,
    'UTF-8'
);
echo '<p>Hello, ' . $safeName . '</p>';

7.4 Sessions and CSRF protect different properties

A browser can attach a session cookie automatically. A cross-site request can therefore carry credentials even when the attacker cannot read the response. A CSRF defense establishes that a state-changing browser request belongs to an intended application interaction. It does not replace authorization, and XSS can undermine the protections around a session.

<?php
declare(strict_types=1);
// This example expects HTTPS and a configured session handler.
ini_set('session.use_strict_mode', '1');
session_set_cookie_params([
    'secure' => true,
    'httponly' => true,
    'samesite' => 'Lax',
    'path' => '/',
]);
session_start();

if (!isset($_SESSION['csrf']) || !is_string($_SESSION['csrf'])) {
    $_SESSION['csrf'] = bin2hex(random_bytes(32));
}
$token = $_SESSION['csrf'];

if (($_SERVER['REQUEST_METHOD'] ?? '') === 'POST') {
    $submitted = $_POST['csrf'] ?? null;
    if (!is_string($submitted) || !hash_equals($token, $submitted)) {
        http_response_code(403);
        exit('Invalid request token');
    }
    // Authenticate, authorize, validate, and then execute the action.
    session_write_close();
    echo 'Token accepted; the business action is not implemented.';
    exit;
}
session_write_close();
header('Content-Type: text/html; charset=UTF-8');
$encoded = htmlspecialchars($token, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
echo '<form method="post">';
echo '<input type="hidden" name="csrf" value="' . $encoded . '">';
echo '<button type="submit">Submit protected action</button></form>';

7.5 Uploads are a storage and delivery boundary

<?php
declare(strict_types=1);
function storeTextAttachment(array $upload, string $privateDirectory): string
{
    if (!isset($upload['error'], $upload['tmp_name'])
        || !is_int($upload['error'])
        || !is_string($upload['tmp_name'])
        || $upload['error'] !== UPLOAD_ERR_OK) {
        throw new InvalidArgumentException('Invalid upload');
    }
    $temporary = $upload['tmp_name'];
    if (!is_uploaded_file($temporary)) {
        throw new InvalidArgumentException('Expected an HTTP upload');
    }
    $bytes = filesize($temporary);
    if ($bytes === false || $bytes < 1 || $bytes > 1_000_000) {
        throw new InvalidArgumentException('Invalid attachment size');
    }
    $mime = (new finfo(FILEINFO_MIME_TYPE))->file($temporary);
    if ($mime !== 'text/plain') {
        throw new InvalidArgumentException('Expected plain text');
    }
    $directory = realpath($privateDirectory);
    if ($directory === false || !is_dir($directory)) {
        throw new RuntimeException('Storage directory is unavailable');
    }
    $storageKey = bin2hex(random_bytes(16)) . '.txt';
    if (!move_uploaded_file($temporary, $directory . '/' . $storageKey)) {
        throw new RuntimeException('Could not store attachment');
    }
    return $storageKey;
}

7.6 Outbound requests and dangerous interpretation

Fetching a submitted URL can turn your server into a way to reach private services. A URL parser alone is not an SSRF defense: redirects, DNS resolution, alternate address forms, and network placement matter. Prefer fixed provider endpoints or a narrow approved destination policy plus controlled egress. Do not let an authenticated user supply arbitrary internal URLs merely because the request has a session.

Keep data out of interpreters: do not unserialize untrusted PHP objects, assemble shell commands from user input, or dynamically include paths chosen by a request. For imports, parse the documented data format into validated values. For processes, use a library with an argument-vector API and a fixed executable. Review error logs and tracing for secrets as well as the response body.

Read further: OWASP authorization^[34] · XSS prevention^[38] · CSRF prevention^[39] · Password hashing^[35]

What to master

• Unit tests for business rules, database integration tests, HTTP feature tests, and contract tests.
• Fixtures, factories, useful test doubles, deterministic time, and tests for failure paths.
• PHPUnit, PHPStan, Xdebug breakpoints, call stacks, and variable inspection.
• Exceptions versus PHP errors, structured logs, request identifiers, and minimal reproductions.
• Regression tests, code review, and CI checks chosen around meaningful risks.

8.1 Test the promise at the right boundary

A useful test proves a behavior that matters when the implementation changes. “The mock was called once” can help for a specific protocol, but it is often weaker than proving that a denied request caused no write or that a replay produced one logical effect. Make test failures explain the violated contract.

8.2 A focused PHPUnit test

<?php
declare(strict_types=1);
namespace Community\Tests;

use Community\Title;
use InvalidArgumentException;
use PHPUnit\Framework\TestCase;

final class TitleTest extends TestCase
{
    public function testItKeepsAnOrdinaryTitle(): void
    {
        $title = new Title('First post');
        self::assertSame('First post', $title->value);
    }

    public function testItRejectsWhitespaceOnlyText(): void
    {
        $this->expectException(InvalidArgumentException::class);
        new Title(" \t\n ");
    }
}

vendor/bin/phpunit --bootstrap vendor/autoload.php tests/TitleTest.php
vendor/bin/phpunit --bootstrap vendor/autoload.php tests

Do not make unit tests rely on an actual clock, random network delays, or a live provider account when those dependencies are not the behavior being tested. Inject a clock or transport where it improves control. Conversely, do not replace the actual database with a fake when the point is to verify a SQL constraint or transaction rule.

8.3 Static analysis adds information before execution

<?php
declare(strict_types=1);
/**
 * @param array{id: int, name: string}|null $student
 */
function greeting(?array $student): string
{
    if ($student === null) {
        return 'Student not found';
    }
    return 'Hello, ' . $student['name'];
}
echo greeting(['id' => 100, 'name' => 'Amina']) . PHP_EOL;
echo greeting(null) . PHP_EOL;

Hello, Amina
Student not found

parameters:
    level: 8
    paths:
        - src
    tmpDir: var/phpstan

vendor/bin/phpstan analyse --no-progress
php -l src/Title.php

A baseline can help introduce an analyzer to an existing codebase, but every ignored finding needs an ownership and reduction plan. Broadly declaring everything mixed or silencing all errors removes the information you wanted the analyzer to provide. Favor precise types where they reflect a real contract.

8.4 Debug the actual path

1. Reproduce: record the request, data, version, and configuration needed to trigger the problem.
2. Narrow: identify the earliest boundary where actual values differ from the contract.
3. Inspect: use a breakpoint to read the stack and local values; inspect SQL and external request metadata where needed.
4. Explain: write the causal chain, including the hidden assumption.
5. Repair: add a focused regression case and change the responsible boundary.
6. Verify: run the relevant tests and observe the previously failing behavior.

Xdebug step debugging is useful for following a request through middleware, a controller, a service, and an adapter. Configure it deliberately for development; avoid exposing debugger access or collecting sensitive values through careless production debugging. A profiler answers a different question from a breakpoint debugger.

8.5 Diagnostics should preserve evidence

An exception type, correlation ID, operation name, elapsed time, and safe resource identifiers can explain a failure without recording raw passwords, cookies, complete uploaded documents, or provider secrets. Structured logs help compare events across requests and workers. Metrics expose trends; traces expose a path; neither excuses a missing explanation of the failure.

Read further: PHPUnit manual^[80] · PHPStan^[48] · Xdebug^[49]

What to master

• Latency, throughput, p50/p95/p99, CPU time, waiting time, worker utilization, and load-test methodology.
• Generators, file streams, bounded batches, bulk writes, and resumable imports.
• PDO result buffering, ORM hydration, narrow selects, and end-to-end streaming.
• OPcache versus Redis application caching; cache keys, invalidation, TTL, stampedes, and stale data.
• FPM capacity, process memory, database capacity, output buffering, and when analytics needs a separate system.

9.1 Name the workload before choosing a technique

“Big data” describes several different problems. Ten million stored rows with selective queries is different from a million-row export, a high arrival rate of small requests, or a CPU-heavy transformation. State the input size, access pattern, acceptable latency, freshness, concurrency, and failure behavior first. PHP often coordinates databases, storage, queues, and analytical engines; moving every dataset into a PHP array is rarely a useful goal.

PDO MySQL commonly uses buffered query results by default. Eloquent’s cursor keeps relatively little application state, but the database driver can still retain the raw result. A cursor method’s name is not proof of end-to-end bounded memory. With an unbuffered MySQL result, you also have restrictions on issuing another query on that connection until the result is consumed.

9.2 Parse and validate incrementally

<?php
declare(strict_types=1);
/**
 * Expected CSV header: id,email,name
 * @return Generator<int, array{id:int, email:string, name:string}>
 */
function peopleFromCsv(string $path): Generator
{
    $handle = fopen($path, 'rb');
    if ($handle === false) {
        throw new RuntimeException('Could not open input');
    }
    try {
        $header = fgetcsv($handle, null, ',', '"', '');
        if ($header !== ['id', 'email', 'name']) {
            throw new InvalidArgumentException('Unexpected CSV header');
        }
        $record = 1;
        while (($fields = fgetcsv($handle, null, ',', '"', '')) !== false) {
            $record++;
            if (count($fields) !== 3
                || !is_string($fields[0])
                || preg_match('/^[1-9][0-9]*$/D', $fields[0]) !== 1
                || !is_string($fields[1])
                || !is_string($fields[2])) {
                throw new InvalidArgumentException("Malformed record {$record}");
            }
            $id = filter_var(
                $fields[0],
                FILTER_VALIDATE_INT,
                ['options' => ['min_range' => 1]]
            );
            $name = trim($fields[2]);
            if ($id === false
                || filter_var($fields[1], FILTER_VALIDATE_EMAIL) === false
                || !mb_check_encoding($name, 'UTF-8')
                || $name === ''
                || mb_strlen($name, 'UTF-8') > 80) {
                throw new InvalidArgumentException("Invalid record {$record}");
            }
            yield ['id' => $id, 'email' => $fields[1], 'name' => $name];
        }
        if (!feof($handle)) {
            throw new RuntimeException('Input read failed');
        }
    } finally {
        fclose($handle);
    }
}

$path = $argv[1] ?? null;
if (!is_string($path)) {
    throw new InvalidArgumentException('Usage: php import-read.php people.csv');
}
$count = 0;
foreach (peopleFromCsv($path) as $person) {
    // Validate further and write a bounded batch here.
    $count++;
}
echo "Valid records: {$count}" . PHP_EOL;

id,email,name
100,amina@example.test,Amina
101,jules@example.test,"Jules, Jr."
102,mei@example.test,Mei

Valid records: 3

A resumable import needs more than a generator. Define a job identity, immutable source identity or checksum, a row/record identity, validation policy, batch transaction, durable checkpoint, duplicate rule, and a final report. Commit the data and its checkpoint together when they share a database. Decide whether one bad record rejects the whole file or is recorded as a row-level error. Do not silently change that contract halfway through a large import.

9.3 Bound database exports with a high-water mark

<?php
declare(strict_types=1);
/** @param resource $output */
function exportPostMetadata(PDO $db, int $trustedTenantId, $output): void
{
    $max = $db->prepare(
        'SELECT COALESCE(MAX(id), 0) FROM posts WHERE tenant_id = :tenant'
    );
    $max->execute(['tenant' => $trustedTenantId]);
    $upperId = (int) $max->fetchColumn();
    $max->closeCursor();

    $page = $db->prepare(
        'SELECT id, author_id, created_at FROM posts
         WHERE tenant_id = :tenant AND id > :after AND id <= :upper
         ORDER BY id ASC LIMIT 500'
    );
    if (fputcsv($output, ['id', 'author_id', 'created_at'], ',', '"', '') === false) {
        throw new RuntimeException('Could not write export header');
    }
    $lastId = 0;
    while (true) {
        $page->bindValue(':tenant', $trustedTenantId, PDO::PARAM_INT);
        $page->bindValue(':after', $lastId, PDO::PARAM_INT);
        $page->bindValue(':upper', $upperId, PDO::PARAM_INT);
        $page->execute();
        $rows = $page->fetchAll(PDO::FETCH_ASSOC); // At most 500 rows.
        $page->closeCursor();
        if ($rows === []) {
            break;
        }
        foreach ($rows as $row) {
            $written = fputcsv($output, [
                (string) $row['id'],
                (string) $row['author_id'],
                (string) $row['created_at'],
            ], ',', '"', '');
            if ($written === false) {
                throw new RuntimeException('Could not write export row');
            }
            $lastId = (int) $row['id'];
        }
    }
}

For a private export, prefer a job that writes to authorized private storage and publishes completion metadata. If you stream over HTTP, consider reverse-proxy buffering, disconnects, timeouts, partial files, and session locks. Sending some bytes does not make the operation resumable. Large exports may need an asynchronous interface rather than keeping a web worker occupied for minutes.

CSV quoting solves CSV syntax; it does not necessarily prevent a spreadsheet from interpreting a text cell as a formula. If you export user-authored names, titles, or other text, choose a spreadsheet-safe representation policy and test it with the actual consuming software. Preserve the underlying data contract and do not assume one escaping trick behaves identically in every spreadsheet.

9.4 Measure memory and time without inventing results

<?php
declare(strict_types=1);
function numbers(int $count): Generator
{
    for ($i = 1; $i <= $count; $i++) {
        yield $i;
    }
}
$mode = $argv[1] ?? 'generator';
if (!in_array($mode, ['generator', 'array'], true)) {
    throw new InvalidArgumentException('Use generator or array');
}
$count = 500_000;
$start = hrtime(true);
$values = $mode === 'array' ? range(1, $count) : numbers($count);
$sum = 0;
foreach ($values as $number) {
    $sum += $number;
}
printf(
    "%s sum=%d elapsed_ms=%.2f peak_mib=%.2f\n",
    $mode,
    $sum,
    (hrtime(true) - $start) / 1_000_000,
    memory_get_peak_usage(true) / 1_048_576
);

Both sums should be 125000250000.
Elapsed time and peak memory are measurements to collect on your system.

9.5 Cache only a defined representation

A useful feed cache key might include tenant, viewer permission scope, representation version, page cursor, and a version of the feed data. If viewers have different visibility, a tenant-only key can disclose data. After a committed mutation, invalidate or advance the relevant version under a documented freshness policy. TTL limits a key’s lifetime; it does not guarantee immediate freshness. When many requests miss together, bound rebuild work rather than overwhelming the database.

9.6 Worker occupancy explains one capacity constraint

For an ordinary FPM worker handling one request at a time, the request occupies a worker while PHP waits as well as while it computes. A slow network call or session wait can consume capacity even at low CPU usage. The calculator below is an idealized arithmetic illustration using mean occupancy time. It omits CPU competition, database limits, arrival bursts, service-time variance, and other queues.

Collect median, p95, p99, error rate, throughput, queue depth, worker memory, query count, and downstream latency where relevant. State whether caches are warm, which dataset was used, and which workload mix generated the report. A faster average that hides a failing tail or a rising error rate is not a complete improvement.

Read further: Generators^[52] · PDO/MySQL buffering^[50] · Eloquent streaming caveat^[81] · FPM capacity^[58]

What to master

• Resource design, validation, response schemas, error contracts, pagination, rate limits, and versioning.
• Session or token authentication choices and authorization on every relevant API operation.
• HTTP clients, connection and request timeouts, status handling, bounded retries, and backoff with jitter.
• Idempotency keys, signed webhooks, deduplication, event order, and durable event acceptance.
• Email, payments, object storage, and provider limits using maintained SDKs where appropriate.

10.1 An API is a contract across an unreliable boundary

Specify methods, authentication, authorization, field types, size limits, status behavior, pagination, error shape, and compatibility policy. The consumer should be able to distinguish a rejected operation from an accepted operation whose response was lost. Stable contracts are especially valuable when several clients deploy on different schedules.

10.2 Bound outbound calls and classify the result

<?php
declare(strict_types=1);
function fetchMockStatus(): array
{
    // Fixed local lab endpoint. Use the provider's approved HTTPS URL in production.
    $handle = curl_init('http://127.0.0.1:8090/status');
    if ($handle === false) {
        throw new RuntimeException('Could not initialize transport');
    }
    try {
        curl_setopt_array($handle, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CONNECTTIMEOUT_MS => 500,
            CURLOPT_TIMEOUT_MS => 1500,
            CURLOPT_FOLLOWLOCATION => false,
            CURLOPT_HTTPHEADER => ['Accept: application/json'],
        ]);
        $body = curl_exec($handle);
        if ($body === false) {
            throw new RuntimeException('Transport failure: ' . curl_error($handle));
        }
        $status = (int) curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
        if ($status !== 200) {
            throw new RuntimeException("Unexpected remote status {$status}");
        }
        if (strlen($body) > 64_000) {
            throw new RuntimeException('Mock response is too large');
        }
        $decoded = json_decode($body, false, 16, JSON_THROW_ON_ERROR);
        if (!$decoded instanceof stdClass
            || !isset($decoded->state)
            || !is_string($decoded->state)) {
            throw new RuntimeException('Invalid remote representation');
        }
        return ['state' => $decoded->state];
    } finally {
        unset($handle); // Release this CurlHandle reference.
    }
}

Modern PHP uses a CurlHandle object. The example releases its reference rather than calling curl_close, which has no effect since PHP 8.0 and is deprecated in PHP 8.5.

<?php
declare(strict_types=1);
if (($_SERVER['REQUEST_URI'] ?? '') !== '/status') {
    http_response_code(404);
    exit;
}
header('Content-Type: application/json; charset=UTF-8');
echo json_encode(['state' => 'ready'], JSON_THROW_ON_ERROR);

Retry only when the operation and observed failure support it. A connection failure before sending and a timeout after a possible commit are not equivalent. Use a bounded attempt count and deadline, backoff with jitter, and any provider retry guidance. Respect throttling signals. Retrying an unsafe mutation without an operation identity can multiply effects.

10.3 Design the idempotency record, not just a header

For a change entirely inside one database, insert or claim the unique operation record and commit the business effect and completed result under a coherent transaction design. For a remote provider, a local transaction cannot atomically include the provider’s database. Persist intent, use the provider’s documented idempotency contract where available, and reconcile unknown outcomes. Do not hold a database transaction open and describe a remote call as part of its rollback guarantee.

10.4 Verify webhooks before interpreting their body

<?php
declare(strict_types=1);
function validLabSignature(
    string $rawBody,
    string $timestamp,
    string $signature,
    string $secret,
    int $now
): bool {
    if ($secret === ''
        || preg_match('/^[0-9]{10}$/D', $timestamp) !== 1
        || preg_match('/^[a-f0-9]{64}$/D', $signature) !== 1) {
        return false;
    }
    $sentAt = (int) $timestamp;
    if (abs($now - $sentAt) > 300) {
        return false;
    }
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

$body = '{"event_id":"demo-1","type":"post.created"}';
$timestamp = '1800000000';
$secret = 'local-lab-secret-only';
$signature = hash_hmac('sha256', $timestamp . '.' . $body, $secret);
var_dump(validLabSignature($body, $timestamp, $signature, $secret, 1800000000));
var_dump(validLabSignature($body . ' ', $timestamp, $signature, $secret, 1800000000));

bool(true)
bool(false)

After verification, validate the event schema and persist durable receipt or work before acknowledging it according to the provider contract. Deliveries can be repeated and arrive out of order. An old event must not overwrite a newer state simply because it was received later. Where the event is a notification rather than an authoritative complete record, fetch the current provider state through the approved API when needed.

10.5 Error responses and integration observability

A useful error representation includes a stable application code, safe explanatory text, and a correlation ID. Field errors may be appropriate for validation. Stack traces, SQL, access tokens, internal network addresses, and raw provider secrets do not belong in a public response. Internally, record the operation identity, attempt number, provider request ID, latency, and outcome category so an uncertain action can be investigated.

Read further: Stripe webhook behavior^[63] · Stripe idempotent requests^[61]

What to master

• FPM concurrency, CLI workers, job queues, schedulers, and concurrency versus parallel execution.
• Job reservation, acknowledgments, visibility timeouts, retries, dead-letter handling, and idempotency.
• Atomic database operations, uniqueness, locks, lease expiry, and crash recovery.
• Dispatch after commit, the remaining database-to-queue failure gap, and transactional outbox patterns.
• Persistent worker state, restart behavior, graceful shutdown, bounded memory, and optional fibers or event loops.

11.1 Concurrency exists even when one request is synchronous

One PHP request may execute ordinary code sequentially while many other PHP workers run at the same time. They can compete for database rows, cache keys, files, and provider operations. A queue adds more competing processes; it does not remove the need for invariants. Concurrency reasoning starts with the shared resource and its enforcement boundary.

Fibers are not an instruction to run ordinary CPU-bound PHP code simultaneously on several cores. Suspending a fiber does not make a blocking database or network call nonblocking by itself. A runtime needs an appropriate scheduler and I/O integration. Understand the deployment model before adopting an asynchronous style.

11.2 A job can run more than once

Consider a worker that applies an effect and then crashes before acknowledging the message. The broker can redeliver it because it cannot know the worker’s application state. A handler must therefore define what a repeat means. At-least-once delivery can be useful, but it requires idempotent processing or durable deduplication at the relevant effect boundary.

11.3 Persist business changes and event intent together

The outbox pattern stores the intended event in the same transaction as the local business change. A separate process publishes it later. This avoids committing a post and losing the only record that a notification should be produced. It also avoids pretending that sending to a broker participates in a normal PDO transaction.

<?php
declare(strict_types=1);
function createPostWithOutbox(
    PDO $db,
    int $trustedTenantId,
    int $authenticatedAuthorId,
    PostTitle $title,
    string $validatedBody
): int {
    if ($db->inTransaction()) {
        throw new LogicException('This use case owns its transaction');
    }
    $eventId = bin2hex(random_bytes(16));
    $db->beginTransaction();
    try {
        $post = $db->prepare(
            'INSERT INTO posts (tenant_id, author_id, title, body)
             VALUES (:tenant, :author, :title, :body)'
        );
        $post->execute([
            'tenant' => $trustedTenantId,
            'author' => $authenticatedAuthorId,
            'title' => $title->value,
            'body' => $validatedBody,
        ]);
        $postId = (int) $db->lastInsertId();
        $event = $db->prepare(
            'INSERT INTO outbox_events (event_id, tenant_id, event_type, payload)
             VALUES (:event, :tenant, :type, :payload)'
        );
        $event->execute([
            'event' => $eventId,
            'tenant' => $trustedTenantId,
            'type' => 'post.created',
            'payload' => json_encode([
                'event_id' => $eventId,
                'tenant_id' => $trustedTenantId,
                'post_id' => $postId,
                'schema_version' => 1,
            ], JSON_THROW_ON_ERROR),
        ]);
        $db->commit();
        return $postId;
    } catch (Throwable $failure) {
        if ($db->inTransaction()) {
            $db->rollBack();
        }
        throw $failure;
    }
}

A production publisher needs a bounded batch, a claim/ownership policy for multiple publishers, a retry schedule, and visibility into stuck rows. A useful shape is: claim a batch in a short database transaction, send outside that transaction, then mark progress only if the claim still belongs to this publisher. Decide whether per-resource ordering is required. A lease alone does not prevent a stale worker from applying an external effect; use appropriate ownership/fencing or provider idempotency where needed.

11.4 Deduplicate a local effect atomically

<?php
declare(strict_types=1);
function applyPostCreated(
    PDO $db,
    int $trustedEventTenantId,
    string $eventId
): bool {
    if (preg_match('/^[a-f0-9]{32}$/D', $eventId) !== 1) {
        throw new InvalidArgumentException('Invalid internal event ID');
    }
    if ($db->inTransaction()) {
        throw new LogicException('This handler owns its transaction');
    }
    $db->beginTransaction();
    try {
        $receipt = $db->prepare(
            'INSERT INTO consumer_receipts
             (consumer_name, event_id, tenant_id)
             VALUES (:consumer, :event, :tenant)'
        );
        try {
            $receipt->execute([
                'consumer' => 'tenant-post-counter-v1',
                'event' => $eventId,
                'tenant' => $trustedEventTenantId,
            ]);
        } catch (PDOException $failure) {
            if ($failure->getCode() === '23000'
                && (int) ($failure->errorInfo[1] ?? 0) === 1062) {
                $db->rollBack();
                return false; // This consumer already handled this event.
            }
            throw $failure;
        }
        $counter = $db->prepare(
            'UPDATE post_counters
             SET created_count = created_count + 1
             WHERE tenant_id = :tenant'
        );
        $counter->execute(['tenant' => $trustedEventTenantId]);
        if ($counter->rowCount() !== 1) {
            throw new RuntimeException('Tenant counter is not initialized');
        }
        $db->commit();
        return true;
    } catch (Throwable $failure) {
        if ($db->inTransaction()) {
            $db->rollBack();
        }
        throw $failure;
    }
}

The event identity must be trustworthy and bound to the intended tenant. Do not accept arbitrary event IDs and tenant IDs from a public endpoint as trusted internal messages. Receipt retention is also part of the guarantee: deleting the receipt while old deliveries remain possible can let a replay apply again.

11.5 Framework dispatch timing and process lifetime

DB::transaction(function () use ($actorId, $tenantId) {
    // Perform the authorized local write.
    GenerateExport::dispatch($actorId, $tenantId)->afterCommit();
});

Long-lived queue and application workers retain a different lifecycle from ordinary request-local code. Avoid storing a current user, tenant, request, growing collection, or stale container binding in a shared object. Restart workers during releases so new code is loaded, and bound job execution and resource use. The exact reset behavior depends on the runtime.

Read further: Laravel queues^[66] · Transactional outbox^[65] · PHP fibers^[64]

What to master

• Linux process basics, Nginx or Apache, FPM, containers where useful, and environment configuration.
• Versioned builds, CI/CD, dependency installation, safe migrations, worker reloads, rollback, and upgrade testing.
• Secrets, file permissions, HTTPS, production error handling, health checks, logs, metrics, and tracing.
• Backups, restore drills, incidents, capacity planning, and operational runbooks.
• Client requirements, acceptance criteria, data policies, documentation, cost tradeoffs, and maintenance handoff.

12.1 A production release includes the running system

A repository is only part of the product. The deployed runtime also has extensions, configuration, secrets, a database schema, storage permissions, web-server routing, queue workers, scheduled tasks, telemetry, and backups. A professional delivery makes those dependencies explicit and recoverable.

12.2 The public root should be small

server {
    listen 443 ssl;
    server_name community.example.test;
    root /srv/community/current/public;
    index index.php;

    # Configure TLS certificates and policies for your environment.
    client_max_body_size 2m;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /index.php {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root/index.php;
        fastcgi_pass unix:/run/php/community-fpm.sock;
    }

    # Only the intended front controller can execute as PHP.
    location ~* \.php(?:/|$) {
        return 404;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

12.3 Budget PHP workers with the downstream system

[community]
user = community
group = community
listen = /run/php/community-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

pm = dynamic
pm.max_children = 12
pm.start_servers = 3
pm.min_spare_servers = 2
pm.max_spare_servers = 5
pm.max_requests = 500

request_slowlog_timeout = 2s
slowlog = /var/log/php/community-slow.log
request_terminate_timeout = 30s

php_admin_flag[display_errors] = off
php_admin_flag[log_errors] = on
php_admin_value[error_log] = /var/log/php/community-error.log

CLI and FPM can load different configuration files and extensions. Verify the running environment, not just the output of one local php command. OPcache settings, code refresh behavior, and worker restarts belong in the release procedure. If timestamp checks are disabled, establish an explicit refresh/restart strategy rather than expecting edited files to appear automatically.

12.4 Use a safe last-resort exception boundary

<?php
declare(strict_types=1);
$requestId = bin2hex(random_bytes(16));
set_exception_handler(static function (Throwable $failure) use ($requestId): void {
    error_log(json_encode([
        'event' => 'unhandled_exception',
        'request_id' => $requestId,
        'exception_type' => $failure::class,
    ], JSON_THROW_ON_ERROR));

    if (headers_sent()) {
        exit; // A partial response cannot safely be replaced here.
    }
    http_response_code(500);
    header('Content-Type: application/json; charset=UTF-8');
    header('X-Request-ID: ' . $requestId);
    header('Cache-Control: no-store');
    echo json_encode([
        'error' => [
            'code' => 'internal_error',
            'message' => 'The request could not be completed.',
            'request_id' => $requestId,
        ],
    ], JSON_THROW_ON_ERROR);
});

12.5 Build one release artifact and verify it

composer validate --strict
composer install --no-interaction --prefer-dist
composer audit
composer check-platform-reqs
vendor/bin/phpunit --bootstrap vendor/autoload.php tests
vendor/bin/phpstan analyse --no-progress

composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
composer check-platform-reqs --no-dev
php artisan optimize
php artisan queue:restart

12.6 A backup is useful when restoration works

Define recovery needs with the client: acceptable data loss, acceptable outage, retention, and which systems must be restored together. A database backup alone may not contain private attachments, export files, configuration, or the identities needed to decrypt or reconnect services. Test restoration into an isolated environment and verify application behavior and data relationships, not merely that a backup file exists.

For an incident, first identify the affected users and operations, establish a safe containment step, preserve useful evidence, and communicate through the agreed process. After recovery, document cause, contributing conditions, detection gaps, and a concrete prevention or mitigation task. A useful incident report explains why the system behaved that way without inventing certainty.

12.7 Client delivery includes decisions and limits

Read further: Laravel deployment^[69] · FPM configuration^[58] · PHP support lifecycle^[71]