File: README.md

Recommend this page to a friend!
  Classes of Sergey Karavay  >  Nano REST  >  README.md  >  Download  
File: README.md
Role: Documentation
Content type: text/markdown
Description: Documentation
Class: Nano REST
Send REST requests to Web servers using Curl
Author: By
Last change: Updates:
- updated README.
Updates:
- RequestContext::setEncodeArraysUsingDuplication to build proper query strings in some cases;
- requestContext::setHttpQueryCustomProcessor to add custom post-processor for query string;
- all usages of "uri" were replaced by "url" for consistency.
Updates:
- added scrutinizer badge to README;
- small refactoring to reduce code duplication;
- small refactoring for cURL verbose handling.
Updates:
- fixed LICENCE typo;
Date: 2 years ago
Size: 6,544 bytes
 

Contents

Class file image Download

PHP Nano Rest

Latest Stable Version Build Status Maintainability Test Coverage Scrutinizer Code Quality SensioLabs Insight License composer.lock Total Downloads

Easy-to-use self-containing lightweight package to deal with cURL requests.

Such packages as Guzzle are great of course, but they are too heavy for small projects. You don't need an overkill package for some easy stuff, and that's when something small and neat may help.

Requirements

  • PHP >= 7.1;
  • cURL extension.

Installation

Require the package using command line:

composer require "gino-pane/nano-rest:1.*"

or just put a new dependency in your existing composer.json and run composer install after that:

"require": {
    ...
    "gino-pane/nano-rest": "1.*"
},

Usage

Project's philosophy implies usage of RequestContext and ResponseContext objects. RequestContext aggregates request settings whilst ResponseContext contains response data.

Response context can be typed. Currently only JsonResponseContext available for JSON responses. Response type must be set explicitly by user. If no response type set, DummyResponseContext will be used.

Please take a look at examples below, which may clarify everything.

POST some data to endpoint

require './vendor/autoload.php';

$nanoRest = new NanoRest();

//explicitly set expected response type
$nanoRest->setResponseContext(ResponseContext::getByType(ResponseContext::RESPONSE_TYPE_JSON));

//create request context
$requestContext = (new RequestContext('http://httpbin.org/post')) //pass URL to constructor
    ->setMethod(RequestContext::METHOD_POST) //set request method. GET is default
    ->setRequestParameters([ //set some request parameters. They will be attached to URL
        'foo' => 'bar'
    ])
    ->setData('Hello world!') //set request data for body
    ->setContentType(RequestContext::CONTENT_TYPE_TEXT_PLAIN) //being set by default
    ->setHeaders([ // set some headers for request
        'bar' => 'baz'
    ]);

$responseContext = $nanoRest->sendRequest($requestContext);

$responseContext->getHttpStatusCode(); //200
$responseContext->hasHttpError() //false

$responseContext->getArray();

/
array(8) {
  'args' =>
  array(1) {
    'foo' =>
    string(3) "bar"
  }
  'data' =>
  string(12) "Hello world!"
  'files' =>
  array(0) {
  }
  'form' =>
  array(0) {
  }
  'headers' =>
  array(8) {
    'Accept' =>
    string(3) "/"
    'Accept-Encoding' =>
    string(13) "deflate, gzip"
    'Bar' =>
    string(3) "baz"
    'Connection' =>
    string(5) "close"
    'Content-Length' =>
    string(2) "12"
    'Content-Type' =>
    string(25) "text/plain; charset=UTF-8"
    'Host' =>
    string(11) "httpbin.org"
    'User-Agent' =>
    string(13) "php-nano-rest"
  }
  'json' =>
  NULL
  'origin' =>
  string(12) "93.85.47.181"
  'url' =>
  string(31) "http://httpbin.org/post?foo=bar"
}
*/

RequestContext provides setCurlOption/setCurlOptions which allow to override default cURL options and customize request for all your needs. Please examine source code and provided IntegrationTest carefully to get the whole idea.

Change the way how request query is generated

By default http_build_query encodes arrays using php square brackets syntax, like this:

?text[0]=1&text[1]=2&text[2]=3

But sometimes you'll want it to work like this instead:

?text=1&text=2&text=3

Or even in some other custom-defined way.

That's why setEncodeArraysUsingDuplication and setHttpQueryCustomProcessor methods were added to RequestContext:

$url = "http://some.url";
$data = ['text' => [1,2,3]];

$request = (new RequestContext($url))
            ->setRequestParameters($data)
            ->setEncodeArraysUsingDuplication(false);

$requestUrl = $request->getRequestUrl(); //http://some.url?text%5B0%5D=1&text%5B1%5D=2&text%5B2%5D=3

$url = "http://some.url";
$data = ['text' => [1,2,3]];

$request = (new RequestContext($url))
            ->setRequestParameters($data)
            ->setEncodeArraysUsingDuplication(true);

$requestUrl = $request->getRequestUrl(); //http://some.url?text=1&text=2&text=3

Method setHttpQueryCustomProcessor allows you to set your custom Closure that will be called on HTTP query string so you could process it as you wish. Initial request $data array will be passed to it as a second parameter.

$url = "http://some.url";
$data = ['text' => [1,2,3]];

$request = (new RequestContext($url))
            ->setRequestParameters($data)
            ->setEncodeArraysUsingDuplication(true);
            
$request->setHttpQueryCustomProcessor(
    function (string $query, array $data) {
        return str_replace('text', 'data', $query);
    }
);

$requestUrl = $request->getRequestUrl(); //http://some.url?data=1&data=2&data=3

Changelog

To keep track, please refer to CHANGELOG.md.

Contributing

Please refer to CONTRIBUTION.md.

License

Please refer to LICENSE.

Notes

Powered by composer-package-template.


For more information send a message to info at phpclasses dot org.