# Doctrine Migrations in Our PHP Project

Doctrine Migrations offer a structured approach to apply database schema changes programmatically. In our PHP project, migrations mainly interact with two types of databases: multiple `licence_X` databases and a `media_manager` configuration database.

## 1. Migrations for `licence_X` Databases

Each licence, denoted as `licence_X` (where X is an identifier), has its own dedicated database. While this might seem intricate, migrations simplify and manage schema changes effectively.

### Overview

Most migrations within the `licence_X` context are applicative. These migrations typically introduce changes to support new project features or modifications. A unique aspect of this setup is that every migration file is applied across all `licence_X` databases.

### Working with Licence_X Migrations
#### Creating Migrations

- Use the `make migration_licence_generate` command to create a new migration file for the respective `licence_X` database.
- Modify the newly generated migration file within `./Migrations/Licence` with the necessary SQL changes.
- Test the migration on a development `licence_X` database to ensure its correctness.

#### Applying Migrations

- Execute the `make migration` command to apply migrations across all `licence_X` and `media_manager` databases.
- Always backup your databases before initiating migrations.

#### Rollback 'one' Migration on every licence_X
You can execute the following command as many times as needed, you might want to run `make migration_licence_delete` in case there is ghost migration peding

- Run the `make migration_licence_prev` command for the `licence_X` database.

#### Deleting Migration on every licence_X
Sometimes you have ghost registered migration due to developing environment. It is boring to delete migration on every licence existing so we made a command for that! You can execute the following command as many times as needed:

- Run the `make migration_licence_delete VERSION=Version20231128092552` command for the `licence_X` database.

#### Running 'one' Migration
Sometimes you want to run a specific migration on every license existing after some changes like adding a new index.  
We made a command for that ;)  
You can execute the following command as many times as needed:

- Run the `make migration_licence_up` command for the `licence_X` database by specifying your migration file.

Example:

```bash
make migration_licence_up VERSION=Version123456789
```

#### Reverting 'one' Migration
Sometimes you want to revert a specific migration on every license existing after some changes like adding a new index.  
We made a command for that ;)  
You can execute the following command as many times as needed:

- Run the `make migration_licence_down` command for the `licence_X` database by specifying your migration file.

Example:

```bash
make migration_licence_down VERSION=Version123456789
```

## 2. Migrations for `media_manager` Database

The `media_manager` database functions as a configuration repository where licences are listed.

### Overview

Most translation (trads) migrations belong to this category. Besides translations, other migrations are applicative and contribute to the project's evolution.

### Working with MediaManager Migrations
#### Creating Migrations

- Use the `make migration_media_manager_generate` command, targeting the `media_manager` database.
- Modify the newly generated migration file within `./Migrations/MediaManager` with the necessary SQL changes. 
- Test on a development version of the `media_manager` database.

#### Applying Migrations

- Execute the `make migration` command to apply migrations across all `media_manager` and `licence_X` databases.
- As with `licence_X` migrations, always ensure database backups before running migrations.

#### Rollback 'one' Migration
You can execute the following command as many times as needed:

- Run the `make migration_media_manager_prev` command for the `media_manager` database.

#### Running 'one' Migration
Sometimes you want to run a specific migration on media_manager database after some changes like adding a new 
translation or editing a translation.  
We made a command for that ;)  
You can execute the following command as many times as needed:

- Run the `make migration_media_manager_up` command for the `media_manager` database by specifying your migration file.

Example:

```bash
make migration_media_manager_up VERSION=Version123456789
```

#### Reverting 'one' Migration
Sometimes you want to revert a specific migration on media_manager database after some changes like adding a new
translation or editing a translation.  
We made a command for that ;)  
You can execute the following command as many times as needed:

- Run the `make migration_media_manager_down` command for the `media_manager` database by specifying your migration file.

Example:

```bash
make migration_media_manager_down VERSION=Version123456789
```

---
## Structure
- **General Configuration**: `./Migrations/config` (This configuration typically doesn't need modifications.)
- **Licence Migrations**: `./Migrations/Licence` (This is where `licence_X` migrations are stored.)
- **Media Manager Migrations**: `./Migrations/MediaManager` (This is where `media_manager` migrations are stored.)


### Doc
Doctrine migration column options: https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/schema-representation.html#column

The working environment for migrations looks like :
```bash
.
├── config
│   ├── migrationLicence.php
│   ├── migrationsDbLicence.php
│   ├── migrationsDbMediaManager.php
│   ├── migrationsLicence.json
│   └── migrationsMediaManager.json
├── Licence
│   ├── Version20210420080425.php
│   ├── Version20210420085447.php
│   └── Version20210421090805.php
├── MediaManager
│   ├── Version20210419122949.php
│   ├── Version20210419145336.php
│   ├── Version20210419152236.php
│   └── Version20210421085732.php
└── old
    └── 202008131440_container_commentaire.sql

```


---
## Translations
We translate every system translation through migration in French(default) and English. For that we have a template of translation migration. 
You just want to generate a new migration and then copy/paste the template from previous translation migration. 
```php
    /**
     * @return string[][]
     */
    private function getNewTradsToInsert(): array
    {
        return [
            [
                'langtxt_var_name' => 'THIS_IS_THE_KEY_YOU_TAKE_FROM_VIEW',
                'langtxt_1' => 'Ca c\'est la valeur en français par défault qui est la même quand la vue',
                'langtxt_2' => 'Finally you put here the english version',
            ],
        ];
    }
```
---

## [Make](https://makefiletutorial.com/)  Commands for Migrations

Our PHP project simplifies Doctrine migrations using a Makefile. Developers can use Make commands instead of direct Doctrine commands, offering a more intuitive experience.

- `make migration`: A general migration command.
- `make migration_licence_generate`: Generates a migration file for a specific `licence_X` database.
- `make migration_licence_delete`: Removes a migration from a `licence_X` database.
- `make migration_licence_prev`: Implements the previous migration to a `licence_X` database.
- `make migration_licence_up`: Runs the up() function of your migration file to a `licence_X` database.
- `make migration_licence_down`: Runs the down() function of your migration file to a `licence_X` database.
- `make migration_media_manager_generate`: Creates a migration file for the `media_manager` database.
- `make migration_media_manager_prev`: Applies the previous migration to the `media_manager` database.

## Conclusion

While managing migrations for our PHP project with multiple `licence_X` databases and a `media_manager` configuration database might seem challenging, Doctrine Migrations and our Make commands ensure a smooth and consistent application of schema changes. Always test migrations in a development setting and backup databases before deploying migrations in a production environment.

---