Skip to content

Autoload

Belikhun edited this page Sep 15, 2026 · 2 revisions

🧭 Autoload

Blink resolves a class name to a file path, tries the path, and only falls back to scanning when the path says nothing. Resolved paths are cached, so a warm request loads its classes without touching the filesystem to find them.

Path resolution

A class is mapped through the longest matching namespace prefix in CONFIG::$AUTOLOAD. Blink\ always maps to blink's own classes/ and cannot be overridden.

CONFIG::$AUTOLOAD = array(
	"App\\" => BASE_PATH . "/classes"
);

For the remaining part of the name, two file shapes are tried, in this order:

Class First try Then
App\Model\Order classes/Model/Order.php classes/Model/Order/Order.php
App\Ticker classes/Ticker.php classes/Ticker/Ticker.php

A class that owns a directory

The second shape is the useful one. A class with parts of its own can sit among them rather than beside the folder holding them, and the repeated directory name is absorbed rather than added to the namespace:

classes/
  Ticker/
    Ticker.php        <- Blink\Ticker
    Runner.php        <- Blink\Ticker\Runner
    Pattern.php       <- Blink\Ticker\Pattern
    Task/
      Task.php        <- Blink\Ticker\Task
      CommandTask.php <- Blink\Ticker\Task\CommandTask

Ticker/Ticker.php declares Blink\Ticker, not Blink\Ticker\Ticker. Nothing in the file changes between the two shapes: the namespace declaration is the same either way, so moving a class from Ticker.php into Ticker/Ticker.php needs nothing but the move.

Blink itself keeps every class that owns a directory in this shape, which is why Blink\Model, Blink\Essence, Blink\Console\Command and the rest live one level in. Do the same in an application or don't; the autoloader finds either.

A file that loads without defining the class throws ClassNotDefined, naming the file, which is what a typo in a class name looks like from the outside.

The scan fallback

Two shapes a path cannot describe: a file holding more than one class, and a class in the global namespace. For those, the autoloader indexes every file under CONFIG::$INCLUDES by the classes declared in it and looks the name up there.

CONFIG::$INCLUDES = array(
	BASE_PATH . "/includes",
	BASE_PATH . "/classes"
);

The scan reads every file in those directories, so it runs at most once per request, and only after path resolution has already failed. A class found this way is cached like any other, so the scan is a first-request cost.

The cache

Resolved paths are written to DATA_ROOT/autoload.php from the shutdown handler, and only when something new was resolved. The file carries an @version key from Blink::cacheVersion(), a digest of the blink version, the application version and CONFIG::$MODULES; a cache written for another combination is discarded.

cache:clear removes it. Nothing else needs to: a moved file simply misses its cached path and is resolved again.

When a class cannot be found

The paths tried for every miss are recorded, and the error page shows them in two places: the Autoload context lists every class loaded during the request and every miss with what was tried, and a ClassNotFound gets a tip listing the same paths. That is usually enough to spot a misplaced or misnamed file.

Clone this wiki locally