Getting Started
Edit this pageGetting 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:
1 2
$ 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:
1
$ 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:
1 2
$ 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):
1
$ symfony project:create --title=demo --plan=development
Deploying a Project
Finally, deploy the project to the cloud:
1
$ 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:
1
$ 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:
1 2
$ 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:
1 2 3 4 5 6 7 8
# 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:
1 2
$ 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:
1
$ symfony deploy
Browse the new version and notice that the domain name is different now (each environment has its own domain name):
1
$ 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:
1 2 3 4 5
$ 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
.