Namespaces and Autoloading

<?php

declare(strict_types=1);

namespace Library\Catalogue;

const MAX_COPIES = 5;

function normaliseIsbn(string $isbn): string
{
    return str_replace('-', '', $isbn);       // str_replace: falls back to the global function
}

final class Book
{
    public function __construct(public string $isbn) {}
}

$book = new Book(normaliseIsbn('978-0-00-000001-1'));

echo Book::class, "\n";                        // Library\Catalogue\Book
echo __NAMESPACE__, "\n";                      // Library\Catalogue
echo \Library\Catalogue\MAX_COPIES, ' ', namespace\MAX_COPIES, "\n";   // 5 5 -- the namespace keyword
echo $book->isbn, "\n";

<?php

declare(strict_types=1);

namespace Library\Catalogue {
    final class Book { public function __construct(public string $title) {} }
    final class Author { public function __construct(public string $name) {} }
    function slug(string $s): string { return strtolower(str_replace(' ', '-', $s)); }
    const DEFAULT_SHELF = 'A';
}

namespace Library\Loans {
    final class Loan { public function __construct(public string $title) {} }
}

namespace App {
    use Library\Catalogue\Book;                       // class
    use Library\Catalogue\{Author, Book as Title};    // group use, with an alias
    use Library\Loans\Loan as Borrowing;              // alias to avoid a clash or improve clarity
    use function Library\Catalogue\slug;              // function
    use const Library\Catalogue\DEFAULT_SHELF;        // constant

    $book = new Book('The Dispossessed');
    $same = new Title('The Dispossessed');
    echo slug($book->title), ' ', DEFAULT_SHELF, ' ', get_class(new Borrowing('x')), ' ', $same::class, "\n";
}

the-dispossessed A Library\Loans\Loan Library\Catalogue\Book

<?php

declare(strict_types=1);

namespace Library\Catalogue;

use DateTimeImmutable;                        // import the global class...

echo strlen('Kindred'), "\n";                  // functions fall back to global: 7
echo PHP_VERSION_ID >= 80500 ? "8.5+\n" : "older\n";   // constants fall back too

$now = new DateTimeImmutable('2026-10-05');    // ...because classes do not fall back
echo $now->format('Y'), "\n";

try {
    $class = 'ArrayObject';
    var_dump(new $class() instanceof \ArrayObject);   // strings are fully qualified: works
} catch (\Error $e) {
    echo $e->getMessage(), "\n";
}

<?php

declare(strict_types=1);

// Create a tiny source tree to autoload from (normally it already exists).
$base = sys_get_temp_dir() . '/autoload-demo/src';
@mkdir($base . '/Catalogue', 0777, true);
file_put_contents($base . '/Catalogue/Book.php', <<<'PHP'
<?php
declare(strict_types=1);
namespace Library\Catalogue;
final class Book { public function __construct(public string $title) {} }
PHP);

// A minimal PSR-4 autoloader: prefix "Library\" maps to the src/ directory.
spl_autoload_register(static function (string $class) use ($base): void {
    $prefix = 'Library\\';
    if (!str_starts_with($class, $prefix)) {
        return;                                          // not ours: let the next autoloader try
    }
    $relative = substr($class, strlen($prefix));         // "Catalogue\Book"
    $file = $base . '/' . str_replace('\\', '/', $relative) . '.php';
    if (is_file($file)) {
        require $file;
    }
});

$book = new Library\Catalogue\Book('Kindred');           // triggers the autoloader
echo $book->title, "\n";                                 // Kindred
var_dump(class_exists('Library\Catalogue\Missing'));     // bool(false): autoloader ran, found nothing
var_dump(class_exists('Library\Catalogue\Other', false));  // bool(false): false = do not autoload

library-catalogue/
├── composer.json
├── bin/catalogue.php
└── src/
    ├── functions.php
    └── Catalogue/
        └── Book.php        namespace Library\Catalogue; final readonly class Book

{
    "name": "acme/library-catalogue",
    "type": "project",
    "require": {
        "php": ">=8.5"
    },
    "autoload": {
        "psr-4": {
            "Library\\": "src/"
        },
        "files": ["src/functions.php"]
    }
}

<?php

declare(strict_types=1);

// bin/catalogue.php
require __DIR__ . '/../vendor/autoload.php';

use Library\Catalogue\Book;
use function Library\slug;

$book = new Book('The Left Hand of Darkness', 1969);
echo slug($book->title), "\n";        // the-left-hand-of-darkness

composer dump-autoload            # regenerate vendor/autoload.php after changing "autoload"
php bin/catalogue.php
composer dump-autoload --optimize # production: also build a classmap of every class (faster)

<?php

declare(strict_types=1);

namespace Library;

spl_autoload_register(function (string $class): void {
    echo "  autoload($class)\n";
});

function check(string $label, callable $code): void
{
    echo $label, "\n";
    try {
        $code();
    } catch (\Error $e) {
        echo '  ', get_class($e), ': ', $e->getMessage(), "\n";
    }
}

check('Missing::class', fn () => print('  ' . Missing::class . "\n"));
check('instanceof', fn () => var_dump(new \stdClass() instanceof Missing));
check('class_exists($name, false)', fn () => var_dump(class_exists(Missing::class, false)));
check('class_exists($name)', fn () => var_dump(class_exists(Missing::class)));
check('a type declaration', function () { $f = fn (?Missing $m = null) => 'called'; echo '  ', $f(), "\n"; });
check('catch (Missing)', function () { try { throw new \RuntimeException('x'); } catch (Missing | \RuntimeException) { echo "  caught\n"; } });
check('new', fn () => new Missing());
check('a static call', fn () => Missing::make());

Missing::class
  Library\Missing
instanceof
bool(false)
class_exists($name, false)
bool(false)
class_exists($name)
  autoload(Library\Missing)
bool(false)
a type declaration
  called
catch (Missing)
  caught
new
  autoload(Library\Missing)
  Error: Class "Library\Missing" not found
a static call
  autoload(Library\Missing)
  Error: Class "Library\Missing" not found

<?php

declare(strict_types=1);

// bin/case.php
require __DIR__ . '/../vendor/autoload.php';

foreach (['Library\catalogue\book', 'Library\Catalogue\Book', 'Library\catalogue\book', 'Library\Catalogue\Loan'] as $name) {
    try {
        echo $name, ': ', (new ReflectionClass($name))->getName(), "\n";
    } catch (ReflectionException $e) {
        echo $name, ': ', $e->getMessage(), "\n";
    }
}

$ composer dump-autoload && php bin/case.php
Library\catalogue\book: Class "Library\catalogue\book" does not exist
Library\Catalogue\Book: Library\Catalogue\Book
Library\catalogue\book: Library\Catalogue\Book
Library\Catalogue\Loan: Class "Library\Catalogue\Loan" does not exist
$ composer dump-autoload --optimize --strict-psr; echo "exit $?"
Generating optimized autoload files
Class Library\Catalogue\Loan located in ./src/Catalogue/loan.php does not comply with psr-4 autoloading standard (rule: Library\ => ./src). Skipping.
Generated optimized autoload files containing 2 classes
exit 1