feature #4526 Deploy Symfony application on Platform.sh. (GuGuss)

This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #4526).

Discussion
----------

Deploy Symfony application on Platform.sh.

Commits
-------

105088a Update map.rst.inc
257e9a8 Coding standard for PHP block.
18ca974 Fix coding standards #2
29988aa Use alphabetical order.
75a1c56 Fix duplicated references.
8fb400e Add some references.
a8b6df8 Reference available services
62f76bf Better match Symfony documentation standard.
b70f413 Github => GitHub
c2a5675 Fix typo and add Github link.
b4383b5 Deploy Symfony application on Platform.sh.

cookbook/deployment/index.rst

@@ -7,3 +7,4 @@ Deployment
     tools
     azure-website
     heroku
+    platformsh

cookbook/deployment/platformsh.rst

@@ -0,0 +1,190 @@
+.. index::
+   single: Deployment; Deploying to Platform.sh
+
+Deploying to Platform.sh
+========================
+
+This step-by-step cookbook describes how to deploy a Symfony web application to 
+`Platform.sh`_. You can read more about using Symfony with Platform.sh on the 
+official `Platform.sh documentation`_.
+
+Deploy an Existing Site
+-----------------------
+
+In this guide, it is assumed your codebase is already versioned with Git.
+
+Get a Project on Platform.sh
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You need to subscribe to a `Platform.sh project`_. Choose the development plan
+and go through the checkout process. Once your project is ready, give it a name 
+and choose: **Import an existing site**.
+
+Prepare Your Application
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To deploy your Symfony application on Platform.sh, you simply need to add a 
+``.platform.app.yaml`` at the root of your Git repository which will tell
+Platform.sh how to deploy your application (read more about 
+`Platform.sh configuration files`_).
+
+.. code-block:: yaml
+
+    # .platform.app.yaml
+    
+    # This file describes an application. You can have multiple applications
+    # in the same project.
+
+    # The name of this app. Must be unique within a project.
+    name: myphpproject
+
+    # The toolstack used to build the application.
+    toolstack: "php:symfony"
+
+    # The relationships of the application with services or other applications.
+    # The left-hand side is the name of the relationship as it will be exposed
+    # to the application in the PLATFORM_RELATIONSHIPS variable. The right-hand
+    # side is in the form `<service name>:<endpoint name>`.
+    relationships:
+        database: "mysql:mysql"
+
+    # The configuration of app when it is exposed to the web.
+    web:
+        # The public directory of the app, relative to its root.
+        document_root: "/web"
+        # The front-controller script to send non-static requests to.
+        passthru: "/app.php"
+
+    # The size of the persistent disk of the application (in MB).
+    disk: 2048
+
+    # The mounts that will be performed when the package is deployed.
+    mounts:
+        "/app/cache": "shared:files/cache"
+        "/app/logs": "shared:files/logs"
+
+    # The hooks that will be performed when the package is deployed.
+    hooks:
+        build: |
+          rm web/app_dev.php
+          app/console --env=prod assetic:dump --no-debug
+        deploy: |
+          app/console --env=prod cache:clear
+
+For best practices, you should also add a ``.platform`` folder at the root of
+your Git repository which contains the following files:
+
+.. code-block:: yaml
+
+    # .platform/routes.yaml
+    "http://{default}/":
+        type: upstream
+        upstream: "php:php"
+
+.. code-block:: yaml
+
+    # .platform/services.yaml
+    mysql:
+        type: mysql
+        disk: 2048
+
+An example of these configurations can be found on `GitHub`_. The list of
+`available services <configure-services>`_ can be found on the Platform.sh documentation.
+
+Configure Database Access
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Platform.sh overrides your database specific configuration via importing the
+following file::
+    
+    // app/config/parameters_platform.php
+    <?php
+    $relationships = getenv("PLATFORM_RELATIONSHIPS");
+        if (!$relationships) {
+            return;
+    }
+
+    $relationships = json_decode(base64_decode($relationships), true);
+
+    foreach ($relationships['database'] as $endpoint) {
+        if (empty($endpoint['query']['is_master'])) {
+          continue;
+        }
+
+        $container->setParameter('database_driver', 'pdo_' . $endpoint['scheme']);
+        $container->setParameter('database_host', $endpoint['host']);
+        $container->setParameter('database_port', $endpoint['port']);
+        $container->setParameter('database_name', $endpoint['path']);
+        $container->setParameter('database_user', $endpoint['username']);
+        $container->setParameter('database_password', $endpoint['password']);
+        $container->setParameter('database_path', '');
+    }
+
+    # Store session into /tmp.
+    ini_set('session.save_path', '/tmp/sessions');
+
+Make sure this file is listed in your *imports*:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    imports:
+        - { resource: parameters_platform.php }
+
+Deploy your Application
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Now you need to add a remote to Platform.sh in your Git repository (copy the 
+command that you see on the Platform.sh web UI):
+
+.. code-block:: bash
+
+    $ git remote add platform [PROJECT-ID]@git.[CLUSTER].platform.sh:[PROJECT-ID].git
+
+``PROJECT-ID``
+    Unique identifier of your project. Something like ``kjh43kbobssae``
+``CLUSTER``
+    Server location where your project is deplyed. It can be ``eu`` or ``us``
+
+Commit the Platform.sh specific files created in the previous section:
+
+.. code-block:: bash
+
+    $ git add .platform.app.yaml .platform/* 
+    $ git add app/config/config.yml app/config/parameters_platform.php
+    $ git commit -m "Adding Platform.sh configuration files."
+
+Push your code base to the newly added remote:
+
+.. code-block:: bash
+
+    $ git push platform master
+
+That's it! Your application is being deployed on Platform.sh and you'll soon be
+able to access it in your browser.
+
+Every code change that you do from now on will be pushed to Git in order to 
+redeploy your environment on Platform.sh.
+
+More information about `migrating your database and files <migrate-existing-site>`_ can be found on the 
+Platform.sh documentation.
+
+Deploy a new Site
+-----------------
+
+You can start a new `Platform.sh project`_. Choose the development plan and go 
+through the checkout process.
+
+Once your project is ready, give it a name and choose: **Create a new site**.
+Choose the *Symfony* stack and a starting point such as *Standard*.
+
+That's it! Your Symfony application will be bootstrapped and deployed. You'll 
+soon be able to see it in your browser.
+
+.. _`Platform.sh`: https://platform.sh
+.. _`Platform.sh documentation`: https://docs.platform.sh/toolstacks/symfony/symfony-getting-started
+.. _`Platform.sh project`: https://marketplace.commerceguys.com/platform/buy-now
+.. _`Platform.sh configuration files`: https://docs.platform.sh/reference/configuration-files
+.. _`GitHub`: https://github.com/platformsh/platformsh-examples
+.. _`configure-services`: https://docs.platform.sh/reference/configuration-files/#configure-services
+.. _`migrate-existing-site`: https://docs.platform.sh/toolstacks/symfony/migrate-existing-site/

cookbook/map.rst.inc

@@ -54,6 +54,7 @@
   * :doc:`/cookbook/deployment/tools`
   * :doc:`/cookbook/deployment/azure-website`
   * :doc:`/cookbook/deployment/heroku`
+  * :doc:`/cookbook/deployment/platformsh`
 
 * :doc:`/cookbook/doctrine/index`