diff --git a/docs/en/04_Changelogs/4.4.0.md b/docs/en/04_Changelogs/4.4.0.md index a2f99ad4a7f..f7da0568114 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 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`. + +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)