Starting your Development

There are two main cases when developing within Contao: either you want to customize your project-specific web application, or you want to create a re-usable extension - either for your own purposes or for others. In either case, the principles are the same. However, when creating an extension for Contao, there are some differences in structure and procedure. This articles covers the former case and also assumes the usage of the Contao Managed Edition. Another article explains how to create a reusable extension.

The purpose of this article is to show the directory structure of Contao and explain what goes where - and what to do initially for certain customization tasks.

Structure

After a fresh install of Contao, your project will have a certain initial file & directory structure (which is similar to the structure of a pure Symfony project using the symfony/skeleton for example).

When customizing your web application, the following files and folders will usually be of interest. Some of those will need to be created manually:

Application Configuration

The configuration of a Symfony application is done within the config/ directory through various YAML files. The Contao Managed Edition automatically loads the following configurations, if present:

imports:
    - { resource: services.yml }

Contao Configuration & Translations

Contao has its own configuration files in the form of PHP arrays, as well as translation files in the form of either PHP arrays or in an XLIFF format. These files are generally defined within the contao/ folder of your project’s root directory (or app/Resources/contao/ in Contao 4.4).

Have a look at the DCA documentation on how to handle DCA files and the translation documentation on how to handle translation files. The content of the config.php depends on the use-case and its documentation is covered in the applicable topics of the framework documentation.

Autoloading, Services and Controllers

Any custom class that is needed for the web application - like a Model, a Content Element or a class for a Hook for example - needs to be loaded. Typically the code for customizing the web application for Contao will be put in the \App namespace. The default composer.json of the recent Contao Managed Edition versions already contains the appropriate autoloading directive:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Any of these classes can also be registered as Symfony services, which is necessary if you want to use dependency injection and service tagging. Registering Contao hooks, content elements, front end modules, cron jobs and Data Container callbacks is done via service tags.

For the application development it is recommended to use autowiring and auto-configuration, which makes it easy to create new services and tag them automatically (through annotations or class interfaces) - and thus enables quick development of Contao content elements, hooks, callbacks etc.

# config/services.yaml
services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\:
        resource: ../src

If you want to implement regular controllers and define their routes via PHP attributes, you will also need to register these routes via the automatically loaded config/routes.yaml:

# config/routes.yaml
app.controller:
    resource: ../src/Controller
    type: attribute

Once this is configured, hooks, callbacks, content elements and front end modules for example can be created without having to configure them in separate files by using annotations for service tagging.

All this is not needed, if you only need to change or extend the Data Container Array definition of a table, or want to change a translation for example.

Next: create your first DCA adjustment.