From c8925c93a0b3239ce0bf3248fdf6c44e1c5a4900 Mon Sep 17 00:00:00 2001 From: Damian Mooyman Date: Mon, 2 Oct 2017 15:07:47 +1300 Subject: [PATCH] Update documentation for file migration --- .../14_Files/04_File_Migration.md | 57 +++++++++++++++++++ docs/en/04_Changelogs/4.0.0.md | 24 ++------ 2 files changed, 63 insertions(+), 18 deletions(-) create mode 100644 docs/en/02_Developer_Guides/14_Files/04_File_Migration.md diff --git a/docs/en/02_Developer_Guides/14_Files/04_File_Migration.md b/docs/en/02_Developer_Guides/14_Files/04_File_Migration.md new file mode 100644 index 000000000..e0cf8cd9a --- /dev/null +++ b/docs/en/02_Developer_Guides/14_Files/04_File_Migration.md @@ -0,0 +1,57 @@ +summary: Manage migration of legacy files to the new database structure + +# File migration + +Since the structure of `File` dataobjects has changed between 3.0 and 4.0, a new task `MigrateFileTask` +has been added to assist in migration of legacy files. + +You can run this task on the command line: + +``` +$ ./framework/sake dev/tasks/MigrateFileTask +``` + +This task will also support migration of existing File DataObjects to file versioning. Any +pre-existing File DataObjects will be automatically published to the live stage, to ensure +that previously visible assets remain visible to the public site. + +If additional security or visibility rules should be applied to File dataobjects, then +make sure to correctly extend `canView` via extensions. + +## Automatic migration + +Migration can be invoked by either this task, or can be configured to automatically run during dev build +by setting the `File.migrate_legacy_file` config to true. However, it's recommended that this task is +run manually during an explicit migration process, as this process could potentially consume large +amounts of memory and run for an extended time. + +```yml +SilverStripe\Assets\File: + migrate_legacy_file: true +``` + +## Migration of thumbnails + +If you have the [asset admin](https://github.com/silverstripe/silverstripe-asset-admin) module installed +this will also ensure that thumbnails for these images are generated when running 'MigrateFileTask'. +Existing thumbnails will not be migrated however, and must be re-generated for use in the CMS. + +Note: Thumbnails can be regenerated on a one-by-one basis within the CMS by re-saving it +within the file edit details form. + +## Discarded files during migration + +Note that any File dataobject which is not in the `File.allowed_extensions` config will be deleted +from the database during migration. Any invalid file on the filesystem will not be deleted, +but will no longer be attached to a dataobject anymore, and should be cleaned up manually. + +To disable this, set the following config: + +```yaml +SilverStripe\Assets\FileMigrationHelper: + delete_invalid_files: false +``` + +Note that pre-existing security solutions for 3.x (such as +[secure assets module](https://github.com/silverstripe/silverstripe-secureassets)) +are incompatible with core file security. diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index 487621855..0c5859b90 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -829,24 +829,16 @@ guide for configuration instruction. #### Migrating File DataObject from 3.x to 4.0 -Since the structure of `File` dataobjects has changed, a new task `MigrateFileTask` has been added to assist -in migration of legacy files. Migration can be invoked by either this task, or can be configured to automatically -run during dev build by setting the `File.migrate_legacy_file` config to true. However, it's recommended that -this task is run manually during an explicit migration process, as this process could potentially consume -large amounts of memory and run for an extended time. +Since the structure of `File` dataobjects has changed between 3.0 and 4.0, a new task `MigrateFileTask` +has been added to assist in migration of legacy files. +You can run this task on the command line: -```yml -SilverStripe\Assets\File: - migrate_legacy_file: true +``` +$ ./framework/sake dev/tasks/MigrateFileTask ``` -This task will also support migration of existing File DataObjects to file versioning. Any -pre-existing File DataObjects will be automatically published to the live stage, to ensure -that previously visible assets remain visible to the public site. - -If additional security or visibility rules should be applied to File dataobjects, then -make sure to correctly extend `canView` via extensions. +For more information on this task please consult the [file migration documentation](/developer_guides/files/file_migration). Note that any File dataobject which is not in the `File.allowed_extensions` config will be deleted from the database during migration. Any invalid file on the filesystem will not be deleted, @@ -859,10 +851,6 @@ SilverStripe\Assets\FileMigrationHelper: delete_invalid_files: false ``` -Note that pre-existing security solutions for 3.x (such as -[secure assets module](https://github.com/silverstripe/silverstripe-secureassets)) -are incompatible with core file security. - #### Upgrade code which acts on `Image` As all image-specific manipulations has been refactored from `Image` into an `ImageManipulations` trait, which