class CacheListClassLoader extends ClassLoader (View source)

Provides a simple method of caching the list of class file locations.

CacheListClassLoader provides a simple way to implement your own caching handlers for the ClassLoader. The base idea of this cache is to call a provided cache save handler when a new class location is found with the whole class location cache. The saved cache location should be provided in the constructor when the class loader is constructed.

Properties

protected bool $verbose from ClassLoader

Methods

__construct(array $cache)

Creates a new CacheListClassLoader instance.

bool
register()

Registers this instance as a class autoloader.

bool
unregister()

Unregisters this instance as a class autoloader.

bool
isRegistered()

Tells if this instance is currently registered as a class autoloader.

useIncludePath(bool $enabled = true)

Tells whether to use include_path as part of base paths.

setVerbose(bool $enabled)

Sets whether to return values and throw exceptions from loadClass.

setFileExtensions(array $extensions)

Sets list of dot included file extensions to use for finding files.

addBasePath(string|array $path, string|null $namespace = null)

Adds a PSR-0 compliant base path for searching classes.

array
getBasePaths()

Returns all known base paths.

addPrefixPath(string|array $path, string|null $namespace = null)

Adds a PSR-4 compliant prefix path for searching classes.

array
getPrefixPaths()

Returns all known prefix paths.

bool|null
loadClass(string $class)

Loads the class by first checking if the file path is cached.

string|false
findFile(string $class)

Attempts to find a file for the given class using known paths.

bool
loadFile(string $file, string $class)

Loads the class from the given file and stores the path into cache.

setCacheHandler(callable $callback)

Sets the callback used to store the cache.

Details

__construct(array $cache)

Creates a new CacheListClassLoader instance.

The parameter should contain the paths provided to your cache save handler. If no cache exists yet, an empty array should be provided instead.

Parameters

array $cache The cached paths stored by your cache handler

bool register()

Registers this instance as a class autoloader.

Return Value

bool True if the registration was successful, false if not

bool unregister()

Unregisters this instance as a class autoloader.

Return Value

bool True if the unregistration was successful, false if not

bool isRegistered()

Tells if this instance is currently registered as a class autoloader.

Return Value

bool True if registered, false if not

ClassLoader useIncludePath(bool $enabled = true)

Tells whether to use include_path as part of base paths.

When enabled, the directory paths in include_path are treated as base paths where to look for classes. This option defaults to false for PSR-4 compliance.

Parameters

bool $enabled True to use include_path, false to not use

Return Value

ClassLoader Returns self for call chaining

ClassLoader setVerbose(bool $enabled)

Sets whether to return values and throw exceptions from loadClass.

PSR-4 requires that autoloaders do not return values and do not throw exceptions from the autoloader. By default, the verbose mode is set to false for PSR-4 compliance.

Parameters

bool $enabled True to return values and exceptions, false to not

Return Value

ClassLoader Returns self for call chaining

ClassLoader setFileExtensions(array $extensions)

Sets list of dot included file extensions to use for finding files.

If no list of extensions is provided, the extension array defaults to just '.php'.

Parameters

array $extensions Array of dot included file extensions to use

Return Value

ClassLoader Returns self for call chaining

ClassLoader addBasePath(string|array $path, string|null $namespace = null)

Adds a PSR-0 compliant base path for searching classes.

In PSR-0, the class namespace structure directly reflects the location in the directory tree. A base path indicates the base directory where to search for classes. For example, if the class 'Foo\Bar', is defined in '/usr/lib/Foo/Bar.php', you would simply need to add the directory '/usr/lib' by calling:

addBasePath('/usr/lib')

Additionally, you may specify that the base path applies only to a specific namespace. You can do this by adding the namespace as the second parameter. For example, if you would like the path in the previous example to only apply to the namespace 'Foo', you could do so by calling:

addBasePath('/usr/lib/', 'Foo')

Note that as per PSR-0, the underscores in the class name are treated as namespace separators. Therefore 'Foo_Bar_Baz', would need to reside in 'Foo/Bar/Baz.php'. Regardless of whether the namespace is indicated by namespace separators or underscores, the namespace parameter must be defined using namespace separators, e.g 'Foo\Bar'.

In addition to providing a single path as a string, you may also provide an array of paths. It is also possible to provide an associative array where the keys indicate the namespaces. Each value in the associative array may also be a string or an array of paths.

Parameters

string|array $path Single path, array of paths or an associative array
string|null $namespace Limit the path only to specific namespace

Return Value

ClassLoader Returns self for call chaining

array getBasePaths()

Returns all known base paths.

The paths will be returned as an associative array. The key indicates the namespace and the values are arrays that contain all paths that apply to that specific namespace. Paths that apply to all namespaces can be found inside the key '' (i.e. empty string). Note that the array does not include the paths in include_path even if the use of include_path is enabled.

Return Value

array All known base paths

ClassLoader addPrefixPath(string|array $path, string|null $namespace = null)

Adds a PSR-4 compliant prefix path for searching classes.

In PSR-4, it is possible to replace part of namespace with specific path in the directory tree instead of requiring the entire namespace structure to be present in the directory tree. For example, if the class 'Vendor\Library\Class' is located in '/usr/lib/Library/src/Class.php', You would need to add the path '/usr/lib/Library/src' to the namespace 'Vendor\Library' by calling:

addPrefixPath('/usr/lib/Library/src', 'Vendor\Library')

If the method is called without providing a namespace, then the paths work similarly to paths added via addBasePath(), except that the underscores in the file name are not treated as namespace separators.

Similarly to addBasePath(), the paths may be provided as an array or you can just provide a single associative array as the parameter.

Parameters

string|array $path Single path or array of paths
string|null $namespace The namespace prefix the given path replaces

Return Value

ClassLoader Returns self for call chaining

array getPrefixPaths()

Returns all known prefix paths.

The paths will be returned as an associative array. The key indicates the namespace and the values are arrays that contain all paths that apply to that specific namespace. Paths that apply to all namespaces can be found inside the key '' (i.e. empty string).

Return Value

array All known prefix paths

bool|null loadClass(string $class)

Loads the class by first checking if the file path is cached.

Parameters

string $class Full name of the class to load

Return Value

bool|null True if the class was loaded, false if not

string|false findFile(string $class)

Attempts to find a file for the given class using known paths.

Parameters

string $class Full name of the class

Return Value

string|false Path to the class file or false if not found

protected bool loadFile(string $file, string $class)

Loads the class from the given file and stores the path into cache.

Parameters

string $file Full path to the file
string $class Full name of the class

Return Value

bool Always returns true

Exceptions

RuntimeException If the class was not defined in the included file

CacheListClassLoader setCacheHandler(callable $callback)

Sets the callback used to store the cache.

Whenever a new file location for class is found, the cache handler is called with an associative array containing the paths for different classes. The cache handler should store the array and provide it in the constructor in following requests.

Parameters

callable $callback Callback for storing cache

Return Value

CacheListClassLoader Returns self for call chaining