From a98cc8ee9ff30e490b72637dbf173c927c8ef194 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Wed, 19 Mar 2025 18:18:10 +0000 Subject: [PATCH 1/4] Mention global separation stuff in upgrade guide --- content/collections/docs/5-to-6.md | 61 ++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/content/collections/docs/5-to-6.md b/content/collections/docs/5-to-6.md index 71fd8f098..ec0263158 100644 --- a/content/collections/docs/5-to-6.md +++ b/content/collections/docs/5-to-6.md @@ -123,6 +123,67 @@ If you're using any of Statamic's `months_ago`, `weeks_ago`, `days_ago`, `hours_ You _may_ need to updates your templates to account for these changes. +### Globals + +We have made various changes to how globals are stored and localized. If you use globals in your app, please read through these changes and take any necessary action. + +#### Single site installs: Variables are now stored separately from the global set config +Global Variables are now stored separately from the global set's config, allowing config and content to be properly separated. + +Instead of living under a `data` key in the global set's YAML file, they now live in a separate YAML file in a directory named after your default site, usually called `default`. + +**Before:** +```yaml +# content/globals/seo.yaml + +title: SEO +data: + meta_description: Synthwave nostalgia with soaring sax and heartfelt vibes. + meta_image: the-midnight.jpg +``` + +**After:** +```yaml +# content/globals/seo.yaml + +title: SEO +``` + +```yaml +# content/globals/default/seo.yaml + +meta_description: Synthwave nostalgia with soaring sax and heartfelt vibes. +meta_image: the-midnight.jpg +``` + +_This change may have been performed automatically by Statamic during the upgrade process._ + +**Note:** This change _doesn't_ affect multi-sites or sites storing global variables in the database, since they're already stored separately. + +#### Multi-sites: Localized sites are now determined by the `sites` array +Previously, when you configured the sites a global set was localized into, it created the global variable files for you, then used the existence of those files to determine which sites the global set was localized into. + +Now, Statamic will use the `sites` array in the global set's config file to determine which sites the global set is localized into, as well as mapping the origins for localizations. + +```yaml +# content/globals/seo.yaml + +title: SEO +sites: + en: null + fr: en # Localized from en + de: null # No origin +``` + +_This change may have been performed automatically by Statamic during the upgrade process._ + +**Note:** This change _doesn't_ affect single-site installs. + +#### Events +Previously, when saving global variables in the Control Panel, the entire global set would have been saved, causing the `GlobalSetSaving`, `GlobalSetCreated` and `GlobalSetSaved` events to be dispatched. However, now, only the global variable _itself_ will be saved. + +This means that if you were listening to any of these events to pick up changes to global variables, you should instead listen for the [`GlobalVariablesSaving`](https://statamic.dev.test/extending/events#globalvariablessaving), [`GlobalVariablesCreated`](https://statamic.dev.test/extending/events#globalvariablescreated) and [`GlobalVariablesSaved`](https://statamic.dev.test/extending/events#globalvariablessaved) events. + ## Low impact changes ### Moment.js has been removed From c27b6a1e6b81bb50a414214024209be60353b89d Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Fri, 21 Mar 2025 17:25:18 +0000 Subject: [PATCH 2/4] Mention removal of addLocalization / removeLocalization methods --- content/collections/docs/5-to-6.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/content/collections/docs/5-to-6.md b/content/collections/docs/5-to-6.md index ec0263158..f5d545ae2 100644 --- a/content/collections/docs/5-to-6.md +++ b/content/collections/docs/5-to-6.md @@ -184,6 +184,19 @@ Previously, when saving global variables in the Control Panel, the entire global This means that if you were listening to any of these events to pick up changes to global variables, you should instead listen for the [`GlobalVariablesSaving`](https://statamic.dev.test/extending/events#globalvariablessaving), [`GlobalVariablesCreated`](https://statamic.dev.test/extending/events#globalvariablescreated) and [`GlobalVariablesSaved`](https://statamic.dev.test/extending/events#globalvariablessaved) events. +#### Removed methods on `GlobalSet` class +The `addLocalization` and `removeLocalization` methods have been removed from the `GlobalSet` class. + +If you were calling these methods in your app, you should update your code to call `save` and `delete` on the `Variables` class instead. + +```php +$globalSet->addLocalization($globalSet->makeLocalization('en')->data(['foo' => 'bar'])); // [tl! remove] +$globalSet->removeLocalization('en'); // [tl! remove] + +$globalSet->makeLocalization('en')->data(['foo' => 'bar'])->save(); // [tl! add] +$globalSet->in('en')->delete(); // [tl! add] +``` + ## Low impact changes ### Moment.js has been removed From 3293337b2b1c8ed5f28c49b69286806c57c9c3b7 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Fri, 21 Mar 2025 17:35:36 +0000 Subject: [PATCH 3/4] Remove globals wrangling step from "converting to multisite" guide --- content/collections/tips/converting-from-single-to-multi-site.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/collections/tips/converting-from-single-to-multi-site.md b/content/collections/tips/converting-from-single-to-multi-site.md index e4bc20043..716c967f3 100644 --- a/content/collections/tips/converting-from-single-to-multi-site.md +++ b/content/collections/tips/converting-from-single-to-multi-site.md @@ -57,7 +57,6 @@ Now you'll need to update your default site content file & folder structure, so - Take the `root` and `tree` variables, and move them in a file in a subdirectory named after your default site's handle. (eg. `content/trees/navigation/pages.yaml` to `content/trees/navigation/default/pages.yaml`) - Add a `sites` array to the root structure's yaml file with each site you want the structure to be available in. 3. For each global set: - - Take the values inside the `data` array, and move them to the top level in a file in a subdirectory named after the default site's handle. (eg. `content/globals/pages.yaml` to `content/globals/default/pages.yaml`) - Add a `sites` array to the root global's yaml file with each site you want the global to be available in. At this point, your content will be available in the default site. You will need to localize each piece of content by following the steps in its respective documentation. From e698441e5cc30c74efdc92df9430c45c97c22679 Mon Sep 17 00:00:00 2001 From: Duncan McClean Date: Tue, 25 Mar 2025 15:20:36 +0000 Subject: [PATCH 4/4] use `->in('en')` instead of `->addLocalization()` --- content/collections/docs/5-to-6.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/collections/docs/5-to-6.md b/content/collections/docs/5-to-6.md index f5d545ae2..4d3420fb4 100644 --- a/content/collections/docs/5-to-6.md +++ b/content/collections/docs/5-to-6.md @@ -193,7 +193,7 @@ If you were calling these methods in your app, you should update your code to ca $globalSet->addLocalization($globalSet->makeLocalization('en')->data(['foo' => 'bar'])); // [tl! remove] $globalSet->removeLocalization('en'); // [tl! remove] -$globalSet->makeLocalization('en')->data(['foo' => 'bar'])->save(); // [tl! add] +$globalSet->in('en')->data(['foo' => 'bar'])->save(); // [tl! add] $globalSet->in('en')->delete(); // [tl! add] ```