Autoloading (5.7.5.10 and earlier)

Edit

Improvements?

Let us know by posting here.

Concrete CMS automatically loads its classes based on namespace. For example:

$page = \Concrete\Core\Page\Page::getByPath('/about-us');

How do we know where to find \Concrete\Core\Page\Page? We use a modified autoloader based on the PSR-4 format

PSR-4 basically states that projects can map different namespace prefixes to arbitrary starting directories. That's what we're doing. Within the Concrete class loader, we map the concrete/src directory to the \Concrete\Core namespace. That means that any class that exists within the \Concrete\Core namespace must traverse inside the src directory, and from then on, adhere exactly to casing and directory rules. So

\Concrete\Core\Page\Page

Can be found at

concrete/src/Page/Page.php

If you are writing code that belongs in a /src directory, you must adhere to PSR-4 as is. Classes must be capitalized, nested properly, etc…

For classes that do not exist within the src/ directory (such as block controllers, attribute controllers, etc...) We ask that you name your controllers with the same capitalization that PSR-4 requires, but you name your files with Concrete's classic lowercase + underscore method. These files will be converted by camelcasing those filenames on the fly.

What does that mean? The blocks directory and its contents still looks the same as Concrete before 5.7 (at that time, Concrete CMS was known as concrete5). For example, the Page List block's controller is still located at

concrete/blocks/page_list/controller.php

If you were strictly following PSR-4, you would need to name your class

controller

inside the name space

\Concrete\Block\page_list

This is ugly and causes other problems. So instead, when we request the class

\Concrete\Block\PageList\Controller

We first check to see if

concrete/blocks/PageList/Controller.php

exists (since that is the default PSR-4 autoloading behavior.)

If it does not (and it won't, for blocks, attributes, single page controllers, etc...) – then we uncamelcase using our own methods, starting at the item after blocks. Backslashes become directory separators, and camelcasing becomes underscores.

concrete/blocks/page_list/controller.php

And that's how we handle non-library classes in Concrete (concrete5) 5.7.

Full Reference: Namespace and Class Locations

Standard PSR-4

The following namespaces map to src/ directories which contain files that fully conform to PSR-4.

  • Concrete\Core\ → concrete/src/
  • Application\Src\ → application/src/
  • Concrete\Package\MyPackageNamespace\Src\ → packages/my_package_namespace/src/

Any files found in these locations must exactly conform to PSR4 in their filenames and their class names.

Modified PSR-4

Concrete Core Directory

The following namespaces automatically map to locations in the concrete/ directory

  • Concrete\Attribute → concrete/attributes/
    e.g.:
    • Concrete\Attribute\Boolean\Controller → concrete/attributes/boolean/controller.php
    • Concrete\Attribute\Select\Option → concrete/attributes/select/option.php
  • Concrete\MenuItem → concrete/menu_items/
    e.g.:
    • Concrete\MenuItem\MyMenu\Controller → concrete/attributes/my_menu/controller.php
  • Concrete\Authentication → concrete/authentication/
    e.g.:
    • Concrete\Authentication\Facebook\Controller → concrete/authentication/facebook/controller.php
  • Concrete\Block → concrete/blocks/
    e.g.:
    • Concrete\Blocks\Autonav\Controller → concrete/blocks/autonav/controller.php
    • Concrete\Blocks\Form\MiniSurvey → concrete/blocks/form/mini_survey.php
  • Concrete\Theme → concrete/themes/
    e.g.:
    • Concrete\Theme\Elemental\PageTheme → concrete/themes/elemental/page_theme.php
  • Concrete\Controller\PageType → concrete/controllers/page_types/
    e.g.:
    • Concrete\Controller\PageType\BlogEntry → concrete/controllers/page_types/blog_entry.php
  • Concrete\Controller → concrete/controllers/
    e.g.:
    • Concrete\Controller\Dialog\UploadFile → concrete/controllers/dialog/upload_file.php
  • Concrete\Job → concrete/jobs/
    e.g.:
    • Concrete\Jobs\IndexSearchEngine → concrete/jobs/index_search_engine.php
  • Concrete\StartingPointPackage → concrete/config/install/packages/
    e.g.:
    • Concrete\StartingPointPackage\ElementalFull\Controller → concrete/config/install/packages/elemental_full/controller.php

Package Directory

All of the above applies to Concrete packages – just substitute \Concrete\Package\YourPackageHandle (where YourPackageHandle is the camelcased version of the your_package_handle package directory found in packages/). For example:

  • Concrete\Package\FancySlider\Block\FancySlider\Controller → packages/fancy_slider/blocks/fancy_slider/controller.phgp
  • Concrete\Package\FileSetTools\Attribute\FileData\Controller → packages/file_set_tools/attributes/file_data/controller.php
  • Concrete\Package\FileManagerMenu\MenuItem\FileManager\Controller → packages/file_manager_menu/menu_items/file_manager/controller.php

Application Directory

The application/ directory holds custom code for the current Concrete application. It's overrides directory namespaces follow the same pattern as the concrete/ directory – just with Application\ as the first segment of the namespace.

  • Application\Block\FancySlider\Controller → application/blocks/fancy_slider/controller.phgp
  • Application\Attribute\FileData\Controller → application/attributes/file_data/controller.php
  • Application\MenuItem\FileManager\Controller → application/menu_items/file_manager/controller.php

This also applies to overrides made to core classes.

  • Application\Block\RssDisplayer\Controller → application/blocks/rss_displayer/controller.php