silverstripe-framework/docs/en/04_Changelogs/4.11.0.md

title
4.11.0 (unreleased)

4.11.0 (unreleased)

Overview

• Regression test and Security audit
• Dropping support for PHP 7.3
• GraphQL v4 major release
• Features and enhancements
  • Upload and use WebP images in the CMS
  • Preview any DataObject in any admin section
  • Meta generator tag now shows framework version number
  • Allow-plugins configuration option in Composer versions 2.2.0 and up
  • Users will recieve an email if their password is changed
  • Other features
• Bugfixes
• Dependency and internal API changes

Regression test and Security 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.

Dropping support for PHP 7.3

In accordance with our PHP support policy, Silverstripe CMS Recipe release 4.11.0 drops support for PHP 7.3. We expect to drop support for PHP 7 altogether around January 2023.

GraphQL 4 major release

Silverstripe CMS Recipe 4.11 defaults to installing silverstripe/graphql version 4, which has just had a stable major release. Previous releases installed version 3.

What does silverstripe/graphql do and why are you changing this?

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 CMS sites. This opens a lot of use cases like using Silverstripe CMS as “headless” CMS.

Up until CMS Recipe 4.11, 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.

silverstripe/graphql v4 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?

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 and stores them in a .graphql-generated folder in the root of your project.

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 now mentioned in the 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 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 or production environment. There are several ways to do this depending on your hosting situation - see the deploying the schema documentation.

If you were already using 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 documentation, and are encouraged to read the GraphQL documentation generally to make sure your existing knowledge carries over to the new major release.

That sounds risky, do I absolutely have to use version 4?

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

If your project composer.json file already explicitly requires silverstripe/graphql, 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 release. To stay on silverstripe/graphql:^3, you'll need to "inline" the silverstripe/recipe-cms requirements in your root composer.json and change silverstripe/graphql to ^3.

You can inline silverstripe/recipe-cms by running this command:

composer update-recipe silverstripe/recipe-cms

If your project does not directly require silverstripe/recipe-cms or silverstripe/graphql, you may still be getting silverstripe/graphql installed if you require other modules that depend on it. To fix your silverstripe/graphql to version 3, run this composer command:

composer require silverstripe/graphql:^3

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

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 this entry to your .gitignore.

The .gitignore file in silverstripe/installer 4.11 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 update your .gitignore file.

Features and enhancements

Upload and use WebP images

WebP is an alternative image format for displaying picture on websites. It provides generally better results in most use cases to JPEG and PNG.

Read An image format for the Web for more information about WebP.

WebP 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? 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 will be end-of-life in June 2022 and that its market share are now under 1% according to most surveys, we decided the time had come to enable WebP by default in the CMS.

Once your project is upgraded to Silverstripe Recipe CMS 4.11, 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 upload by adding this snippet to your YML config:

---
Name: myproject-assetsfiletypes
After: '#assetsfiletypes'
---
SilverStripe\Assets\File:
  allowed_extensions:
    webp: false

Read Allowed file types in the Silverstripe CMS documentation for more information on how to enable or disable new image file formats.

Preview any DataObject in any admin section

The CMS preview panel has historically been available for Versioned DataObjects in the Pages admin section. This has now been expanded to allow any DataObject (regardless of whether it uses theVersioned extension) to be previewed in any section of the CMS.

This can be used to allow content authors to see the content they are creating in the context it will be presented to users. Example use cases include previewing DataObjects which belong to a page (e.g. the dnadesign/silverstripe-elemental module allows previewing elemental blocks which are not inline-editable), and previewing DataObjects in a custom admin section, such as templates for emails or system-generated PDF documents.

The Preview Documentation has been updated with code examples which show how to enable CMS preview on DataObjects in a couple of different scenarios.

Meta generator tag now shows framework version number

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 provide aggregate installation numbers to the product team who maintain Silverstripe CMS which will be used to make informed product decisions.

If you dislike this behaviour, the entire meta generator tag can be disabled via:

SilverStripe\CMS\Model\SiteTree:
  meta_generator: ''

The version portion of the metagenerator tag can be disabled via:

SilverStripe\CMS\Model\SiteTree:
  show_meta_generator_version: false

Allow-plugins configuration option in Composer versions 2.2.0 and up

• As of Composer 2.2.0, the allow-plugins option adds a layer of security. Developers will be prompted to allow plugins when running composer install for the first time on existing projects, or for any new projects not using silverstripe/installer or silverstripe/recipe-kitchen-sink.
• The plugins needed for all silverstripe projects are: composer/installers silverstripe/recipe-plugin silverstripe/vendor-plugin New installations using silverstripe/silverstripe-installer and silverstripe/recipe-kitchen-sink from 4.11 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. This won't affect new installs using silverstripe/installer or silverstripe-recipe-kitchen-sink, 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 recieve an email if their password is changed

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 to false:

SilverStripe\Security\Member:
  notify_password_change: false

The email content can also be changed by overriding the SilverStripe\Control\Email\ChangePasswordEmail template.

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.

Other new features

• A new AbstractGridFieldComponent class has been added to make it easier to globally add fundamental functionality to GridFieldComponents. 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 AbstractGridFieldComponent abstract class.
• New options have been added to the dnadesign/silverstripe-elemental module to control what content is indexed for searching elemental blocks. see the documentation for details.

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

• If guzzlehttp/guzzle is required, it must now be at least 7.3.0. This was done to ensure that v2 of guzzlehttp/psr7 is installed, which is used by embed/embed v4
• embed/embed has been upgraded from v3 to v4. The internal implementation of the internal Embeddable interface has been changed from EmbedResource to 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