Autoloads and class naming
Part 3, chapter 8. The kernel does not use include lines for classes. It keeps autoload arrays, maps from class
name to file, and loads a class the first time code uses it. Your extension's classes are added to those maps by a
generator you run after adding or renaming a class.
The arrays
| File | Holds | Generated with |
|---|---|---|
autoload/ezp_kernel.php | the kernel's classes | -k (kernel maintainers only) |
var/autoload/ezp_extension.php | the classes of the extensions | -e |
var/autoload/ezp_override.php | kernel classes replaced by extensions | -o |
var/autoload/ezp_tests.php | test classes | -s |
The extension array lives in var/, because it describes this installation's extensions, not the kernel.
The generator
php bin/php/ezpgenerateautoloads.php -eExpected: Found <n> classes, added <n> of them to the autoload array.. Useful options (from --help):
| Option | Effect |
|---|---|
-e | the extension array |
-n | dry run: count, write nothing |
-v | list what it finds |
--exclude <dir> | skip folders |
<extension> argument | one extension only |
What it scans
In extension mode it walks the whole folder of every extension on disk (active or not, in every extension root) for PHP files that declare a class, interface or
trait, and skips each extension's tests/ folder (test classes go into the tests array) and tests/ of Composer
packages vendored inside the extension (kernel/private/classes/ezautoloadgenerator.php). Folders listed in the root's
.autoloadignore are never walked.
So your classes can live in classes/, classes/<subfolder>/, autoloads/, modules/ ... wherever it makes sense.
classes/ is the convention.
Naming
Class names are global: two extensions with a class Helper break each other. The conventions of this ecosystem:
| Kind | Convention | Example |
|---|---|---|
| Your classes | a prefix of your extension or organization, camel case | mysiteHelloGreeter, acmeShopExporter |
| New classes of this project | the exp prefix | expInfo, expExtensionCatalogue |
| Extensions and classes from 7x | sevenx or exp, as 7x needs | sevenx_dse, explayouts |
| The kernel's historical classes | eZ..., ezp... | eZINI, ezpExtension (never reuse the prefix for new code) |
| File name | the class name in lower case | classes/mysitehellogreeter.php |
| Datatypes | <datatype>type.php, class <Name>Type | datatypes/mysiterating/mysiteratingtype.php |
| Metadata | <extension>Info in ezinfo.php | mysite_helloInfo |
Why 7x has two prefixes: sevenx is 7x's official public PHP code prefix, because a class name cannot start with a
digit and "7x" therefore cannot be one; exp is used with intent to build the Exponential brand and to assign
ownership to the Exponential project and the Exponential Foundation. See Naming prefixes: sevenx and exp.
One class per file. Do not declare functions or constants at file level in a class file: autoloading only works for classes.
Composer libraries inside an extension
An extension that needs a third-party library can require it in its composer.json; Composer's own autoloader loads
it, beside the kernel's arrays. A small library vendored into the extension (extension/<ext>/vendor/...) is found by
the generator too; prefer a Composer requirement where possible.
When a class is not found
php bin/php/ezpgenerateautoloads.php -e -vand look for your class in the output.- Is the file in an extension root (
extension/or a folder ofAdditionalExtensionDirectories[])? Every extension on disk is scanned, active or not, but only an active extension's settings register its parts. - Is there a parse error in the file?
php -lit; a file PHP cannot parse is skipped. - Does another extension declare the same class name? The generator warns about duplicates.
- Clear the caches and make the running PHP see the new map: reload PHP-FPM or
./console exp:velocity deploy.
php bin/php/checkclasses.php --quiet-ok then loads every class and lists those PHP refuses.
Related pages
- Previous: Settings in an extension
- Next: Modules and views
- Kernel class overrides: the last resort
- Debugging extensions
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.