diff --git a/development/development/upgrade.rst b/development/development/upgrade.rst new file mode 100644 index 00000000..87e6bfc0 --- /dev/null +++ b/development/development/upgrade.rst @@ -0,0 +1,18 @@ +============= +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. + +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. + +Contents: + +.. toctree:: + :maxdepth: 3 + + upgrade/400 diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst new file mode 100644 index 00000000..740c5a9a --- /dev/null +++ b/development/development/upgrade/400.rst @@ -0,0 +1,124 @@ +================ +phpBB 3.3 to 4.0 +================ + +phpBB 4.0 is a major release that contains backward compatibility breaks and also introduces some deprecations. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +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 + +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: + +- `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. + +Major changes +============= + +Ban system +---------- +The ban system has been greatly refactored for phpBB 4.0. As part of this, the following changes were introduced: + +- Added support for banning `CIDR blocks `_ +- Added support for IPv6 banning +- Removed "exclude" functionality which resulted in ambiguous settings + +Class and function changes +========================== +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 + :header-rows: 1 + + * - Class or function + - Path + - Type of change + - Version + - Explanation + * - ``\phpbb\avatar\driver\remote`` + - ``phpbb/avatar/driver/remote.php`` + - Removed + - ``4.0.0-a1`` + - Use alternative avatar like gravatar or upload avatar. + * - ``\phpbb\ban\*`` + - ``phpbb/ban/*`` + - Added + - ``4.0.0-a1`` + - Added new refactored banning system. See the API docs for `\\phpbb\\ban `_ namespace. + * - ``\phpbb\captcha\plugins\incomplete`` + - ``phpbb/captcha/plugins/incomplete.php`` + - Added + - ``4.0.0-a1`` + - Placeholder CAPTCHA that prevents e.g. registration until safer captcha like reCAPTCHA or QA is enabled. + * - ``\phpbb\captcha\plugins\gd`` + - ``phpbb/captcha/plugins/gd.php`` + - Removed + - ``4.0.0-a1`` + - Use safer captcha like reCAPTCHA or QA. + * - ``\phpbb\captcha\plugins\gd_wave`` + - ``phpbb/captcha/plugins/gd_wave.php`` + - Removed + - ``4.0.0-a1`` + - Use safer captcha like reCAPTCHA or QA. + * - ``\phpbb\captcha\plugins\nogd`` + - ``phpbb/captcha/plugins/nogd.php`` + - Removed + - ``4.0.0-a1`` + - Use safer captcha like reCAPTCHA or QA. + * - ``\phpbb\captcha\char_cube3d`` + - ``phpbb/captcha/char_cube3d.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + * - ``\phpbb\captcha\colour_manager`` + - ``phpbb/captcha/colour_manager.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + * - ``\phpbb\captcha\gd`` + - ``phpbb/captcha/gd.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + * - ``\phpbb\captcha\gd_wave`` + - ``phpbb/captcha/gd_wave.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + * - ``\phpbb\captcha\non_gd`` + - ``phpbb/captcha/non_gd.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + * - ``\phpbb\form\form_helper`` + - ``phpbb/form/form_helper.php`` + - Added + - ``4.0.0-a1`` + - Introduced form_helper for generating and checking form tokens. + +**Explanation of columns:** + +* **Class or function:** The name of the class or function that was added, changed, deprecated, or removed in this version. +* **Path:** Path to file. +* **Type of change:** The type of change, e.g. added, changed, deprecated, or removed in this version. +* **Version:** Version in which this change was introduced. +* **Explanation:** The suggested approach to handle the change. This could involve using an alternative function, migrating code to a new approach, or providing additional information. diff --git a/development/index.rst b/development/index.rst index 732ce7e6..e28bdcf2 100644 --- a/development/index.rst +++ b/development/index.rst @@ -8,6 +8,7 @@ Contents: start/install start/getting_started + development/upgrade development/processes development/git development/index