contao-community-alliance / composer-plugin
Composer plugin that provides installers for contao-module and legacy-contao-module.
Installs: 613 805
Dependents: 659
Suggesters: 0
Security: 0
Stars: 7
Watchers: 19
Forks: 10
Open Issues: 0
Type:composer-plugin
Requires
- php: ^7.1 || ^8.0
- composer-plugin-api: ^2.0
- symfony/finder: ^4.4 || ^5.2 || ^6.0
- symfony/process: ^4.4 || ^5.2 || ^6.0
Requires (Dev)
- composer/composer: ^2.0
- symfony/phpunit-bridge: ^3.0
Conflicts
- contao/core: *
- contao/core-bundle: <4.9
- 3.2.x-dev
- 3.2.4
- 3.2.3
- 3.2.2
- 3.2.1
- 3.2.0
- 3.1.x-dev
- 3.1.6
- 3.1.5
- 3.1.4
- 3.1.3
- 3.1.2
- 3.1.1
- 3.1.0
- 3.0.9
- 3.0.8
- 3.0.7
- 3.0.6
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 3.0.0
- 2.4.x-dev
- 2.4.3
- 2.4.2
- 2.4.1
- 2.4.0
- 2.3.8
- 2.3.7
- 2.3.6
- 2.3.5
- 2.3.4
- 2.3.3
- 2.3.2
- 2.3.1
- 2.3
- 2.2.5
- 2.2.4
- 2.2.3
- 2.2.2
- 2.2.1
- 2.2
- 2.1
- 2.0.2
- 2.0.1
- 2.0.0
- 2.0.0-beta4
- 2.0.0-beta3
- 2.0.0-beta2
- 2.0.0-beta1
This package is auto-updated.
Last update: 2024-09-20 10:14:04 UTC
README
The Contao Composer plugin is responsible for correctly installing Contao 3 extensions in a Composer environment.
Composer files are always located in the vendor
folder, but they must be copied/symlinked to system/modules
to be correctly detected by Contao.
Be aware that this plugin is not necessary for Contao 4 / Symfony bundles. If you however do support both Contao 3 and Contao 4, make sure to follow the old way which is still fully supported in Contao 4. You will obviously not be able to use new bundle features (like the DIC) though.
composer.json
Follow the Composer manual on how the basic composer.json
in your library should look like.
A few simple rules will make your package compatible with Contao 3:
- Change the type of your package to
contao-module
- Add a requirement for the correct Contao version
- Add a requirement to the Contao Composer plugin
- Add the sources to the
extras => contao
section - If necessary, specify your runonce files
Example:
{ "name": "vendor/package-name", "type": "contao-module", "license": "LGPL-3.0+", "require": { "contao/core-bundle": "4.*", "contao-community-alliance/composer-plugin": "3.*" }, "extra": { "contao": { "sources": { "": "system/modules/extension-name" }, "runonce": [ "config/update.php" ] } }, "replace": { "contao-legacy/extension-name": "self.version" } }
Require Contao
In Contao 4, the bundled modules were restructured so each module is a separate Symfony bundle. This means that a user can decide not to install the news or calendar extension if it's not needed for their system.
Your extension should always require contao/core-bundle
in the appropriate version (see About semantic versioning).
If your code is extending other modules like news or calendar, make sure to add correct requirements for the
respective Symfony bundles (e.g. contao/news-bundle
or contao/calendar-bundle
).
Contao 4 was designed to be backwards-compatible with Contao 3. Therefore, it is very much possible to have an extension that does support both Contao 3 and Contao 4. If your extension works with Contao 3.5 and Contao 4, a correct requirement could look like this:
{ "require": { "contao/core-bundle": "~3.5 || ~4.1" } }
Require the Contao Composer Plugin
There are two different versions of the Plugin currently actively supported.
-
Version 2 of the plugin is made for Contao 3. It supports installing Composer packages in
TL_ROOT/composer
instead of the root directory of your installation. -
Version 3 of the plugin is made for Contao 4. In Contao 4, the
vendor
folder is located in your installation root, and Contao is just another dependency of your installation.
Make sure to require the correct version of the plugin. If your module does support Contao 3 and Contao 4, the correct require statement looks like this:
{ "require": { "contao-community-alliance/composer-plugin": "~2.4 || ~3.0" } }
Versions older than 2.4 will not support contao/core-bundle
, so make sure to set a correct dependency. If you only
support Contao 4, the required version would simply be 3.*
. However, you should probably create a Symfony bundle
and not require the Contao Composer Plugin at all…
Be aware that your root project (the composer.json
in your root folder) should be of type project, otherwise
the plugin will not install Contao sources.
Sources
In the sources section, you can define which files should be copied where on installation. This is necessary
for Contao 3 extensions to be installed in the system/modules
folder.
If your GIT repository contains only files that should be copied into the system/modules/extension-name
folder,
simply specify an empty source and the target folder.
{ "extra": { "contao": { "sources": { "": "system/modules/extension-name" } } } }
However, you could also restructure your GIT so that Contao files live in their own folder. In this case, you can use the Composer autoloader and follow PSR-0 or PSR-4 namespaces. However, your extension is then incompatible with the old extension repository.
You can define multiple files or folder to be copied/symlinked into the Contao installation. Your package can even install multiple Contao extensions at once.
{ "extra": { "contao": { "sources": { "config": "system/modules/extension-name/config", "dca": "system/modules/extension-name/dca", "templates": "system/modules/extension-name/templates" } } }, "autoload": { "psr-4": { "VendorName\\ExtensionName\\": "src/" } } }
Userfiles
The userfiles
property allows to copy files from a Composer package to the /files
folder in Contao.
As this folder can be renamed in the Contao configuration, the installer automatically tries to find the correct location.
Be aware that userfiles are only copied once if they do not exist, they are not overwritten on an update.
{ "extra": { "contao": { "userfiles": { "src/system/modules/my-module/files/images": "my-module/images" } } } }
Runonces
Putting runonce.php
files into your extension's config
directory is a bad practice with Composer.
The file will be deleted by Contao after it's executed, which means Composer will complain about modified files
on the next update. To work around this, you can specify a list of runonce files in the composer.json
.
They will be executed after each installation or update, but they won't be deleted. There is no need to name
them runonce.php
either, feel free to use any other name.
{ "extra": { "contao": { "runonce": [ "src/system/modules/extension-name/runonce/init_update.php", "src/system/modules/extension-name/runonce/do_db_update.php", "src/system/modules/extension-name/runonce/refresh_entities.php" ] } } }
The runonce files will be executed in the order you specify them.
About semantic versioning
Following Semanting Versioning is crucial to the success of Composer installation. If you (the developer) do not follow semantic versioning, it is very hard for others, (and the dependency manager) to install correct versions of your library.
You should also get familiar with the Composer version constraints to correctly set your dependencies. Incorrect dependencies will lead to broken installations, and it's always the developer's fault!
Server requirements
The Contao Composer Plugin requires an up-to-date server configuration. Contao 4 does no longer support the so-called "safe mode hack", and the plugin now requires symlink support.