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