README

Laravel Extractor

Communicate with remote servers or microservices in an easy way.

All requests and responses can be cached and manipulated on runtime using middlewares.

Donate me if you like this package 😎

List of contents

Install
How to use
Change log
Contributing
Security
Credits
License

Install

Via Composer

$ composer require shetabit/extractor

If you are using Laravel 5.5 or higher then you don't need to add the provider and alias.

In your config/app.php file add below lines.

# In your providers array.
'providers' => [
	...
	Shetabit\Extractor\Providers\ExtractorServiceProvider::class,
]

How to use

Send requests

you can send requests to remote API using Request class, see the below example:

// at the top
use Shetabit\Extractor\Classes\Request;

//...

// create new request
$request = new Request();

// set api's url and method
$request->setUri($url)->setMethod('get');

// run the request and get data
$response = $request->fetch();

var_dump($response); // show given response

as you see, you can work with remote API in an easy way.

the Request has more methods to add fields, headers and etc.

use Shetabit\Extractor\Classes\Request;

//...
$request = new Request();


# Example 1:
$request
	->setUri('http://your-site.com')
	->setMethod('post')
	// add some headers
	->addHeader('Authorization', "Bearer dfaerfaeaeva1351adsfaecva")
	->addHeader('Accept', 'application/json')
	// add form parameters
	->addFormParam('email', $email)
    ->addFormParam('password', $password);

$response = $request->fetch(); // run request


# Example 2:
$request
	->setUri('http://your-site.com')
	->setMethod('get')
	// add query string
	->addQuery('page', $page)
	->addQuery('s', $search);

$response = $request->fetch(); // run request

Send concurrent requests

you can send concurrent requests like the below

use Shetabit\Extractor\Classes\Request;
use Shetabit\Extractor\Contracts\RequestInterface;

// ...

$request = new Request;

$responses = $request
    ->createBag()
    ->addRequest(function(RequestInterface $request) {
        $request->setUri('http://google.com/');
    })
    ->addRequest(function(RequestInterface $request) {
        $request->setUri('http://bing.com/');
    })
    ->fetch();

Event listeners

you can set success and error listener for each requests seperately. here is another example that uses onSuccess and onError listeners.

use Shetabit\Extractor\Classes\Request;
use Shetabit\Extractor\Contracts\RequestInterface;

// ...

$request = new Request;

# Example 1: using on success
$response = $request
	->setUri('http://google.com/')
	->onSuccess(function (ResponseInterface $response, RequestInterface $request) {
		echo $response->getBody();
	})
	->fetch();


# Example 2: using on error
$response = $request
	->setUri('http://yahoo.com/')
    ->onSuccess(function (ResponseInterface $response, RequestInterface $request) {
                echo 'success';
            })
            ->onError(function (ResponseInterface $response, RequestInterface $request) {
                echo 'fail';
            });


# Example 3: using request's bag
$response = $request
    ->createBag()
    ->addRequest(function (RequestInterface $request) {
        $request
            ->setUri('http://google.com/')
            ->onSuccess(function (ResponseInterface $response, RequestInterface $request) {
                echo $response->getBody();
            });
    })
    ->addRequest(function (RequestInterface $request) {
        $request
            ->setUri('http://yahoo.com/')
            ->onSuccess(function (ResponseInterface $response, RequestInterface $request) {
                echo 'success';
            })
            ->onError(function (ResponseInterface $response, RequestInterface $request) {
                echo 'fail';
            });
    })
    ->fetch();

Middlewares

How to create

Middlewares can be created by running the below command

php artisan make:extractor-middleware test

The former command will create a middleware named test in app\Http\RemoteRequests\Middlewares path.

You can add a middleware to request like the below:

$request
    ->setUri('http://your-site.com')
    ->setMethod('get')
    ->middleware(new AuthMiddleware)
    ->fetch();

Multiple middlewares can be used by calling middleware method multiple times:

$request
    ->setUri('http://your-site.com')
    ->setMethod('get')
    ->middleware(new Test1)
    ->middleware(new Test2)
    ->fetch();

Each middleware has a handle method that can be used to handle requests and responses.

The following middleware would perform some task before the request is handled by the application:

public function handle($request, Closure $next) {
    if($user->name == 'john') {
        $request->addQuery('name', 'john');
    }

    return $next($request);
}

However, this middleware would perform its task after the request is handled by the application:

public function handle($request, Closure $next)
{
    $response = $next($request);

    // Perform action

    return $response;
}

Global middlewares

You can use Request::withGlobalMiddlewares to add global middlewares. global middlewares will be binded to all requests.

// in your AppServiceProvider

protected boot()
{
    Request::withGlobalMiddlewares([
        // list of middlewares
    ]);
}

in each request, you can unbind global middlewares, if you need them just use withoutMiddleware like the below:

// at the top
use Shetabit\Extractor\Classes\Request;

$url = 'http://google.com/';

$response = (new Request)
	->setUri($url)
	->withoutMiddleware(new TestMiddleware)
	->fetch();

Cache

you can cache responses according to requests.

// at the top
use Shetabit\Extractor\Classes\Request;

$url = 'http://google.com/';
$ttl = 5; // 5 seconds

$response = (new Request)->setUri($url)->cache($ttl)->fetch();

Notice: TTL (Time To Live) is the same as Laravel cache.

// at the top
use Shetabit\Extractor\Classes\Request;

$url = 'http://google.com/';
$ttl = now()->addMinutes(10); // 10 minutes

$response = (new Request)->setUri($url)->cache($ttl)->fetch();

Conditional configs

Sometimes you need to add some configs when a condition happens, in this kind of situations you can use the when method to add conditional configs.

# Example 1: simple

$request
    ->when('condition1', function($request) {
        $request
            ->setUri('http://your-site.com')
            ->setMethod('get')
            ->middleware(new AuthMiddleware);
    });


// Example 2: nested
$request
    ->when('condition1', function($request) {
        $request
            ->setUri('http://your-site.com')
            ->setMethod('get')
            ->middleware(new AuthMiddleware);
    })
    ->when('condition2', function($request) {
        $request
            ->setUri('http://shop-site.com')
            ->setMethod('get');
    })
    ->whenNot('condition3', function($request) {
        $request
            ->setUri('http://shop-site.com')
            ->setMethod('patch')
            ->when('condition4', function($request) {
                $request->setMethod('delete'); // sets method to delete
            });
    })
    ->fetch();

Client

You can encapsulate any request that exists between the current microservice and the remote microservice within a Client.

Create clients

Clients can be created using a simple command

php artisan make:extractor-client  clientName

Clients will saved in app/Http/RemoteRequests/Clients by default.

lets create and example, imagine you have and remote Api (or microservice) and need to login into it.

then, your Login micro-client can be similar to below codes:

namespace App\Http\RemoteRequests\Clients\Auth;

use Shetabit\Extractor\Abstracts\MicroClientAbstract;
use Shetabit\Extractor\Contracts\ResponseInterface;

class Login extends MicroClientAbstract
{
    protected $mobile;
    protected $password;

    public function __construct($username, $password = null)
    {
        $this->username = $username;
        $this->password = $password;

        parent::__construct();
    }

    /**
     * Get requests' endpoint
     *
     * @return string
     */
    protected function getEndPoint()
    {
        return 'http://yoursite.com/api/v1/auth';
    }

    /**
     * Run client
     *
     * @return ResponseInterface
     * @throws \Exception
     */
    public function run() : ResponseInterface
    {
        $response = $this
            ->request
            ->setUri($this->getEndPoint())
            ->setMethod('post')
            ->addFormParam('username', $this->username)
            ->addFormParam('password', $this->password)
            ->fetch();

         return $response;
    }
}

Run a client

you can run the Login micro-client like the below (we have Login client example at the top)

// dump data
$username = 'test';
$password = 'something';

$client = new Login($username, $password);

// run client and login into remote service (remote api)
$response = $client->run();

// dump show response's body
var_dump($response->getBody());

as you see, client starts to work as you call the run method, fetches and returns a response.

On progress features

internal error exceptions
resource and API resource clients
proxy requests to another server (middleware)

Change log

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email khanzadimahdi@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

shetabit / extractor

Maintainers

Details