getting-started.rst

Getting Started

Installing the Symfony CLI Tool

To manage your Symfony projects with Platform.sh, you will need:

• Git and SSH;
• The symfony CLI tool (go to the Download page for instructions on how to install it on your local machine);
• A Platform.sh account.

To get started with the Symfony CLI tool, run symfony to get some common commands or symfony help to list all available commands.

Tip

Even if you can use the Platform.sh CLI tool, we highly recommend you to use the Symfony CLI tool as it provides a tighter integration with Symfony via specific commands. When using a command from the official Platform.sh documentation, replace platform with symfony.

Note

On Windows, you may have to use Git Bash instead of Powershell to run the CLI commands due to compatibility reasons.

Deploying a Project on Platform.sh

There are three steps needed to deploy a project on Platform.sh:

• Configure the project by describing its infrastructure;
• Create the project on Platform.sh;
• Deploy the project.

Configuring Platform.sh for a Project

If you want to play with Platform.sh with a simple sample project, create a Symfony Demo project:

$ symfony new --demo --cloud /path/to/demo
$ cd /path/to/demo

Platform.sh manages the entire infrastructure of your project, from code to services (databases, queues, search, ...), from email sending to crons and workers. This infrastructure is described through configuration files, stored along side your code. The --cloud flag automatically generates the Platform.sh configuration files.

If you want to deploy an existing project, generate a sensible default Platform.sh configuration from within the project's directory:

$ symfony project:init

The command generates a default set of configuration files: .platform.app.yaml, .platform/services.yaml, .platform/routes.yaml, and php.ini.

Don't forget to commit the new files in your repository:

$ git add .platform.app.yaml .platform/services.yaml .platform/routes.yaml php.ini
$ git commit -m "Add Platform.sh configuration"

If you have a closer look at .platform.app.yaml for a Symfony project, you will notice the calls to symfony-build and symfony-deploy scripts during the build and deploy hooks respectively. These scripts register some environment variables depending on the services you require (names match the one expected by Symfony recipes). They also build the application cache and run the database migrations if any. They should cover most use cases for Symfony applications.

Creating a Project in the Cloud

Then, create a new Platform.sh project (you will need to create a Platform.sh account):

$ symfony project:create --title=demo --plan=development

Deploying a Project

Finally, deploy the project to the cloud:

$ symfony deploy

Note

If you have private dependencies, you might need to authorize Platform.sh to let Platform.sh access them during project build.

Check that everything went fine by opening the deployed URL:

$ symfony cloud:url --primary

Working on a Project

Now that the project is deployed, let's describe a typical scenario where you want to fix a bug or add a new feature.

First, you need to know that the main branch always represents the production environment. Any other branch is for developing new features, fixing bugs, or updating the infrastructure.

Let's create a new environment (a Git branch) to make some changes, without impacting production:

$ git checkout main
$ symfony env:branch feat-a

This command creates a new local feat-a branch based on the main branch and activate a related environment on Platform.sh. If you have some services enabled, the new environment inherits the data of the parent environment (the production one here).

Let's make some simple visual changes. If you have created a Symfony demo application, edit the templates/default/homepage.html.twig template and make the following change:

# templates/default/homepage.html.twig
{% block body %}
    <div class="page-header">
-        <h1>{{ 'title.homepage'|trans|raw }}</h1>
+        <h1>Welcome to the Platform.sh Demo</h1>
    </div>

    <div class="row">

Tip

If you want to check that the change is correct on your local machine, run symfony server:start -d and symfony open:local to test it in your local browser.

Commit the change:

$ git commit -a -m "Update text"
# in a real-life scenario, you would also push the change to the upstream Git repository

And deploy the change to the feat-a environment:

$ symfony deploy

Browse the new version and notice that the domain name is different now (each environment has its own domain name):

$ symfony cloud:url --primary

Iterate by changing the code, committing, and deploying. When satisfied with the changes, merge it to main, deploy, and remove the feature branch:

$ git checkout main
$ git merge feat-a
$ symfony env:delete feat-a
$ git branch -d feat-a
$ symfony deploy

Note

Note that deploying production was fast as it reused the image built for the feat-a environment.

Tip

For a long running branch, you can keep the code up-to-date with main via git merge main or git rebase main. And you can also keep the data in sync with the production environment via symfony env:sync.