Composer and Autoloading in PHP Explained — Stop Requiring Files Manually

<?php

/**
 * bootstrap.php — The single entry point that wires everything together.
 * This is the ONLY require statement your application needs.
 * Composer's autoloader handles everything else from here.
 */
require_once __DIR__ . '/vendor/autoload.php';

// At this point, ANY class from ANY installed Composer package
// (plus your own PSR-4 mapped classes) is available instantly.
// PHP won't actually load the class file until you USE the class — lazy loading.

// Let's use Carbon (a popular date library) as a concrete example.
// No require for Carbon anywhere — the autoloader finds it automatically.
use Carbon\Carbon;

$launchDate = Carbon::create(2024, 3, 15, 9, 0, 0);
$now = Carbon::now();

$daysUntilLaunch = $now->diffInDays($launchDate, false);

if ($daysUntilLaunch > 0) {
    echo "Launch is in {$daysUntilLaunch} days." . PHP_EOL;
} else {
    echo "Launch was " . abs($daysUntilLaunch) . " days ago." . PHP_EOL;
}

// The autoloader only loaded Carbon's class files when 'new Carbon' was triggered.
// Every other Composer package stayed untouched on disk — no wasted memory.

{
    "name": "theforge/invoice-app",
    "description": "A real-world invoicing application",
    "require": {
        "php": ">=8.1",
        "nesbot/carbon": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    },
    "minimum-stability": "stable"
}

/* HOW THIS MAPPING WORKS:
 *
 * Namespace prefix  ->  Directory
 * "App\\"          ->  "src/"
 *
 * So PHP resolves class names like this:
 *   App\Models\Invoice       ->  src/Models/Invoice.php
 *   App\Services\PdfExporter ->  src/Services/PdfExporter.php
 *   App\Http\Controllers\InvoiceController -> src/Http/Controllers/InvoiceController.php
 *
 * The autoload-dev section works identically but is EXCLUDED
 * when you run: composer install --no-dev (i.e., on production).
 * This keeps test classes off your production server automatically.
 */

<?php

// FILE: src/Models/Invoice.php
// Namespace MUST match directory path relative to the PSR-4 root (src/)
declare(strict_types=1);

namespace App\Models;

use Carbon\Carbon; // Loaded from vendor/ by Composer — no require needed

class Invoice
{
    private Carbon $issuedAt;
    private Carbon $dueDate;

    public function __construct(
        private readonly string $invoiceNumber,
        private readonly string $clientName,
        private readonly float $amountDue,
        int $paymentTermDays = 30
    ) {
        // Carbon is available here because Composer mapped it automatically
        $this->issuedAt = Carbon::now();
        $this->dueDate  = Carbon::now()->addDays($paymentTermDays);
    }

    public function getInvoiceNumber(): string { return $this->invoiceNumber; }
    public function getClientName(): string    { return $this->clientName; }
    public function getAmountDue(): float      { return $this->amountDue; }

    public function isOverdue(): bool
    {
        // Check if today is past the due date
        return Carbon::now()->isAfter($this->dueDate);
    }

    public function getSummary(): string
    {
        $status    = $this->isOverdue() ? 'OVERDUE' : 'Current';
        $dueDateFmt = $this->dueDate->format('Y-m-d');

        return sprintf(
            "Invoice %s | Client: %s | Amount: $%.2f | Due: %s | Status: %s",
            $this->invoiceNumber,
            $this->clientName,
            $this->amountDue,
            $dueDateFmt,
            $status
        );
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// FILE: src/Services/InvoiceMailer.php  (separate file — shown inline for clarity)
// ─────────────────────────────────────────────────────────────────────────────

// <?php
// declare(strict_types=1);
// namespace App\Services;
//
// use App\Models\Invoice;
//
// class InvoiceMailer
// {
//     public function send(Invoice $invoice, string $recipientEmail): bool
//     {
//         // Real implementation would use a mail library
//         echo "Sending invoice {$invoice->getInvoiceNumber()} to {$recipientEmail}" . PHP_EOL;
//         return true;
//     }
// }

// ─────────────────────────────────────────────────────────────────────────────
// FILE: index.php  (project root — the application entry point)
// ─────────────────────────────────────────────────────────────────────────────

// <?php
// declare(strict_types=1);
//
// require_once __DIR__ . '/vendor/autoload.php'; // The ONE require to rule them all
//
// use App\Models\Invoice;
// use App\Services\InvoiceMailer;
//
// // PHP sees 'App\Models\Invoice', fires Composer autoloader,
// // which loads src/Models/Invoice.php — automatically, silently, correctly.
// $invoice = new Invoice(
//     invoiceNumber: 'INV-2024-0042',
//     clientName:    'Acme Corporation',
//     amountDue:     1850.00,
//     paymentTermDays: 14
// );
//
// echo $invoice->getSummary() . PHP_EOL;
//
// $mailer = new InvoiceMailer();
// $mailer->send($invoice, 'accounts@acmecorp.com');

{
    "autoload": {

        "psr-4": {
            "App\\": "src/"
            // BEST FOR: Your own modern application code.
            // HOW IT WORKS: Translates namespace to file path dynamically.
            // WHEN TO USE: Always, for new code you write.
        },

        "classmap": [
            "lib/legacy/",
            "lib/generated/"
            // BEST FOR: Old code with no consistent naming convention.
            // HOW IT WORKS: Scans directories at dump-autoload time, builds
            //               a complete class-to-file lookup table.
            // WHEN TO USE: Integrating a legacy library or generated PHP code.
            // GOTCHA: New classes in these dirs need composer dump-autoload
            //         before they're discoverable.
        ],

        "files": [
            "src/helpers.php"
            // BEST FOR: Global functions that aren't classes.
            // HOW IT WORKS: PHP includes EVERY file in this list on EVERY request.
            // WHEN TO USE: Sparingly — helper functions like str_humanize() etc.
            // NEVER USE FOR: Classes. That's what psr-4 and classmap are for.
        ]

    }
}

// ─────────────────────────────────────────────────────────────────────────────
// REAL EXAMPLE: src/helpers.php  — functions, not classes
// ─────────────────────────────────────────────────────────────────────────────

<?php
// These functions are available globally across the whole application
// because this file is listed under "files" in composer.json autoload.

if (!function_exists('format_currency')) {
    /**
     * Formats a float as a localised currency string.
     * The function_exists guard prevents fatal errors if this file
     * is ever accidentally included twice.
     */
    function format_currency(float $amount, string $currencyCode = 'USD'): string
    {
        $formatter = new NumberFormatter('en_US', NumberFormatter::CURRENCY);
        return $formatter->formatCurrency($amount, $currencyCode);
    }
}

// Usage anywhere in your application (after vendor/autoload.php is required):
// echo format_currency(1850.00); // Output: $1,850.00