Drupal Release: 9.3.0-alpha1

TL;DR

Drupal 9.3.0-alpha1 introduces significant PHP 8.1 compatibility improvements, enhanced accessibility features in the Olivero theme, migration system enhancements, and various bug fixes. This release focuses on future-proofing Drupal with Symfony 6 compatibility changes, reducing jQuery dependencies, and improving the developer and user experience with new entity management capabilities and UI improvements.

Key highlights include PHP 8.1 compatibility fixes, Symfony 6 preparation, accessibility improvements in Olivero theme, migration system enhancements, and new entity management features like bundle classes and module-specific permissions forms.

Highlight of the Release

• PHP 8.1 compatibility improvements across the codebase
• Symfony 6 compatibility preparation with updated type hints and method signatures
• Accessibility enhancements in the Olivero theme including improved contrast and keyboard navigation
• New bundle classes feature allowing entities to be subclassed using bundle-specific classes
• Module-specific permissions forms for better permission management
• Improved file handling with new services replacing deprecated functions
• Migration system enhancements with better error handling and source plugin improvements
• Reduced jQuery dependencies with vanilla JavaScript replacements
• Security fixes addressing multiple vulnerabilities
• Enhanced menu editing experience with improved UI

Migration Guide

PHP 8.1 Compatibility

If you're upgrading to PHP 8.1, be aware that this release includes numerous compatibility fixes. However, you should still test your custom code for PHP 8.1 deprecation notices, particularly around:

• Passing NULL to string functions
• Using NULL as default values where not appropriate
• Static trait method calls
• Array key handling

Deprecated File Functions

Several file handling functions have been deprecated in favor of service-based alternatives:

// Old way (deprecated)
file_save_data($data, $destination, $replace);
file_copy($source, $destination, $replace);
file_move($source, $destination, $replace);
_file_save_upload_single($form_field_name, $validators, $destination, $form_field_name);

// New way
$file = \Drupal::service('file.repository')->writeData($data, $destination, $replace);
$file = \Drupal::service('file.repository')->copy($source, $destination, $replace);
$file = \Drupal::service('file.repository')->move($source, $destination, $replace);
$file = \Drupal::service('file.upload_handler')->handleFileUpload($form_field_name, $validators, $destination, $form_field_name);

Entity Bundle Classes

If you're using the new bundle classes feature, be aware that the entity class is now determined by the active entity-type definition. This might affect code that assumes a specific class for entities.

jQuery Dependencies

Several jQuery dependencies have been removed or replaced with vanilla JavaScript. If your custom code extends or depends on these components, you may need to update:

• BigPipe no longer uses jQuery
• jQuery.once is deprecated
• jQuery.trim and jQuery.merge have vanilla JS alternatives

Configuration Entity Changes

Configuration entity migrations now properly support rollback. If you have custom migration code, ensure it's compatible with this change.

Plugin System Changes

The plugin system now only considers NULL context values to be empty to facilitate the use of otherwise FALSE values. If your code relies on the previous behavior, you may need to update it.

Symfony 6 Compatibility

Many method signatures have been updated with type hints to prepare for Symfony 6 compatibility. If you're extending or implementing these methods, you'll need to update your signatures accordingly.

Upgrade Recommendations

This is an alpha release (9.3.0-alpha1) and is not recommended for production sites. It's primarily intended for:

1. Developers and module maintainers who want to test their code against the upcoming changes, especially PHP 8.1 compatibility fixes and Symfony 6 preparation.

2. Theme developers who want to test with the enhanced Olivero theme and Claro theme improvements.

3. Site builders who want to preview the new features like module-specific permissions forms and improved menu editing experience.

Testing Recommendations

If you're testing this alpha release:

1. Test with PHP 8.1 if possible to identify any remaining compatibility issues.

2. Check custom modules for compatibility with the new bundle classes feature and deprecated file handling functions.

3. Review JavaScript code that might be affected by reduced jQuery dependencies.

4. Test migrations to ensure they work with the enhanced migration system.

Production Sites

For production sites, it's recommended to:

1. Wait for the stable 9.3.0 release before upgrading.

2. Review the full release notes when the stable version is available.

3. Test thoroughly in a staging environment before upgrading production.

4. Update custom code to address deprecated functions and prepare for PHP 8.1 compatibility.

5. Update contributed modules to versions compatible with Drupal 9.3.x.

Bug Fixes

PHP 8.1 Compatibility Fixes

• Fixed numerous PHP 8.1 deprecation notices across the codebase:
  • Updated exception constructors to use empty strings instead of null (#3209619)
  • Added ReturnTypeWillChange attribute where necessary (#3224523)
  • Fixed issues with NULL being passed to string functions (#3236284, #3239294, #3239295)
  • Fixed array key handling in various components (#3239746)
  • Updated hash calculation for PHP 8.1 (#3239552)
  • Fixed issues with static trait method calls (#3239442)
  • Addressed issues with NULL default values in SQLite schema introspection (#3232699)

Entity and Field Handling

• Fixed EntityBase::getTypedData() to return the correct data type for configuration entities (#2870874)
• Fixed issue where configuration entity migrations couldn't be rolled back (#3239298)
• Fixed TypeError in _editor_get_file_uuids_by_field() (#2974156)
• Fixed issue where plugin system didn't properly handle FALSE context values (#3194768)
• Fixed issue where EntityInterface::label() could return NULL (#3232673)

Media and File Handling

• Fixed JSON:API file uploads to public file root (#3214675)
• Fixed oEmbed media controller not properly bubbling cacheability metadata (#3230772)
• Fixed missing content-type header in OEmbedIframeController::render (#3230547)
• Fixed issue with oEmbed thumbnail GET request file extension determination (#3231731)
• Fixed issue where users deleted via JSON:API DELETE didn't follow site-wide cancel_method (#3228000)

UI and Accessibility

• Fixed links with "@" being converted into email addresses incorrectly (#2016739)
• Fixed mobile search input in IE11 not visually responding to keypress (#3190537)
• Fixed comment form save button having incorrect background color and contrast ratio violation (#3211395)
• Fixed Olivero wide search form not closing on blur (#3226785)
• Fixed underlined text in CKEditor 5 not rendering as underlined in Claro (#3229172)
• Fixed text being cut off at mobile if site-branding text goes to two lines (#3211622)
• Fixed contextual links of reusable content blocks not displaying when rendering entities via Layout Builder (#3020876)

Views and Filters

• Fixed Views contextual filter "allow multiple" not working for user roles filter (#3132145)
• Fixed PHP errors when overriding query settings in Views (#3231861)
• Fixed issue where machine name field throws notices if before source field (#990218)
• Fixed issue where link URL in views wasn't translatable (#3008138)

Other Fixes

• Fixed CSS aggregation failures on many variations of @import (#2936067)
• Fixed race condition in 'public://simpletest' mkdir call (#3192365)
• Fixed LogMessageParser breaking messages containing braces (#2909805)
• Fixed issue where adding new text format gives Uncaught TypeError (#2763075)
• Fixed HtmlHeadLink processing not allowing duplicated alternate hreflang links (#2945033)
• Fixed incorrect break (</br>) tag (#3212498)

New Features

Entity Management Improvements

• Bundle Classes: Added support for entity subclassing using "bundle classes", allowing developers to create specialized entity classes for specific bundles (#2570593)
• Module-specific Permissions Forms: Added a "Manage permissions" tab for each bundle that has associated permissions, making permission management more intuitive (#2934995)
• Generic Access API: Implemented generic access API for node and media revision UI (#3043321)

File Handling Improvements

• New File Services: Added new services to replace deprecated file handling functions:
  • Deprecated file_save_data(), file_copy(), and file_move() in favor of service-based alternatives (#3223209)
  • Added FileUploadHandler service for non-form file uploads (#3245244)
  • Moved _file_save_upload_single() to a service (#3232248)

Migration System Enhancements

• Source Plugin Improvements:

  • Added ability to filter menu links by menu name(s) in menu_link source plugin (#3064016)
  • Fixed TermTranslation query and added missing source plugin test (#3187616)
  • Added index on source_ids_hash for migrate_message_* tables for better performance (#3085192)
  • Fixed migration of nodes with CCK nodereferrer fields (#2784783)

• Process Plugin Enhancements:

  • Fixed FieldLink process plugin to properly handle protocol-relative external URLs (#3232681)
  • Fixed EntityReferenceTranslationDeriver process pipeline (#3199578)
  • Added support for migrating Drupal 7 date field "todate" value (#3095237)

• Error Handling:

  • Enhanced MigrateExecutable to add details for the migration & destination property to exceptions that cause a row failure (#2976098)

JavaScript Improvements

• Reduced jQuery Dependencies:

  • Removed jQuery dependency from BigPipe (#3204273)
  • Refactored uses of jQuery trim function to use vanilla JavaScript (#3239132)
  • Added CustomEvent polyfill to support IE11 (#3239507)

• Tabbable Elements:

  • Improved Drupal.tabbingManager to constrain tab navigation to the browser (#3229828)

• Third-party Libraries:

  • Added loadjs library (#3228351)
  • Updated to js-cookie 3.0.1 (#3225811)

Theme Enhancements

• Olivero Theme Improvements:

  • Styled maintenance page (#3194560)
  • Improved wide dropdown hover states (#3228801)
  • Fixed primary menu JS for deep menu structures (#3225241)
  • Styled Views exposed filters as inline (#3224958)
  • Fixed z-index issues with search bar and header (#3212670, #3214191)

• Claro Theme Improvements:

  • Implemented new Gray scale (#3154539)
  • Fixed vertical tabs with #parents (#3219340)

Security Updates

Security Advisory Fixes

• SA-CORE-2021-006: Fixed security vulnerabilities (details not fully specified in commit messages) (#SA-CORE-2021-006)
• SA-CORE-2021-007: Fixed security vulnerabilities (details not fully specified in commit messages) (#SA-CORE-2021-007)
• SA-CORE-2021-008: Fixed security vulnerabilities (details not fully specified in commit messages) (#SA-CORE-2021-008)
• SA-CORE-2021-009: Fixed security vulnerabilities (details not fully specified in commit messages) (#SA-CORE-2021-009)
• SA-CORE-2021-010: Fixed security vulnerabilities (details not fully specified in commit messages) (#SA-CORE-2021-010)

Access Control Improvements

• Fixed issue where NodeAddAccessCheck allowed roles holding the "Administer content types" permission to create nodes (#2744381)
• Implemented generic access API for node and media revision UI (#3043321)
• Added module-specific permissions forms for better permission management (#2934995)

Other Security Enhancements

• Fixed issue where users deleted via JSON:API DELETE didn't follow the site-wide cancel_method in the user settings (#3228000)
• Improved error handling and validation in various components
• Updated dependencies to address potential security issues (#3232571, #3236249, #3238201, #3239772, #3245724)

Performance Improvements

Database and Query Performance

• Added index on source_ids_hash for migrate_message_* tables to improve migration performance (#3085192)
• Improved configuration entity query conditions processing by only processing values for operators that have values (#3232695)

JavaScript Performance

• Removed jQuery dependency from BigPipe for better frontend performance (#3204273)
• Refactored uses of jQuery trim and merge functions to use vanilla JavaScript equivalents (#3239132, #3238863)
• Added loadjs library for more efficient JavaScript loading (#3228351)
• Updated to js-cookie 3.0.1 for better performance (#3225811)

Migration System

• Implemented ::doCount() instead of ::count() to allow source counts to be cached (#3190818)
• Improved error handling in MigrateExecutable with more detailed exception information (#2976098)

Testing Improvements

• Converted tests in Renderer to assertions for better performance (#3192839)
• Removed rebuildAll from FileUploadtest where possible (#3236255)
• Set skip_testcases_on_fail:false in nightwatch.conf.js to improve test efficiency (#3217355)
• Used data provider for constructor test in ContentEntityTest (#3200534)

Other Performance Enhancements

• Improved handling of Quick Edit data attributes in tests (#3227161)
• Refactored SQLite schema introspection implementation (#3232699)
• Improved handling of configuration entity query conditions (#3232695)

Impact Summary

Drupal 9.3.0-alpha1 represents a significant step forward in Drupal's evolution, with a strong focus on future compatibility and developer experience improvements. The release introduces extensive PHP 8.1 compatibility fixes, preparing the platform for the latest PHP version while maintaining backward compatibility. This work ensures Drupal remains modern and secure as PHP continues to evolve.

The release also makes substantial progress toward Symfony 6 compatibility by adding appropriate type hints and updating method signatures throughout the codebase. This forward-looking approach ensures a smoother upgrade path when Symfony 6 becomes the target framework version.

For site builders and content editors, the introduction of module-specific permissions forms and improved menu editing experience addresses long-standing usability issues. These changes make common administrative tasks more intuitive and efficient, reducing the learning curve for new users and improving productivity for experienced ones.

The Olivero theme receives significant accessibility enhancements, including improved contrast ratios, better keyboard navigation, and fixes for various display issues on mobile devices. These improvements make Drupal sites more inclusive and usable for all visitors, regardless of their abilities or devices.

For developers, the new bundle classes feature represents a major architectural improvement, allowing for more flexible and powerful entity subclassing. This feature enables developers to create specialized entity classes for specific bundles, opening up new possibilities for code organization and reuse.

The migration system enhancements improve reliability and performance when migrating content from older Drupal versions or other systems. Better error handling, source plugin improvements, and performance optimizations make migrations more robust and efficient.

Security remains a priority with multiple security advisories addressed in this release, along with improvements to access control and validation throughout the system.

Overall, Drupal 9.3.0-alpha1 balances forward-looking technical improvements with practical usability enhancements, maintaining Drupal's position as a modern, secure, and accessible content management framework.