Update the chapter extensions for Contao 4

manual/en/04-managing-content/README.md

@@ -3,9 +3,12 @@
 The following chapters explain how to manage content in Contao. The Contao core
 supports many different content types like articles, news, events, newsletters
 or forms. Further content types like banners, tickets, products or
-recommendations are available in the [Extension Repository][1]. To create
-content, log into the back end and choose one of the modules in the Content
-section of the navigation menu.
+recommendations are available in the [Extension Repository][1] or in
+[Packagist][2] (See "[Finding extensions or bundles][3]" chapter for more
+detailed information). To create content, log into the back end and choose one
+of the modules in the content section of the navigation menu.
 
 
 [1]: https://contao.org/en/extension-list.html
+[2]: https://packagist.org
+[3]: ../05-system-administration/extensions.md#finding-extensions-or-bundles

manual/en/05-system-administration/extensions.md

@@ -1,58 +1,136 @@
-## Extensions
+## Extensions and bundles
 
 Extensions are an essential part of Contao, because they allow you to add extra
-functionality. There are more than 1,400 extensions available in the Contao
-Extension Repository, which you can browse directly in the back end.
-Communication with the repository server is done via SOAP, so you need to enable
-the PHP SOAP extension to use the service (if not enabled by default).
+functionality. There are more than 1,800 extensions available in the Contao
+[Extension Repository][1].
 
+Contao 4 is built on top of the Symfony framework and takes advantage of its
+functionalities but also of its terminology. In a Symfony project, an extension
+is named a bundle.
 
-### Extension catalog
 
-The "extension catalog" module allows you to browse the extension list and to
-install extensions at the push of a button. Use the filter and sorting options
-to find a particular extension and click the info icon or extension title to
-open the details page and install the module.
+### Finding extensions or bundles
 
-![](images/extension-list.jpg)
+Contao has its own [repository][1] where you can find the extensions that are
+compatible with Contao 3.x and lower.
 
-The details page contains a description of the extension and important
-information regarding system requirements, versions and dependencies from other
-modules. Click the "Install" button to download and install the extension.
+The second most commonly used repository is [Packagist][2]. It lists the
+extensions and bundles installable through [Composer][3].
+
+1. [List of Contao 4 bundles][4] in Packagist.
+2. [List of Contao 3 extensions][5] in Packagist.
 
-![](images/extension-details.jpg)
 
-Contao will automatically download and install the extension and update the
-database if necessary.
+### Installing a bundle with Composer
 
-![](images/extension-install.jpg)
+A name of a bundle is divided into two parts. The first part is the name of the
+vendor (project owner) and the second the bundle name. For example:
+`contao/news-bundle`.
 
+Run the command `composer require vendor/bundleName` in your
+command-line interface to start the installation.
 
-### Extension manager
+Contao dependencies (in our case a bundle) are described in a file named
+`composer.json` which is located in the root folder of your Contao installation.
+During the installation process, Composer updates the `composer.json` file and
+determines itself which version of the bundle is best suited to be installed
+depending on your version of Contao.
 
-The "extension manager" module allows you to update and uninstall extensions. It
-automatically checks for updates and notifies you if a new version is available.
-Many extensions also include links to an online manual and/or forum thread where
-you can get support.
+Then you must register your bundle in `app/AppKernel.php` so that it can be
+taken into account by the system. Add the bundle to the list of registered
+bundles:
 
-![](images/extension-manager.jpg)
+```php
+<?php
+// app/AppKernel.php
 
-To uninstall an extension, simply click the uninstall icon and follow the
-instructions. The extension manager will remove all files and folders and update
-the database if necessary. Note that this action cannot be undone and the tables
-cannot be restored!
+// ...
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            // ...
 
-![](images/extension-uninstall.jpg)
+            new <vendor>\<bundle-name>\<bundle-long-name>(),
+        ];
 
+        // ...
+    }
 
-### Manual installation
+    // ...
+}
+```
 
-In case the PHP SOAP extension is not available on your server, you can also
-install Contao extensions manually. Find the respective module in the [extension
-list][1] and download the .zip archive of the latest release. Then unzip the
-files and copy them to your local or remote Contao directory. Finally, check the
-database with the [Contao install tool][2].
+Finally, check the database with the [Contao install tool][7].
+
+With Composer, the cache is cleared automatically.
+
+
+### Installing a Contao extension
+
+An extension can be installed with Composer or manually. With Composer, the
+installation process is the same as a bundle except for the registration in the
+`app/AppKernel.php` file where the code is slightly different.
+
+In the example below, the first parameter `myExtensionName` should be replaced
+by the name of your extension:
+
+```php
+<?php
+// app/AppKernel.php
+
+// ...
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            // ...
+
+            new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()),
+        ];
+
+        // ...
+    }
+
+    // ...
+}
+```
+
+
+#### Manually
+
+Almost all extensions for Contao 3 are also compatible with Contao 4. If a
+Contao 3 extension is not available on Composer, you can install it manually
+and try if it works with Contao 4. Be aware that you must also take care of
+installing all dependencies as listed in the Extension Repository.
+
+Find the extension you want to install in the [Extension Repository][1] and
+download the .zip archive of the latest release. Then unzip the files and copy
+them to the `system/modules` folder. If the extension has public files, you must
+generate a [symbolic link][6] with the command `php app/console contao:symlinks`
+in your command-line interface.
+
+Then you must register your extension in `app/AppKernel.php` so that it can be
+taken into account by the system (see the previous chapter). Finally, check the
+database with the [Contao install tool][7].
+
+When you have made all the installation procedure, you can clear the cache with
+the following command: `php app/console cache:clear -e=prod`.
+
+
+## Extension catalog
+
+Prior to Contao 4, it was possible to install an extension automatically from
+the back end. This feature is under development and will be offered in a future
+release.
 
 
 [1]: https://contao.org/en/extension-list.html
-[2]: ../01-installation/installing-contao.md#the-contao-install-tool
+[2]: https://packagist.org
+[3]: https://getcomposer.org/doc/00-intro.md#introduction
+[4]: https://packagist.org/search/?q=&type=contao-bundle
+[5]: https://packagist.org/search/?q=&type=contao-module
+[6]: https://docs.contao.org/books/cookbook/en/folder-structure.html#symbolic-link
+[7]: ../01-installation/installing-contao.md#the-contao-install-tool

manual/en/SUMMARY.md

@@ -30,5 +30,5 @@
     * [Insert tags](04-managing-content/insert-tags.md)
 * [System administration](05-system-administration/README.md)
     * [Users and groups](05-system-administration/users-and-groups.md)
-    * [Extensions](05-system-administration/extensions.md)
+    * [Extensions and bundles](05-system-administration/extensions.md)
     * [Maintenance](05-system-administration/maintenance.md)

manual/fr/05-administration-du-systeme/extensions.md

@@ -1,64 +1,140 @@
-## Extensions
+## Extensions et bundles
 
 Les extensions sont une partie essentielle de Contao, car ils vous permettent
-d'ajouter des fonctionnalités supplémentaires. Il existe plus de 1400 extensions
-disponibles dans le référentiel d'extensions de Contao, que vous pouvez parcourir
-directement à partir du back office. La communication avec le serveur du
-référentiel s'effectue via SOAP, donc vous devez activer l'extension SOAP de PHP
-pour utiliser le service (si elle n'est pas activée par défaut).
+d'ajouter des fonctionnalités supplémentaires. Il existe plus de 1800 extensions
+disponibles dans le [référentiel d'extensions][1] de Contao.
 
+Contao 4 est conçu sur la base du framework Symfony et tire profit de ses
+fonctionnalités mais aussi de sa terminologie. Dans un projet Symfony, une
+extension est nommée un bundle.
 
-### Catalogue d'extensions
 
-Le module "Catalogue d'extensions" vous permet de parcourir la liste des
-extensions et d'installer des extensions par simple pression d'un bouton.
-Utilisez les options de filtrage et de tri pour trouver une extension
-particulière et cliquez sur l'icône d'information ou le titre de l'extension
-pour ouvrir la page de détails et installer le module.
+### Trouver des extensions ou des bundles
 
-![](images/liste-extension.jpg)
+Contao a son propre [référentiel][1] où vous pouvez trouver les extensions qui
+sont compatibles avec Contao 3.x et antérieures.
 
-La page de détails contient une description de l'extension et des informations
-importantes concernant les configurations du système requises ainsi que les
-versions et les dépendances d'autres modules. Cliquez sur le bouton "Installer"
-pour télécharger et installer l'extension.
+Le second référentiel le plus couramment utilisé est [Packagist][2]. Il liste
+les extensions et bundles qui peuvent être installés par [Composer][3].
+
+1. [Liste des bundles de Contao 4][4] dans Packagist.
+2. [Liste des extensions de Contao 3][5] dans Packagist.
 
-![](images/details-extension.jpg)
 
-Contao téléchargera et installera automatiquement l'extension et mettra à jour
-la base de données si nécessaire.
+### Installer un bundle avec Composer
 
-![](images/installer-extension.jpg)
+Le nom d'un bundle est divisé en deux parties. La première partie est le nom du
+"vendor" (propriétaire du projet) et le second, le nom du bundle. Par exemple :
+`contao/news-bundle`.
 
+Exécutez la commande `composer require vendor/bundleName` dans votre interface
+en ligne de commande afin de démarrer l'installation.
 
-### Gestionnaire d'extensions
+Les dépendances de Contao (dans notre cas un bundle) sont décrites dans un
+fichier nommé `composer.json` qui est situé dans le dossier racine de votre
+installation de Contao. Au cours du processus d'installation, Composer met à
+jour le fichier `composer.json` et détermine lui-même quelle version du bundle
+est la mieux adaptée pour être installée en fonction de votre version de Contao.
 
-Le module "Gestionnaire d'extensions" vous permet de mettre à jour et de
-désinstaller des extensions. Il vérifie automatiquement les mises à jour et
-vous avertit si une nouvelle version est disponible. De nombreuses extensions
-incluent également des liens vers un manuel en ligne et/ou un fil de discussion
-dans un forum où vous pouvez obtenir de l'aide.
+Ensuite, vous devez enregistrer votre bundle dans `app/AppKernel.php` afin
+qu'il puisse être pris en compte par le système. Ajoutez le bundle à la liste
+des bundles enregistrés :
 
-![](images/gestionnaire-extension.jpg)
+```php
+<?php
+// app/AppKernel.php
 
-Pour désinstaller une extension, cliquez simplement sur l'icône de
-désinstallation et suivez les instructions. Le gestionnaire d'extensions va
-supprimer tous les fichiers et répertoires et mettre à jour la base de données
-si nécessaire. Notez que cette action ne peut pas être annulée et les tables ne
-peuvent pas être restaurées !
+// ...
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            // ...
 
-![](images/desinstaller-extension.jpg)
+            new <vendor>\<bundle-name>\<bundle-long-name>(),
+        ];
 
+        // ...
+    }
 
-### Installation manuelle
+    // ...
+}
+```
 
-Dans le cas où l'extension SOAP de PHP n'est pas disponible sur votre serveur,
-vous pouvez également installer des extensions de Contao manuellement. Trouvez
-le module correspondant dans la [liste des extensions][1] et téléchargez
-l'archive .zip de la dernière version. Ensuite, décompressez les fichiers et
-copiez-les dans votre répertoire local ou distant de Contao. Enfin, vérifiez
-la base de données avec l'[outil d'installation de Contao][2].
+Enfin, vérifiez la base de données avec l'[outil d'installation de Contao][7].
+
+Avec Composer, le cache est automatiquement effacé.
+
+
+### Installer une extension de Contao
+
+Une extension peut être installée avec Composer ou manuellement. Avec Composer,
+le processus d'installation est le même que celui d'un bundle à l'exception de
+l'enregistrement dans le fichier `app/AppKernel.php` où le code est légèrement
+différent.
+
+Dans l'exemple ci-dessous, le premier paramètre `myExtensionName` doit être
+remplacé par le nom de votre extension :
+
+```php
+<?php
+// app/AppKernel.php
+
+// ...
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            // ...
+
+            new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()),
+        ];
+
+        // ...
+    }
+
+    // ...
+}
+```
+
+
+#### Manuellement
+
+Presque toutes les extensions pour Contao 3 sont également compatibles avec
+Contao 4. Si une extension de Contao 3 n'est pas disponible avec Composer, vous
+pouvez l'installer manuellement et essayer s'il fonctionne avec Contao 4. Soyez
+conscient que vous devez aussi prendre soin d'installer toutes les dépendances
+comme indiqué dans le référentiel d'extensions.
+
+Trouver l'extension que vous souhaitez installer dans le
+[référentiel d'extensions][1] et télécharger l'archive .zip de la dernière
+version. Puis, décompressez les fichiers et copiez-les dans le dossier
+`system/modules`. Si l'extension a des fichiers publics, vous devez générer un
+[lien symbolique][6] avec la commande `php app/console contao:symlinks` dans
+votre interface en ligne de commande.
+
+Ensuite, vous devez enregistrer votre extension dans `app/AppKernel.php` afin
+qu'elle puisse être prise en compte par le système (voir le chapitre précédent).
+Enfin, vérifiez la base de données avec l'[outil d'installation de Contao][7].
+
+Lorsque vous avez effectué toute la procédure d'installation, vous pouvez
+effacer le cache avec la commande suivante :
+`php app/console cache:clear -e=prod`.
+
+
+## Catalogue d'extensions
+
+Avant Contao 4, il était possible d'installer automatiquement une extension à
+partir du back office. Cette fonctionnalité est en cours de développement et
+sera proposée dans une version ultérieure.
 
 
 [1]: https://contao.org/en/extension-list.html
-[2]: ../01-installation/installer-contao.md#loutil-dinstallation-de-contao
+[2]: https://packagist.org
+[3]: https://getcomposer.org/doc/00-intro.md#introduction
+[4]: https://packagist.org/search/?q=&type=contao-bundle
+[5]: https://packagist.org/search/?q=&type=contao-module
+[6]: https://docs.contao.org/books/cookbook/en/folder-structure.html#symbolic-link
+[7]: ../01-installation/installer-contao.md#loutil-dinstallation-de-contao