Server Laravel Package

Getting Started

• Install with composer require sajya/server and publish the config (php artisan vendor:publish --provider="Sajya\Server\ServiceProvider"). You get config/sajya.php, which is the first file to read: it holds the route prefix (default rpc), middleware, optional domain, and the procedure bindings map.
• The package exposes one JSON‑RPC 2.0 endpoint (POST /rpc by default). Everything—method routing, batching, notifications—goes through that single URL, so there is no per-procedure routing to learn.
• Scaffold your first procedure with php artisan make:procedure MathProcedure, then register it in config/sajya.php under bindings (or rely on the documented discovery mechanism if you prefer). A procedure is a class extending Sajya\Server\Procedure with a static $name (e.g. math) and public methods that become callable as math@add.
• First use case: a single procedure + a single call. POST {"jsonrpc":"2.0","method":"math@add","params":{"a":2,"b":3},"id":1} and expect {"jsonrpc":"2.0","result":5,"id":1}. Get that round-trip working (route middleware included) before adding validation, auth, or batches.

Implementation Patterns

• Method addressing is procedure@method. Keep procedure names short and stable (user, billing, math) because they are part of your public contract; treat procedure@method as an API route name you would not rename casually.
• Parameter binding maps the params object onto method arguments by name. Type-hint scalars/arrays on the method signature and let PHP coerce; for structured input, accept an array or a dedicated DTO and validate inside the method with the Laravel Validator facade (or a FormRequest-style service class) so failures come back as proper JSON-RPC errors rather than PHP errors.
• Registration: the bindings array in config/sajya.php is the source of truth. Group by domain ('user' => UserProcedure::class) and keep the file small; split large APIs into multiple procedures rather than one god-procedure with 40 methods.
• Auth and throttling belong on the route: set 'middleware' => ['api', 'auth:sanctum', 'throttle:60,1'] in the config, then read the caller via the injected request/auth() inside the procedure. Because it is one endpoint, per-method authorization must be done explicitly inside the method (policies/gates), not via route middleware.
• Error handling: throw Sajya\Server\Exceptions\RpcException (with your own code and data payload) for expected domain failures. Reserve generic exceptions for genuine bugs—they surface as internal errors and are useless to clients. Define a small enum of application error codes and reuse it across procedures; this is the closest thing the package has to a shared error contract.
• Batching and notifications come free: send an array of call objects for a batch, and omit id for fire-and-forget notifications. Use batches when a screen needs several independent lookups, but keep them small—one slow method stalls the whole response.
• Versioning: when a contract changes, add a new procedure (userV2) or a new method rather than mutating an existing one. Bindings make this cheap, and old clients keep working.
• Testing: write plain HTTP tests—$this->postJson('/rpc', [...])->assertJsonPath('result', ...)—including a test for each error code and one for an unknown method (-32601). These tests are the main defence against accidental renames of procedure@method.
• Laravel 13.x: 7.1.0 adds compatibility. If you are on Laravel 13, pin ^7.1; on older Laravel versions stay on the prior major/minor line and upgrade deliberately, since this package tracks the framework closely.

Gotchas and Tips

• Every public method is callable. A public helper on your procedure class is exposed as procedure@helper to the outside world. Make helpers private/protected. This is the single most common mistake with this package.
• Argument names are the API. Renaming a method parameter silently breaks clients even though PHP tooling and static analysis report nothing. Cover each method with a happy-path HTTP test so renames fail CI.
• Missing id means no response body. Notifications return an empty 200-ish response. If a client "hangs", check that it sent an id. Conversely, batching notifications with requests returns only results for the requests.
• Config cache. bindings are read from config; after editing, run php artisan config:clear in local/dev, and remember config:cache in deploy pipelines or new procedures will 404 with "method not found".
• IS_INSTANCEOF attribute lookups (7.1.0). Attribute retrieval now matches subclasses, not just exact classes. Practical effect: a custom attribute that extends a package attribute now applies to your methods where it previously did not—handy for building your own annotations, but it can change behavior in code that relied on exact-class matching. If you have custom attributes or override attribute handling, add a test asserting which methods pick them up.
• Middleware order matters. Global api middleware plus an auth middleware that returns HTML redirects will produce a non-JSON-RPC body on 401; configure auth to return JSON (or add a JSON-aware exception handler) or clients will fail to parse the error.
• Debugging: log the raw request body in a middleware when a call misbehaves—JSON-RPC failures are hard to diagnose from the error alone. -32600 (invalid request), -32601 (method not found) and -32602 (invalid params) each point to a different layer: payload shape, binding name, or method signature.
• Extension points: subclass Sajya\Server\Procedure for shared behavior (logging, permission checks) across all your procedures, and centralise error-code mapping in one place rather than throwing ad-hoc codes per method. Those two hooks cover most of what teams end up wanting to customise.
• The rest of 7.1.0 is CI/dependency housekeeping (checkout, cache, auto-commit actions); no runtime changes beyond the attribute lookup and Laravel 13 support. A patch-level bump is safe, but re-run your procedure tests after upgrading to confirm attribute-driven behavior is unchanged.