4. Install an application using Flavours

There are various ways to add packages to PHP projects. You are probably used to using Composer, and adding dependencies to the composer.json file. You can try that now with a dependency you’re already familiar with.

First, add the dependency. Then, test that it is installed as expected by running:

docker-compose build

If you commit and push your changes once again as you did in the previous section, the project will be rebuilt with the new dependency when the cloud environment is redeployed.

Introducing Flavours

However, this project is managed using Flavours, which gives us an additional way of working. Flavours is a platform-independent specification for building containerised web projects; the Flavours addon manager for PHP Laravel - flavour/fam-php-laravel - knows how to add a package to a Laravel project.

We will add the laravel-responsecache package. It’s an open-source addon, released by the Belgian agency Spatie, and can improve performance of Laravel sites by caching responses.

Install the Flavours CLI

The Flavours CLI is an open-source package, published at GitHub.

Run:

npm install -g @flavour/cli

Run the flavour add command

Run the flavour add command, as follows:

➜ flavour add composer/spatie/laravel-responsecache:6.1.1
  ❯ Installing composer/spatie/laravel-responsecache:6.1.1
    ✔ Getting metadata
    ✔ Checking validity
    ✔ Adding requirement
  ✔ Installed composer/spatie/laravel-responsecache:6.1.1

laravel-responsecache is now installed in the project.

About the command

The command breaks down thus:

  flavour add     composer/spatie/laravel-responsecache:6.1.1
  command action namespace/addon name                  :version number

The Flavours CLI looks up the open Flavours registry at https://addons.flavours.dev, and finds the particular version there, and pulls down the YAML data it contains.

The CLI uses the information provided about the addon to identify the appropriate addon manager, which processes the YAML and performs the steps required by the add action.

Check what the command has done to the project

In this case, the addon manager will apply some changes to the project. You can see what they are by running git diff:

In its app.flavour, which includes Flavours description of the project, you’ll find in the addons section:

'composer/spatie/laravel-responsecache:6.1.1':
    manager: 'flavour/fam-php-laravel:0.1.1'
    hash: 9c5f4b2311089d4c5b0def4a0ded5bd927ddd8936d7db18da4cb84283e3413d1

app.flavour is in essence what makes a project Flavours-aware.

And on the project’s composer.json require section, the addon is listed as a component of the project, so that when the project is built, the addon will be installed:

"spatie/laravel-responsecache": "6.1.1"

Finally, if it wasn’t there already, you will find a .flavour directory, which contains information about the addon and some configuration for it.

Rebuild the project:

docker-compose build web

When you start the project again with docker-compose up it will now be running with laravel-responsecache installed and activated.

Deploy to the Cloud

To deploy your changes to the Test server, push your changes, and run a deployment command:

git add composer.json app.flavour .flavour
git commit -m "Added laravel-responsecache"
git push origin master
divio project deploy test

Divio’s hosting service is Flavours-aware; your changes, once pushed and deployed on the Control Panel, will automatically use the composer.json file to rebuild the project with the new package installed.

Explore configuration

As a Flavours-aware host, the Divio Control Panel recognises the newly installed package. In the project’s Addons view in the Dashboard, you will see it listed along with its version number and configuration options:

''

From its options menu, select Configure. You will be presented with a pane of default options (some of which you can edit). These defaults were contained in the addon’s YAML. If you hit Save, your options will be applied as environment variables (you can see them in the Env Variables view).

When next deployed, those variables will be applied.

Where to go next?

This completes the basic cycle of project creation, development and deployment; you should now be familiar with the fundamental concepts and tools involved.

Other sections of the documentation expand upon them. The how-to guides in particular cover many common operations. And if there’s something you’re looking for but can’t find, please contact Divio support.