Add the "folder structure" chapter and modify the "extension" chapter

manual/en/01-installation/configuring-the-live-server.md

@@ -22,7 +22,6 @@ You also need several PHP extensions to get the full functionality.
 |---------------|-------------------------------|-----------|
 | GDlib         | image resizing                | yes       |
 | DOM           | XML files                     | yes       |
-| SOAP          | Extension Repository          | no        |
 | Phar          | Live Update                   | no        |
 | mbstring      | multi-byte character handling | no        |
 | mcrypt        | data encryption               | no        |

manual/en/01-installation/installing-contao.md

@@ -20,7 +20,7 @@ URL. Example: curl -L http://download.contao.org/4.0.2 | tar -xzp
 
 ### Installing with Composer
 
-You can also install Contao with Composer using the [contao/standard-edition][6]
+You can also install Contao with Composer using the [contao/standard-edition][3]
 repository.
 
 ```bash
@@ -35,15 +35,15 @@ created automatically.
 want to install a specific version, you must insert it in the command as for
 example: `php composer.phar create-project contao/standard-edition:4.0.2 <target>`
 
-First of all, before running this command, you must [install Composer][7]. It
+First of all, before running this command, you must [install Composer][4]. It
 can be installed globally with the following two commands on Mac OS X or Linux:
 
 ```bash
 curl -sS https://getcomposer.org/installer | php
 sudo mv composer.phar /usr/local/bin/composer
 ```
 
-On Windows, you can download and run the [installer][10].
+On Windows, you can download and run the [installer][5].
 
 During the installation in your command-line interface, you must assign a value
 to a number of parameters:
@@ -69,14 +69,14 @@ Default values are listed in parentheses. All these data will be included in the
 configuration file `app/config/parameters.yml`.
 
 The `secret` parameter allows you to create a key that will be used against
-[CSRF][8] attacks. It is very important to take time to create a strong key. As
+[CSRF][6] attacks. It is very important to take time to create a strong key. As
 described in the Symfony documentation:
 
 > **Note** Its value should be a series of characters, numbers and symbols
 chosen randomly and the recommended length is around 32 characters.
 
 You can find more information about this configuration on the
-[official Symfony website][9].
+[official Symfony website][7].
 
 
 ### The Contao install tool
@@ -129,10 +129,123 @@ process is completed. The link in the lower right corner will take you to the
 administration area.
 
 
+### Folder structure
+
+Below, a representation of the folder structure of Contao and some files
+commonly used.
+
+```bash
+├── app
+│   ├── AppKernel.php
+│   ├── cache
+│   ├── config
+│   └── logs
+├── assets
+├── files
+├── system
+│   ├── config
+│   │   └── localconfig.php
+│   └── modules
+├── templates
+├── vendor
+│   ├── contao
+│   └── symfony
+└── web
+    ├── .htaccess (hidden file)
+    ├── app_dev.php
+    ├── app.php
+    ├── install.php
+    └── share
+```
+
+#### app/
+
+This is the application folder which includes especially Symfony cache files,
+Symfony configuration files and log files.
+
+
+#### assets/
+
+`assets/` contains components such as jQuery or TinyMCE. Contao CSS and JS
+source files are also located in this folder as well as the combined and
+minified CSS and JS files and resized images. It is available from the `web/`
+folder through a symbolic link (See the [symbolic link chapter][8]).
+
+
+#### files/
+
+`files/` contains public files such as images, CSS, JavaScript, etc. It is
+available from the `web/` folder through a symbolic link.
+
+
+#### system/
+
+`system/` contains Contao configuration files, the back end theme(s) and
+[Contao modules][9].
+
+
+#### templates/
+
+`templates/` contains customized templates. See the [template chapter][10].
+
+
+#### vendor/
+
+This is the location of external libraries as well as the source code of Contao
+and Symfony. This folder also includes Contao's [bundles][11] such as the
+newsletter, the core, the news, etc. and bundles developed by the community.
+
+
+#### web/
+
+This is the web root folder that contains public files, the
+[front controllers][12] and the access to the Contao install tool.
+
+`app.php` and `app_dev.php` are the front controllers. `app.php` is used in a
+production environment and all the pages requested by visitors go through this
+single entry point. `app_dev.php` has the same goal as `app.php` but for a
+development environment. This mode displays a toolbar with some debugging
+options.
+
+`share/` contains shared files such as XML files (e.g. sitemaps or RSS feeds).
+
+> **Warning** For security purpose, the `web/` folder should be the only one to
+be accessible by visitors.
+
+
+### Symbolic link
+
+Public files (CSS, JavaScript, images, etc.) are only available from the `web/`
+folder. If some folders must be publicly available and are located outside the
+`web/` folder, the system generates [symbolic links][13] (also written symlink)
+for each of them. For example, the `web/assets` folder is a reference that
+targets the original folder `assets` placed at the same level as the `web/`
+folder.
+
+Public files of each bundle are located in the `web/bundles` folder through
+symlinks. These can be regenerated from the back end under maintenance.
+
+
+### Contao modules
+
+Existing extensions developed for Contao 3.5 and lower can be used with Contao
+4 if they fulfill the compatibility requirements. You can see if an extension is
+compatible by checking its `composer.json` file in the section `require` (e.g.
+`contao/core-bundle":"~3.2 || ~4.1`). The procedure for installing an extension
+is described in the chapter [extension][14].
+
+
 [1]: https://contao.org/en/download.html
 [2]: http://www.winscp.net/
-[6]: https://github.com/contao/standard-edition
-[7]: https://getcomposer.org/download/
-[8]: https://en.wikipedia.org/wiki/Cross-site_request_forgery
-[9]: http://symfony.com/doc/current/reference/configuration/framework.html#secret
-[10]: https://getcomposer.org/doc/00-intro.md#using-the-installer
+[3]: https://github.com/contao/standard-edition
+[4]: https://getcomposer.org/download/
+[5]: https://getcomposer.org/doc/00-intro.md#using-the-installer
+[6]: https://en.wikipedia.org/wiki/Cross-site_request_forgery
+[7]: http://symfony.com/doc/current/reference/configuration/framework.html#secret
+[8]: #symbolic-link
+[9]: #contao-modules
+[10]: ../04-managing-content/templates.md
+[11]: http://symfony.com/doc/current/glossary.html#term-bundle
+[12]: https://en.wikipedia.org/wiki/Front_Controller_pattern
+[13]: https://en.wikipedia.org/wiki/Symbolic_link
+[14]: ../05-system-administration/extensions.md

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,134 @@
-## 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][3]. It lists the
+extensions and bundles installable through [Composer][2].
+
+1. [List of Contao 4 bundles][6] in Packagist.
+2. [List of Contao 3 extensions][7] 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][5].
+
+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][4] 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][5].
+
+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://getcomposer.org/doc/00-intro.md#introduction
+[3]: https://packagist.org
+[4]: ../01-installation/installing-contao.md#symbolic-link
+[5]: ../01-installation/installing-contao.md#the-contao-install-tool
+[6]: https://packagist.org/search/?q=&type=contao-bundle
+[7]: https://packagist.org/search/?q=&type=contao-module

manual/en/SUMMARY.md

@@ -31,5 +31,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)