mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-10-22 14:05:37 +02:00
f276fccb78
* DOCS Add missing content from beta/rc changelogs * DOCS Add documentation for report count limiting. This was added to the report module README but really belongs here. * DOCS Add information about some new features. * DOCS Add and standardise anchor links. * DOCS Various updates to wording and formatting in 4.11.0 changelog * DOCS Move php changelog notes This is consistent with their placement in the 4.10.0 changelogs. * DOCS Requested PR changes * DOCSUse relative URLs for links to docs from changelog. * DOCS Use code blocks for terminal commands * DOCS requested PR changes * DOCS Don't need to inline recipe to downgrade graphql. * DOCS Move php parts back where they were. * DOCS Fix typos in changelog.
214 lines
17 KiB
Markdown
214 lines
17 KiB
Markdown
---
|
||
title: 4.11.0 (unreleased)
|
||
---
|
||
|
||
# 4.11.0 (unreleased)
|
||
|
||
## Overview
|
||
|
||
- [Regression test and Security audit](#audit)
|
||
- [Adding support for PHP 8.1](#php81)
|
||
- [Dropping support for PHP 7.3](#phpeol)
|
||
- [GraphQL v4 major release](#graphqlv4)
|
||
- [Features and enhancements](#features-and-enhancements)
|
||
- [Upload and use WebP images in the CMS](#webp)
|
||
- [Preview any DataObject in any admin section](#cms-preview)
|
||
- [Meta generator tag now shows framework version number](#meta-tag-version)
|
||
- [Allow-plugins configuration option in Composer versions 2.2.0 and up](#composer)
|
||
- [Users will recieve an email if their password is changed](#change-password-email)
|
||
- [Other features](#other-features)
|
||
- [Bugfixes](#bugfixes)
|
||
- [Dependency and internal API changes](#dependency-internal-api-changes)
|
||
|
||
## Regression test and Security audit {#audit}
|
||
|
||
This release has been comprehensively regression tested and passed to a third party for a security-focused audit.
|
||
|
||
While it is still advised that you perform your own due diligence when upgrading your project, this work is performed to ensure a safe and secure upgrade with each recipe release.
|
||
|
||
## Adding support for PHP 8.1 {#php81}
|
||
|
||
The Silverstripe CMS recipe now officially supports PHP 8.1. This version of PHP introduced various deprecation warnings, most notably when passing null arguments to many native PHP functions. Silverstripe CMS now makes liberal use of the null coalescing operator when calling native PHP functions to convert null arguments to scalars. Other changes including adding the `__serialize` and `__unserialize` methods to classes implementing the [`Serializable`](https://www.php.net/manual/en/class.serializable) interface and adding the [`[#\ReturnTypeWillChange]`](https://www.php.net/manual/en/migration81.incompatible.php#migration81.incompatible.core.type-compatibility-internal) attribute to methods on classes implementing various PHP interfaces such as [`Iterator`](https://www.php.net/manual/en/class.iterator).
|
||
|
||
## Dropping support for PHP 7.3 {#phpeol}
|
||
|
||
In accordance with our [PHP support policy](/getting_started/server_requirements#php), Silverstripe CMS Recipe 4.11.0 drops support for PHP 7.3.
|
||
|
||
## GraphQL 4 major release {#graphqlv4}
|
||
|
||
Silverstripe CMS Recipe 4.11.0 defaults to installing `silverstripe/graphql` version 4, which has just had a stable release. Previous releases installed version 3.
|
||
|
||
### What does `silverstripe/graphql` do and why are you changing this? {#graphqlv4-why}
|
||
|
||
GraphQL is a query language for APIs. It was initially designed by Facebook but it is now used widely across the internet by all sorts of organisations including GitHub, AirBnB, Lyft, PayPal, Shopify, and Silverstripe CMS – to name just a few.
|
||
|
||
`silverstripe/graphql` is an implementation of GraphQL specific to Silverstripe CMS. It is used to power some aspects of the CMS UI. It can also be used by developers to create APIs that other web services can use to read or update data in your Silverstripe sites. This opens a lot of use cases like using Silverstripe CMS as a “headless” CMS.
|
||
|
||
Up until CMS Recipe 4.11.0, Silverstripe CMS would default to using `silverstripe/graphql` version 3. While `silverstripe/graphql` v3 was sufficient to support the basic CMS use cases it was being used for, it was not performant enough to build more complex applications.
|
||
|
||
`silverstripe/graphql` v4 is a complete rewrite and provides substantial performance improvements. It provides developers a first class tool for building APIs and allowing third party services to integrate with their Silverstripe CMS websites.
|
||
|
||
### What do I need to know to get started? {#graphqlv4-basic-info}
|
||
|
||
Part of the reason why `silverstripe/graphql` v4 is so much faster than v3 is that it has a “code generation” step. Silverstripe CMS will generate PHP classes for your GraphQL schemas which are then used to respond to queries or perform mutations. Previously the schema configuration had to be interpreted for every GraphQL request.
|
||
|
||
If you do not have a custom schema, all you need to know is:
|
||
|
||
- There are two new folders that your web server user will need write access to: `.graphql-generated` and `public/_graphql`. These are mentioned in the [Server Requirements](/getting_started/server_requirements/) documentation.
|
||
- If these folders do not exist when `silverstripe/graphql` needs them, the module will try to create them.
|
||
- The GraphQL schema for the CMS will need to be generated. For the most common hosting scenarios you will be fine letting this happen during dev/build, but read the [building the schema](/developer_guides/graphql/getting_started/building_the_schema) documentation to know what your options are – especially if you have a multi-server hosting solution.
|
||
- You will need to deploy the generated schema to your test and production environments. There are several ways to do this depending on your hosting situation – see the [deploying the schema](/developer_guides/graphql/getting_started/deploying_the_schema) documentation for details.
|
||
|
||
If you were already using `silverstripe/graphql` v3 for your own custom schema and queries and want to upgrade to v4, you will also need to read the [Upgrading to GraphQL 4](/upgrading/upgrading_to_graphql_4) documentation, and are encouraged to read the [GraphQL documentation](/developer_guides/graphql/) in general to make sure your existing knowledge carries over to the new major release.
|
||
|
||
### That sounds risky, do I absolutely have to use version 4? {#graphqlv4-can-i-use-v3}
|
||
|
||
Silverstripe CMS has been shipping with dual support for `silverstripe/graphql` v3 and v4 since the 4.8 release. Until now `silverstripe/graphql` v4 had been in alpha and you had to explicitly opt-in to get it. At Silverstripe, we are already using `silverstripe/graphql` v4 in production on several projects.
|
||
|
||
All the supported Silverstripe CMS modules that use `silverstripe/graphql` have dual-support. If you wish to stay on `silverstripe/graphql` v3, you can do so and it will not block you from upgrading to Silverstripe CMS 4.11.
|
||
|
||
#### Opting out of `silverstripe/graphql` version 4 and sticking to version 3 {#graphqlv4-how-to-use-v3}
|
||
|
||
If your project composer.json file already explicitly requires `silverstripe/graphql` version 3, you don’t need to do anything.
|
||
|
||
If your project uses `silverstripe/recipe-cms`, it will install `silverstripe/graphql:^4.0` when you upgrade to the 4.11.0 release if you don't have the graphql module listed as an explicit dependency. To stay on `silverstripe/graphql:^3`, you'll need to explicitly declare this dependency and tell composer to downgrade _it's_ dependencies.
|
||
|
||
You may also see `silverstripe/graphql` version 4 being installed even if your project does not directly require `silverstripe/recipe-cms` or `silverstripe/graphql` if you require other modules that depend on it.
|
||
|
||
To downgrade `silverstripe/graphql` to version 3, run this composer command:
|
||
|
||
```
|
||
composer require silverstripe/graphql:^3 --with-all-dependencies
|
||
```
|
||
|
||
To validate which version of `silverstripe/graphql` your project is using, run this composer command:
|
||
|
||
```
|
||
composer show silverstripe/graphql
|
||
```
|
||
|
||
To view which dependencies require `silverstripe/graphql`, run this composer command:
|
||
|
||
```
|
||
composer why silverstripe/graphql
|
||
```
|
||
|
||
### Tracking or ignoring the `.graphql-generated` and `public/_graphql` folders {#graphqlv4-track-new-folders}
|
||
|
||
Existing projects will not have an entry in their `.gitignore` file for `.graphql-generated` or `public/_graphql`. It is best practice for most situations to not track these folders in version control. You’ll have to manually add these entries to your `.gitignore` file.
|
||
|
||
The `.gitignore` file in `silverstripe/installer` 4.11.0 has been updated to ignore both of these folders. If you start a new project from `silverstripe/installer` 4.11.0 and want to track the new folders, you’ll have to remove those entries from your `.gitignore` file.
|
||
|
||
## Features and enhancements {#features-and-enhancements}
|
||
|
||
### Upload and use WebP images {#webp}
|
||
|
||
WebP is an image format which is optimised for displaying pictures on websites. It provides generally better results in most use cases to JPEG and PNG. It has wide – but not universal – support across web browsers. Internet Explorer is the main browser that does not support WebP at this stage. Read [Can I use WebP?](https://caniuse.com/webp) to see which browsers can render WebP images.
|
||
|
||
Until now, Silverstripe CMS would default to blocking content authors from uploading WebP images. Given that [Internet Explorer went out of support on June 15 2022](https://blogs.windows.com/windowsexperience/2021/05/19/the-future-of-internet-explorer-on-windows-10-is-in-microsoft-edge/), and that its market share is now under 1% according to most surveys, we decided the time had come to allow WebP uploads by default in the CMS.
|
||
|
||
Once your project is upgraded to Silverstripe Recipe CMS 4.11.0, your content authors will automatically be able to upload WebP images and add them to web pages. We recommend you have a conversation with your users about the pros and cons of WebP so they can make an informed decisions about when to use this image format.
|
||
|
||
If your website still caters to a significant number of visitors with browsers that do not support WebP, you can disable WebP image uploads by adding this snippet to your YAML config:
|
||
|
||
```yml
|
||
---
|
||
Name: project-assetsfiletypes
|
||
After: '#assetsfiletypes'
|
||
---
|
||
SilverStripe\Assets\File:
|
||
allowed_extensions:
|
||
webp: false
|
||
```
|
||
|
||
Read [Allowed file types](/Developer_Guides/Files/Allowed_file_types) in the Silverstripe CMS documentation for more information on how to enable or disable new image file formats.
|
||
|
||
Read [An image format for the Web](https://developers.google.com/speed/webp) for more information about the WebP format in general.
|
||
|
||
### Preview any DataObject in any admin section {#cms-preview}
|
||
|
||
The CMS preview panel has historically only been available for `DataObject` classes with the `Versioned` extension in the "Pages" admin section. This has now been expanded to allow any `DataObject` (regardless of whether it uses the `Versioned` extension) to be previewed in any section of the CMS.
|
||
|
||
This can be used to allow content authors to preview any content they are creating in the context it will be presented to users. Example use cases include previewing a `DataObject` which belongs to a page (e.g. the [dnadesign/silverstripe-elemental module](https://github.com/silverstripe/silverstripe-elemental) allows previewing elemental blocks even if they aren't inline-editable), and previewing a `DataObject` in a custom admin section, such as templates for emails or system-generated PDF documents.
|
||
|
||
The [CMS preview documentation](/developer_guides/customising_the_admin_interface/preview/) has been updated with code examples which show how to enable CMS preview for `DataObject` classes in a couple of different scenarios.
|
||
|
||
### Meta generator tag now shows framework version number {#meta-tag-version}
|
||
|
||
The meta generator tag, which can be seen in the meta tags when you view source on a regular page, now includes the framework version truncated to show just the major and minor version, e.g. `4.11`.
|
||
|
||
This version number will allow the product team who maintains Silverstripe CMS to make informed product decisions based on aggregate installation numbers.
|
||
|
||
If you dislike this behaviour, the entire meta generator tag can be disabled via YAML config:
|
||
|
||
```yml
|
||
SilverStripe\CMS\Model\SiteTree:
|
||
meta_generator: ''
|
||
```
|
||
|
||
You can also disable _just_ the version portion of the metagenerator tag:
|
||
|
||
```yml
|
||
SilverStripe\CMS\Model\SiteTree:
|
||
show_meta_generator_version: false
|
||
```
|
||
|
||
### Allow-plugins configuration in Composer versions 2.2.0 and up {#composer}
|
||
|
||
Composer 2.2.0 introduced a new [allow-plugins](https://getcomposer.org/doc/06-config.md#allow-plugins) configuration for `composer.json`. Developers will be prompted to allow plugins when running `composer install` for the first time on existing Silverstripe projects, or for any new Silverstripe projects not using `silverstripe/installer`.
|
||
|
||
The plugins which should be allowed for all Silverstripe projects are:
|
||
- `composer/installers`
|
||
- `silverstripe/vendor-plugin`
|
||
- `silverstripe/recipe-plugin` (if your project uses a Silverstripe recipe)
|
||
|
||
New projects using `silverstripe/silverstripe-installer` from 4.11.0 onwards will have the above plugins added to the `allowed-plugins` configuration by default.
|
||
|
||
From July 2022 Composer will no longer prompt to allow plugins when running `composer install` (specifically, the Composer documentation states "the default will become `{}` and plugins will not load anymore unless allowed"). This won't affect new projects using `silverstripe/installer`, but will affect other new projects and existing projects where `allowed-plugins` hasn't yet been defined. In those cases developers will need to declare the allowed plugins manually in the project's `composer.json` file.
|
||
|
||
### Users will receive an email if their password is changed {#change-password-email}
|
||
|
||
The `SilverStripe\Security\Member.notify_password_change` configuration has been set to `true` by default – it used to be `false`. This means when a user changes their password on a project in "live" mode, they will recieve an email alerting them that their password was changed. The email includes a link to change their password again, so that users can recover their account in the event that someone else changed their password without their knowledge.
|
||
|
||
This change was made to improve the default security of your projects, but if you do not want this behaviour you can disable it by setting the configuration back to false:
|
||
|
||
```yml
|
||
SilverStripe\Security\Member:
|
||
notify_password_change: false
|
||
```
|
||
|
||
[info]
|
||
Note that this configuration is already enabled by default in the `cwp/cwp-core` module. Projects which have that as a dependency won't experience any change in behaviour.
|
||
[/info]
|
||
|
||
The email content can also be changed in a couple of ways:
|
||
|
||
- Override the `SilverStripe\Control\Email\ChangePasswordEmail` template.
|
||
- [Create an `Extension`](/developer_guides/extending/extensions/) for [`Member`](api:SilverStripe\Security\Member) that implements the `updateChangedPasswordEmail(Email $email)` method.
|
||
|
||
### Other new features {#other-features}
|
||
|
||
- A new [`AbstractGridFieldComponent`](api:SilverStripe\Forms\GridField\AbstractGridFieldComponent) class has been added to make it easier to globally add fundamental functionality to `GridField` components. All classes packaged with the Silverstripe framework which implement the `GridFieldComponent` interface are subclasses of the new abstract class, making them all `Injectable`.
|
||
|
||
Maintainers of third-party packages which include classes that implement `GridFieldComponent` are encouraged to subclass the new `AbstractGridFieldComponent` abstract class.
|
||
- New options have been added to the [dnadesign/silverstripe-elemental](https://github.com/silverstripe/silverstripe-elemental) module to control what content is indexed for searching elemental blocks. see [the documentation](https://github.com/silverstripe/silverstripe-elemental/blob/4/docs/en/searching-blocks.md#configuration) for details.
|
||
- Multiple backticked environment variables can be included in a single injected property via YAML configuration. See [Using environment variables in config](/getting_started/environment_management#using-environment-variables-in-config) for details.
|
||
- Individual fields in the `$searchable_fields` configuration can be used to search across multiple database fields. See [Searchable Fields](/developer_guides/model/scaffolding/#searchable-fields) for details.
|
||
- A new `RelationValidationService` has been added. If enabled, when you run `dev/build` it will check that the relations on your DataObjects are set correctly according to the principles in the [Relations between Records](/developer_guides/model/relations/) documentation. See [many_many](/developer_guides/model/relations/#many-many) to see how to enable it.
|
||
- In `ReportAdmin`, the count of items per report is now capped at 10,000 to avoid timing out when loading the list of reports. This number is configurable – see [Counts in `ReportAdmin`](/developer_guides/customising_the_admin_interface/how_tos/customise_site_reports/#counts-in-reportadmin) for details.
|
||
- Using the `silverstripe/session-manager` module, administrators are now able to globally revoke active sessions for all users. This is done using the `InvalidateAllSessions` build task. See [the module's readme](https://github.com/silverstripe/silverstripe-session-manager#developer-details) for details.
|
||
|
||
## Bugfixes {#bugfixes}
|
||
|
||
This release includes a number of bug fixes to improve a broad range of areas. Check the change logs for full details of these fixes split by module. Thank you to the community members that helped contribute these fixes as part of the release!
|
||
|
||
## Dependency and internal API changes {#dependency-internal-api-changes}
|
||
|
||
- The `embed/embed` dependency has been upgraded from v3 to v4. The internal implementation of the internal [`Embeddable`](api:SilverStripe\View\Embed\Embeddable) interface has been changed from [`EmbedResource`](api:SilverStripe\View\Embed\EmbedResource) to [`EmbedContainer`](api:SilverStripe\View\Embed\EmbedContainer).
|
||
- `embed/embed` has been configured to use a guzzle client instead of the default curl client so that a proxy configuration value can be set if required
|
||
- If you have `guzzlehttp/guzzle` as a dependency in your project, it must now be at least `7.3.0`. This is to ensure that v2 of `guzzlehttp/psr7` is installed, which is used by `embed/embed` v4
|
||
|
||
<!--- Changes below this line will be automatically regenerated -->
|
||
|
||
<!--- Changes above this line will be automatically regenerated -->
|