Sajya Server

To customize the behavior of the JSON-RPC server, you can publish the default configuration file to your application's config directory.

php artisan vendor:publish --tag=config

If you need to customize the views used by the package, you can publish them to resources/views/vendor/sajya using the views tag.

php artisan vendor:publish --tag=views

The InternalErrorException is a specific type of RpcException used to signal internal server errors within the JSON-RPC protocol. When this error is encountered, it follows the standard JSON-RPC error code for internal errors.

Error Details:

• JSON-RPC Error Code: -32603
• Default Message: Internal error
• Data: Can optionally contain additional error context via the $data parameter.

The Sajya\Server\Exceptions\InvalidParams exception is thrown when request parameters fail validation. It is a specialized RpcException that follows the JSON-RPC error specification. When caught, it provides a standard error code and message.

Error Details:

• Code: -32602 (Standard JSON-RPC code for 'Invalid params')
• Message: 'Invalid params'
• Data: Can contain additional context or details about the specific validation failure via the $data parameter.

The Request class provides fluent setter methods to configure the properties of a JSON-RPC request. Most setters return $this to allow for method chaining.

• setMethod(string $name): Sets the name of the requested method.
• setParams(array $params): Merges new parameters into the existing params collection.
• setId($name): Sets the request identifier (cast to a string).
• setVersion(string $version): Sets the JSON-RPC version (defaults to '2.0').

use Sajya\Server\Http\Request;

$request = (new Request())
    ->setMethod('sum')
    ->setParams(['a' => 1, 'b' => 2])
    ->setId(123)
    ->setVersion('2.0');

The Request class implements JsonSerializable. When serialized (e.g., via json_encode()), it produces a JSON object containing the jsonrpc version, the method, and optionally the params and id if they are present.

$request = (new Request())->setMethod('ping')->setId('abc');

echo json_encode($request);
// Output: {"jsonrpc":"2.0","method":"ping","id":"abc"}

The Sajya\Server\App class is the main entrypoint for managing JSON-RPC requests. You initialize it by providing an array of procedure classes and an optional delimiter.

Constructor Parameters

• array $procedures: An array of class names. Each class must extend Sajya\Server\Procedure.
• ?string $delimiter: The character used to separate the procedure name from the method name in the JSON-RPC method string. If not provided, it defaults to @ or the value configured in config('sajya.delimiter').

If a class provided in $procedures does not extend Procedure, the application will abort with a 500 error.

use Sajya\Server\App;

// Initialize with specific procedures and a custom delimiter
$app = new App([
    App\Procedures\UserProcedure::class,
    App\Procedures\OrderProcedure::class,
], ':');

In JSON-RPC, a notification is a request that does not include an id. You can determine if the current Request instance is a notification by calling isNotification(), which returns true if the request ID is empty.

if ($request->isNotification()) {
    // Handle as a notification (no response expected)
}

The terminate() method handles the request processing and then triggers the Laravel application termination process. This is useful for ensuring the JSON-RPC response is returned while allowing the underlying framework to clean up.

Parameters

• string $content: The raw JSON-RPC request content.

Returns

• Sajya\Server\Http\Response[]|Sajya\Server\Http\Response|null

$app->terminate($request->getContent());

The makeFromResult() static method is the primary way to instantiate a Response object. It automatically synchronizes the response's id and version with the provided Request object, ensuring the response matches the incoming RPC call. If no Request is provided, a new instance is created.

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

// Assuming $result is the data you want to return
$response = Response::makeFromResult($result, $request);