Api class details

Milo\Github\Api class constructor accepts Milo\Github\Http\IClient optionally. Usually you don't need it untill you use a CachedClient for example. Read about clients on another page.

Most important methods of the class are Api::delete(), Api::get(), Api::head(), Api::patch(), Api::post() and Api::put(). These you need to GitHub API access and all of them returns Milo\Github\Http\Response. Following example shows other handy methods:

$api = new Milo\Github\Api;

# Set OAuth token
$api->setToken($token);

# and get OAuth token
$api->getToken();

# Set default URL parameters, handy for unauthorized access with higher rate limit
$api->setDefaultParameters(['client_id' => '...', 'client_secret' => '...']);

# Get current HTTP client, handy to access Client::onRequest() and Client::onResponse()
$client = $api->getClient();

# Milo\Github\Http\Request factory
$request = $api->createRequest('GET', '/api/path', [], ['Content-Type' => '...'], '');

# Make request object manually
$request = new Milo\Github\Http\Request('GET', 'https://github.com/v3/api/path', [...]);

# Send the request, get the response
$response = $api->request($request);

# Response body decoder (read below)
$data = $api->decode($response);

Encoding data to JSON

If you pass an array or an object to Api::patch(), Api::post(), Api::put() or Api::createRequest() methods as a content argument, method performs encoding to JSON and sets the Content-Type header for you. If you pass raw content as a string, it is up to you set proper header.

$gist = [
    'description' => 'API test',
    'private' => true,
    'files' => [
        'test1.txt' => [
            'content' => 'This is a milo/github-api test ' . time(),
        ],
        'test2.txt' => [
            'content' => 'This is a milo/github-api test ' . time(),
        ],
    ],
];
$response = $api->post('/gists', $gist);

# But
$json = json_encode($gist);
$response = $api->post('/gists', $json, [], ['Content-Type' => 'application/json']);

Response content decoding

Method Api::decode() decodes the response. It checks response headers. If it is a JSON, it performs a JSON decoding and it returns decoded structure. If it isn't JSON, it returns raw content (e.g. HTML).

By default, all responses with HTTP code lower than 300 are supposed as success and you get decoded content. But on code >=300 you get one of Milo\Github\ApiException descendants. Read about exceptions.

You may need to allow only one or two success codes. Use 2nd argument:

# HTTP response codes <300 are OK, codes >= 300 implies to exception
$api->decode($response);

# Only HTTP response codes 200 and 201 are OK, exception for others
$api->decode($response, [200, 201]);

URL parameters substitution

GitHub API documentation page uses URL templates like {repo} or {owner}. You can use it. All parameters are poped from $parameters argument and replaced in URL. The rest is used in URL query.

# URL will be /users/milo/repos?type=owner
$response = $api->get('/users/{user}/repos', [
    'user' => 'milo',
    'type' => 'owner'
]);

# The same without substitution
$response = $api->get('/users/milo/repos', [
    'type' => 'owner'
]);

The documentation used to use URL parameters like :repo or :owner. You can use it too.

# URL will be /users/milo/repos?type=owner
$response = $api->get('/users/:user/repos', [
    'user' => 'milo',
    'type' => 'owner'
]);