Sajya Server

https://github.com/sajya/server
Admin
A Laravel package providing complete JSON-RPC 2.0 server implementation with validation, batch...
Tokens:50,194
Snippets:363
Trust Score:6.7
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### Request::loadArray example

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Shows how to create a Request from a decoded JSON-RPC array. The static factory calls matching setters for each key, with 'jsonrpc' explicitly setting the version. Unknown keys are ignored. The example demonstrates retrieving method and id after construction.

```php
$request = Request::loadArray([
    'jsonrpc' => '2.0',
    'method'  => 'math@sum',
    'params'  => ['a' => 1],
    'id'      => 9,
]);
$request->getMethod();   // "math@sum"
$request->getId();       // "9"
```

--------------------------------

### Full example config file (config/sajya.php)

Source: https://github.com/sajya/server/blob/master/_autodocs/configuration.md

Shipped configuration file with three keys: delimiter, max_batch_size, and encode_options. Defaults: '@', 30, and 0 respectively. The effective max_batch_size is 30 after publishing, or 50 if the key is removed.

```php
<?php

return [

    'delimiter' => '@',

    'max_batch_size' => 30,

    'encode_options' => 0,
];
```

--------------------------------

### Parser classification example

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-parser.md

Shows how to instantiate Parser with different JSON-RPC payloads and check isBatch(), isNotification(), and isError().

```php
use Sajya\Server\Http\Parser;

$single = new Parser('{"jsonrpc":"2.0","method":"math@sub","params":[1,2],"id":1}');
$single->isBatch();          // false
$single->isNotification();   // false

$batch = new Parser('[{"jsonrpc":"2.0","method":"math@sub","params":[1,2],"id":1}]');
$batch->isBatch();           // true

$notif = new Parser('{"jsonrpc":"2.0","method":"math@log","params":[1]}');
$notif->isNotification();    // true

$bad = new Parser('{invalid json');
$bad->isError();             // true
```

--------------------------------

### Example procedure class (MathProcedure)

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Shows a concrete procedure class with a static $name and public methods that receive the RPC Request. The subtract method uses positional parameters, while divide uses named parameters.

```php
namespace App\Http\Procedures;

use Sajya\Server\Procedure;
use Sajya\Server\Http\Request;

class MathProcedure extends Procedure
{
    public static string $name = 'math';

    public function subtract(Request $request): int
    {
        return (int) $request->get('0') - (int) $request->get('1');
    }

    public function divide(Request $request): float|int
    {
        return $request->get('a') / $request->get('b');
    }
}
```

--------------------------------

### PingProcedure with RpcMethod attribute

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Example procedure using the RpcMethod attribute to document the ping method. The attribute has no runtime effect on dispatch.

```php
use Sajya\Server\Attributes\RpcMethod;

class PingProcedure extends Procedure
{
    public static string $name = 'ping';

    #[
        RpcMethod(
            description: 'Execute the procedure.',
            params: ['key' => 'required', 'array' => 'max:5'],
            result: ['key' => 'string', 'array' => 'max:4'])
    ]
    public function ping(): string
    {
        return 'pong';
    }
}
```

--------------------------------

### Full test-case setup using ProceduralRequests

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedural-requests.md

Complete PHPUnit feature test that uses the trait, sets the RPC route in setUp(), and demonstrates both callProcedure with chained assertions and callHttpProcedure for custom error-code assertions.

```php
namespace Tests\Feature;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Sajya\Server\Testing\ProceduralRequests;

class RpcTest extends BaseTestCase
{
    use ProceduralRequests;

    protected function setUp(): void
    {
        parent::setUp();

        $this->setRpcRoute('rpc.api');   // or setRpcUrl('/api/rpc')
    }

    public function testSum()
    {
        $response = $this->callProcedure('math@sum', ['a' => 2, 'b' => 3], 1);

        $response->assertJson([
            'jsonrpc' => '2.0',
            'id'      => '1',
            'result'  => 5,
        ]);
    }

    public function testRawCallForCustomAssertions()
    {
        $response = $this->callHttpProcedure('math@bad', [], 2);

        $response->assertStatus(200)
                 ->assertJsonPath('error.code', -32601);
    }
}
```

--------------------------------

### DynamicProcedure implementing Proxy

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Example procedure that implements Proxy. When no public method matches the method name, this __invoke is called and returns the request parameters.

```php
use Sajya\Server\Procedure;
use Sajya\Server\Proxy;
use Sajya\Server\Http\Request;

class DynamicProcedure extends Procedure implements Proxy
{
    public static string $name = 'dynamic';

    public function __invoke(Request $request): mixed
    {
        // no public method "dynamic@whatever" exists → this is called
        return $request->getParams();
    }
}
```

--------------------------------

### makeFromResult example with Request

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-response.md

Creates a response from a result using a Request that supplies id and version. Passing an Exception as result routes through setError() to produce an error response. The example shows json_encode output: {"id":"3","result":"pong","jsonrpc":"2.0"}.

```php
use Sajya\Server\Http\Response;
use Sajya\Server\Http\Request;

$request = (new Request)->setId(3)->setVersion('2.0');
$response = Response::makeFromResult('pong', $request);

json_encode($response);
// {"id":"3","result":"pong","jsonrpc":"2.0"}
```

--------------------------------

### JSON-RPC request and response example

Source: https://github.com/sajya/server/blob/master/_autodocs/endpoints.md

Shows a single JSON-RPC 2.0 request with positional params and its corresponding response. The response echoes the request id and returns the result.

```json
// Request
{"jsonrpc": "2.0", "method": "fixture@subtract", "params": [42, 23], "id": 1}

// Response
{"id": "1", "result": 19, "jsonrpc": "2.0"}
```

--------------------------------

### Notification handling example

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Creates a request without an id to represent a notification, then shows isNotification() returns true and jsonSerialize() output.

```php
$request = (new Request)->setMethod('audit@log')->setParams(['event' => 'login']);
$request->isNotification();              // true
$request->jsonSerialize();               // ['jsonrpc' => '2.0', 'method' => 'audit@log', 'params' => ['event' => 'login']]
```

--------------------------------

### Direct invocation example

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/json-rpc-controller.md

Shows how to invoke the controller directly in a test or custom router. Creates a Request with a JSON-RPC payload, calls the controller with a procedure class and delimiter '@', then checks status, content-type, and decoded data.

```php
use Sajya\Server\JsonRpcController;
use Illuminate\Http\Request;

$controller = new JsonRpcController;

$httpRequest = Request::create('/point', 'POST', [], [], [], [], '{"jsonrpc":"2.0","method":"math@sum","params":{"a":1,"b":2},"id":1}');

/** @var \Illuminate\Http\JsonResponse $json */
$json = $controller($httpRequest, [\App\Http\Procedures\MathProcedure::class], '@');

$json->status();       // 200
$json->header('content-type'); // application/json
$json->getData(true);  // ['id' => '1', 'result' => 3, 'jsonrpc' => '2.0']
```

--------------------------------

### Register rpc routes with names and middleware

Source: https://github.com/sajya/server/blob/master/_autodocs/endpoints.md

Shows how to register rpc routes in a Laravel service provider test harness. Includes examples with a default delimiter, a custom delimiter '.', and attaching GzipCompress middleware.

```php
$app['router']->rpc('point', $this->mapProcedures)->name('rpc.point');
$app['router']->rpc('delimiter', $this->mapProcedures, '.')->name('rpc.delimiter');
$app['router']->rpc('compress', $this->mapProcedures)->middleware(GzipCompress::class)->name('rpc.compress');
```

--------------------------------

### Pretty-printed responses via encode_options

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/json-rpc-controller.md

Configuration example for pretty-printing JSON-RPC responses. Setting 'encode_options' in config/sajya.php to JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE causes every response body to be formatted accordingly.

```php
// config/sajya.php
'encode_options' => JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE,
```

```php
// has the controller-level effect: every response body is formatted
// response()->json($response, 200, [], JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE)
```

--------------------------------

### Checking batch size limit with checkBatchSizeWithinLimit

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Returns true when the current request count exceeds the configured 'sajya.max_batch_size' (fallback 50, shipped default 30). The example sets the config to 5 and shows that 6 returns true while 5 returns false.

```php
config(['sajya.max_batch_size' => 5]);
$app->checkBatchSizeWithinLimit(6); // true
$app->checkBatchSizeWithinLimit(5); // false
```

--------------------------------

### Parse JSON-RPC payload and inspect request

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-parser.md

Creates a Parser from a JSON-RPC string and calls makeRequests() to obtain a Request object. The example shows how to retrieve the method, id, and params from the first request. The payload must be a valid JSON-RPC string; makeRequests() returns an array of Request or Exception objects.

```php
$parser = new Parser('{"jsonrpc":"2.0","method":"math@sum","params":{"a":1,"b":2},"id":5}');
$requests = $parser->makeRequests();

$request = $requests[0]; // Sajya\Server\Http\Request
$request->getMethod();   // "math@sum"
$request->getId();       // "5"
$request->getParams();   // collect(['a' => 1, 'b' => 2])
```

--------------------------------

### Publishing config and views via artisan

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/server-service-provider.md

Commands to publish the package config and views using `vendor:publish` with the provider and tags.

```bash
php artisan vendor:publish --provider="Sajya\Server\ServerServiceProvider"   # config only
php artisan vendor:publish --provider="Sajya\Server\ServerServiceProvider" --tag=views
```

--------------------------------

### Generate docs for route with sajya:docs

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Command to generate documentation for the route containing the PingProcedure. Stores the docs at /api/docs.html on the default disk.

```bash
php artisan sajya:docs rpc.ping --name=docs.html --path=/api/
# stored on default disk at /api/docs.html (see api-reference/docs.md)
```

--------------------------------

### Generate API documentation with sajya:docs

Source: https://github.com/sajya/server/blob/master/_autodocs/endpoints.md

Artisan command to generate static HTML documentation for a specific rpc route. Writes to the default filesystem disk at {path}{name} (default /api/docs.html).

```bash
php artisan sajya:docs rpc.point --name=docs.html --path=/api/
```

--------------------------------

### Generate static docs with sajya:docs command

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/docs.md

Shows how to generate static documentation for an rpc route using the artisan command, including custom name and path options.

```bash
# routes:
# Route::rpc('/api/rpc', [MathProcedure::class])->name('rpc.api');

php artisan sajya:docs rpc.api
# → storage/app/api/docs.html (default disk, default path/name)

php artisan sajya:docs rpc.api --name=index.html --path=public/docs/
# → public/docs/index.html, ready to serve statically
```

--------------------------------

### JSON-RPC error response example

Source: https://github.com/sajya/server/blob/master/_autodocs/endpoints.md

Shows an error response with code -32602 for invalid params, including a data object with validation messages.

```json
// Error response
{"id": "1", "error": {"code": -32602, "message": "Invalid params", "data": {"params": ["The params field must be an array."]}}, "jsonrpc": "2.0"}
```

--------------------------------

### make:procedure Artisan Command

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Generates a new procedure class file. Run `php artisan make:procedure` with a class name to create a stub in the default namespace.

```APIDOC
## make:procedure Artisan Command

### Description
Generates a new procedure class file. Run `php artisan make:procedure` with a class name to create a stub in the default namespace.

### Command
`php artisan make:procedure {name}`

### Parameters
- **name** (string) - Required - The class name of the procedure to create.

### Example
```bash
php artisan make:procedure MathProcedure
# → app/Http/Procedures/MathProcedure.php
```

### Generated Stub
```php
namespace {{ namespace }};

use Sajya\Server\Procedure;
use Illuminate\Http\Request;

class {{ class }} extends Procedure
{
    public static string $name = '{{ class }}';

    public function handle(Request $request)
    {
        // write your code
    }
}
```
```

--------------------------------

### Registering RPC endpoints in routes/web.php

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/server-service-provider.md

Shows how to use the `Route::rpc()` macro to register RPC endpoints, including a basic variant and a variant with a custom delimiter and middleware.

```php
use App\Http\Procedures\MathProcedure;
use App\Http\Procedures\HealthProcedure;
use Sajya\Server\Middleware\GzipCompress;

Route::rpc('/api/rpc', [MathProcedure::class, HealthProcedure::class])
    ->name('rpc.api');

// custom delimiter and middleware variant
Route::rpc('/api/rpc-alt', [MathProcedure::class], '.')
    ->middleware(['auth:sanctum', GzipCompress::class])
    ->name('rpc.alt');
```

--------------------------------

### Building a request and reading it back

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Creates a Request with id, method, params, and version, then checks isNotification() and json_encode output.

```php
use Sajya\Server\Http\Request;

$request = (new Request)
    ->setId(1)
    ->setMethod('math@subtract')
    ->setParams([42, 23])
    ->setVersion('2.0');

$request->isNotification(); // false
json_encode($request);      // {"jsonrpc":"2.0","method":"math@subtract","params":[42,23],"id":1}
```

--------------------------------

### getVersion(): ?string

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-response.md

Returns the JSON-RPC version string, or null if not set.

```APIDOC
## getVersion(): ?string

### Description
Returns the JSON-RPC version string, or null if not set.

### Method
getVersion

### Returns
- **?string** - The JSON-RPC version.
```

--------------------------------

### Running a procedure synchronously via the job

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/handle-procedure.md

Creates a Request with method 'math@divide' and params, then instantiates HandleProcedure with the FQCN@method string and calls handle(). The result is checked for RpcException, and report() is called on it.

```php
use Sajya\Server\HandleProcedure;
use Sajya\Server\Http\Request;

$request = (new Request)
    ->setId(1)
    ->setMethod('math@divide')
    ->setParams(['a' => 1, 'b' => 0])
    ->setVersion('2.0');

$job = new HandleProcedure('App\Http\Procedures\MathProcedure@divide', $request);
$result = $job->handle();

if ($result instanceof \Sajya\Server\Exceptions\RpcException) {
    // RuntimeException subclass, e.g. RuntimeRpcException with
    // code 0, message "Division by zero"
    report($result);
}
```

--------------------------------

### Collect annotations programmatically with Docs

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/docs.md

Retrieves an rpc route by name and iterates over its annotations, printing the method name and highlighted request HTML.

```php
use Sajya\Server\Docs;
use Illuminate\Support\Facades\Route;

$route = Route::getRoutes()->getByName('rpc.docs');

$docs = new Docs($route);
foreach ($docs->getAnnotations() as $entry) {
    printf("%s%s%s — %s\n", $entry['name'], $entry['delimiter'], $entry['method'], (string) $entry['description']);
    echo (string) $entry['request'];   // highlighted <pre> HTML
}
```

--------------------------------

### Generated procedure stub

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Shows the template used by the make:procedure command. The placeholders {{ namespace }} and {{ class }} are replaced during generation. The stub includes a handle method with a comment to write custom logic.

```php
namespace {{ namespace }};

use Sajya\Server\Procedure;
use Illuminate\Http\Request;

class {{ class }} extends Procedure
{
    public static string $name = '{{ class }}';

    public function handle(Request $request)
    {
        // write your code
    }
}
```

--------------------------------

### Reuse Parser rules for custom validation

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-parser.md

Uses the static rules() method to validate a JSON-RPC request with Laravel's Validator. The example shows that an id of boolean true fails validation because the id must be a string or integer. The rules require jsonrpc to be "2.0", method to be a string, params to be an array, and id to be an Identifier instance.

```php
use Illuminate\Support\Facades\Validator;
use Sajya\Server\Http\Parser;

$validator = Validator::make(['jsonrpc' => '2.0', 'method' => 'x', 'id' => true], Parser::rules());
$validator->fails(); // true — id must be a string or integer
```

--------------------------------

### Basic App instantiation and handle() call

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Creates an App with two procedure classes and a custom delimiter '@', then handles a JSON-RPC request. The response result is 19 for the math@subtract method.

```php
use Sajya\Server\App;
use Sajya\Server\Http\Response;

$app = new App([
    \App\Http\Procedures\MathProcedure::class,
    \App\Http\Procedures\TextProcedure::class,
], '@');

/** @var Response $response */
$response = $app->handle('{"jsonrpc":"2.0","method":"math@subtract","params":[42,23],"id":1}');
$response->getResult(); // 19
```

--------------------------------

### ServerServiceProvider class with commands array

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/server-service-provider.md

Defines the service provider class and registers the artisan commands `ProcedureMakeCommand` and `DocsCommand` via the `$commands` property.

```php
class ServerServiceProvider extends ServiceProvider
{
    protected array $commands = [
        ProcedureMakeCommand::class,
        DocsCommand::class,
    ];
}
```

--------------------------------

### Handle missing route with sajya:docs

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/docs.md

Shows the output and exit code when the specified route does not exist.

```bash
php artisan sajya:docs rpc.nope
# Route 'rpc.nope' not found   (exit code 1)
```

--------------------------------

### Artisan make:procedure command

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/procedure.md

Generates a new procedure class in the default namespace app/Http/Procedures. The command is named make:procedure and creates a file with the given class name.

```bash
php artisan make:procedure MathProcedure
# → app/Http/Procedures/MathProcedure.php
```

--------------------------------

### GzipCompress handle method behavior

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/gzip-compress.md

Shows the exact logic: calls the next middleware, then checks if the client requested gzip via getEncodings(). If yes, compresses the response; otherwise returns it unchanged.

```php
$response = $next($request);

return in_array('gzip', $request->getEncodings(), true)
    ? $this->compress($response, $compress)
    : $response;
```

--------------------------------

### Binding singleton registration

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/server-service-provider.md

Registers the `Binding` class as a singleton in the container, resolving it with the container instance.

```php
$this->app->singleton(Binding::class, fn ($container) => new Binding($container));
```

--------------------------------

### Route::rpc() macro

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/server-service-provider.md

Defines a POST route for JSON-RPC endpoints. Accepts a URI, an array of procedure classes, and an optional delimiter. Returns an Illuminate\Routing\Route instance for chaining.

```APIDOC
## [POST] /{uri}

### Description
Registers a JSON-RPC endpoint at the given URI. The route accepts a list of procedure classes and an optional delimiter, which are stored as route defaults.

### Method
POST

### Endpoint
`/{uri}` (dynamic, set via `$uri` argument)

### Parameters
#### Path Parameters
- **uri** (string) - Required - The URI for the POST route.

#### Query Parameters
None.

#### Request Body
Not specified in source.

### Request Example
Not specified in source.

### Response
#### Success Response (200)
Not specified in source.

#### Response Example
Not specified in source.

### Usage Example
```php
use App\Http\Procedures\MathProcedure;
use App\Http\Procedures\HealthProcedure;
use Sajya\Server\Middleware\GzipCompress;

Route::rpc('/api/rpc', [MathProcedure::class, HealthProcedure::class])
    ->name('rpc.api');

// custom delimiter and middleware variant
Route::rpc('/api/rpc-alt', [MathProcedure::class], '.')
    ->middleware(['auth:sanctum', GzipCompress::class])
    ->name('rpc.alt');
```
```

--------------------------------

### new App(array $procedures = [], ?string $delimiter = null)

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Constructs the central JSON-RPC engine with a list of procedure classes and an optional delimiter. Validates that each procedure class extends Sajya\Server\Procedure, aborting with HTTP 500 otherwise.

```APIDOC
## Constructor: new App(array $procedures = [], ?string $delimiter = null)

### Description
Creates an App instance that parses raw JSON-RPC requests, resolves and dispatches procedures, and returns Response objects. Used directly when embedding Sajya in non-HTTP contexts.

### Method
Constructor

### Endpoint
`new App(array $procedures = [], ?string $delimiter = null)`

### Parameters
- **$procedures** (string[]) - Optional - Class names (FQCN) of procedures to register. Each class must extend `Sajya\Server\Procedure`.
- **$delimiter** (?string) - Optional - Delimiter separating procedure name from method name. Defaults to `config('sajya.delimiter', '@')`.

### Returns
App instance

### Throws
- `abort(500, ...)` when any class in `$procedures` is not a subclass of `Procedure`.

### Example
```php
use Sajya\Server\App;
use Sajya\Server\Http\Response;

$app = new App([
    \App\Http\Procedures\MathProcedure::class,
    \App\Http\Procedures\TextProcedure::class,
], '@');

/** @var Response $response */
$response = $app->handle('{"jsonrpc":"2.0","method":"math@subtract","params":[42,23],"id":1}');
$response->getResult(); // 19
```
```

--------------------------------

### GzipCompress class handle method signature

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/gzip-compress.md

Defines the middleware class with a handle method that accepts a request, next closure, and optional compression level (default 6). The level is passed to gzencode().

```php
class GzipCompress
{
    public function handle(Request $request, Closure $next, int $compress = 6)
}
```

--------------------------------

### getVersion(): string

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Returns the JSON-RPC version of the request. Defaults to '2.0'.

```APIDOC
## getVersion(): string

### Description
Returns the JSON-RPC version of the request. Defaults to '2.0'.

### Method
getVersion

### Returns
- **string** — The JSON-RPC version (e.g., '2.0').
```

--------------------------------

### Route::rpc() macro definition

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/server-service-provider.md

Defines the `Route::rpc()` macro that creates a POST route to `JsonRpcController` with default `procedures` and `delimiter` values.

```php
Route::macro('rpc', fn (string $uri, array $procedures = [], ?string $delimiter = null) => Route::post($uri, [JsonRpcController::class, '__invoke'])
    ->setDefaults([
        'procedures' => $procedures,
        'delimiter'  => $delimiter,
    ]));
```

--------------------------------

### handle(Request $request, Closure $next, int $compress = 6)

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/gzip-compress.md

Processes an incoming HTTP request and compresses the JSON-RPC response with gzip if the client advertises the 'gzip' content-encoding. Returns the downstream response unchanged when gzip is not requested.

```APIDOC
## handle(Request $request, Closure $next, int $compress = 6)

### Description
Processes an incoming HTTP request and compresses the JSON-RPC response with gzip if the client advertises the 'gzip' content-encoding. Returns the downstream response unchanged when gzip is not requested.

### Method
handle

### Parameters
- `$request` (Illuminate\Http\Request) - Required - Incoming HTTP request; encodings read via `$request->getEncodings()`.
- `$next` (Closure) - Required - Next middleware in the chain.
- `$compress` (int) - Optional - gzip compression level (`gzencode()` level argument). Default: `6`.

### Returns
`Illuminate\Http\JsonResponse` — the unchanged downstream response when the client did not request gzip; otherwise the compressed response.

### Behavior
```php
$response = $next($request);

return in_array('gzip', $request->getEncodings(), true)
    ? $this->compress($response, $compress)
    : $response;
```
```

--------------------------------

### handle() batch with one notification

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Shows how handle() processes a batch request containing a notification. The notification response is rejected, so count($responses) returns 1.

```php
$body = '[
  {"jsonrpc":"2.0","method":"fixture@subtract","params":[42,23],"id":1},
  {"jsonrpc":"2.0","method":"fixture@log"}   // notification: no id
]';

$responses = $app->handle($body); // Response[]
count($responses);                // 1 (notification response rejected)
```

--------------------------------

### RPC Facade Class Definition

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/binding.md

Defines the RPC facade with methods bind, model, and bindResolve. The facade accessor returns the Binding class.

```php
class RPC extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return Binding::class;
    }
}
```

--------------------------------

### Notification dispatch (fire-and-forget) with HandleProcedure

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/handle-procedure.md

Shows how to dispatch a notification (request without 'id') via App::handle(). The response is null and HandleProcedure is queued with dispatchAfterResponse(); the queue worker must run to execute it.

```php
use Sajya\Server\App;
use Sajya\Server\HandleProcedure;

$app = new App([\App\Http\Procedures\AuditProcedure::class]);

// no "id" in the request → notification
$response = $app->handle('{"jsonrpc":"2.0","method":"audit@record","params":{"event":"login"}}');

// $response === null; HandleProcedure was queued with dispatchAfterResponse()
// Run the queue worker (php artisan queue:work) to execute it.
```

--------------------------------

### findProxy(string $class): ?string

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Finds the first registered procedure that matches the given class name and implements the Proxy interface. It returns the FQCN suffixed with '@__invoke' or null if no match is found.

```APIDOC
## findProxy(string $class): ?string

### Description
Finds the first registered procedure that matches the given class name and implements the Proxy interface. It returns the FQCN suffixed with '@__invoke' or null if no match is found.

### Method
findProxy

### Parameters
- `$class` (string) - Required - The class part extracted from the request `method`.

### Returns
- `?string` - FQCN of the first matching `Proxy` procedure suffixed with `@__invoke`, or `null`.

### Behavior
Filters registered procedures by `Procedure::$name === $class` and `is_subclass_of($procedure, Proxy::class)`, returns the first hit — no method check. Used by `findProcedure()` as a fallback.
```

--------------------------------

### findProcedure(Request $request): ?string

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Resolves the FQCN of the procedure and method for a given request. It splits the method on the delimiter, matches procedures by name and public method, and falls back to a Proxy implementation if available.

```APIDOC
## findProcedure(Request $request): ?string

### Description
Resolves the FQCN of the procedure and method for a given request. It splits the method on the delimiter, matches procedures by name and public method, and falls back to a Proxy implementation if available.

### Method
findProcedure

### Parameters
- `$request` (\Sajya\Server\Http\Request) - Required - The request whose `method` (`"{name}{delimiter}{method}"`) is resolved.

### Returns
- `?string` - The FQCN of the matched procedure suffixed with `@methodName` (e.g. `App\Http\Procedures\MathProcedure@subtract`), or `null` when no procedure/method matches and no `Proxy` fallback exists.

### Resolution order
1. Split `method` on `$this->delimiter` (both class and method parts).
2. Procedures whose `Procedure::$name` equals the class part **and** that have a public method with the method part name.
3. Otherwise the first procedure whose `$name` matches and that implements `Proxy` (mapped to `@__invoke`).

### Example
```php
use Sajya\Server\Http\Request;

$request = (new Request)->setId(1)->setMethod('fixture@subtract')->setParams([42, 23])->setVersion('2.0');
$app->findProcedure($request); // "Tests\FixtureProcedure@subtract"
$app->findProcedure((new Request)->setMethod('nope@nope')); // null
```
```

--------------------------------

### Register GzipCompress middleware on rpc route

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/gzip-compress.md

Shows basic usage and parameterized middleware with explicit compression level ':9'. Attach to an rpc route in a service provider or routes file.

```php
use Sajya\Server\Middleware\GzipCompress;

// In a route service provider or routes file:
Route::rpc('/api/rpc', [\App\Http\Procedures\MathProcedure::class])
    ->middleware(GzipCompress::class)
    ->name('rpc.api');

// with an explicit compression level via parameterized middleware:
Route::rpc('/api/rpc', [\App\Http\Procedures\MathProcedure::class])
    ->middleware(GzipCompress::class.':9')
    ->name('rpc.api');
```

--------------------------------

### getMethod(): ?string

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Returns the requested method name in the format '{procedure}@{method}'. Returns null if not set.

```APIDOC
## getMethod(): ?string

### Description
Returns the requested method name in the format '{procedure}@{method}'. Returns null if not set.

### Method
getMethod

### Returns
- **?string** — The method name or null.
```

--------------------------------

### isBatch(): bool

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-parser.md

Determines whether the payload is a non-empty JSON array (list), indicating a batch request.

```APIDOC
## isBatch(): bool

### Description
Determines whether the payload is a non-empty JSON array (list), indicating a batch request.

### Method
isBatch

### Returns
- **bool** - Whether the payload is a non-empty JSON array (list).

```

--------------------------------

### Composer extra.laravel configuration

Source: https://github.com/sajya/server/blob/master/_autodocs/configuration.md

Declares the ServerServiceProvider for auto-discovery and registers the RPC facade alias. Required for the package to be recognized by Laravel.

```json
"extra": {
    "laravel": {
        "providers": [
            "Sajya\\Server\\ServerServiceProvider"
        ],
        "aliases": {
            "RPC": "Sajya\\Server\\Facades\\RPC"
        }
    }
}
```

--------------------------------

### getParams(): Collection

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Returns the request parameters as an Illuminate Collection.

```APIDOC
## getParams(): Collection

### Description
Returns the request parameters as an Illuminate Collection.

### Method
getParams

### Returns
- **Illuminate\Support\Collection** — The request parameters.
```

--------------------------------

### RpcException::__construct

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/rpc-exception.md

Constructor for the RpcException base class. Initializes the exception with optional message, code, and previous exception, falling back to class defaults.

```APIDOC
## RpcException::__construct

### Description
Constructor for the RpcException base class. Initializes the exception with optional message, code, and previous exception, falling back to class defaults.

### Method
`__construct`

### Signature
`public function __construct(?string $message = null, ?int $code = null, ?RuntimeException $previous = null)`

### Parameters
- `$message` (?string) - Optional - Overrides the class default message.
- `$code` (?int) - Optional - Overrides the class default code.
- `$previous` (?RuntimeException) - Optional - Chained previous exception.

### Returns
`void`
```

--------------------------------

### Handle RPC request and check for error

Source: https://github.com/sajya/server/blob/master/_autodocs/errors.md

Use the App::handle() method to process a JSON-RPC request and inspect the response for errors. The response is always HTTP 200; check isError() and getError() to retrieve the exception instance.

```php
use Sajya\Server\App;
use Sajya\Server\Http\Response;

$app = new App([MyProcedure::class]);

/** @var Response $response */
$response = $app->handle('{"jsonrpc":"2.0","method":"calc@div","params":{"a":1,"b":0},"id":1}');

if ($response->isError()) {
    $error = $response->getError(); // instance of Sajya\Server\Exceptions\... 
    // \Sajya\Server\Exceptions\RuntimeRpcException: code 0, message "Division by zero"
}
```

--------------------------------

### findProcedure() with Request

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/app.md

Builds a Request object and calls findProcedure() to resolve a method. Returns the FQCN suffixed with @methodName, or null when no match.

```php
use Sajya\Server\Http\Request;

$request = (new Request)->setId(1)->setMethod('fixture@subtract')->setParams([42, 23])->setVersion('2.0');
$app->findProcedure($request); // "Tests\FixtureProcedure@subtract"
$app->findProcedure((new Request)->setMethod('nope@nope')); // null
```

--------------------------------

### setVersion(string $version): self

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-response.md

Sets the JSON-RPC version string. Returns the current instance for chaining.

```APIDOC
## setVersion(string $version): self

### Description
Sets the JSON-RPC version string. Returns the current instance for chaining.

### Method
setVersion

### Parameters
- **$version** (string) - Required - Version string.

### Returns
- **self** - The current instance.
```

--------------------------------

### Resolve bindings with bindResolve()

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/binding.md

Resolves method parameters from the request params collection, applying registered binders and deep key lookup. Returns key/value pairs filtered for truthiness, ordered by reflected parameter order.

```php
use Illuminate\Support\Collection;
use Sajya\Server\Binding;
use Sajya\Server\Facades\RPC;

/** @var Binding $binding */
$binding = app(Binding::class);

RPC::bind('qty', fn ($value) => max(0, (int) $value));   // clamp negatives to 0

$params = new Collection(['name_deep_value' => 'x', 'qty' => -5]);
$args = $binding->bindResolve('App\Http\Procedures\ReportProcedure@deepValue', $params);
// ['nameDeepValue' => 'x', 'qty' => 0]
```

--------------------------------

### Constructor override of code/message and debug mode trace

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/rpc-exception.md

Shows how RuntimeRpcException accepts explicit message and code in its constructor, overriding the defaults. Also demonstrates that when debug mode is enabled, json_encode adds file, line, and trace details to the serialized exception.

```php
use Sajya\Server\Exceptions\RuntimeRpcException;

$e = new RuntimeRpcException('Custom failure', 1001);
json_encode($e);
// {"code":1001,"message":"Custom failure","data":null}

// debug mode adds trace detail:
config(['app.debug' => true]);
json_encode(new MethodNotFound);
// {"code":-32601,"message":"Method not found","data":null,"file":"...","line":...,"trace":"..."}
```

--------------------------------

### bind(string $key, $binder): void

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/binding.md

Registers a custom binder for a procedure parameter. The binder is invoked through the container with the parameter value and current route.

```APIDOC
## bind(string $key, $binder): void

### Description
Registers a custom binder. At resolution time the binder is invoked through the container with `['value' => $value, 'route' => Route::current()]`.

### Method
`bind`

### Parameters
- `$key` (string) - Required - Procedure method parameter name.
- `$binder` (Closure|string) - Required - Callback or callable class/string, registered via `RouteBinding::forCallback($this->container, $binder)`.

### Returns
`void`

### Example
```php
use Sajya\Server\Facades\RPC;

RPC::bind('a', fn ($value) => (int) $value * 2);
```
```

--------------------------------

### new Request()

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Creates a new JSON-RPC 2.0 request value object with empty params and version '2.0'.

```APIDOC
## Constructor

### Description
Creates a new JSON-RPC 2.0 request value object with empty params and version '2.0'.

### Method
`__construct`

### Signature
`public function __construct()`

### Parameters
None.

### Returns
`Request` with `params = collect()` and `version = '2.0'`.
```

--------------------------------

### POST {uri} - JSON-RPC Endpoint

Source: https://github.com/sajya/server/blob/master/_autodocs/endpoints.md

The only HTTP entry point into the JSON-RPC engine. It accepts a JSON-RPC 2.0 request (single or batch) and returns a JSON-RPC response. The route is registered via the Route::rpc() macro and handled by JsonRpcController.

```APIDOC
## [POST] {uri}

### Description
Accepts a JSON-RPC 2.0 request (single or batch) and returns a JSON-RPC response. The route is registered via the Route::rpc() macro and handled by JsonRpcController.

### Method
POST

### Endpoint
{uri} (user-supplied, e.g., /point, /api/rpc)

### Parameters
#### Request Body
- **jsonrpc** (string) - Required - Must be exactly "2.0".
- **method** (string) - Required - "{procedureName}{delimiter}{publicMethod}", e.g., fixture@subtract.
- **params** (array) - Optional - Positional or named parameters.
- **id** (string | int | null) - Optional - Omit for a notification (no response).

For batch requests, the body is a JSON array of the above objects.

### Request Example
{"jsonrpc": "2.0", "method": "fixture@subtract", "params": [42, 23], "id": 1}

### Response
#### Success Response (200)
- **jsonrpc** (string) - "2.0" (omitted when Response::getVersion() is null).
- **result** (mixed) - Present when no error.
- **error** (object) - Present when an error occurred; contains code (int), message (string), data (mixed). With debug mode, extra keys file, line, trace appear.
- **id** (string | int | null) - Echoes the request id (null for parse errors / invalid requests).

#### Response Example
{"id": "1", "result": 19, "jsonrpc": "2.0"}

#### Error Response Example
{"id": "1", "error": {"code": -32602, "message": "Invalid params", "data": {"params": ["The params field must be an array."]}}, "jsonrpc": "2.0"}

### Notes
- HTTP status is always 200; errors are transported in the body.
- Batch size limit: if the batch count exceeds config('sajya.max_batch_size', 50), the whole batch is answered with a single -32000 "Maximum batch size exceeded." error response.
- Content-Type: application/json (not enforced by the controller).
```

--------------------------------

### __invoke method behavior

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/json-rpc-controller.md

Exact behavior of the __invoke method: creates an App instance, handles the request content, and returns a JSON response with status 200 and configurable encode options. The response is always HTTP 200 even for RPC errors.

```php
$application = new App($procedures, $delimiter);
$response = $application->handle($request->getContent());
return response()->json($response, 200, [], config('sajya.encode_options', 0));
```

--------------------------------

### Request::loadArray()

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-request.md

Static factory that builds a Request from a decoded JSON-RPC array, mapping keys to setters and ignoring unknown keys.

```APIDOC
## Static Factory

### Description
Builds a `Request` instance from a decoded JSON-RPC request array. For each key, calls the matching setter if it exists (`set` + `ucfirst($key)`); `jsonrpc` explicitly calls `setVersion($value)`. Unknown keys are ignored.

### Method
`loadArray`

### Signature
`public static function loadArray(array $collection): Request`

### Parameters
- **$collection** (array) - Required - Decoded JSON-RPC request: `jsonrpc`, `method`, `params`, `id`.

### Returns
`Request`

### Example
```php
$request = Request::loadArray([
    'jsonrpc' => '2.0',
    'method'  => 'math@sum',
    'params'  => ['a' => 1],
    'id'      => 9,
]);
$request->getMethod();   // "math@sum"
$request->getId();       // "9"
```
```

--------------------------------

### __invoke(Request $request, array $procedures, ?string $delimiter = null): JsonResponse

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/json-rpc-controller.md

Handles an incoming HTTP request for a JSON-RPC route. It builds an App from the provided procedures and delimiter, processes the raw request body, and returns a JSON response with HTTP status 200.

```APIDOC
## __invoke(Request $request, array $procedures, ?string $delimiter = null): JsonResponse

### Description
Handles an incoming HTTP request for a JSON-RPC route. It builds an App from the provided procedures and delimiter, processes the raw request body, and returns a JSON response with HTTP status 200.

### Method
__invoke

### Endpoint
N/A (Controller method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **$request** (Illuminate\Http\Request) - Required - The incoming HTTP request; only `getContent()` is used.
- **$procedures** (string[]) - Required - Injected from route default `procedures` (the array passed to the `rpc` macro).
- **$delimiter** (?string) - Optional - Injected from route default `delimiter`; `null` → config fallback inside `App`.

### Request Example
```php
$httpRequest = Request::create('/point', 'POST', [], [], [], [], '{"jsonrpc":"2.0","method":"math@sum","params":{"a":1,"b":2},"id":1}');
```

### Response
#### Success Response (200)
- **status** (int) - HTTP status code, always 200.
- **header('content-type')** (string) - Content-Type header, typically `application/json`.
- **getData(true)** (array) - Decoded JSON response body.

#### Response Example
```json
{"id":"1","result":3,"jsonrpc":"2.0"}
```

### Error Handling
- Propagates `abort(500, ...)` from `App::__construct()` if a procedure class does not extend `Procedure`.
- RPC errors are encoded in the JSON body; no other exceptions escape.
```

--------------------------------

### curl request with Accept-Encoding: gzip

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/gzip-compress.md

Client requests gzip compression. The response is 200 OK with Content-Encoding: gzip and the compressed JSON-RPC body.

```bash
curl -H "Content-Type: application/json" \
     -H "Accept-Encoding: gzip" \
     --data '{"jsonrpc":"2.0","method":"math@sum","params":{"a":1,"b":2},"id":1}' \
     http://localhost/api/rpc --compressed
# 200 OK, Content-Encoding: gzip, body: {"id":"1","result":3,"jsonrpc":"2.0"}
```

--------------------------------

### Register custom binder with RPC::bind()

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/binding.md

Registers a custom binder for a parameter. The binder is invoked with ['value' => $value, 'route' => Route::current()] at resolution time.

```php
use Sajya\Server\Facades\RPC;

RPC::bind('a', fn ($value) => (int) $value * 2);
```

--------------------------------

### getResult()

Source: https://github.com/sajya/server/blob/master/_autodocs/api-reference/http-response.md

Returns the result value of the response.

```APIDOC
## getResult()

### Description
Returns the result value of the response.

### Method
getResult

### Returns
- **mixed** - The result value.
```
Tokens:
Raw