Welcome to the Contao manual for developers and the Contao ecosystem! This introduction is meant to give you an overall idea of how things work in Contao and its ecosystem, people with assigned roles, whom to talk to and where to get help.
This document is split into these chapters:
This chapter provides an overview over the capabilities of the Contao Open Source CMS and should help new developers with getting their web application project started with Contao more easily.
This chapter describes the ins and outs of the Contao ecosystem. It provides articles about Contao libraries, how to use and extend Contao and general articles about concepts unique to this CMS.
The reference is a goto guide for all available options in certain features, like say DCA configuration or Hooks.
This section contains a continuously growing collection of specific recipes and guides that explain how to correctly solve the most recurrent problems that Contao & Symfony developers face in their day to day work.
This section contains documentation about various internal procedures or articles about topics that do not fit into the regular documentation.
To understand why things are the way they are in Contao it’s very helpful to understand at least some of its history. Contao has been on the market since 2006 and has never been rewritten from scratch but the code base has evolved step by step as the years passed by instead. In 2015, Contao 4 was released as a Symfony bundle which can be added to your regular Symfony application just like any Symfony bundle you know.
This is still the case to this day.
For Contao and its community, the release of Contao 4 meant a huge technical leap, being confronted with Composer and Symfony
all of a sudden now.
The Core team decided that the project needs the ability to transition slowly from Contao 3 to Contao 4 as adoption would
never take place otherwise. That’s why Contao 4 essentially still carries around code that’s been there for years because
of backwards compatibility.
Most of this code resides in
core-bundle/src/Resources/contao so it does not interfere with code that’s been written later
on, put into namespaces properly and being unit tested as you’d expect it from any modern CMS.
Examples for legacy code that still works might be your typical library classes any CMS that’s been on the market for
a while would provide such as file operations (
Folder), request handling (
Environment) and many more. Most
of which are not used anymore in new code as there are better alternatives at hand using Composer now.
Contao heavily relies on superglobals in older code which basically served as some sort of Dependency Injection Container
back in the days which is why you’ll still come across loads of
$GLOBALS usages all over the place.
However, there’s a steady transition going on and with every new release there are new ways introduced as to how you can
e.g. register a new content element. The old code is just still floating around to make sure all the already existing
extensions still work.
With the transition to Symfony with Contao 4, Contao also adopted Semantic Versioning. In August 2022, the first major version since migrating to Symfony was released: Contao 5. The Core team used this first major version to get rid of a ton of legacy code that has been accumulated over versions 4.0 to 4.13 but also some of the very old libraries from before. Yet still, you’ll find that all the statements above are still true for many parts of Contao. We’re continuing our path of transforming the Content Management System our community loves step by step while trying to pay highest attention to ensure smooth transitions.
One special thing to be aware of when working with Contao is that unfortunately we carry a very old burden with us which is input encoding.
User input must not be trusted, it must be encoded when output because that’s the only place where you can encode correctly depending on the context.
Unfortunately, back when Contao was created, there was no such thing as
Smarty was probably already on the market
but automated output encoding was likely less of an issue back then.
So when Contao decided to use plain old PHP as templates, one would have to call some special encode method on every
variable that was echo’ed. Instead of doing that, it was decided to encode the input and store the data encoded in the
database already. You do have the option to disable this when you develop your own extensions to Contao but
it’s just something to keep in mind. We all know it’s wrong but migrating away from already encoded data is very hard
and likely will only become a thing when we switch to Contao 5.
So be aware of this. Don’t just use e.g. Symfony’s
Request class to fetch user input, store it as is in the DB and
let Contao display it in the front end or back end.
Everything related to Contao development happens in one of the repositories assigned to the “Contao” organisation on GitHub. Here’s a description of the most important repositories you should be familiar with:
This is the Contao Monorepository where all of the active development of the
core-bundle and additional bundles takes
place. It’s likely the most important repository you want to follow.
The Contao bundles are designed in such a way that you can add them to your very own Symfony application but most of the setups of Contao are using the “Managed Edition”. The Managed Edition basically consists of the
which itself provides the skeleton of a full Symfony application. Using a Composer script it will build a complete
Symfony application around your
composer.json. The Managed Edition was a thing before “Symfony Flex” appeared on the
market. If you install the Contao Managed Edition you have the advantage that updates of Contao will be easier as you
don’t have to update your
config.yaml to the latest settings with every release.
The idea is that bundles can register themselves to the kernel when it is installed, similar to what Symfony Flex does
with its recipes. For that matter, we use the “Manager Plugin”.
The Contao Manager Plugin is a Composer plugin that provides access to bundles to register themselves to the kernel, configuring the DI container, adding routes and much more.
So far, everything you got to know from Contao’s ecosystem still requires you to work on command line. Thanks to the Contao Managed Edition a lot of tedious work is automated for you but to set it all up and manage it, you still need to feel comfortable with the CLI, Composer and much more. As a developer that should not be much of an issue for you so you might probably stop here but to get a complete picture of the Contao ecosystem, please continue reading.
The majority of Contao’s users want to be able to install Contao on their web server and manage it there. The Contao Manager is Contao’s answer to this need. It’s a GUI that’s compiled to a single PHAR file which is distributed on contao.org and provides self update functionality. You can install it on your web server and start managing your setup using a nice GUI.
Composer packages usually don’t contain extensive descriptions and they are managed in English only which is why Contao provides a repository where additional metadata and translations for these packages can be provided. They are then used within the Contao Manager so if you want people to not just install your Contao bundle on CLI but also from the Contao Manager you might want to contribute additional information here.
This is the repository where the documentation you’re reading is being managed. The more contributors the better the documentation. Thus, we’re counting on your contribution!
Sometimes it’s helpful if you know the people involved in Contao development. As an Open Source project it is what people make it, so please, contribute!
In any case, the current core team members consist of (in alphabetical order)
In addition, there’s a core team for the documentation:
Contao people are active on multiple channels. If you find a bug or want to request a feature (or ideally
prepare a pull request) please do so on the respective repository (most likely the
contao/contao mono repository).
Other than that there are the following channels: