Why so many settings in Chamilo's configuration.php?

If you install Chamilo 1.11.6, for example, and dive into the details of its configuration, you might get confused by the fact that we have a "settings_current" table in the database at the same time as we have a (large) number of settings to be enabled through the app/config/configuration.php file. This boils down to one rule that we have established in Chamilo: minor versions do not contain database changes.

Major versus Minor versions

So the first question is: what is a "minor" version. To answer that, maybe let's look at the opposite first. A Major version of Chamilo is a version that contains a lot of changes (usually new features for the end user) and that *requires* database changes to work, if you upgrade from a previous version. Typically, in Chamilo, a major version will be numbered like this: 1.9, 1.10, 1.11, 2 A major version is always considered as being the ".0" version as well, so 1.9 = 1.9.0, 1.10 = 1.10.0, 1.11 = 1.11.0 and 2 = 2.0. Starting at version 2, we hope to only use 1 number to represent the major version (so the serie of major versions will continue as 1.11, 2, 3, 4, ...). A Minor version is mostly a "patch" version. It fixes bugs or adds minor new features that do not require database changes.

The no-DB-change rule

When we moved away from Dokeos, we established that we needed stricter rules to ensure a better software quality in the future, so I (personally) established the no-DB-change rule based on our bad experience in the previous project, where everything had gone sideways, pretty much. Under this rule (which you can find in the first section of the Release cycle wiki page of Chamilo), a minor version cannot contain any database change in comparison to the initial major version of its serie. So 1.11.6 will have the exact same database (and files) structure as 1.11 (or 1.11.0) or any other minor version of this serie. This also extends to the basic configuration settings of Chamilo. By preventing new settings to be added like crazy to the configuration page in Chamilo, we maintain a coherent set of databases and tables throughout the whole spectrum of Chamilo installations worldwide.


Because of that, we needed a "patch" mechanism to be able to add a few configuration settings anyway, but not mix them up with the database. This is because the primary key of the settings_current table in Chamilo, where settings are stored, is a numeric ID and it can be used by plugins to insert additional settings, so it is not possible for us to just check a simple ID and know if this system has been "hacked" since its installation. The configuration file of Chamilo was initially (a very long time ago, before the creation of the settings_current table) used to store all configuration settings. It is still used today to store the database accesses and some settings that we don't want Chamilo administrators to access through the web panel (for different motives, one being security against hacks, another being security against misconduct or mistakes). And some external developers used that file (located at app/config/configuration.php) to store some temporary global values for testing or development. So the configuration file came naturally as the ideal place to store those temporary settings that appear (and are needed) between minor versions. The process we use now is the following (between minor versions):
  • whenever we need a new setting, we register it in main/install/configuration.dist.php, which is the template shipped with any Chamilo package, used during installation to generate the final configuration.php file
  • the setting is "commented", meaning it is prefixed by "//" to avoid it being taken into account
  • a new setting *always* is set in such a way that, when it is "false" or undefined, the previous behaviour of Chamilo remains unchanged (so it doesn't affect in any way people not wanting the corresponding feature and upgrading from one minor version of Chamilo to another)
  • by default, it is set to "false"
  • for new installations, the setting will appear commented out in app/config/configuration.php
  • for upgrades, the setting will not appear in app/config/configuration.php, but only in main/install/configuration.dist.php
  • the new code we create in Chamilo checks (through the api_get_configuration_value() function) whether the setting is enabled before showing the feature
In some exceptional cases, we might need a database change to add this new feature. In this case, we will simply add the SQL query (as a comment) next to the corresponding option in configuration.dist.php

Upgrade to following major version

Every time we upgrade Chamilo to a new major version, we take the main/install/configuration.dist.php file from the latest minor version and integrate all relevant settings into the settings_current table in the database so they appear in the Chamilo configuration settings interface. We also automatically apply all optional database changes so they are available in the form of empty table, ready to be used when the setting is enabled.