This note began as a short forum post, now expanded and refined for posterity.

Concrete CMS uses PHP namespaces to organize its classes. At a high level, a package is simply a directory with a structured set of sub‑directories. Within that structure, developers need to establish a clear mapping between directories, files, namespaces, and the classes they contain.

As well as the standard namespace mapping, there are some quirky conventions for specific components such as blocks, controllers, and attributes. These conventions ensure consistency across the ecosystem and make it easier for the core framework to locate and load the relevant classes.

For more general classes, however, developers have considerably more flexibility. By convention, reusable or broadly applicable classes are placed under the /src/ sub‑directory. This is a widely adopted practice, but it is not a strict requirement - Concrete CMS will happily load classes from other locations as long as the namespace and auto-loading rules are respected.

General class mapping

The simplest way to do this is to map folders and namespaces is the array $pkgAutoloaderRegistries declared in the package controller. Here we declare that and classes within the namespace \TestClasses can be found beneath the package directory src/TestClasses.

protected $pkgAutoloaderRegistries = ['src/TestClasses' => '\TestClassses']; 

This is not limited to a single mapping. The array is a list of mappings. If some logic is needed in working out what the mapping should be, such as conditionally adding a namespace, we can alternatively declare the method getPackageAutoloaderRegistries() in our package controller.

public function getPackageAutoloaderRegistries()
{
    $namespace_mapping_array = ['src/TestClasses' => '\TestClassses'];
    return $namespace_mapping_array;
}

Within the package, we now have the folder my_package/src/TestClasses/ and within that a file my_package/src/TestClasses/MyTestClass.php. In the file we have:

Namespace TestClassses; 

class MyTestClass {
...
} 

Anywhere we want to use that class we add the line

use TestClassses\MyTestClass;

The namespace \TestClasses applies to the directory src/TestClasses and all classes and directories below that without further mapping. So namespace \TestClasses\WithinNamepace maps to the directory src/TestClasses/WithinNamespace.

You can use this to target autoloading to a namespace anywhere. It doesn't need to be directly beneath /src/.

protected $pkgAutoloaderRegistries = [
  'src/Deeper/Path/TestClasses' => '\TestClassses',
  'src/Another/Path/DifferentFolder' => '\MyPackageName\MyPackageClassses',
  'vendor/Path/To/Vendor/File' => '\VendorName',
]; 

Once a namespace is declared, it cascades down into all subfolders. So in the first of the above, class files in the folder src/Deeper/Path/TestClasses/Utilities would use the namespace \TestClassses\Utilities.

The vendor example is rarely used because most vendor classes are installed with php composer, which then creates a vendor specific autoloader. Nevertheless, such variations can occasionally come in useful.

Core Conventions

As noted previously, there are Concrete CMS conventions that have to be adhered to for the controllers, blocks, attributes.

Note the singular/plural and snake_case/CamelCase differences. When the loading of a controller goes wrong, it is often a typo in case or a singular/plural that is the root of the problem.

Vendor Classes

Vendor code is usually located beneath the /vendor/ directory. The php composer will generate an autoloader that needs to be included or required from the package controller on_start() method.

However, as noted above, we can also use the concrete loader for vendor classes by simply adding an appropriate mapping for the respective /vendor/ sub-directory to $pkgAutoloaderRegistries.