A tour of the source tree
This page is for PHP developers who open an Exponential checkout for the first time. It walks through the directories and entry points at the root, says what lives where, and which places are generated or belong to the installation rather than to the code.
Warning
.htaccess slows down every request. When .htaccess files are enabled (AllowOverride anything but None), let alone
used, Apache looks for them and reads and evaluates them on every request, in every directory of the path, and
page loading times go up drastically (measured). The only real fix is to switch the feature off for
the virtual host: AllowOverride None in the HTTPS virtual host, and the rules in the virtual host's own
configuration as mod_rewrite rules. That is far faster in production speed tests and well worth the time it takes
to optimize a production configuration. Switch over right away: copy the rules of the
example HTTPS virtual host into your virtual host (with the static cache, also
staticcache_offload.conf), set AllowOverride None, run apachectl configtest, reload Apache and
test the site. The same rules for other servers: nginx, LiteSpeed,
Caddy, IIS, Velocity (built in); where virtual host rules go in a control
panel: Plesk, cPanel, DirectAdmin, ISPConfig.
On LiteSpeed or OpenLiteSpeed, the server's own page cache can also answer anonymous visitors and crawlers without PHP: Page caching with LiteSpeed and OpenLiteSpeed.
Contents
- The entry points
- Code directories
- Inside kernel/
- Inside lib/
- Configuration and generated files
- Quality and tests
- What you change and what you leave alone
The entry points
| File | Runs |
|---|---|
index.php | every web page: maintenance check, autoload.php, then new ezpKernel( new ezpKernelWeb() ) and run() |
index_rest.php | the REST API |
index_treemenu.php | the admin's content tree menu |
index_cluster.php | serving clustered binary files |
bin/php/*.php | command line scripts; one dispatcher, bin/php/console, runs them all as exp:<name> |
runcronjobs.php | cronjob parts (php runcronjobs.php frequent) |
index_soap.php, index_webdav.php | the SOAP and WebDAV servers (soap.php and webdav.php only forward to them, until a later major version) |
Every PHP entry point starts with autoload.php. It defines EXP_ROOT_DIR (the installation root, an absolute path),
loads lib/phpcompat.php on PHP older than 8.1, decides about the engine archive and registers the class map
autoloader (How a request runs in PHP).
An example of how a console command is built from these parts: the commands that put .htaccess and config.php
into place (Setting up .htaccess and config.php from the console).
| File | Role |
|---|---|
bin/php/setupfiles.php, bin/php/configphp.php | the scripts behind exp:setupfiles (exp:setup:status, exp:setup:htaccess, exp:setup:config) and exp:configphp (exp:config:list, get, set, unset); they run without the console too |
kernel/private/classes/commands/setupfiles.php, configphp.php | the console command classes |
kernel/classes/expsetupfilecopy.php | the safe copy: dry run, diff, backup to var/backup/, atomic write, mode and owner |
kernel/classes/expconfigphpeditor.php | reads config.php as PHP tokens and changes one define() at a time, checked with php -l |
kernel/classes/expconfigphpcatalogue.php | the list of documented settings, read from the comments of config.php-RECOMMENDED |
tests/tests/kernel/private/classes/commands/expSetupFilesAndConfigPhpCommandsTest.php | their tests |
Code directories
| Directory | Holds | Namespaces and prefixes |
|---|---|---|
kernel/ | the CMS: modules, content model, users, roles, workflows, setup, the request kernel | eZ*, ezp*, exp* classes; Exponential\... for runnables |
lib/ | general libraries the kernel builds on | eZ*, ezp*, exp* |
extension/ | shipped extensions and your own | each extension's own prefix |
cronjobs/ | the kernel's cronjob part files (cronjobs/workflow.php ...) | thin files calling Exponential\Cronjob\Kernel\... |
design/ | the kernel's designs: standard, base, admin, admin3, admin4, admin4l, editor, plain ... | templates, stylesheets, images |
update/ | database update scripts and SQL per engine (update/database/sqlite/, postgresql/, mysql/) | |
share/ | share/filelist.md5 and other shipped data | |
schemas/, templates/, support/ | XML schemas, shipped templates for packages, support files |
Inside kernel/
Most top-level directories of kernel/ are modules: kernel/content/, kernel/user/, kernel/setup/,
kernel/role/, kernel/workflow/, kernel/shop/ and more. Each holds a module.php, its views and often a
function_definition.php for fetch functions. Two directories are not modules:
| Directory | Holds |
|---|---|
kernel/classes/ | the content model and services: eZContentObject, eZContentObjectTreeNode, eZPersistentObject, eZDataType and the datatypes in kernel/classes/datatypes/, workflow types, the help system (kernel/classes/help/), the debug bar (kernel/classes/debugbar/) |
kernel/private/classes/ | the request kernel (ezpkernel.php, ezpkernelweb.php), ezpEvent, and the runnable classes: commands/, cronjobs/, views/, services/, runnable/ |
kernel/common/ | shared helpers, for example ezpI18n and template operators used everywhere |
kernel/sql/ | the kernel's database schema per engine |
Inside lib/
| Library | Main classes |
|---|---|
lib/ezutils/ | eZINI, eZDebug, eZDebugSetting, eZSys, eZHTTPTool, eZExecution, eZCLI, eZURI, eZExtension, the debug bar report |
lib/ezdb/ | eZDB and the drivers (eZSQLite3DB, eZPostgreSQLDB, eZMySQLiDB, expMongoDB), the SQL query cache |
lib/eztemplate/ | the template engine (eZTemplate), its compiler and the built-in operators |
lib/ezfile/ | files, directories, eZLog |
lib/ezi18n/, lib/ezlocale/ | translation and locale |
lib/ezdbschema/ | schema handling and .dba files |
lib/ezsession/ | sessions |
lib/phpcompat.php | functions newer than PHP 8.0, defined only when PHP lacks them |
lib/version.php | the release number |
Configuration and generated files
| Path | What it is | In git |
|---|---|---|
settings/*.ini | the kernel's default settings | yes |
settings/override/, settings/siteaccess/ | the installation's own settings; may hold secrets | no (installation) |
config.php | constants for this installation (from config.php-RECOMMENDED; exp:setup:config copies it, exp:config:* edits it) | no |
.htaccess | the Apache and LiteSpeed rules (from .htaccess_root or .htaccess_root_static; exp:setup:htaccess copies it) | no (installation) |
var/backup/setup/, var/backup/config/ | the copies exp:setup:* and exp:config:* keep of every file they replace or edit | no |
config.env.php | EXP_ENV, the environment name of this machine (from config.env.php.example) | no |
autoload/ezp_kernel.php | the kernel class map | yes |
var/autoload/ezp_extension.php, ezp_override.php, ezp_tests.php | generated class maps | no |
var/cache/, var/log/, var/<site>/ | caches, logs, storage | no |
vendor/ | Composer packages | no |
dist/engine.phar | the optional engine archive | no (dist/ is ignored) |
Quality and tests
| Path | Purpose |
|---|---|
phpunit.xml, tests/bootstrap.php, tests/tests/ | PHPUnit configuration, bootstrap and the tests |
tests/test-map.json | which tests cover which source files |
tests/runtests.php | the legacy runner for database tests (--dsn ... --db-per-test) |
tests/bin/bootsmoke.php | the boot smoke test CI runs on PHP 8.0 |
phpcs.xml.dist, bin/phpcs/ | the code style and the project's own sniffs |
phpstan.neon.dist, phpstan-baseline.neon | static analysis at level 1 with its baseline |
Makefile, .githooks/, composer.dev.json | the make targets, the git hooks and the development tools |
.github/workflows/ | CI: Quality, PHPUnit, Performance, CI health |
What you change and what you leave alone
- Your work goes into an extension in nearly every case. The kernel is changed only for kernel fixes and features you contribute back (Contributing PHP changes).
- Never edit generated files (
var/autoload/*, caches); regenerate them. - Never commit installation files:
settings/override/,config.php,config.env.php,var/. In a project repository of your own, add/config.phpto its.gitignore: it can hold the cluster database password. - Never edit
vendor/; extensions installed by Composer can be live git checkouts in some installations, and Composer would replace them.
Related pages
- Exponential for PHP developers
- Project files
- Extension directory layout
- Directories under var/
- Setting up .htaccess and config.php from the console
- 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.