From 5a76b536ff6160ed4dafd25b050cd68d0ced5013 Mon Sep 17 00:00:00 2001 From: Maxime Rainville Date: Mon, 29 Apr 2019 14:37:56 +1200 Subject: [PATCH 1/2] DOC Update change log to reference updated migration task --- docs/en/04_Changelogs/4.4.0.md | 73 +++++++++++++++++++--------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/docs/en/04_Changelogs/4.4.0.md b/docs/en/04_Changelogs/4.4.0.md index a2f99ad4a7f..b10220263aa 100644 --- a/docs/en/04_Changelogs/4.4.0.md +++ b/docs/en/04_Changelogs/4.4.0.md @@ -11,6 +11,27 @@ ## Upgrading {#upgrading} +### Adopting to new `_resources` directory + +The name of the directory where vendor module resources are exposed can now be configured by defining a `extra.resources-dir` key in your `composer.json` file. If the key is not set, it will automatically default to `resources`. New projects will be preset to `_resources`. +This will avoid potential conflict with SiteTree URL Segments. + +1. Update your `.gitignore` file to ignore the new `_resources` directory. This file is typically located in the root of your project or in the `public` folder. +2. Add a new `extra.resources-dir` key to your composer file. +```js +{ + // ... + "extra": { + // ... + "resources-dir": "_resources" + } +} +``` +3. Expose your vendor assets by running `composer vendor-expose`. +4. Remove the old `resources` folder. This folder will be located in the `public` folder if you have adopted the public web root, or in the root of your project if you haven't. + +You may also need to update your server configuration if you have applied special conditions to the `resources` path. + ### Optional migration to hash-less public asset URLs {#hashless-urls} SilverStripe 4.x introduced an [asset abstraction](https://docs.silverstripe.org/en/4/developer_guides/files/file_storage/) @@ -34,7 +55,7 @@ The original "hashed" file paths continue to work through redirects. In order to opt-in to moving these files, run the following command: ``` -TODO File migration task command +vendor/bin/sake dev/tasks/MigrateFileTask ``` Note that you can run this task without CLI access by installing and configuring @@ -42,27 +63,6 @@ the [queuedjobs](https://github.com/symbiote/silverstripe-queuedjobs) module. Further information is provided in the [Hash-less Public Asset URLs FAQ](#hashless-faq) below. -### Adopting to new `_resources` directory - -The name of the directory where vendor module resources are exposed can now be configured by defining a `extra.resources-dir` key in your `composer.json` file. If the key is not set, it will automatically default to `resources`. New projects will be preset to `_resources`. -This will avoid potential conflict with SiteTree URL Segments. - -1. Update your `.gitignore` file to ignore the new `_resources` directory. This file is typically located in the root of your project or in the `public` folder. -2. Add a new `extra.resources-dir` key to your composer file. -```js -{ - // ... - "extra": { - // ... - "resources-dir": "_resources" - } -} -``` -3. Expose your vendor assets by running `composer vendor-expose`. -4. Remove the old `resources` folder. This folder will be located in the `public` folder if you have adopted the public web root, or in the root of your project if you haven't. - -You may also need to update your server configuration if you have applied special conditions to the `resources` path. - ### Hash-less Public Asset URLs FAQ {#hashless-faq} #### How are files named and renamed? @@ -73,9 +73,9 @@ Here's an example of how file names changed during an initial 4.x migration, and * File migrated under SS 4.x with `legacy_filenames=false`: `assets/[content-hash]/myfile.pdf` (Regression: links to `assets/myfile.pdf` no longer work) * File migrated under SS 4.x with `legacy_filenames=true`: `assets/myfile.pdf` * File with updated file content under SS 4.x: `assets/[new-content-hash]/myfile.pdf` (Regression: links to `assets/[content-hash]/myfile.pdf` no longer work) - * File with hotfix applied (SS 4.2.3): `assets/[new-content-hash]/myfile.pdf` (redirects to `assets/myfile.pdf`) - * File with full fix applied (SS 4.3.x) : `assets/myfile.pdf` (no redirect required) - * Newly uploaded file with full fix applied: `assets/my-other-file.pdf` (no redirect required) + * File with hotfix applied (SS 4.2.3): `assets/myfile.pdf` and `assets/[old-content-hash]/myfile.pdf` redirects to `assets/[new-content-hash]/myfile.pdf` + * File with full fix applied (SS 4.3.x) : `assets/myfile.pdf` and `assets/[old-content-hash]/myfile.pdf` redirects to `assets/[new-content-hash]/myfile.pdf` + * Newly uploaded file with full fix applied (SS 4.4.0): `assets/my-other-file.pdf` (no redirect required) More details on how files are stored can be found in the ["File Storage" guide](/developer_guides/files/file_storage). @@ -91,7 +91,13 @@ If you have a high traffic site with lots of direct references to asset URLs we recommend that you configure HTTP caching for these redirects in your webserver (e.g. through `.htaccess`). -The redirect code can be configured via `FlysystemAssetStore.redirect_response_code`. +The redirect code can be configured via `FlysystemAssetStore.permanent_redirect_response_code`. + +If you upgrade an older SilverStripe 4 project to SilverStripe 4.4 and choose not to run the file migratation task, +your files will still be stored under an "hash" folder. Browsers who try to access this file via the "hashless" url will +be redirected to the "hash" URL with a `302 Temporary Redirect`. + +The temporary redirect code can be configured via `FlysystemAssetStore.redirect_response_code`. #### Do I need to regenerate HTML with existing links to assets? @@ -120,12 +126,16 @@ this can lead to improved search engine rankings (since existing files under new #### Can I migrate away from the legacy_filenames=true option? -Technically yes, but there’s no official migration script for it. +Yes. Simply disable `legacy_filenames` in your YML configuration, then run the `MigrateFileTask`. This will normalise +the path of all existing assets. #### Can I still choose legacy_filenames=true when starting new upgrades? -Technically yes, but you need to be aware of the tradeoffs. -Once the regression has been fixed, we don’t see the need for people to choose this option any more. +Technically yes, but you need to be aware of the tradeoffs. Once the regression has been fixed, we don’t see the need +for people to choose this option any more. + +SilverStripe 4.4, ignores the `legacy_filenames` in most situation. Enabling `legacy_filenames` on a fresh SilverStripe +4.4 installation will have no affect. #### How do I test that the fix has worked on my site? @@ -133,8 +143,9 @@ Before applying the upgrade and migration script: Find an existing published and draft file. Get the link by clicking on the preview in `admin/assets`. It should link to `assets/[hash]/myfile.pdf`. -After applying the upgrade and migration script, you can test that it applied correctly. -Please perform these tests on a test or UAT environment, since your local environment might have different routing conditions. +After applying the upgrade and migration task, you can test that it applied correctly. +Please perform these tests on a test or UAT environment, since your local environment might have different routing +conditions. * Check that the file still routes correctly with the hash in place (should redirect) * Remove `[hash]/`, and check that it still routes correctly (should not redirect) From 83c2668535a2d2f40a3c35c02b1ba4a09909e8c8 Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Tue, 30 Apr 2019 08:43:47 +1200 Subject: [PATCH 2/2] Update docs/en/04_Changelogs/4.4.0.md --- docs/en/04_Changelogs/4.4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/04_Changelogs/4.4.0.md b/docs/en/04_Changelogs/4.4.0.md index b10220263aa..f7da0568114 100644 --- a/docs/en/04_Changelogs/4.4.0.md +++ b/docs/en/04_Changelogs/4.4.0.md @@ -93,7 +93,7 @@ in your webserver (e.g. through `.htaccess`). The redirect code can be configured via `FlysystemAssetStore.permanent_redirect_response_code`. -If you upgrade an older SilverStripe 4 project to SilverStripe 4.4 and choose not to run the file migratation task, +If you upgrade an older SilverStripe 4 project to SilverStripe 4.4 and choose not to run the file migration task, your files will still be stored under an "hash" folder. Browsers who try to access this file via the "hashless" url will be redirected to the "hash" URL with a `302 Temporary Redirect`.