# Get started

[Symfony](https://symfony.com/) is a PHP framework that you can use to create web applications.
Upsun Fixed is the official Symfony Cloud Application Platform.

This guide provides instructions for deploying, and working with, Symfony on Upsun Fixed.

## Before you begin

You need:

- [Git](https://git-scm.com/downloads).
  Git is the primary tool to manage everything your app needs to run.
  Push commits to deploy changes and control configuration through YAML files.
  These files describe your infrastructure, making it transparent and version-controlled.
- A Upsun Fixed account.
  If you don't already have one, [register for a trial account](https://auth.upsun.com/register).
  You can sign up with an email address or an existing GitHub, Bitbucket, or Google account.
  If you choose one of these accounts, you can set a password for your Upsun Fixed account later.
- The [Symfony CLI](https://symfony.com/download).
  This lets you interact with your project from the command line.
  You can also do most things through the [Web Console](https://fixed.docs.upsun.com/administration/web.md).

**Note**: 

The Symfony CLI wraps the [Upsun Fixed CLI](https://fixed.docs.upsun.com/administration/cli.md) with added features related to Symfony.
So when using Symfony, you can replace ``platform <command>`` by ``symfony cloud:<command>`` in all of your commands.

## Create your Symfony app

To get familiar with Upsun Fixed, create a new Symfony project from scratch.
The present tutorial uses the [Symfony Demo](https://symfony.com/doc/current/setup.md#the-symfony-demo-application) app as an example :

```bash
symfony new <PROJECT_NAME> --demo --cloud
cd <PROJECT_NAME>
```

The `--demo` flag pulls the [Symfony Demo skeleton](https://github.com/symfony/demo). 
The `--cloud` flag automatically generates the Upsun Fixed configuration files.

**Note**: 

Alternatively, you can deploy an **existing Symfony project**.
To do so, follow these steps:

 - To generate a sensible default Upsun Fixed configuration,
run the following command from within the project’s directory:

```bash {}
symfony project:init
```

This generates the following set of configuration files: ``.platform.app.yaml``, ``.platform/services.yaml``, ``.platform/routes.yaml``, and ``php.ini``.

 - Commit these new files to your repository:

```bash {}
git add .platform.app.yaml .platform/services.yaml .platform/routes.yaml php.ini
git commit -m "Add Upsun Fixed configuration"
```

Upsun Fixed manages the entire infrastructure of your project,
from code to services (such as databases, queues, or search engines),
all the way to email sending, [cron jobs](https://fixed.docs.upsun.com/guides/symfony/crons.md), and [workers](https://fixed.docs.upsun.com/guides/symfony/workers.md).
This infrastructure is described through configuration files stored alongside your code.

## Create the project

To create the project on Upsun Fixed, run the following command from within the project's directory:

```bash
symfony cloud:create --title PROJECT_TITLE --set-remote
```

The `--set-remote` flag sets the new project as the remote for this repository.

**Tip**: 

You can link any repository to an existing Upsun Fixed project using the following command:

```bash {}
symfony project:set-remote <PROJECT_ID>
```

## Deploy your project

To deploy your project, run the following command:

```bash
symfony cloud:push
```

**Tip**: 

During deployment, the logs from the Upsun Fixed API are displayed in your terminal so you can monitor progress.
To stop the display of the logs **without interrupting the deployment**,
use ``CTRL+C`` in your terminal.
To go back to displaying the logs, run ``symfony cloud:activity:log``.

Congratulations, your first Symfony app has been deployed on Upsun Fixed!

Now that your app is deployed in production mode,
you can define a custom domain for your live website.
To do so, see how to [set up a custom domain on Upsun Fixed](https://fixed.docs.upsun.com/administration/web/configure-project.md#domains),
or run the following command:

```bash
symfony cloud:domain:add <YOUR_DOMAIN>
```

## Make changes to your project

Now that your project is deployed, you can start making changes to it.
For example, you might want to fix a bug or add a new feature.

In your project, the main branch always represents the production environment.
Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   ```bash
   symfony cloud:branch feat-a
   ```

   This command creates a new local `feat-a` Git branch based on the main Git branch
   and activates a related environment on Upsun Fixed.
   The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.

   For example, if you created a Symfony Demo app,
   edit the `templates/default/homepage.html.twig` template and make the following visual changes:

   ```diff {location="templates/default/homepage.html.twig",}
   {% block body %}

   -        {{ 'title.homepage'|trans|raw }}
   +        Welcome to the Upsun Fixed Demo

   ```

3. Commit your changes:

   ```bash
   git commit -a -m "Update text"
   ```

4. Deploy your changes to the `feat-a` environment:

   ```bash
   symfony cloud:push
   ```

   Note that each environment has its own domain name.
   To view the domain name of your new environment, run the following command:

   ```bash
   symfony cloud:url --primary
   ```

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

   ```bash
   git checkout main
   git merge feat-a
   symfony environment:delete feat-a
   git branch -d feat-a
   symfony cloud:push
   ```

   **Note**: 

Deploying to production was fast because the image built for the ``feat-a`` environment was reused.

   For a long running branch, to keep the code up-to-date with the main branch, use `git merge main` or `git rebase main`.
   You can also keep the data in sync with the production environment by using `symfony cloud:env:sync`.

## Use a third-party Git provider

When you choose to use a third-party Git hosting service, the Upsun Fixed Git
repository becomes a read-only mirror of the third-party repository. All your
changes take place in the third-party repository.

Add an integration to your existing third-party repository:

- [BitBucket](https://fixed.docs.upsun.com/integrations/source/bitbucket.md)
- [GitHub](https://fixed.docs.upsun.com/integrations/source/github.md)
- [GitLab](https://fixed.docs.upsun.com/integrations/source/gitlab.md)

## Next steps

### Symfony integration

Learn more about the [Symfony integration](https://fixed.docs.upsun.com/guides/symfony/integration.md),
a set of tools and auto-configurations that makes it easier to use Upsun Fixed for Symfony projects.

### Environment variables

When you use the Symfony integration,
more [environment variables](https://fixed.docs.upsun.com/guides/symfony/environment-variables.md) related to Symfony are defined.

### Local development

Once Symfony has been deployed on Upsun Fixed,
you might want to [set up a local development environment](https://fixed.docs.upsun.com/guides/symfony/local.md).

### Symfony CLI tips

You might find the following commands useful when using the Symfony CLI.

-   Open the web administration console:

    ```bash
    symfony cloud: web
    ```

-   Open the URL of the current environment:

    ```bash
    symfony cloud: url
    ```

-   Open an SSH connection to your environment:

    ```bash
    symfony cloud: ssh
    ```

-   Initialize a new project using templates:

    ```bash
    symfony project:init
    ```

-   Get a list of all the domains:

    ```bash
    symfony cloud:domains
    ```

-   Create a new environment:

    ```bash
    symfony cloud:branch new-branch
    ```

-   Get a list of all the environments:

    ```bash
    symfony cloud:environments
    ```

-   Push code to the current environment:

    ```bash
    symfony cloud:push
    ```

-   Get a list of all the active projects:

    ```bash
    symfony cloud:projects
    ```

-   Add a user to the project:

    ```bash
    symfony cloud:user:add
    ```

-   List variables:

    ```bash
    symfony cloud:variables
    ```

You might find the following commands useful when using a database with your Symfony app.

-   Create a local dump of the remote database:

    ```bash
    symfony cloud: db:dump --relationship database
    ```

-   Run an SQL query on the remote database:

    ```bash
    symfony cloud: sql 'SHOW TABLES'
    ```

-   Import a local SQL file into a remote database:

    ```bash
    symfony cloud: sql < my_database_backup.sql
    ```