Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phpexpertsinc/restspeaker
A quick and easy GuzzleHTTP extension for effortlessly handling RESTful APIs.
https://github.com/phpexpertsinc/restspeaker
Last synced: about 5 hours ago
JSON representation
A quick and easy GuzzleHTTP extension for effortlessly handling RESTful APIs.
- Host: GitHub
- URL: https://github.com/phpexpertsinc/restspeaker
- Owner: PHPExpertsInc
- License: mit
- Created: 2019-03-09T03:18:16.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-03-30T01:09:03.000Z (8 months ago)
- Last Synced: 2024-10-29T00:57:23.531Z (19 days ago)
- Language: PHP
- Size: 820 KB
- Stars: 7
- Watchers: 2
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# RESTSpeaker
[](https://travis-ci.org/phpexpertsinc/RESTSpeaker)
[](https://codeclimate.com/github/phpexpertsinc/RESTSpeaker/maintainability)
[](https://codeclimate.com/github/phpexpertsinc/RESTSpeaker/test_coverage)
RESTSpeaker is a PHP Experts, Inc., Project meant to ease the accessing of APIs.
This library's Speaker classes utilize the Guzzle HTTP Client
via the Composition architectural pattern.
It further extends base Guzzle so that it automagically decodes
JSON responses and is much easier to work with.
## Installation
Via Composer
```bash
composer require phpexperts/rest-speaker
```
## Change log
**Version 2.6.0**
* **[2024-03-29 20:03:40 CDT]** Return the raw data if it is not JSON.
* **[2024-03-29 20:05:27 CDT]** Added PHP 8.3 support.
**Version 2.5.0**
* **[2023-01-30 10:22:26 CDT]** Removed the need to override the RESTAuth methods.
* **[2023-01-30 10:21:58 CDT]** [m] Upgraded to phpunit v9.5.
* **[2023-01-30 09:57:09 CDT]** Added a NoAuth class.
Please see the [changelog](CHANGELOG.md) for more information on what has changed recently.
## Usage
```php
// Instantiation:
// NOTE: Guzzle *requires* baseURIs to end with "/".
$baseURI = 'https://api.myservice.dev/';
// Either use an .env file or configure ussing the appropriate setters.
$restAuth = new RESTAuth(RESTAuth::AUTH_MODE_TOKEN);
$apiClient = new RESTSpeaker($restAuth, $baseURI);
$response = $apiClient->get("v1/accounts/{$uuid}", [
$this->auth->generateAuthHeaders(),
]);
print_r($response);
/** Output:
stdClass Object
(
[the] => actual
[json] => stdClass Object
(
[object] => 1
[returned] => stdClass Object
(
[as] => if
[run-through] => json_decode()
)
)
)
*/
// Get the more to-the-metal HTTPSpeaker:
$guzzleResponse = $apiClient->http->get('/someURI');
```
## Comparison to Guzzle
```php
// Plain Guzzle
$http = new GuzzleClient([
'base_uri' => 'https://api.my-site.dev/',
]);
$response = $http->post("/members/$username/session", [
'headers' => [
'X-API-Key' => env('TLSV2_APIKEY'),
],
]);
$json = json_decode(
$response
->getBody()
->getContents(),
true
);
// RESTSpeaker
$authStrat = new RESTAuth(RESTAuth::AUTH_MODE_XAPI);
$api = new RESTSpeaker($authStrat, 'https://api.my-site.dev/');
// For URLs that return Content-Type: application/json:
$json = $api->post('/members/' . $username . '/session');
// For all other URL Content-Types:
$guzzleResponse = $api->get('https://slashdot.org/');
// If you have a custom REST authentication strategy, simply implement it like this:
class MyRestAuthStrat extends RESTAuth
{
protected function generateCustomAuthOptions(): []
{
// Custom code here.
return [];
}
}
```
# Use cases
PHPExperts\RESTSpeaker\Tests\HTTPSpeaker
✔ Works as a Guzzle proxy
✔ Identifies as its own user agent
✔ Requests the text/html Content-Type
✔ Can get the last raw response
✔ Can get the last status code
PHPExperts\RESTSpeaker\Tests\RESTAuth
✔ Cannot build itself
✔ Children can build themselves
✔ Will not allow invalid auth modes
✔ Can set a custom api client
✔ Wont call a nonexisting auth strat
✔ Supports no auth
✔ Supports XAPI Token auth
✔ Supports custom auth strategies
✔ Has its own env() polyfill
✔ Implements Guzzle's PSR-18 ClientInterface interface.
PHPExperts\RESTSpeaker\Tests\RESTSpeaker
✔ Can build itself
✔ Returns null when no content
✔ Returns exact unmodified data when not JSON
✔ JSON URLs return plain PHP arrays
✔ Can fall down to HTTPSpeaker
✔ Requests the application/json Content-Type
✔ Can get the last raw Guzzle response
✔ Can get the last status code
✔ Will automagically pass arrays as JSON via POST, PATCH and PUT.
✔ Will automagically pass objects as JSON via POST, PATCH and PUT.
✔ Implements Guzzle's PSR-18 ClientInterface interface.
## Testing
```bash
phpunit
```
# Contributors
[Theodore R. Smith](https://www.phpexperts.pro/])
GPG Fingerprint: 4BF8 2613 1C34 87AC D28F 2AD8 EB24 A91D D612 5690
CEO: PHP Experts, Inc.
## License
MIT license. Please see the [license file](LICENSE) for more information.