diff --git a/development/development/upgrade.rst b/development/development/upgrade.rst index 87e6bfc0..5127080d 100644 --- a/development/development/upgrade.rst +++ b/development/development/upgrade.rst @@ -2,13 +2,11 @@ Upgrade Guide ============= -This document outlines changes introduced in different versions of phpBB. These changes may require adjustments to your -existing custom PHP code or Extension code when upgrading to specific versions from a prior versions of phpBB. -It is mainly meant to be used by core and Extension developers and does not provide end user documentation for upgrading. +This guide summarizes code-level changes introduced in various phpBB versions that may require updates to your custom PHP code, extensions, or styles during an upgrade. -Unless explicitly stated otherwise, each version describes the changes compared to the previous major or minor version -that directly preceded it. For example the upgrade guide for 4.0 will describe the changes compared to 3.3 whereas an upgrade guide -for 4.1 will describe the changes compared to 4.0. +It is intended primarily for core developers, extension authors, and style creators. **It does not cover instructions for end users performing a board upgrade.** + +Unless otherwise noted, each upgrade entry documents changes relative to the immediately preceding major or minor release. Contents: diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index cb6d9012..cdc3f6ae 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -2,7 +2,8 @@ phpBB 3.3 to 4.0 ================ -phpBB 4.0 is a major release that contains backward compatibility breaks and also introduces some deprecations. +phpBB 4.0 is a major release that includes backward-incompatible changes and new deprecations. +This guide highlights the most important changes and resources to help extension and style developers adapt their code. .. contents:: Table of Contents :depth: 2 @@ -14,42 +15,56 @@ Basics PHP --- -The minimum required version of PHP for phpBB 4.0 is ``8.1`` with full support for versions ``8.2`` and ``8.3``. -PHP code that worked with the supported versions of phpBB 3.3 should work with phpBB 4.0 as well but might require minor adjustments.Recommendation +phpBB 4.0 requires PHP 8.1 or higher. Most PHP code compatible with phpBB 3.3 should work in phpBB 4.0 with minimal changes, +but you may need to make adjustments depending on deprecated or changed functionality. Symfony ------- -phpBB 4.0 ships with Symfony 6.4. There are quite a few changes to the standard Symfony version that came with phpBB 3.3. -The following upgrade guides provides by Symfony might help with resolving some of the issues you might encounter when upgrading -custom PHP or Extension code for phpBB 4.0: +phpBB 4.0 uses Symfony 6.4, a significant upgrade from the version bundled with phpBB 3.3. As Symfony introduced breaking +changes across versions, we recommend reviewing the following Symfony upgrade guides when updating custom code or extensions: - `Upgrade Symfony from 3.x to 4.0 `_ - `Upgrade Symfony from 4.4 to 5.0 `_ - `Upgrade Symfony from 5.x to 6.0 `_ -You can find more upgrade guides in the `Symfony Repository `_ on GitHub. +Additional guides are available in the `Symfony GitHub repository `_. + +Twig +---- +phpBB 4.0 uses Twig 3.14, which introduces deprecations that may impact extension and style development. +We recommend reviewing the official Twig deprecation guide when updating your custom templates or Twig-related code: + +- `Twig 3.x Deprecated Features `_ Major changes ============= Ban system ---------- -The ban system has been greatly refactored for phpBB 4.0. As part of this, the following changes were introduced: +The ban system has been significantly refactored in phpBB 4.0. Key changes include: -- Added support for banning `CIDR blocks `_ -- Added support for IPv6 banning -- Removed "exclude" functionality which resulted in ambiguous settings +- `CIDR block `_ support for banning IP ranges. +- IPv6 banning is now supported. +- “Exclude” functionality has been removed due to ambiguity and inconsistent behavior. Removal of Jabber/XMPP ---------------------- -The Jabber/XMPP functionality has been removed from phpBB 4.0. This includes the Jabber/XMPP settings in the ACP and the Jabber/XMPP notification system. -Users with Jabber/XMPP accounts will no longer receive notifications via Jabber/XMPP and have instead been migrated to email notifications. -The Jabber/XMPP functionality was removed due to the lack of support for the XMPP protocol in modern browsers and the fact that it was not widely used by phpBB users. +All Jabber/XMPP features have been removed in phpBB 4.0: + +- Jabber/XMPP settings in the ACP are gone. +- XMPP-based notifications have been discontinued. +- Users who previously used Jabber/XMPP will now receive notifications via email. + +This removal was driven by lack of browser support for XMPP and limited adoption within the phpBB community. Class and function changes ========================== +Several classes and functions have been changed or removed. If your extension or code uses phpBB internals, you’ll want to: + +- Review the updated `phpBB 4.0 API documentation `_ +- Audit your code for usages of deprecated or removed methods/classes + The following table lists class and function changes that might affect custom PHP or Extension code. -Also have a look at the `phpBB API documentation `_ for further insight into the class and function API in phpBB 4.0. .. list-table:: :widths: 15 15 10 10 50 @@ -145,6 +160,12 @@ Also have a look at the `phpBB API documentation ``. + + Arguments: + + - Icon type ('font' | 'png' | 'svg') + - Icon name (e.g.: 'bold') + - Icon title; optional, default: empty ``''`` + - Hide the icon title from view; optional, default: ``false`` + - Additional classes (e.g.: 'fa-fw'); optional, default: ``'fas'`` + - Additional attributes for the icon, where the key is the attribute, ``{'data-ajax': 'mark_forums'}`` results in ``data-ajax="mark_forums"``; optional, default: ``{}``