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,135 @@
-## 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 `php composer.phar 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.
+
+Add the following line as in the example below by changing the first parameter
+`myExtensionName` with the name of your extension.
+
+```php
+new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()),
+```
+
+```php
+<?php
+// app/AppKernel.php
+
+// ...
+class AppKernel extends Kernel
+{
+    public function registerBundles()
+    {
+        $bundles = [
+            // ...
+
+            new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()),
+        ];
+
+        // ...
+    }
+
+    // ...
+}
+```
+
+
+#### Manually
+
+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]: ../01-installation/installing-contao.md#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)