Requests: composer says one name, the namespace says another

The package, the namespace, the repository and the homepage are four different names

The repository is under the WordPress organisation. The install command tells you to require a package named after an individual. Every class in the examples sits under a namespace beginning with the organisation's name. The documentation lives on a personal domain belonging to that same individual. And the repository description calls the thing by a fifth name entirely, adding a word for the language. So the package you depend on, the namespace you import, the repository you clone and the site you read are four separate identities, and only two of them belong to the organisation. It is worth holding on to when a build breaks, because the fix will be found under a personal name. The class-loader example adds a sixth: its path assumes the code sits inside a vendor directory under the repository's own name, which no Composer install of the package name would produce.

The install-from-source command uses a protocol that no longer works

One of the four install routes is a clone command using the unauthenticated git protocol:

$ git clone git://github.com/WordPress/Requests.git

That protocol was disabled by the hosting service several years ago, so the route is dead while still being printed in the current documentation. The lines after it are the interesting part. The autoloader is included by requiring a file from a source directory, and then the file asks you to register it as well, hedged with the phrase that you will probably also want to. Two steps for one mechanism, one of them optional in tone. And the repository carries two source directories at its root, the one this route points at and another that nothing on the page explains.

It will not implement the PHP HTTP standards, and the hedge has no version on it

There is a section on the two interface standards the PHP community agreed for HTTP messages and for HTTP clients. It explains that both were created after this library was conceived, and then states that at this time there is no intention to add a native implementation of either. That sentence is the most consequential architectural statement in the file and it has no version attached, no date and no tracking issue, so nothing in the file would tell you whether it still holds. What follows is the resolution: an individual has written an adapter package that presents this library as a standard-compliant client, and the file recommends it. The full chain for a standards-compliant user is therefore a repository owned by one organisation, a package published under an individual's name, and an adapter published under a third name.

Five features listed, and four more shipped as runnable examples

The feature list has five entries: international domains and URLs, browser-style certificate verification, basic and digest authentication, automatic decompression, and connection timeouts. The prose around it claims more than that, and the examples directory proves it. There are ten example files, of which four cover things the feature list never mentions: cookies, a cookie jar, sessions, and a proxy. So a fifth of the documented surface is unlisted. Two smaller gaps in the same direction. The list of supported verbs has six entries and stops before options and trace, which is the pair you would reach for when probing a cross-origin endpoint or debugging a request path. And multipart uploads are promised in the prose while no example exercises them.

Two transports picked at runtime, and a certificate directory that has to be dated by hand

The library uses one of two low-level transports depending on what the system has available, and the file does not say how the choice is made or how to force the other one. That matters more than it sounds: two transports means two TLS stacks, two sets of verification behaviour and two sets of failure modes, behind one consistent interface. Related to that, browser-style certificate verification is a named feature, and the repository root carries a directory of certificates. Shipping your own certificate store is the honest way to get consistent verification regardless of what the host has, and it is also an artefact with a shelf life: it is correct on the day it is generated and quietly wrong afterwards unless something refreshes it. Nothing on the front page says who does that or how to check it.

A PHP floor eight years past end of life, and two branches in one file

The dependency claim is that there are none beyond a language version, given as 5.6.20 and above. That is a runtime whose support ended years ago, and the floor is stated to a patch release, which is a level of precision a floor usually does not have. The branch handling is the other loose end. The repository's default branch is the development one, but the badge for the licence and the badge for coverage both point at a different branch, the documentation links point at that branch, the tarball and zipball downloads fetch that branch, and the contributing link points at the development branch. So a person who clones gets one thing and a person who downloads the tarball gets another, and the two coverage links disagree about whether they are pinned to a branch at all.

One hundred percent documented, and not quite there yet four sections later

The documentation section says the library is fully documented and points at the generated reference. The test-coverage section, three headings down, says the project strives for full coverage of the library and adds that it is not quite there yet. Two adjacent claims about the same number, one absolute and one hedged, in a file that also hedges its standards decision. The examples carry the same contrast in miniature. The response object exposes its status as a snake_case property and its headers and body as properties, which is the Python library's shape showing through a PHP API, and the opening example dumps a body of nearly twenty-seven thousand characters with the output replaced by an ellipsis. The authentication option is a positional pair with no keys. And the toolchain has two test configuration files, one per major version of the test framework, and no static analysis configuration at all.

Editorial conclusion

Requests fits a PHP application that wants the Python library's calling style with no dependencies beyond the language itself, and it fits an application that has standardised on the PHP HTTP interfaces badly. Verify four things before you install it. Note the name you will actually depend on, because it is a personal Composer handle rather than the organisation, and a fork or a rename breaks your manifest differently than you expect. Ignore the install-from-source command, because the protocol it uses no longer works. Plan for the standards question now, because the project has stated it will not implement them and has pointed at a third-party adapter instead, with no version attached to that statement. And read the bundled certificate directory before you rely on browser-style verification, because a pinned certificate store is a dated artefact whoever ships it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. WordPress/Requests on GitHub