From 773045a973426e5a440806abecba1a88c6545438 Mon Sep 17 00:00:00 2001 From: Matt Friedman Date: Fri, 6 Jun 2025 15:08:27 -0700 Subject: [PATCH 1/7] Add section for template functions --- development/development/upgrade/400.rst | 27 +++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index cb6d9012..1238e9af 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -410,3 +410,30 @@ 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, defaul:t ``'fas'`` + - Additional attributes for the icon, where the key is the attribute, ``{'data-ajax': 'mark_forums'}`` results in ``data-ajax="mark_forums"``; optional, default: ``{}`` + From be80d9f134db28860dfcc6bc12964e9122d9d334 Mon Sep 17 00:00:00 2001 From: Matt Friedman Date: Fri, 6 Jun 2025 15:09:15 -0700 Subject: [PATCH 2/7] Add build_select function to upgrading doc --- development/development/upgrade/400.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index 1238e9af..a0cebda3 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -397,6 +397,12 @@ Also have a look at the `phpBB API documentation Date: Fri, 6 Jun 2025 15:09:38 -0700 Subject: [PATCH 3/7] Minor corrections in upgrading doc --- development/development/upgrade/400.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index a0cebda3..37065cbd 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -281,7 +281,7 @@ Also have a look at the `phpBB API documentation Date: Fri, 6 Jun 2025 15:10:04 -0700 Subject: [PATCH 4/7] Add dispatch change to trigger error in upgrading doc --- development/development/upgrade/400.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index 37065cbd..172640b5 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -145,6 +145,12 @@ Also have a look at the `phpBB API documentation Date: Fri, 6 Jun 2025 20:48:36 -0700 Subject: [PATCH 5/7] Typos --- development/development/upgrade/400.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index 172640b5..46f44794 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -438,7 +438,7 @@ The following table lists function changes that might affect custom Style or Ext * - ``Icon()`` - Added - ``4.0.0-a1`` - - Icons may be rendered using ``{{ Icon('font', 'bold') }}`` in Twig instead of manually writing HTML like ```` + - Icons may be rendered using ``{{ Icon('font', 'bold') }}`` in Twig instead of manually writing HTML like ````. Arguments: @@ -446,6 +446,5 @@ The following table lists function changes that might affect custom Style or Ext - 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, defaul:t ``'fas'`` + - 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: ``{}`` - From c3bba0156a38eb3bb306d08743009fd14ad2a2f4 Mon Sep 17 00:00:00 2001 From: Matt Friedman Date: Sat, 7 Jun 2025 07:06:36 -0700 Subject: [PATCH 6/7] Completely rephrase upgrade guide docs --- development/development/upgrade.rst | 10 +++---- development/development/upgrade/400.rst | 38 +++++++++++++++---------- 2 files changed, 27 insertions(+), 21 deletions(-) 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 46f44794..3fcd1e3b 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,49 @@ 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 `_. 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 From 525a333a215b470c4b89ca5f31a88a5b9f9ef7c6 Mon Sep 17 00:00:00 2001 From: Matt Friedman Date: Sat, 7 Jun 2025 08:11:14 -0700 Subject: [PATCH 7/7] Add link for twig deprecations to upgrade guide --- development/development/upgrade/400.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst index 3fcd1e3b..cdc3f6ae 100644 --- a/development/development/upgrade/400.rst +++ b/development/development/upgrade/400.rst @@ -29,6 +29,13 @@ changes across versions, we recommend reviewing the following Symfony upgrade gu 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 =============