Doctrine migations configuration + initial migrations

composer.json

@@ -36,6 +36,7 @@
         "symfony/serializer": "^5.4 || ^6.2",
         "symfony/translation": "^5.4 || ^6.2",
         "doctrine/doctrine-bundle": "^2.4",
+        "doctrine/doctrine-migrations-bundle": "^3.2",
         "doctrine/orm": "^2.10"
     },
     "require-dev": {
@@ -54,7 +55,8 @@
     "autoload": {
         "psr-4": {
             "Netgen\\RemoteMedia\\": "lib/",
-            "Netgen\\Bundle\\RemoteMediaBundle\\": "bundle/"
+            "Netgen\\Bundle\\RemoteMediaBundle\\": "bundle/",
+            "Netgen\\RemoteMedia\\Migrations\\": "migrations/"
         }
     },
     "autoload-dev": {

docs/CHANGELOG.md

@@ -8,7 +8,7 @@
 * `netgen/open-graph-bundle` is no longer supported and the Open Graph handler is removed
 * requires PHP 8.1+, Symfony 5.4 or 6.2+ (Symfony 7 is excluded by the Composer constraints), `doctrine/orm` 2.10+, `doctrine/doctrine-bundle` 2.4+ and `cloudinary/cloudinary_php` 2.9+ (Cloudinary SDK v1 is no longer supported)
 * Composer package type is now `symfony-bundle` (was `ezplatform-bundle`) and all non-bundle code lives in the new `Netgen\RemoteMedia\` namespace (`lib/`)
-* the `ngremotemedia_field_link` table and the `RemoteMediaFieldLink` entity are removed, resources are stored in the new `ngrm_remote_resource` and `ngrm_remote_resource_location` tables (Doctrine XML mappings), no Doctrine migrations are shipped and v2 data is not migrated automatically
+* the `ngremotemedia_field_link` table and the `RemoteMediaFieldLink` entity are removed, resources are stored in the new `ngrm_remote_resource` and `ngrm_remote_resource_location` tables (Doctrine XML mappings) created by the shipped Doctrine migration `Version030000`, v2 data is not migrated automatically
 * `Netgen\Bundle\RemoteMediaBundle\Core\FieldType\RemoteMedia\Value` is replaced by `Netgen\RemoteMedia\API\Values\RemoteResource` (identified by `remoteId`) and `RemoteResourceLocation` (crop settings, watermark text, source), `Variation` is replaced by `RemoteResourceVariation`
 * `Provider\Cloudinary\Search\Query` and `Result` are replaced by `Netgen\RemoteMedia\API\Search\Query` and `Result` (`getResults()` is now `getResources()` and returns `RemoteResource` objects)
 * `RemoteMediaProvider` is replaced by `Netgen\RemoteMedia\API\ProviderInterface` (service `netgen_remote_media.provider`), its methods take `RemoteResource` / `RemoteResourceLocation` objects
@@ -25,6 +25,8 @@
 ### Added
 
 * `cloudinary.folder_mode` option (`dynamic` / `fixed`) with support for both Cloudinary folder modes
+* Doctrine migration `Version030000` which creates the `ngrm_remote_resource` and `ngrm_remote_resource_location` tables, with its own configuration `migrations/doctrine.yaml` and version table `ngrm_migration_versions`, see [installation instructions](INSTALL.md#database)
+* `doctrine/doctrine-migrations-bundle` is now required
 * `cloudinary.use_asset_folder_as_public_id_prefix` option which prefixes the public ID with the asset folder in `dynamic` folder mode, so the same file can be uploaded to different folders
 * `cloudinary.append_extension`, `cloudinary.unique_filenames`, `cloudinary.cache_requests`, `cloudinary.log_requests` and `cloudinary.encryption_key` options
 * `named_objects` configuration with `ngrm_named_remote_resource` and `ngrm_named_remote_resource_location` Twig functions

docs/INSTALL.md

@@ -176,6 +176,26 @@ netgen_remote_media:
     resource: "@NetgenRemoteMediaBundle/Resources/config/routing.yml"
 ```
 
+## Database
+
+The bundle ships a Doctrine migration which creates its database tables. It requires MySQL or MariaDB:
+
+```
+php bin/console doctrine:migrations:migrate --configuration=vendor/netgen/remote-media-bundle/migrations/doctrine.yaml
+```
+
+Run this command after every update of the bundle, for example as part of your deployment, so new migrations are applied. You can also run it automatically by adding it to the Composer `post-update-cmd` (and/or `post-install-cmd`) scripts in your `composer.json`:
+
+```json
+{
+    "scripts": {
+        "post-update-cmd": [
+            "@php bin/console doctrine:migrations:migrate --no-interaction --configuration=vendor/netgen/remote-media-bundle/migrations/doctrine.yaml"
+        ]
+    }
+}
+```
+
 ## Configure Cloudinary webhook notifications (optional)
 
 If you want to be able to manage resources through Cloudinary interface as well, you might want to configure the [Cloudinary webhook notifications](Cloudinary/WEBHOOK_NOTIFICATIONS.md). Read more on the link.

docs/UPGRADE.md

@@ -8,7 +8,7 @@ Version 3.0 is a major release. The bundle is decoupled from eZ / Ibexa and cont
 
 ### Upgrade `composer.json`
 
-* Require `netgen/remote-media-bundle` `^3.0` and run `composer update`.
+* Require `netgen/remote-media-bundle` `^3.0` and run `composer update`. The bundle now requires `doctrine/doctrine-migrations-bundle`.
 * If you use Ibexa CMS, also require [netgen/remote-media-ibexa](https://github.com/netgen/remote-media-ibexa), which provides the field type, the admin UI integration and the rich text integration that were removed from this bundle.
 * PHP 8.1+, Symfony 5.4 or 6.2+ (Symfony 7 is not supported), `doctrine/orm` 2.10+, `doctrine/doctrine-bundle` 2.4+ and `cloudinary/cloudinary_php` 2.9+ are required.
 * `netgen/open-graph-bundle` is no longer supported and the Open Graph handler is removed.
@@ -18,7 +18,19 @@ Version 3.0 is a major release. The bundle is decoupled from eZ / Ibexa and cont
 
 * The `ngremotemedia_field_link` table is no longer used.
 * The bundle maps two new entities to the `ngrm_remote_resource` and `ngrm_remote_resource_location` tables with Doctrine XML mappings.
-* This bundle does not ship Doctrine migrations, create the tables with the schema tooling of your project (for example a migration generated with `doctrine:migrations:diff`).
+* The tables are created by the Doctrine migration shipped with the bundle (own configuration `migrations/doctrine.yaml`, version table `ngrm_migration_versions`). Run it with:
+
+    ```
+    php bin/console doctrine:migrations:migrate --configuration=vendor/netgen/remote-media-bundle/migrations/doctrine.yaml
+    ```
+
+* If the tables already exist (for example, created with `doctrine:schema:update` on an untagged 3.0), the migration fails. Create the version table, mark the migration as executed and run the migrations again:
+
+    ```
+    php bin/console doctrine:migrations:sync-metadata-storage --configuration=vendor/netgen/remote-media-bundle/migrations/doctrine.yaml
+    php bin/console doctrine:migrations:version 'Netgen\RemoteMedia\Migrations\Doctrine\Version030000' --add --configuration=vendor/netgen/remote-media-bundle/migrations/doctrine.yaml
+    php bin/console doctrine:migrations:migrate --configuration=vendor/netgen/remote-media-bundle/migrations/doctrine.yaml
+    ```
 * Data migration from the v2 data to the new tables is not part of this bundle yet, v2 data is not migrated automatically.
 
 ### Configuration

migrations/Doctrine/Version030000.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Netgen\RemoteMedia\Migrations\Doctrine;
+
+use Doctrine\DBAL\Schema\Schema;
+use Doctrine\Migrations\AbstractMigration;
+
+final class Version030000 extends AbstractMigration
+{
+    public function up(Schema $schema): void
+    {
+        $this->abortIf($this->connection->getDatabasePlatform()->getName() !== 'mysql', 'Migration can only be executed safely on MySQL.');
+
+        $this->addSql(
+            <<<'EOT'
+            CREATE TABLE ngrm_remote_resource (
+              id int NOT NULL AUTO_INCREMENT,
+              remote_id varchar(255) NOT NULL,
+              type varchar(100) NOT NULL,
+              url varchar(255) NOT NULL,
+              name varchar(255) NOT NULL,
+              original_filename varchar(255) NOT NULL,
+              md5 varchar(64) NOT NULL,
+              version varchar(100) DEFAULT NULL,
+              folder longtext COMMENT '(DC2Type:object)',
+              visibility varchar(100) NOT NULL,
+              size int NOT NULL,
+              alt_text text,
+              caption text,
+              tags longtext COMMENT '(DC2Type:array)',
+              metadata longtext COMMENT '(DC2Type:array)',
+              context longtext COMMENT '(DC2Type:array)',
+              created_at datetime NOT NULL COMMENT '(DC2Type:datetime_immutable)',
+              updated_at datetime NOT NULL COMMENT '(DC2Type:datetime_immutable)',
+              PRIMARY KEY (id),
+              UNIQUE KEY UNIQ_4B1F1DB42A3E9C94 (remote_id)
+            ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE utf8mb4_unicode_ci
+            EOT
+        );
+
+        $this->addSql(
+            <<<'EOT'
+            CREATE TABLE ngrm_remote_resource_location (
+              id int NOT NULL AUTO_INCREMENT,
+              remote_resource_id int DEFAULT NULL,
+              source varchar(255) DEFAULT NULL,
+              crop_settings longtext NOT NULL COMMENT '(DC2Type:array)',
+              watermark_text text,
+              created_at datetime NOT NULL COMMENT '(DC2Type:datetime_immutable)',
+              updated_at datetime NOT NULL COMMENT '(DC2Type:datetime_immutable)',
+              PRIMARY KEY (id),
+              KEY IDX_76616F4846147E03 (remote_resource_id),
+              CONSTRAINT FK_76616F4846147E03 FOREIGN KEY (remote_resource_id)
+                REFERENCES ngrm_remote_resource (id) ON DELETE CASCADE
+            ) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE utf8mb4_unicode_ci
+            EOT
+        );
+    }
+
+    public function down(Schema $schema): void
+    {
+        $this->abortIf($this->connection->getDatabasePlatform()->getName() !== 'mysql', 'Migration can only be executed safely on MySQL.');
+
+        $this->addSql('DROP TABLE ngrm_remote_resource_location');
+        $this->addSql('DROP TABLE ngrm_remote_resource');
+    }
+}

migrations/doctrine.yaml

@@ -0,0 +1,7 @@
+migrations_paths:
+    Netgen\RemoteMedia\Migrations\Doctrine: Doctrine
+
+table_storage:
+    table_name: ngrm_migration_versions
+
+transactional: false