Version 2.0.0

BREAKING CHANGES

As Requests 2.0.0 is a major release, this version contains breaking changes. There is an upgrade guide available to guide you through making the necessary changes in your own code.

Overview of changes

• New minimum PHP version

  Support for PHP 5.2 - 5.5 has been dropped. The new minimum supported PHP version is now 5.6.

  Support for HHVM has also been dropped formally now.

  (props @datagutten, @jrfnl, @schlessera, #378, #470, #509)

• New release branch name

  The stable version of Requests can be found in the stable branch (was master).
  Development of Requests happens in the develop branch.

  (props @jrfnl, @schlessera, #463, #490)

• All code is now namespaced (PSR-4)

  The code within the Requests library has all been namespaced and now lives in the WpOrg\Requests namespace.

  The namespaced classes can be found in the src directory. The old library directory and the files within are deprecated.

  For a number of classes, some subtle changes have also been made to their base class name, like renaming the Hooker interface to HookManager.

  A full backward-compatibility layer is available and using the non-namespaced class names will still work during the 2.x and 3.x release cycles, though a deprecation notice will be thrown the first time a class using one of the old PSR-0 based class names is requested.
  For the lifetime of Requests 2.x, the deprecation notices can be disabled by defining a global REQUESTS_SILENCE_PSR0_DEPRECATIONS constant and
  setting the value of this constant to true.

  A complete "translation table" between the Requests 1.x and 2.x class names is available in the upgrade guide.

  Users of the Requests native custom autoloader will need to adjust their code to initialize the autoloader:

  // OLD: Using the custom autoloader in Requests 1.x.
  require_once 'path/to/Requests/library/Requests.php';
  Requests::register_autoloader();
  
  // NEW: Using the custom autoloader in Requests 2.x.
  require_once 'path/to/Requests/src/Autoload.php';
  WpOrg\Requests\Autoload::register();

  (props @jrfnl, @schlessera, #503, #519, #586, #587, #594)

• A large number of classes have been marked as final

  Marking a class as final prohibits extending it.

  These changes were made after researching which classes were being extended in userland code and due diligence has been applied before making these changes. If this change is causing a problem we didn't anticipate, please open an issue to report it.

  (props @jrfnl, @schlessera, #514, #534)

• Input validation

  All typical entry point methods in Requests will now, directly or indirectly, validate the received input parameters for being of the correct type.
  When an incorrect parameter type is received, a catchable WpOrg\Requests\Exception\InvalidArgument exception will be thrown.

  The input validation has been set up to be reasonably liberal, so if Requests was being used as per the documentation, this change should not affect you.
  If you still find the input validation to be too strict and you have a good use-case of why it should be loosened for a particular entry point, please open an issue to discuss this.

  The code within Requests itself has also received various improvements to be more type safe.

  (props @jrfnl, @schlessera, #499, #542, #547, #558, #572, #573, #574, #591, #592, #593, #601, #602, #603, #604, #605, #609, #610, #611, #613, #614, #615, #620, #621, #629)

• Update bundled certificates

  The bundled certificates were updated with the latest version available (published 2021-10-26).

  Previously the bundled certificates in Requests would include a small subset of expired certificates for legacy reasons.
  This is no longer the case as of Requests 2.0.0.

  ⚠️ Note: the included certificates bundle is only intended as a fallback.

  This fallback should only be used for servers that are not properly configured for SSL verification. A continuously managed server should provide a more up-to-date certificate authority list than a software library which only gets updates once in a while.

  Setting the $options['verify'] key to true when initiating a request enables certificate verification using the certificate authority list provided by the server environment, which is recommended.

  The documentation regarding Secure Requests with SSL has also been updated to reflect this and it is recommended to have a read through.

  The included certificates file has now also been moved to a dedicated /certificates directory off the project root.

  (props @jrfnl, @schlessera, @wojsmol, @ZsgsDesign, #535, #571, #577, #622, #632)

• New functionality

  The following new functionality has been added:

  • A public static WpOrg\Requests\Requests::has_capabilities($capabilities = array()) method is now available to check whether there is a transport available which supports the requested capabilities.
  • A public WpOrg\Requests\Response::decode_body($associative = true, $depth = 512, $options = 0) method is now available to handle JSON-decoding a response body.
    The method parameters correspond to the parameters of the PHP native json_decode() function.
    The method will throw an WpOrg\Requests\Exception when the response body is not valid JSON.
  • A WpOrg\Requests\Capability interface. This interface provides constants for the known capabilities. Transports can be tested whether or not they support these capabilities.
    Currently, the only capability supported is Capability::SSL.
  • A WpOrg\Requests\Port class. This class encapsulates typical port numbers as constants and offers a static Port::get($type) method to retrieve a port number based on a request type.
    Using this class when referring to port numbers is recommended.
  • An WpOrg\Requests\Exceptions\InvalidArgument class. This class is intended for internal use only.
  • An WpOrg\Requests\Utility\InputValidator class with helper methods for input validation. This class is intended for internal use only.

  (props @ccrims0n, @dd32, @jrfnl, @schlessera, #167, #214, #250, #251, #492, #499, #538, #542, #547, #559)

• Changed functionality

  • The WpOrg\Requests\Requests::decompress() method has been fixed to recognize more compression levels and handle these correctly.
  • The method signature of the WpOrg\Requests\Transport::test() interface method has been adjusted to enforce support for an optional $capabilities parameter.
    The Request native WpOrg\Requests\Transport\Curl::test() and WpOrg\Requests\Transport\Fsockopen::test() methods both already supported this parameter.
  • The WpOrg\Requests\Transport\Curl::request() and the WpOrg\Requests\Transport\Fsockopen::request() methods will now throw an WpOrg\Requests\Exception when the $options['filename'] contains an invalid path.
  • The WpOrg\Requests\Transport\Curl::request() method will no longer set the CURLOPT_REFERER option.
  • The default value of the $key parameter in the WpOrg\Requests\Cookie\Jar::normalize_cookie() method has been changed from null to an empty string.

  (props @datagutten, @dustinrue, @jrfnl, @schlessera, @soulseekah, @twdnhfr, #301, #309, #379, #444, #492, #610)

• Removed functionality

  The following methods, which were deprecated during the 1.x cycle, have now been removed:

  • Requests::flattern(), use WpOrg\Requests\Requests::flatten() instead.
  • Requests_Cookie::formatForHeader(), use WpOrg\Requests\Cookie::format_for_header() instead.
  • Requests_Cookie::formatForSetCookie(), use WpOrg\Requests\Cookie::format_for_set_cookie() instead.
  • Requests_Cookie::parseFromHeaders(), use WpOrg\Requests\Cookie::parse_from_headers() instead.
  • Requests_Cookie_Jar::normalizeCookie(), use WpOrg\Requests\Cookie\Jar::normalize_cookie() instead

  A duplicate method has been removed:

  • Requests::match_domain(), use WpOrg\Requests\Ssl::match_domain() instead.

  A redundant method has been removed:

  • Hooks::__construct().

  (props @jrfnl, @schlessera, #510, #525, #617)

• Compatibility with PHP 8.0 named parameters

  All parameter names have been reviewed to prevent issues for users using PHP 8.0 named parameters and where relevant, a number of parameter names have been changed.

  After this release, a parameter name rename will be treated as a breaking change (reserved for major releases) and will be marked as such in the changelog.

  (props @jrfnl, @schlessera, #533, #560, #561, #599, #612)

• PHP 8.1 compatibility

  All known PHP 8.1 compatibility issues have been fixed and tests are now running (and passing) against PHP 8.1.

  In case you still run into a PHP 8.1 deprecation notice or other PHP 8.1 related issue, please open an issue to report it.

  (props @jrfnl, @schlessera, #498, #499, #500, #501, #505, #634)

• Updated documentation

  The documentation website has been updated to reflect all the changes in Requests 2.0.0.

  The API documentation for Requests 2.x is now generated using phpDocumentor ❤️ and available on the website.
  For the time being, the Requests 1.x API documentation will still be available on the website as well.

  (props @costdev, @jrfnl, @schlessera, @szepeviktor, #476, #480, #489, #495, #526, #528, #532, #543, #562, #578, #590, #606, #607, #608, #618, #622, #625, #626, #630, #642)

• General housekeeping

  • In a number of places, code modernizations, possible now the minimum PHP version has gone up to PHP 5.6, have been applied.
    (#504, #506, #512, #539, #541, #599, #623)

  • Lots of improvements were made to render the tests more reliable and increase the coverage.
    (#446, #459, #472, #503, #508, #511, #520, #521, #548, #549, #550, #551, #552, #553, #554, #555, #556, #557, #558, #566, #581, #591, #595, #640)

  • The move for all CI to GitHub Actions has been finalized. Travis is dead, long live Travis and thanks for all the fish.
    (#447, #575, #579)

  • A GitHub Actions workflow has been put in place to allow for automatically updating the website on releases.
    This should allow for more rapid releases from now on.
    (#466, #544, #545, #563, #569, #583, #626)

  • Development-only dependencies have been updated.
    (#516, #517)

  • Various other general housekeeping and improvements for contributors.
    (#488, #491, #523, #513, #515, #522, #524, #531, #535, #536, #537, #540, #588, #616)

  (props @jrfnl, @schlessera)