Skip to content
This repository has been archived by the owner on Apr 21, 2021. It is now read-only.

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

Closed
wants to merge 19 commits into from
Closed
Changes from 7 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion manual/en/01-installation/configuring-the-live-server.md
Original file line number Diff line number Diff line change
@@ -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 |
132 changes: 122 additions & 10 deletions manual/en/01-installation/installing-contao.md
Original file line number Diff line number Diff line change
@@ -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,122 @@ 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. But they must necessarily fulfil the compatibility requirements of Contao 4
to work properly. 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
120 changes: 85 additions & 35 deletions manual/en/05-system-administration/extensions.md
Original file line number Diff line number Diff line change
@@ -1,58 +1,108 @@
## Extensions

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
If a bundle and a Contao extension have the same purpose, they are nevertheless
not developed in the same way and the installation procedure is different for
each of them.

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.
> **Warning** Even if a Contao extension can be installed, this does not mean
that it is compatible with Contao 4. The extension you want to use must take
into account the prerequisites of the version 4.

![](images/extension-list.jpg)

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.
### Installing a Contao extension

![](images/extension-details.jpg)
With Contao 4.0, an extension can be installed with Composer or manually.

Contao will automatically download and install the extension and update the
database if necessary.

![](images/extension-install.jpg)
#### With Composer

An extension that can be installed via Composer can be found through its main
repository [Packagist][2]. A name of an extension is divided into two parts.
The first part is the name of the project owner and the second the extension
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

project owner is usually called vendor

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept "project owner" in parentheses because everyone does not necessarily know this term.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Like me for example ;-)

name. For example: `companyName/extensionName`.

### Extension manager
Dependencies (in our case an extension) are described in a file named
`composer.json` which is located in the root folder of your Contao installation.

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.
This is the first step you need to do. Open the `composer.json` file and add the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The whole chapter can probably be simplified a lot. One should simply run php composer.phar require companyName/extensionName and let Composer handle the rest (update composer.json and determining the best version).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, it's easier that way. Modified in e3ca998

new dependency in the `require` key.

![](images/extension-manager.jpg)
```json
"require": {
"companyName/extensionName": "~1.0",
},
```

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!
You must also enter the version you want to use. The `~` [operator][3] means you
want the latest version of `1.*`.

![](images/extension-uninstall.jpg)
Run the command `php composer.phar update companyName/extensionName` in your
command-line interface to start the installation.

After the installation, you can clear the cache with the following command:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In a Contao 4 standard edition, this is automatically done by Composer (using the scripts defined in your root composer.json)

`php app/console cache:clear -e=prod`.

### 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].
#### 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 `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
below). Finally, check the database with the [Contao install tool][5].


##### AppKernel.php

Instantiate the `ContaoModuleBundle` class. The first parameter is the name of
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can reuse the examples from http://symfony.com/doc/current/cookbook/bundles/best_practices.html#installation-instructions for how to adjust the AppKernel?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's done in 7b553cd

your extension.

```php
new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()),
```

**Example**:

```php
// app/AppKernel.php

public function registerBundles()
{
$bundles = [
new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
new Contao\CoreBundle\ContaoCoreBundle(),
new Contao\CoreBundle\HttpKernel\Bundle\ContaoModuleBundle('myExtensionName', $this->getRootDir()),
];

// ...

return $bundles;
}
```

After the installation, 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/articles/versions.md#tilde
[4]: ../01-installation/installing-contao.md#symbolic-link
[5]: ../01-installation/installing-contao.md#the-contao-install-tool
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.