Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

GH Pages: various minor tweaks to the content #478

Merged
merged 1 commit into from
Apr 27, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions api/class-Requests_Exception.html
Original file line number Diff line number Diff line change
Expand Up @@ -294,11 +294,11 @@ <h4>Overrides</h4>
<code><a href="source-class-Requests_Exception.html#43-51" title="Go to source code">getType</a>( )</code>

<div class="description short">
<p>Like <code><a href="class-Exception.html#_getCode">Exception::getCode()</a></code>, but a string code.</p>
<p>Like getCode(), but a string code.</p>
</div>

<div class="description detailed hidden">
<p>Like <code><a href="class-Exception.html#_getCode">Exception::getCode()</a></code>, but a string code.</p>
<p>Like getCode(), but a string code.</p>



Expand Down
101 changes: 51 additions & 50 deletions docs/authentication-custom.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,54 @@
layout: documentation
title: Custom Authentication
---
Custom Authentication
=====================
Custom authentication handlers are designed to be straight-forward to write.
In order to write a handler, you'll need to implement the `Requests_Auth`
interface.

An instance of this handler can then be passed to Requests via the `auth`
option, just like for normal authentication.

Let's say we have a HTTP endpoint that checks for the `Hotdog` header and
authenticates the call if said header is set to `Yummy`. (I don't know of any
services that do this; perhaps this is a market waiting to be tapped?)

```php
class MySoftware_Auth_Hotdog implements Requests_Auth {
protected $password;

public function __construct($password) {
$this->password = $password;
}

public function register(Requests_Hooks &$hooks) {
$hooks->register('requests.before_request', array($this, 'before_request'));
}

public function before_request(&$url, &$headers, &$data, &$type, &$options) {
$headers['Hotdog'] = $this->password;
}
}
```

We then use this in our request calls like this:

```php
$options = array(
'auth' => new MySoftware_Auth_Hotdog('yummy')
);
$response = Requests::get('http://hotdogbin.org/admin', array(), $options);
```

For more information on how to register and use hooks, see the [hooking
system documentation][hooks].

[hooks]: hooks.html

***

Previous: [Authenticating your request](authentication.html)

Next: [Requests through proxy](proxy.html)

Custom Authentication
=====================
Custom authentication handlers are designed to be straight-forward to write.
In order to write a handler, you'll need to implement the `Requests_Auth`
interface.

An instance of this handler can then be passed to Requests via the `auth`
option, just like for normal authentication.

Let's say we have a HTTP endpoint that checks for the `Hotdog` header and
authenticates the call if said header is set to `Yummy`. (I don't know of any
services that do this; perhaps this is a market waiting to be tapped?)

```php
class MySoftware_Auth_Hotdog implements Requests_Auth {
protected $password;

public function __construct($password) {
$this->password = $password;
}

public function register(Requests_Hooks &$hooks) {
$hooks->register('requests.before_request', array($this, 'before_request'));
}

public function before_request(&$url, &$headers, &$data, &$type, &$options) {
$headers['Hotdog'] = $this->password;
}
}
```

We then use this in our request calls like this:

```php
$options = array(
'auth' => new MySoftware_Auth_Hotdog('yummy')
);
$response = Requests::get('http://hotdogbin.org/admin', array(), $options);
```

For more information on how to register and use hooks, see the [hooking
system documentation][hooks].

[hooks]: hooks.html

***

Previous: [Authenticating your request](authentication.html)

Next: [Requests through proxy](proxy.html)
75 changes: 38 additions & 37 deletions docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,40 +2,41 @@
layout: documentation
title: Authentication
---
Authentication
==============
Many requests that you make will require authentication of some type. Requests
includes support out of the box for HTTP Basic authentication, with more
built-ins coming soon.

A Basic authenticated call can be made like this:

```php
$options = array(
'auth' => new Requests_Auth_Basic(array('user', 'password'))
);
Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options);
```

As Basic authentication is usually what you want when you specify a username
and password, you can also just pass in an array as a shorthand:

```php
$options = array(
'auth' => array('user', 'password')
);
Requests::get('http://httpbin.org/basic-auth/user/password', array(), $options);
```

Note that `POST`/`PUT` requests take a `$data` parameter, so you need to pass that
before `$options`:

```php
Requests::post('http://httpbin.org/basic-auth/user/password', array(), null, $options);
```

***

Previous: [Advanced usage](usage-advanced.html)

Next: [Custom authentification](authentication-custom.html)

Authentication
==============
Many requests that you make will require authentication of some type. Requests
includes support out of the box for HTTP Basic authentication, with more
built-ins coming soon.

A Basic authenticated call can be made like this:

```php
$options = array(
'auth' => new Requests_Auth_Basic(array('user', 'password'))
);
Requests::get('https://httpbin.org/basic-auth/user/password', array(), $options);
```

As Basic authentication is usually what you want when you specify a username
and password, you can also just pass in an array as a shorthand:

```php
$options = array(
'auth' => array('user', 'password')
);
Requests::get('https://httpbin.org/basic-auth/user/password', array(), $options);
```

Note that `POST`/`PUT` requests take a `$data` parameter, so you need to pass that
before `$options`:

```php
Requests::post('https://httpbin.org/basic-auth/user/password', array(), null, $options);
```

***

Previous: [Advanced usage](usage-advanced.html)

Next: [Custom authentification](authentication-custom.html)
67 changes: 34 additions & 33 deletions docs/goals.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,37 @@
layout: documentation
title: Goals
---
Goals
=====

1. **Straight-forward interface**

Requests is designed to provide a straight forward, unified interface to making
requests, regardless of what is available on the system. This means not worrying.

2. **Fully tested code**

Requests strives to have 90%+ code coverage from the unit tests, aiming for
the ideal 100%. Introducing new features always means introducing new tests

Note: some parts of the code are not covered by design. These sections are
marked with `@codeCoverageIgnore` tags.

3. **Maximum compatibility**

No matter what you have installed on your system, you should be able to run
Requests. We use cURL if it's available, and fallback to sockets otherwise.
We require only a baseline of PHP 5.2, leaving the choice of PHP minimum
requirement fully in your hands, and giving you the ability to support many
more hosts.

4. **No dependencies**

Requests is designed to be entirely self-contained and doesn't require
anything else at all. You can run Requests on an entirely stock PHP build
without any additional extensions outside the standard library.

***

Next: [Why Requests Instead of X?](why-requests.html)

Goals
=====

1. **Straight-forward interface**

Requests is designed to provide a straight forward, unified interface to making
requests, regardless of what is available on the system. This means not worrying.

2. **Fully tested code**

Requests strives to have 90%+ code coverage from the unit tests, aiming for
the ideal 100%. Introducing new features always means introducing new tests

Note: some parts of the code are not covered by design. These sections are
marked with `@codeCoverageIgnore` tags.

3. **Maximum compatibility**

No matter what you have installed on your system, you should be able to run
Requests. We use cURL if it's available, and fallback to sockets otherwise.
We require only a baseline of PHP 5.2, leaving the choice of PHP minimum
requirement fully in your hands, and giving you the ability to support many
more hosts.

4. **No dependencies**

Requests is designed to be entirely self-contained and doesn't require
anything else at all. You can run Requests on an entirely stock PHP build
without any additional extensions outside the standard library.

***

Next: [Why Requests Instead of X?](why-requests.html)
Loading