katsana / minions
JSON-RPC Communication for Laravel
Installs: 89 786
Dependents: 4
Suggesters: 0
Security: 0
Stars: 7
Watchers: 5
Forks: 2
Open Issues: 2
Requires
- php: >=7.2
- clue/buzz-react: ^2.5
- datto/json-rpc: ^6.0
- illuminate/database: ^6.0 || ^7.0 || ^8.0
- illuminate/pipeline: ^6.0 || ^7.0 || ^8.0
- illuminate/validation: ^6.0 || ^7.0 || ^8.0
- laravie/codex-security: ^1.0
- laravie/stream: ^1.3
- nyholm/psr7: ^1.2
- orchestra/canvas-core: ^4.7 || ^5.0 || ^6.0
- react/event-loop: ^1.1
- react/promise: ^2.5
- symfony/psr-http-message-bridge: ^1.3 || ^2.0
Requires (Dev)
- clue/block-react: ^1.3
- clue/mq-react: ^1.2
- mockery/mockery: ^1.3.1
- orchestra/canvas: ^4.5 || ^5.0 || ^6.0
- orchestra/testbench: ^4.0 || ^5.0 || ^6.0
Suggests
- clue/block-react: Allow to use traditional, blocking environment with Minions (^1.3).
- clue/mq-react: Allow to limit concurrent JSON-RPC Client requests on Minions (^1.2).
- katsana/minions-polyfill: Allow to use Laravel Routing as RPC Server Polyfill (^1.0).
- katsana/minions-server: Allow to use ReactPHP as RPC Server (^1.0).
- dev-master / 3.x-dev
- 2.x-dev
- v2.6.2
- v2.6.1
- v2.6.0
- v2.5.0
- v2.4.0
- v2.3.0
- v2.2.1
- v2.2.0
- v2.1.0
- v2.0.1
- v2.0.0
- 1.x-dev
- v1.10.0
- v1.9.0
- v1.8.0
- v1.7.0
- v1.6.1
- v1.6.0
- v1.5.1
- v1.5.0
- v1.4.1
- v1.4.0
- v1.3.1
- v1.3.0
- v1.2.5
- v1.2.4
- v1.2.3
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.0
- v0.5.0
- v0.4.6
- v0.4.5
- v0.4.4
- v0.4.3
- v0.4.2
- v0.4.1
- v0.4.0
- v0.3.1
- v0.3.0
- v0.2.1
- v0.2.0
- v0.1.1
- v0.1.0
- v0.0.2
- v0.0.1
This package is auto-updated.
Last update: 2024-11-15 13:16:53 UTC
README
Installation
Minions can be installed via composer:
composer require "katsana/minions"
Setup
The package will automatically register a service provider.
Next, you need to publish the Minions configuration file:
php artisan vendor:publish --provider="Minions\MinionsServiceProvider" --tag="config"
Setting Project ID
Each project need to have a unique Project ID to be used to identify authorized RPC requests. You can set the project ID on config/minions.php
configuration file:
<?php return [ // ... 'id' => 'project-id', // ... ];
Configure Projects
Next, you need to setup the project clients and servers information:
<?php return [ // ... 'projects' => [ 'client-project-id' => [ 'token' => 'secret-token', 'signature' => 'secret-signature', ], 'server-project-id' => [ 'endpoint' => 'http://server-project-id:8084', 'token' => 'another-secret-token', 'signature' => 'another-secret-signature', ], ], // ... ];
endpoint
is only required for configurating server project connection from a client project. A server will never send request to a client project.- Each project should have a pair of unique
token
andsecret
, this will be shared only by the client and server as a form of message verification.
Security
token
is used as an Authorization
bearer token header for the request and signature
is used to sign the message sent via the request.
For projects running on private intranet you may skip setting up
token
andsignature
by setting the value tonull
.
Request Handler
To receive a request from a client, first we need to create a request handler on the server, for example let say we want to create a Add
request.
<?php namespace App\JsonRpc; use Minions\Http\Request; use Minions\Http\ValidatesRequests; class MathAdd { use ValidatesRequests; /** * Handle the incoming request. * * @param \Minions\Http\Request $request * * @return mixed */ public function __invoke(Request $request) { return \array_sum($request->all()); } /** * Authorize the incoming request. * * @param \Minions\Http\Request $request * * @return bool */ public function authorize(Request $request): bool { return true; } }
You can use
php artisan minions:make MathAdd
to generate the base stub fileApp\JsonRpc\MathAdd
.
Registering the route
To register the route, all you need to do is add the request handler to routes/rpc.php
:
<?php use Minions\Router; Router::rpc('math.add', 'App\JsonRpc\MathAdd');
You can run the following command to stub routes/rpc.php
:
php artisan vendor:publish --provider="Minions\Http\MinionsServiceProvider" --tag="routes"
Checking authorization
You can check whether the project is authorized to use the request by overriding the authorize()
method.
/** * Authorize the incoming request. * * @param \Minions\Http\Request $request * * @return bool */ public function authorize(Request $request): bool { return $request->id() === 'platform'; // only allow access from `platform` }
Validating the request
You can validate the request using Laravel Validation. Minions also introduce Minions\Http\ValidatesRequests
trait which you can import and expose validate()
and validateWith()
method. e.g:
<?php namespace App\JsonRpc; use App\User; use Minions\Http\Request; use Minions\Http\ValidatesRequests; class User { use ValidatesRequests; /** * Handle the incoming request. * * @param \Minions\Http\Request $request * * @return mixed */ public function __invoke(Request $request) { $this->validate($request, [ 'email' => ['required', 'email'], ]); return User::where('email', '=', $request['email'])->firstOrFail(); } }
Making a Request
To make a request, you can create the following code:
<?php use Minions\Client\Message; use Minions\Client\ResponseInterface; use Minions\Minion; Minion::broadcast('server-project-id', Minion::message( 'math.add', [1, 2, 3, 4] ))->then(function (ResponseInterface $response) { assert(10, $response->getRpcResult()); }); Minion::run();
Running the RPC Server
To run Minions RPC Server, you have two options:
- ReactPHP RPC Server using katsana/minions-server
- Laravel Routing (Polyfill) RPC Server using katsana/minions-polyfill
Please go through each option documentation for installation and usages guide.