PHP 8.6 | Make "characters to be trimmed" explicit

[jrfnl]

PHP 8.6 | Make "characters to be trimmed" explicit

By default, the PHP native [lr]trim() functions, trim ASCII whitespace and the NUL byte character.

PHP 8.6 changes the default value of the $characters parameter to also include the form feed - "\f" - character, which was previously not trimmed.

⚠️ Keep in mind that [lr]trim() only operates on the leading and/or trailing characters for a text string. It does not affect the characters in the "middle" !

Requests uses [lr]trim() in various places throughout the codebase.

To make this code PHP cross-version compatible, this commit makes the following changes:

• Introduces a new final Trim class containing two class constants to represent the different PHP native default values for the $characters parameter.
  This class has been explicitly marked as not part of the public API to allow for changing that class to an enum once support for PHP < 8.1 has been dropped.
• Makes the $characters being trimmed explicit in each of the [lr]trim() function calls (if it wasn't already).

To determine which characters should be trimmed, the following rule of thumb has been used:
"Use the PHP 8.6 default (Trim::WHITESPACE_CHARS), except when the trimming may be subject to an RFC or other documented rules, in which case use the PHP < 8.6 default (Trim::WHITESPACE_CHARS_NO_FF)"

That way, we preserve existing behaviour in "important" places, while benefitting from the new default value everywhere else.

Note: this PR does not update the tests. Tests should be updated to safeguard changed behaviour, but the changes in this PR do not constitute significantly changed behaviour for those places where the behaviour was "changed" (where Trim::WHITESPACE_CHARS was used).
And where the change could be significant, the behaviour was not changed (Trim::WHITESPACE_CHARS_NO_FF).

As a follow-up to this PR, an issue should be opened to review the trimming for those function calls where the behaviour was not changed in this PR (Trim::WHITESPACE_CHARS_NO_FF), against the applicable RFCs or other documentation.

Refs:

• https://wiki.php.net/rfc/trim_form_feed
• https://www.php.net/manual/en/function.trim.php

PHP 8.6 | GH Pages: make "characters to be trimmed" explicit

The script to convert certain markdown documents to documents suitable for use in the GH Pages website, makes some calls to trim() functions.

In all cases, form feed characters should be stripped (like PHP 8.6 will do by default).

This commit standardized on the PHP 8.6 behaviour.

Note: this commit does not use the new Trim class as Requests isn't loaded when running this script (stand-alone).

Refs:

• https://wiki.php.net/rfc/trim_form_feed
• https://www.php.net/manual/en/function.trim.php