Manifests#

Purpose#

Manifests help to cache information which is too expensive to generate on each request. Some manifests generate maps, e.g. class names to filesystem locations. Others store aggregate information like nested configuration graphs.

Manifests are immutable for a given revision of the codebase, and hence should be packaged during deployment. Object Caching and Partial Template Caching are examples of mutable caches outside of manifests, which need to be generated and expired during runtime.

Storage#

By default, manifests are serialised and cached via a cache generated by the ManifestCacheFactory. This can be customised via SS_MANIFESTCACHE environment variable to point to either another CacheFactory or a class that implements the CacheInterface interface provided by php-fig/cache.

Traversing the filesystem#

Since manifests usually extract their information from files in the project root, they require a powerful traversal tool: FileFinder. The class provides filtering abilities for files and folders, as well as callbacks for recursive traversal. Each manifest has its own implementation, for example ManifestFileFinder, adding more domain specific filtering like including themes, or excluding tests.

PHP class manifest#

The ClassManifest builds a manifest of all classes, interfaces and some additional items present in a directory, and caches it.

It finds the following information:

• Class and interface names and paths
• All direct and indirect descendants of a class
• All implementors of an interface
• All module configuration files

The gathered information can be accessed through ClassLoader::inst(), as well as ClassInfo. Some useful commands of the ClassInfo API:

• ClassInfo::subclassesFor($class): Returns a list of classes that inherit from the given class
• ClassInfo::ancestry($class): Returns the passed class name along with all its parent class names
• ClassInfo::implementorsOf($interfaceName): Returns all classes implementing the passed in interface

In the absence of a generic module API, it is also the primary way to identify which modules are installed, through ClassManifest::getModules(). All modules contain either a _config.php file, or a _config/ folder. Modules can be specifically excluded from manifests by creating a blank _manifest_exclude file in the module folder.

Modules can either be:

• a toplevel folder in the project root, or
• a third-party package installed via composer (i.e. in the vendor/ directory).

By default, the finder implementation will exclude any classes stored in files within a tests/ folder, unless tests are executed.

Theme manifests#

The ThemeManifest class builds a manifest of all templates present in a directory, in both modules and themes.

Templates in tests/ folders are automatically excluded. The chapter on template inheritance provides more details on its operation.

Config manifest#

The ConfigManifest loads builds a manifest of configuration items, for both PHP and YAML. It also takes care of ordering and merging configuration fragments. The chapter on configuration has more details.

Flushing#

If a ?flush=1 query parameter is added to a URL, a call to flush() will be triggered on any classes that implement the Flushable interface. This enables developers to clear manifest caches, for example when adding new templates or PHP classes. Note that you need to be in dev mode or logged-in as an administrator for flushing to take effect.