mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
DOC Update change log to reference updated migration task (#8945)
* DOC Update change log to reference updated migration task * Update docs/en/04_Changelogs/4.4.0.md
This commit is contained in:
Maxime Rainville
Ingo Schommer
parent
86e683c5ec
commit
e95dde8f1e
@ -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 `<img>` and `<a>` 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()
|
||||
|
||||
Loading…
Reference in New Issue
Block a user