Adjust blackfire documentation

docs/custom-container/enable-blackfire.rst

@@ -59,15 +59,19 @@ Blackfire env variables
 
 Additionally the following ``.env`` variables can be created for easy configuration:
 
-+------------------------------+---------------+---------------------------------------------------------------+
-| Variable                     | Default value | Description                                                   |
-+==============================+===============+===============================================================+
-| ``BLACKFIRE_SERVER_ID``      | ``id``        | A valid server id is required in order to use blackfire.      |
-+------------------------------+---------------+---------------------------------------------------------------+
-| ``BLACKFIRE_SERVER_TOKEN``   | ``token``     | A valid server token is required in order to use blackfire.   |
-+------------------------------+---------------+---------------------------------------------------------------+
-| ``BLACKFIRE_SERVER``         | ``latest``    | Controls the Blackfire version to use.                        |
-+------------------------------+---------------+---------------------------------------------------------------+
++------------------------------+---------------+-------------------------------------------------------------------------+
+| Variable                     | Default value | Description                                                             |
++==============================+===============+=========================================================================+
+| ``BLACKFIRE_SERVER``         | ``latest``    | Controls the Blackfire version to use.                                  |
++------------------------------+---------------+-------------------------------------------------------------------------+
+| ``BLACKFIRE_SERVER_ID``      | ``id``        | A valid server id is required in order to start ``blackfire-agent``.    |
++------------------------------+---------------+-------------------------------------------------------------------------+
+| ``BLACKFIRE_SERVER_TOKEN``   | ``token``     | A valid server token is required in order to start ``blackfire-agent``. |
++------------------------------+---------------+-------------------------------------------------------------------------+
+| ``BLACKFIRE_CLIENT_ID``      | ``id``        | A valid client id is required in order to use ``blackfire`` cli.        |
++------------------------------+---------------+-------------------------------------------------------------------------+
+| ``BLACKFIRE_CLIENT_TOKEN``   | ``token``     | A valid client token is required in order to use ``blackfire`` cli.     |
++------------------------------+---------------+-------------------------------------------------------------------------+
 
 
 Instructions
@@ -89,8 +93,8 @@ Copy the Blackfire Docker Compose overwrite file into the root of the Devilbox g
    * :ref:`overwrite_existing_docker_image`
 
 
-2. Adjust ``env`` settings (required)
--------------------------------------
+2. Adjust ``env`` settings
+--------------------------
 
 By default Blackfire is using some dummy values for BLACKFIRE_SERVER_ID and BLACKFIRE_SERVER_TOKEN.
 You must however aquire valid values and set the in your ``.env`` file in order for Blackfire
@@ -113,10 +117,57 @@ to properly start. Those values can be obtained at their official webpage.
    #BLACKFIRE_SERVER=1.18.0
    BLACKFIRE_SERVER=latest
 
+You must also explicitly enable the PHP ``blackfire`` module and disable ``xdebug`` via ``.env``
+
+.. code-block:: bash
+   :caption: .env
+
+   PHP_MODULES_ENABLE=blackfire
+   PHP_MODULES_DISABLE=xdebug
+
 .. seealso:: :ref:`env_file`
 
 
-3. Start the Devilbox
+3. Copy blackfire php.ini template
+----------------------------------
+
+In order for the PHP ``blackfire`` module to know where the ``blackfire-agent`` is listening,
+we must configure its PHP settings. There is already a default template that you can simply copy.
+
+.. code-block:: bash
+
+   host> cp cfg/php-ini-7.2/devilbox-php.ini-blackfire cfg/php-ini-7.2/blackfire.ini
+
+.. note::
+   The above example shows the procedure for PHP 7.2, if you are using a different version,
+   you must navigate to its corresponding configuration directory.
+
+
+4. Configure blackfire cli (optional)
+-------------------------------------
+
+If you want to use the ``blackfire`` cli from within the PHP container, its configuration must be
+configured. There is already a startup template which does it for you.
+
+You first need to add the Blackfire client id and token to ``.env``:
+
+.. code-block:: bash
+   :caption: .env
+
+   BLACKFIRE_CLIENT_ID=<valid client id>
+   BLACKFIRE_CLIENT_TOKEN=<valid client token>
+
+Then all that's left to do is to copy the startup script which configures the blackfire cli for you.
+
+.. code-block:: bash
+
+   host> cp autostart/configure-blackfire-cli.sh-example autostart/configure-blackfire-cli.sh
+
+.. seealso::
+   * :ref:`custom_scripts_globally`
+
+
+5. Start the Devilbox
 ---------------------
 
 The final step is to start the Devilbox with Blackfire.
@@ -142,6 +193,9 @@ directory:
    # Copy compose-override.yml into place
    cp compose/docker-compose.override.yml-blackfire docker-compose.override.yml
 
+   # Copy php.ini into place
+   cp cfg/php-ini-7.2/devilbox-php.ini-blackfire cfg/php-ini-7.2/blackfire.ini
+
    # Create .env variable
    echo "BLACKFIRE_SERVER_ID=<valid server id>"       >> .env
    echo "BLACKFIRE_SERVER_TOKEN=<valid server token>" >> .env
@@ -157,5 +211,8 @@ directory:
    echo "#BLACKFIRE_SERVER=1.18.0"                    >> .env
    echo "BLACKFIRE_SERVER=latest"                     >> .env
 
+   echo "PHP_MODULES_ENABLE=blackfire"                >> .env
+   echo "PHP_MODULES_DISABLE=xdebug"                  >> .env
+
    # Start container
    docker-compose up -d php httpd bind blackfire