diff --git a/docs/en/04_Changelogs/4.4.0.md b/docs/en/04_Changelogs/4.4.0.md index 030e4e5b4df..f7da0568114 100644 --- a/docs/en/04_Changelogs/4.4.0.md +++ b/docs/en/04_Changelogs/4.4.0.md @@ -13,6 +13,9 @@ ### 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 @@ -29,6 +32,130 @@ 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/) +system which required a [file migration](https://docs.silverstripe.org/en/4/developer_guides/files/file_migration/) task. +It allowed files to be access protected, have a separate draft stage, +and track changes to file metadata and their contents through the `Versioned` system. + +This change defaulted to adding a content "hash" to file paths, +unless the migration was performed with `legacy_filenames=true`. +The hash would be updated when file contents change, and any link generated +through SilverStripe (e.g. through `HTMLText` or `$Image` template placeholders) +would automatically adjust. However, any direct links from search engines, bookmarks, etc would break. +This limitation was pointed out in the [upgrading advice](4.0.0#asset-storage) to developers, +but the impact wasn’t sufficiently highlighted. + +SilverStripe 4.3.2 introduced a redirect to fix those broken links. +Dynamic redirects are more resource intensive than serving static files. +With SilverStripe 4.4.0, we're providing an optional migration script +to move public files into their "hash-less" locations, removing the need for most redirects. +The original "hashed" file paths continue to work through redirects. +In order to opt-in to moving these files, run the following command: + +``` +vendor/bin/sake dev/tasks/MigrateFileTask +``` + +Note that you can run this task without CLI access by installing and configuring +the [queuedjobs](https://github.com/symbiote/silverstripe-queuedjobs) module. + +Further information is provided in the [Hash-less Public Asset URLs FAQ](#hashless-faq) below. + +### Hash-less Public Asset URLs FAQ {#hashless-faq} + +#### How are files named and renamed? + +Here's an example of how file names changed during an initial 4.x migration, and when upgrading to 4.4: + + * Original file created under SS 3.x: assets/myfile.pdf + * 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/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). + +#### How are redirects handled? + +Redirects from (now legacy) hashed public URLs default to `301 Permanent Redirect`. +By opting into the [file migration to hash-less public URLs](#hashless-urls), +you can minimise these redirects. SilverStripe will automatically generate hash-less public URLs regardless, +but external links might still point to legacy hashed public URLs. +If you have a high traffic site with lots of direct references to asset URLs +(e.g. search engines indexing popular PDF documents), +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.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? + +Pages and other views can contain links to asset locations, +e.g. as HTML content rendered with `` and `` tags. +These might point to old locations of files (prior to running the optional migration). +While SilverStripe will automatically fix these references the next time the view is rendered, +this content is often cached (e.g. in a CDN). + +We have implemented an automatic redirect for URLs pointing to asset +locations prior to running the optional migration script, +so there is no need to regenerate any content. + +#### Is there any data loss or data integrity issue? + +There are no known issues around data integrity. +All files that were available on a SS 3.x site are still available after upgrading to SS 4.x. + +#### Will this change affect my search engine ranking? + +As long as your files are still linked on your website, +search engines will pick up the new links on any projects which have already been migrated. +The 4.3.2 bugfix will redirect links, which passes on any SEO rankings to the new link location. +Since links to files should be permanent after the bugfix has been applied, +this can lead to improved search engine rankings (since existing files under new links don’t need to be re-ranked by search engines). + +#### Can I migrate away from the legacy_filenames=true option? + +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. + +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? + +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 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) + +#### Will this patch redirect URLs for previous file versions? + +Yes, it will attempt to find the most recent public "hash-less" URL +for this file and redirect to it. + + ## Changes to internal APIs - `PDOQuery::__construct()` now has a 2nd argument. If you have subclassed PDOQuery and overridden __construct()