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