[Summary view] [Print] [Text view]

   1  Requests for PHP
   2  ================
   3  
   4  [![CS](https://github.com/WordPress/Requests/actions/workflows/cs.yml/badge.svg)](https://github.com/WordPress/Requests/actions/workflows/cs.yml)
   5  [![Lint](https://github.com/WordPress/Requests/actions/workflows/lint.yml/badge.svg)](https://github.com/WordPress/Requests/actions/workflows/lint.yml)
   6  [![Test](https://github.com/WordPress/Requests/actions/workflows/test.yml/badge.svg)](https://github.com/WordPress/Requests/actions/workflows/test.yml)
   7  [![codecov.io](https://codecov.io/gh/WordPress/Requests/branch/stable/graph/badge.svg?token=AfpxK7WMxj&branch=stable)](https://codecov.io/gh/WordPress/Requests?branch=stable)
   8  [![Packagist License](https://img.shields.io/packagist/l/rmccue/requests)](https://github.com/WordPress/Requests/blob/stable/LICENSE)
   9  
  10  Requests is a HTTP library written in PHP, for human beings. It is roughly
  11  based on the API from the excellent [Requests Python
  12  library](https://requests.readthedocs.io/en/latest/). Requests is [ISC
  13  Licensed](https://github.com/WordPress/Requests/blob/stable/LICENSE) (similar to
  14  the new BSD license) and has no dependencies, except for PHP 5.6+.
  15  
  16  Despite PHP's use as a language for the web, its tools for sending HTTP requests
  17  are severely lacking. cURL has an
  18  [interesting API](https://www.php.net/curl-setopt), to say the
  19  least, and you can't always rely on it being available. Sockets provide only low
  20  level access, and require you to build most of the HTTP response parsing
  21  yourself.
  22  
  23  We all have better things to do. That's why Requests was born.
  24  
  25  ```php
  26  $headers = array('Accept' => 'application/json');
  27  $options = array('auth' => array('user', 'pass'));
  28  $request = WpOrg\Requests\Requests::get('https://api.github.com/gists', $headers, $options);
  29  
  30  var_dump($request->status_code);
  31  // int(200)
  32  
  33  var_dump($request->headers['content-type']);
  34  // string(31) "application/json; charset=utf-8"
  35  
  36  var_dump($request->body);
  37  // string(26891) "[...]"
  38  ```
  39  
  40  Requests allows you to send  **HEAD**, **GET**, **POST**, **PUT**, **DELETE**, 
  41  and **PATCH** HTTP requests. You can add headers, form data, multipart files, 
  42  and parameters with basic arrays, and access the response data in the same way.
  43  Requests uses cURL and fsockopen, depending on what your system has available, 
  44  but abstracts all the nasty stuff out of your way, providing a consistent API.
  45  
  46  
  47  Features
  48  --------
  49  
  50  - International Domains and URLs
  51  - Browser-style SSL Verification
  52  - Basic/Digest Authentication
  53  - Automatic Decompression
  54  - Connection Timeouts
  55  
  56  
  57  Installation
  58  ------------
  59  
  60  ### Install with Composer
  61  If you're using [Composer](https://getcomposer.org/) to manage
  62  dependencies, you can add Requests with it.
  63  
  64  ```sh
  65  composer require rmccue/requests
  66  ```
  67  
  68  or
  69  ```json
  70  {
  71      "require": {
  72          "rmccue/requests": "^2.0"
  73      }
  74  }
  75  ```
  76  
  77  ### Install source from GitHub
  78  To install the source code:
  79  ```bash
  80  $ git clone git://github.com/WordPress/Requests.git
  81  ```
  82  
  83  Next, include the autoloader in your scripts:
  84  ```php
  85  require_once '/path/to/Requests/src/Autoload.php';
  86  ```
  87  
  88  You'll probably also want to register the autoloader:
  89  ```php
  90  WpOrg\Requests\Autoload::register();
  91  ```
  92  
  93  ### Install source from zip/tarball
  94  Alternatively, you can fetch a [tarball][] or [zipball][]:
  95  
  96  ```bash
  97  $ curl -L https://github.com/WordPress/Requests/tarball/stable | tar xzv
  98  (or)
  99  $ wget https://github.com/WordPress/Requests/tarball/stable -O - | tar xzv
 100  ```
 101  
 102  [tarball]: https://github.com/WordPress/Requests/tarball/stable
 103  [zipball]: https://github.com/WordPress/Requests/zipball/stable
 104  
 105  
 106  ### Using a Class Loader
 107  If you're using a class loader (e.g., [Symfony Class Loader][]) for
 108  [PSR-4][]-style class loading:
 109  ```php
 110  $loader = new Psr4ClassLoader();
 111  $loader->addPrefix('WpOrg\\Requests\\', 'path/to/vendor/Requests/src');
 112  $loader->register();
 113  ```
 114  
 115  [Symfony Class Loader]: https://github.com/symfony/ClassLoader
 116  [PSR-4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4.md
 117  
 118  
 119  Documentation
 120  -------------
 121  The best place to start is our [prose-based documentation][], which will guide
 122  you through using Requests.
 123  
 124  After that, take a look at [the documentation for
 125  `\WpOrg\Requests\Requests::request()`][request_method], where all the parameters are fully
 126  documented.
 127  
 128  Requests is [100% documented with PHPDoc](https://requests.ryanmccue.info/api-2.x/).
 129  If you find any problems with it, [create a new
 130  issue](https://github.com/WordPress/Requests/issues/new)!
 131  
 132  [prose-based documentation]: https://github.com/WordPress/Requests/blob/stable/docs/README.md
 133  [request_method]: https://requests.ryanmccue.info/api-2.x/classes/WpOrg-Requests-Requests.html#method_request
 134  
 135  Testing
 136  -------
 137  
 138  Requests strives to have 100% code-coverage of the library with an extensive
 139  set of tests. We're not quite there yet, but [we're getting close][codecov].
 140  
 141  [codecov]: https://codecov.io/github/WordPress/Requests/
 142  
 143  To run the test suite, first check that you have the [PHP
 144  JSON extension ](https://www.php.net/book.json) enabled. Then
 145  simply:
 146  ```bash
 147  $ phpunit
 148  ```
 149  
 150  If you'd like to run a single set of tests, specify just the name:
 151  ```bash
 152  $ phpunit Transport/cURL
 153  ```
 154  
 155  Requests and PSR-7/PSR-18
 156  -------------------------
 157  
 158  [PSR-7][psr-7] describes common interfaces for representing HTTP messages.
 159  [PSR-18][psr-18] describes a common interface for sending HTTP requests and receiving HTTP responses.
 160  
 161  Both PSR-7 as well as PSR-18 were created after Requests' conception.
 162  At this time, there is no intention to add a native PSR-7/PSR-18 implementation to the Requests library.
 163  
 164  However, the amazing [Artur Weigandt][art4] has created a [package][requests-psr-18], which allows you to use Requests as a PSR-7 compatible PSR-18 HTTP Client.
 165  If you are interested in a PSR-7/PSR-18 compatible version of Requests, we highly recommend you check out [this package][requests-psr-18].
 166  
 167  [psr-7]:           https://www.php-fig.org/psr/psr-7/
 168  [psr-18]:          https://www.php-fig.org/psr/psr-18/
 169  [art4]:            https://github.com/Art4
 170  [requests-psr-18]: https://packagist.org/packages/art4/requests-psr18-adapter
 171  
 172  
 173  Contribute
 174  ----------
 175  
 176  1. Check for open issues or open a new issue for a feature request or a bug.
 177  2. Fork [the repository][] on Github to start making your changes to the
 178      `develop` branch (or branch off of it).
 179  3. Write one or more tests which show that the bug was fixed or that the feature works as expected.
 180  4. Send in a pull request.
 181  
 182  If you have questions while working on your contribution and you use Slack, there is
 183  a [#core-http-api] channel available in the [WordPress Slack] in which contributions can be discussed.
 184  
 185  [the repository]: https://github.com/WordPress/Requests
 186  [#core-http-api]: https://wordpress.slack.com/archives/C02BBE29V42
 187  [WordPress Slack]: https://make.wordpress.org/chat/