Remote Procedure Call (RPC) Plugin
The RPC plugin provides an easy way to implement a Remote Procedure Call API. The plugin uses JSON-RPC protocol version 2. You can read the specification here.
The RPC plugin is a system plugin. The class RpcPlugin extends JimboPlugin.
The RPC entry point sets the RPC plugin as the system plugin with Core::setSystemPlugin(). See the example in install/rpc/rpc.php.
Install
RPC Plugin is dependent on Jimbo.
- Check the Jimbo plugin has been installed
- Add the plugin:
git submodule add [email protected]:FestiSystemPlugins/php_festi_plugin_rpc.git plugins/Rpc - Run dump from install folder
- Add area and rule
And add this rule toINSERT INTO festi_url_areas (ident) VALUES ('rpc'); INSERT INTO festi_url_rules (plugin, pattern, method) VALUES ('Rpc', '~^/rpc/(.*)$~', 'onJsonCallMethod');festi_url_rules2areasfor arearpc - Call RPC method
syncRpcMethods - Configure permission section
- Add column
access_tokento users table - Configure
index.phpand.htaccess. Examples can be found ininstall/rpc/ - Add composer package
festi-team/festi-framework-serialization
Upgrading
The files in install/rpc/ are templates. The install copies them into the project (step 8 above).
An upgrade of the plugin does not change the copies of a project.
After each upgrade of the plugin, read the file UPGRADING.md in the repository of the plugin.
It lists the changes that you must make in the copied files and in the log files, and the steps for a product whose clients send the calls below.
A product that upgrades can see these changes in the answers of execUrl:
- A call whose
datanames two stores or more, when one store refuses its entry: the plugin refuses the call as a whole, and no store is changed. - A call whose
datanames two stores or more of a page without a stage: the writes of the stores are one transaction. When the action of one store ends with an error, the plugin undoes the writes of all the stores of the call. - A call with
idParentwhose action names a row that is not a row of that parent row, or a row that does not exist: the plugin refuses the call with aPermissionsException(code 403), and nothing is written. An RPC call is an API call that a client makes with a token, so it must not change or move a row of a different parent row. - A call for a child store with no
idParent, or with anidParentthat is an empty text or0: the plugin refuses each action butlistwith aPermissionsException(code 403), and nothing is read or written. A client that did not sendidParentmust send it now. See the example in Rows of a parent row. - A call of a client that keeps its PHP session between two calls: a store works only with the
idParentof that call. A list of a child store with noidParentgives the way to the parent store, and the plugin does not use the parameter__ctxof a url or the member__tokenofdata. See A client that keeps its session. - A call with no
idParentfor a store that holds a tree (the parent of a row is a row of the same store): the plugin refuses each action, alsolist, with aPermissionsException(code 403). For the rows of the first level, send an empty text asidParent. The same is true for a call for a different store of a page with no stage that shows such a store. See A store whose parent is a row of the same store. - A call with the action
csvImportfor a child store or for a store that holds a tree: the plugin refuses it with aPermissionsException(code 403), with eachidParentand with none. See Actions for more than one row. -
A call for a store whose link to the parent is also a field: the plugin writes the
idParentof the call into the link, and it refuses a call that sends a different value for that field with aPermissionsException(code 403). See A link that is also a field. -
A call through the entry point uses no PHP session. A client that sends a session cookie gets the answers of a client that sends none: the plugin keeps no value between two calls (for example the page, the rows for each page, the order and the filters of a list), and a call leaves no signed-in user in the session. See A client that keeps its session.
-
A refusal of permission through the JSON-RPC endpoint: the client gets an error with the code 403 and the text of the refusal, and the HTTP status 403 for one call. This is true for each refusal of
execUrlof this list and for aPermissionsExceptionof a tool of a product. A fault of the server stays the code 500 with the messageInternal Error. See Errors of a call.
See More than one store in one call and Rows of a parent row.
Authentication
Store the access token of each user in the access_token column of the users table.
The plugin reads the token from one of these two sources. It reads the header first.
- The
X-Authorizationheader. Use this method in production:X-Authorization: XXX - The GET parameter
token. Use this method only for development:https://RPC_HOST/?token=XXX
Warning: Do not use the GET parameter
tokenin production. A URL with a token stays in the web server logs, the proxy logs and the browser history. The browser can also send the URL to other sites in theRefererheader. Thus other persons can read the token and call the RPC methods as the user.
The plugin does not block the GET parameter token. It accepts the parameter in each environment.
Make sure that each production client sends the token only in the X-Authorization header.
Each call needs its token. A call uses no PHP session: the plugin does not take the user from a session cookie, and a call does not sign a browser in. See A client that keeps its session.
The logs of the plugin also hold a token that a client sends in the GET parameter token: the framework adds the URL of the HTTP request to each entry of the logs rpc_errors and rpc, and the mail for SUPPORT_MAIL holds the entry of the log rpc. A sign-in that fails makes such an entry. See the limits in "Errors log" and "Log of the entry point".
Request
You can send parameters using an array or object:
{"jsonrpc":"2.0", "method":"getScraperActions", "params":["linkedin"], "id":1}
{"jsonrpc":"2.0", "method":"getScraperActions", "params":{"ident":"linkedin"}, "id":1}
If you use an object, please ensure that the key name matches the parameter name in the RPC method annotation.
The RPC plugin supports batch requests:
[
{"jsonrpc":"2.0","method":"getScraperActions","params":["linkedin"],"id":1},
{"jsonrpc":"2.0","method":"getScraperActions","params":{"ident":"google"},"id":2}
]
For easy debugging, you can use the GET parameter rawRequest:
https://RPC_HOST/?rawRequest={"jsonrpc":"2.0","method":"syncRpcMethods"}
RPC Method Implementation
Define RPC methods with the #[RpcAttribute] (preferred) or the @rpc doc-tag.
Preferred — #[RpcAttribute]:
use Plugins\Rpc\Domain\Attribute\RpcAttribute;
use core\plugin\attribute\SectionAttribute;
class ScraperPlugin extends DisplayPlugin
{
#[RpcAttribute('getScraperActions')]
#[SectionAttribute('scraper')]
public function getActionsByIdent(string $ident): array
{
...
}
}
RpcAttribute is non-repeatable and targets methods only. The optional constructor argument advertises the method under a custom RPC name; without it the bare attribute mirrors a bare @rpc and the real method name is used.
Legacy — @rpc doc-tag:
class ScraperPlugin extends DisplayPlugin
{
/**
* @rpc getScraperActions
* @param string $ident
* @section scraper
* @return array
*/
public function getActionsByIdent(string $ident): array
{
...
}
}
If @rpc doesn't have a name, the real method name will be used. Attribute form:
#[RpcAttribute]
public function getMentors($idUser = false): mixed
{
...
}
Doc-tag form:
/**
* @rpc
* @param bool $idUser
* @return mixed
* @throws PermissionsException
*/
public function getMentors($idUser = false)
{
...
}
You can use on* methods and methods with DGS as well. Attribute form combines RpcAttribute with UrlRouteAttribute, AreaAttribute, and SectionAttribute:
use core\plugin\attribute\AreaAttribute;
use core\plugin\attribute\SectionAttribute;
use core\plugin\attribute\UrlRouteAttribute;
use Plugins\Rpc\Domain\Attribute\RpcAttribute;
#[RpcAttribute('getProjects')]
#[UrlRouteAttribute('~^/projects/$~')]
#[AreaAttribute('backend')]
#[SectionAttribute('manage_projects')]
public function onDisplayList(Response &$response): bool
{
$store = $this->createStoreInstance("projects");
$store->onRequest($response);
return true;
}
Doc-tag form:
/**
* @rpc getProjects
* @urlRule ~^/projects/$~
* @area backend
* @param Response $response
* @return bool
* @throws SystemException
* @section manage_projects
*/
public function onDisplayList(Response &$response)
{
$store = $this->createStoreInstance("projects");
$store->onRequest($response);
return true;
}
Parameters for the
resultwill be retrieved from theResponseobject
RPC Methods and Inheritance
syncRpcMethods scans each plugin with reflection, which includes inherited methods. An rpc-method name is globally unique (one rpc_methods row per name), so a plugin that extends another plugin (e.g. MCPServerPlugin extends RpcPlugin) must not silently re-register and fight for its parent's rpc methods. Ownership follows one rule plus the #[RpcOverride] escape hatch.
Default — owned by the declaring class
An inherited #[RpcAttribute] method you do not redeclare is not registered under the child plugin; it stays owned by the plugin that declares it. Nothing to annotate — this is automatic. (Trait methods count as declared by the using class, so traits are unaffected.)
#[RpcOverride] — replace an inherited method
Plugins are separate instances: a call is dispatched to $this->plugin->$ownerName->$method(...), so your code only runs when your plugin owns the rpc name. To replace an inherited endpoint, redeclare the entry method with the same rpc name and mark it #[RpcOverride]. The override wins ownership deterministically, regardless of plugin scan order.
use Plugins\Rpc\Domain\Attribute\RpcAttribute;
use Plugins\Rpc\Domain\Attribute\RpcOverrideAttribute;
#[RpcAttribute('execUrl')] // same rpc name as the parent
#[RpcOverrideAttribute]
public function onJsonExecUrl(Response &$response, string $url, ?array $data = null, ?string $area = null): bool
{
return parent::onJsonExecUrl($response, $url, $data, $area);
}
Because the child now owns the entry method, $this is the child instance — so any protected helper the entry method calls resolves to the child's override. Extension points must be protected, not private (private methods are not polymorphic, so a parent:: call still binds the parent's privates), and the entry method must not be private.
#[RpcOverride]is attribute-only (no@rpcOverridedoc-tag): the doc-tag scanner matches@rpcbefore a longer@rpc…name, so a doc-tag form would be misread.
Ambiguous ownership is a hard error. If two plugins claim the same rpc name and neither is marked #[RpcOverride] (or both are), syncRpcMethods throws Duplicate rpc method '<name>' declared by <A> and <B> — mark the replacing one with #[RpcOverride]. instead of silently picking an order-dependent owner.
Working with DGS over RPC
A backend page that renders one or more DGS can be driven entirely over RPC: introspect its stores with getSchemeByUrl, then read or write rows with execUrl — addressing the page by its normal @urlRule URL, with no bespoke endpoint per grid. Higher layers such as the MCP server build on this generic mechanism to expose Festi admin grids to an agent.
1. Introspect — getSchemeByUrl
Call getSchemeByUrl with a concrete page URL. It binds the page read-only and returns the schema of every store on it:
{"jsonrpc":"2.0","method":"getSchemeByUrl","params":["/projects/7/tasks/","backend"],"id":1}
Response shape (one entry per store, keyed by store name):
{
"dgs": {
"<storeName>": {
"table": {"name":"...", "primaryKey":"id"},
"fields": {"<field>": {"requestKey":"<field>", "type":"text", "multiple":false, "values":{"5":"Label"}}},
"actions": {"list":{}, "insert":{}, "edit":{}, "remove":{}},
"request": {"key":"<request.key>", "stageBlock":0, "primaryKey":"id", "parent":null}
}
}
}
request.key— the identifier you address the store by inexecUrl'sdata.request.stageBlock— the StageBuilder block the store occupies; routing is automatic, you do not send it.request.primaryKey— the row-id field name.request.parent—null, or for a child store{"field":"<link field>"}: each call ofexecUrlfor this store needs anidParent, and the plugin refuses each action butlistwithout it. For a store that holds a tree it is{"field":"<link field>","firstLevel":""}:firstLevelis theidParentfor the rows of the first level, and the plugin refuses each action without anidParent. See Rows of a parent row.- each field's
requestKey— the key to send that field's value under in a write. actions— the actions this store currently allows; a read-only grid lists onlylist. Custom actions appear here too — see Custom actions.
2. Read and write — execUrl
execUrl takes the same URL plus a data map keyed by request.key. Each entry names an action and, for writes, the field values. Omit data (or send only {"action":"list"}) to read.
Read:
{"jsonrpc":"2.0","method":"execUrl","params":["/projects/7/tasks/",{"<request.key>":{"action":"list"}},"backend"],"id":1}
Filter a list — send filter with the list action. Key each filter by the field name from the scheme (the <request.key>_<field> key of the list form also works). Only a field that has a filter in the scheme can be filtered. Send a range filter as [from, to], and leave one end empty for an open range. A select filter takes one value of the field; a text filter finds the text in the value (for a foreignKey, in its label):
{"<request.key>":{"action":"list","filter":{"date_from":["2026-05-01","2026-05-31"],"status":"accepted"}}}
Insert — action plus field values:
{"<request.key>":{"action":"insert","caption":"Review","priority":2}}
Edit — send the uppercase row ID plus only the fields you change (a partial update). An omitted
field, files included, keeps its stored value; send a field empty ("", [] for many2many) to clear it.
An insert or an edit does not write a readonly field (a field of the type readonly or with the option readonly): the plugin ignores a value that the call sends for it, and an edit does not put its stored value into the update:
{"<request.key>":{"action":"edit","ID":42,"caption":"Review"}}
Remove — only the uppercase ID:
{"<request.key>":{"action":"remove","ID":42}}
More than one store in one call
data can name more than one store of the page. The plugin examines each entry before it runs one: the store must have the action of the entry, and the state of the row must permit that action. If the plugin refuses one entry, the call ends with the error of that entry and no store is changed.
{"<request.key of the first store>":{"action":"insert","caption":"Review"},"<request.key of the second store>":{"action":"remove","ID":42}}
On a page that shows its stores without a stage, each store that data names runs its action, in the order of the page. The stores write in one transaction:
- If each action ends without an error, the transaction is kept. The response is the response of the store that the page runs last.
- If the action of one store ends with an error, the plugin undoes the writes of all the stores of the call. The response has the
statuserror. Itsmessagestarts withNo store was changed.and gives the action, the store and the error. - If the page raises an exception, the plugin undoes the writes, and the call ends with that exception.
A listener of Store::EVENT_AFTER_UPDATE runs when its store has written, before the transaction ends. A later store of the same call can still undo that write. Use Store::EVENT_COMMIT and Store::EVENT_ROLLBACK for work that depends on the result of the call.
The transaction is the transaction of the connection of the stores. The plugin does not undo a write of a store that has a different connection. If the connection has a transaction before the call, the plugin does not end it: the code that started it ends it, and the message of an error does not start with No store was changed.
On a page with a stage, only the first store that data names runs its action. Send one call for each store of a stage.
Rows of a parent row
A child store holds the rows of one row of a parent store, for example the tasks of one project. In the scheme, such a store has the member request.parent with the field that links a row to its parent. Send the id of the parent row as the parameter idParent in each call of execUrl for the page of that store:
{"jsonrpc":"2.0","method":"execUrl","params":["/projects/tasks/",{"<request.key>":{"action":"list"}},"backend","7"],"id":1}
- A list gives the rows of that parent row.
- An insert writes
idParentinto the link of the new row. - An action for one row (an edit, a remove, the values of a row, an edit of one cell, a download, a relation action, a custom action, a link action) runs only for a row of that parent row. The plugin reads the stored row and compares its link with
idParentbefore the action runs.
A store is a child store when its model has the action parent and the parent relation that this action names, with a field. A store in a block of a stage, a store with a relation but no action parent, and a store with a foreign key field are not child stores for that reason alone. The page can change the model of its store, so read request.parent in the scheme of the page: it is null for a store that has no parent, and a call for such a store does not need idParent.
A call with no idParent
A call for a child store that has no idParent is refused, because the plugin cannot tell which parent row the call is for. This call ends with an error:
{"jsonrpc":"2.0","method":"execUrl","params":["/projects/tasks/",{"<request.key>":{"action":"edit","ID":42,"caption":"Review"}},"backend"],"id":1}
The error is a PermissionsException with the code 403. The plugin does not read the row, and nothing is written:
Action `edit` of `tasks` needs an `idParent`. `tasks` is a child store: each record of it is a record of one parent record. Call execUrl with the `idParent` of that parent record.
Code of a product that calls the method onJsonExecUrl() gets this exception. A client of the JSON-RPC endpoint gets an error with the code 403 and this text (see Errors of a call):
{"jsonrpc":"2.0","error":{"code":403,"message":"Action `edit` of `tasks` needs an `idParent`. `tasks` is a child store: each record of it is a record of one parent record. Call execUrl with the `idParent` of that parent record."},"id":1}
This is the same for each refusal of this section. The class, the code and the text of the exception are also in the errors log.
Send the same call with the id of the parent row of the row:
{"jsonrpc":"2.0","method":"execUrl","params":["/projects/tasks/",{"<request.key>":{"action":"edit","ID":42,"caption":"Review"}},"backend","7"],"id":1}
These rules apply to a call with no idParent:
- Each action but
listis refused: each action for one row, an insert, and each other action of the store (for example an export). - The action
listis not refused. It gives no rows: the response has aurl, which is the way to the parent store. getSchemeByUrlis not refused, so a client can readrequest.parentbefore it knows a parent row.- An
idParentthat is an empty text or0is noidParent. For a store that holds a tree, an empty text names the first level: see A store whose parent is a row of the same store. - The answer is the same for a row that exists and for a row that does not exist.
- When
datanames more than one store and one of them is a child store, the call is refused as a whole.
A row of a different parent row
If the row of the call is not a row of the parent row that idParent names, the call ends with a PermissionsException with the code 403, and nothing is written:
Record `42` of `tasks` is not available for the `idParent` `7`. Call execUrl with the list action and this `idParent` to get the records of that parent.
The answer is the same for a row that does not exist, so a caller cannot learn from it if a different parent row has a row with that id.
The plugin compares idParent with the stored link as two texts. Write idParent as a list answer gives the id of the parent row: 7. A different form of the same number (07, 7.0, +7, 7, 7e0) is not the same text, and the row is refused.
A store whose parent is a row of the same store
In a store that holds a tree (for example folders in folders), the parent of a row is a row of the same store, and the rows of the first level have no parent row. In the scheme, request.parent of such a store has the member firstLevel. The store has the rules of a child store, and these rules for the first level:
- For the rows of a parent row, send the id of that row as
idParent. - For the rows of the first level, send an empty text as
idParent:
{"jsonrpc":"2.0","method":"execUrl","params":["/folders/",{"<request.key>":{"action":"list"}},"backend",""],"id":1}
A list then gives the rows whose link is empty (NULL), and an insert makes a row of the first level. An action for one row runs only for a row whose stored link is NULL. For each other row, and for a row that does not exist, the call ends with a PermissionsException with the code 403, and nothing is written:
Record `42` of `folders` is not available for the first level. Call execUrl with the list action and an empty text as the `idParent` to get the records of the first level.
- Only an empty text that the call sends names the first level. A call with no
idParent(no member inparams, or JSONnull) is refused for each action, also forlist, and nothing is written. AnidParent0is noidParent:
Action `list` of `folders` needs an `idParent`. `folders` holds a tree: each record of it is a record of one parent record or a record of the first level. Call execUrl with the `idParent` of that parent record, or with an empty text as the `idParent` for the records of the first level.
- A page with no stage runs each of its stores, and a store that
datadoes not name runs its list. Thus a call for a different store of such a page is refused in the same way when the page shows a store that holds a tree and the call has noidParent. On a page with a stage only the block of the store thatdatanames runs, and such a call is not refused. getSchemeByUrlis not refused.- Only a store that holds a tree has a first level. For each other child store an empty text is no
idParent.
Warning: a client that makes idParent from a variable that is not set can send an empty text. For a store that holds a tree, such a call works on the first level: its insert makes a row of the first level, and its remove deletes a row of the first level. Make sure that the client sends an empty text only when it wants the first level.
Actions for more than one row
These rules apply to a child store and to a store that holds a tree:
csv(the export) gives only the rows of the parent row of the call.batchInsertwrites theidParentof the call into the link of each new row.parent(the way to the parent store) gives no row.csvImport(the import of a file) is refused for each call, with eachidParentand with none. An import writes a row by the id of its line in the file and writes no link, so it does not keep to the rows of one parent row. The call ends with aPermissionsExceptionwith the code 403, and nothing is written:
Action `csvImport` of `tasks` is not available through execUrl. Each record of `tasks` is a record of one parent record, and an import writes a record by the id of its line in the file: it does not keep to the records of the `idParent` of the call. Call execUrl with the insert action or the edit action for each record.
Send an insert or an edit for each row, or one batchInsert for new rows.
A link that is also a field
The model of a store can have the link to the parent also as a field (in the scheme, the name of request.parent.field is then a member of fields). The link of a row that a call writes is always the parent row of the call:
- Send no value for that field. An insert, an edit and a
batchInsertwrite theidParentof the call into the link. For the first level of a store that holds a tree, they write an empty link (NULL). - A value that is the same text as
idParentis permitted. - A call that sends a different value for that field is refused, also when the value is empty. This is true for an insert, for an edit, for each row of a
batchInsertand for an edit of the cell of the link (grideditor). The call ends with aPermissionsExceptionwith the code 403, and nothing is written:
The value of `id_project` for `tasks` is not the `idParent` of the call. `id_project` is the link of a record of `tasks` to its parent record. Send no value for it: execUrl writes the `idParent` of the call into it.
To move a row to a different parent row, use a method of your product that examines the two parent rows.
A client that keeps its session
A call is signed in by its token and uses no PHP session. A client can send a session cookie with a call (a browser does it by itself). The plugin does not read the session of that cookie, and it writes nothing into it:
- The user of a call is the user of its token. A call with no token is refused, also when the session of the cookie has a signed-in user (see Authentication).
- A call leaves no signed-in user in the session. If the dashboard of your product reads the same session, a call does not sign a browser in there, and a user who signed in at the dashboard stays that user.
- A call gets no value of an earlier call. Send
idParentwith each call: a list with noidParentgives the way to the parent store, and a call with noidParentfor a store that holds a tree is refused. - A store does not keep the page, the rows for each page, the order and the filters of its last list. Send them with each list call that needs them.
- A relation action answers with a
urlthat has the parameter__ctx. The plugin removes this parameter from the request, in the url of the endpoint and in theurlof the call. To work on the rows that theurlnames, send the id of the row of the relation action asidParent. - The plugin does not use a member
__tokenofdata.
Two clients that send the same session cookie with the tokens of two users do not get the user or a value of each other.
Limits
idParent is a value that the client sends. The plugin makes sure that a row is a row of the parent row that the call names. It does not examine if the user of the call is permitted to use that parent row. If the rows of a parent row are a permission limit in your product, give the store its own examination of each row (IRowPermissionListener of the framework).
Foreign-key and many2many fields
Foreign-key and many2many fields take ids, not labels. The scheme lists the selectable ids under each field's values map ({id: label}). As with every field, send the value under the field's requestKey from the scheme — for a foreignKey that is the field name; for a many2many it is the m2m_<linkTable> key the scheme reports.
- foreignKey — send the numeric id under its
requestKey:
{"<request.key>":{"action":"insert","id_status":5}}
- many2many (
multiple: true) — send an array of ids under itsrequestKey; send[]to clear all links:
{"<request.key>":{"action":"insert","m2m_tasks_members":[12,34]}}
If a field's values is truncated (valuesTruncated: true) or absent (autocomplete field), run a list action with a filter to find the id you need.
Custom actions
list, insert, edit, and remove are the built-in actions, but a store can declare its own. The action field is just the action name, not a fixed enum — execUrl invokes whatever the store exposes. Every action the store currently allows is listed in its actions map from getSchemeByUrl; the map key is the exact string to send as action.
Two kinds of custom action appear there:
- Plugin action (
<action type="plugin" plugin="..." method="...">) — runs a plugin method against the selected row. It is keyed aspluginin the scheme. Send it with the uppercase rowID:
{"<request.key>":{"action":"plugin","ID":42}}
- Custom action class (
<action type="<?php echo MyAction::class; ?>">, a class extendingAbstractAction) — keyed under its fully-qualified class name. Send that exact string as theaction, plus whatever rowIDor field values the action reads:
{"<request.key>":{"action":"Plugins\\MyPlugin\\Domain\\Store\\Action\\MyAction","ID":42}}
- Link action (
<action type="..." link="...">) — a navigation action that points at another page rather than executing on this store. Its target URL is carried in the action'slinkattribute (exposed in the scheme), often with a%id%placeholder for the row's primary key (and%s%for other path segments). Don't drive it throughexecUrlon the current store; substitute the row id into the URL and treat the result as a new page — callgetSchemeByUrl/execUrlagainst it (or just fetch it):
link="/user/review/%id%/task/" → /user/review/42/task/
A custom action runs inside the same API-mode bind as the built-in writes — its target store's StageBuilder block is resolved from the request.key exactly as for insert/edit, so the action executes and its JSON response is captured and returned. An action that only renders an HTML view (no API/JSON output) returns nothing useful over execUrl; have the action emit a JSON response before driving it from an agent.
The JSON-RPC transport request is a POST, but introspection and stage-block discovery are read-only binds: each store is pinned to its
listaction while the page binds, so a read-only grid that drops theinsertaction is introspected without error.
Events
The RPC plugin dispatches two events during sync (when building the list of RPC methods from plugin annotations). Other plugins can listen to extend or customize method discovery and stored values.
BeforePluginAnnotationsParseEvent::TYPE
This event is triggered once per plugin, before PluginAnnotations::parse() is called for that plugin. Listeners can extend two parallel channels:
- Doc-tag annotation names — adds custom
@…tags so they are parsed from docblocks and appear in$methodInfo(e.g.mcpReadOnly,mcpDestructivefor MCP tools). - PHP 8 attribute classes — adds custom attribute classes mapped to annotation names, letting plugins declare their own attribute counterparts to those tags.
Event data:
* getPluginContext() – plugin being scanned
* getPluginAnnotations() – the PluginAnnotations instance
* getAnnotationNames() / setAnnotationNames(array) – list of doc-tag annotation names to parse (listeners can add more)
* getAttributeMap() / setAttributeMap(array) – map of FQN attribute class to annotation name (listeners can add more)
init.php:
$this->core->addEventListener(
BeforePluginAnnotationsParseEvent::TYPE,
function (BeforePluginAnnotationsParseEvent $event): void {
$names = $event->getAnnotationNames();
$names[] = 'mcpReadOnly';
$names[] = 'mcpDestructive';
$event->setAnnotationNames($names);
$attributes = $event->getAttributeMap();
$attributes[McpReadOnlyAttribute::class] = 'mcpReadOnly';
$attributes[McpDestructiveAttribute::class] = 'mcpDestructive';
$event->setAttributeMap($attributes);
}
);
PrepareRpcMethodValuesEvent::TYPE
This event is triggered once per RPC method, after the method item (plugin, method, rpc_method, params, description, etc.) is built and before it is written to the rpc_methods table. It can be used to add or change keys in the method values (e.g. is_read_only) so they are stored and available later.
Event data:
* getValues() / setValues(array) – the method row to store (mutate and set back)
* getPluginContext() – plugin
* getMethodName() – method name
* getMethodInfo() – parsed annotations for this method (including any added via BeforePluginAnnotationsParseEvent)
init.php:
$this->core->addEventListener(
PrepareRpcMethodValuesEvent::TYPE,
function (PrepareRpcMethodValuesEvent $event): void {
$values = $event->getValues();
$methodInfo = $event->getMethodInfo();
$values['is_read_only'] = array_key_exists('mcpDestructive', $methodInfo) ? 0 : 1;
$event->setValues($values);
}
);
Update RPC Methods
All RPC methods are stored in the rpc_methods table. To update them, you can call the RPC method syncRpcMethods or call the method from code:
Core::getInstance()->getPluginInstance('Rpc')->syncRpcMethods();
or
https://RPC_HOST/?rawRequest={"jsonrpc":"2.0","method":"syncRpcMethods"}
Client
- jQuery - https://github.com/Textalk/jquery.jsonrpcclient.js
let rpc = new jQuery.JsonRpcClient({ ajaxUrl: 'https://RPC_HOST/' });
rpc.call(
'getScraperActions', ['linkedin'],
function (response) {
console.log("RESULT:", response);
},
function (error) {
console.error(error);
}
);
rpc.batch(
function (batch) {
batch.call('getScraperActions', ['linkedin'], function (response) {
console.log("1", response);
}, function (error) {
console.error(error);
});
batch.call('getScraperActions', { "ident": "linkedin" }, function (response) {
console.log("2", response);
}, function (error) {
console.error(error);
});
},
function (all_result_array) { alert('All done.'); },
function (error_data) { alert('Error in batch response.'); }
);
Override Authorization Logic
init.php:
assert($this instanceof Core);
$this->addEventListener(Core::EVENT_ON_AFTER_INIT, function () {
$this->addEventListener(IRpc::EVENT_ON_TOKEN_LOGIN, function (FestiEvent &$event) {
Core::getInstance()->getPluginInstance('YourNewPlugin')->onInterceptLoginByToken($event);
});
});
public function onInterceptLoginByToken(FestiEvent &$event): void
{
$isAuth = &$event->getTargetValueByKey('is_auth');
$token = &$event->getTargetValueByKey('token');
if (mb_strlen($token) == 32) { // system access token
$isAuth = $this->core->getSystemPlugin()->signinByToken($token);
} else {
$isAuth = $this->_signInByGoogleTokenID($token);
}
if (!$isAuth) {
throw new PermissionsException("Undefined access token.");
}
}
Reusable API
The RPC plugin provides reusable type handling utilities that can be used by other plugins:
ParameterProcessor
The ParameterProcessor class provides public methods for type checking and casting:
isSimpleType(string $typeName): bool- Checks if a type is a simple/primitive typecastToType(mixed $value, string $typeName): mixed- Casts a value to the specified type
These methods are used internally by RPC for parameter processing and are also available for use by dependent plugins (e.g., MCPServer) to maintain consistency in type handling across the codebase.
Error Handling
The RPC plugin follows the JSON-RPC 2.0 specification for error responses. Errors are returned in the following format:
{
"jsonrpc": "2.0",
"error": {
"code": -32000,
"message": "Server error",
"data": {}
},
"id": 1
}
Common error codes:
- -32700 - Parse error
- -32600 - Invalid Request
- -32601 - Method not found
- -32602 - Invalid params
- -32603 - Internal error
- -32000 to -32099 - Server error (custom errors)
Errors of a call
The plugin answers an error of a call with one of these codes. They are codes of the application: the JSON-RPC rules keep only the codes from -32768 to -32000 for the protocol.
| Code | Message | Cause |
|---|---|---|
| 400 | the text of the error | The request is not a valid JSON-RPC request. |
| 403 | the text of the refusal | A refusal of permission: the plugin or a tool refused the call with a PermissionsException. For example a call of execUrl with no idParent for a child store, or for a row that is not a row of the parent row of the call. |
| 404 | Method <name> not found |
The registry has no tool with that name. |
| 500 | Internal Error |
A fault of the server: each other exception of a tool, and each PHP error. The answer has no detail of the fault; the detail is in the errors log. |
A refusal with the code 403:
{"jsonrpc":"2.0","error":{"code":403,"message":"Record `42` of `tasks` is not available for the `idParent` `7`. Call execUrl with the list action and this `idParent` to get the records of that parent."},"id":1}
- The text of a refusal of the plugin holds only values that the call sent: the action, the name of the store, the id of the row and the
idParent. It holds no value of a stored row, and it is the same for a row that exists and for a row that does not exist. - The text of a refusal of a tool of your product is the display message of its
PermissionsException(setDisplayMessage()). Write there only what the user of the call is permitted to read. For an exception with no display message the text isPermission denied.: the client does not get the message of the exception, which is in the errors log. - The HTTP status of the answer of one call is the code of its error. The HTTP status of a batch is 200: read the
errorof each answer of the batch. - A call with no
id(a notification) gets no answer, also when it is refused. - A client must not read the code 500 as "the call was refused": a refusal has the code 403, and the code 500 is a fault that a later call with the same values can have again or not.
Errors log
The plugin writes each error of a call to the log rpc_errors (the file rpc_errors.log in the directory paths.logs of the configuration). The log holds no request param and no argument of a trace frame, because a param can be a credential.
The class Plugins\Rpc\Domain\Log\LogSanitizer makes the safe form of a request and of an exception. RpcPlugin uses only this class to prepare the data of a log entry. Use this class when you add a log entry.
An entry for a PHP warning, notice or deprecation holds:
error: the level of the PHP error.message,file,line: the text and the location of the PHP error.request: a list with theidand themethodof each request of the call. A batch has more than one item.
An entry for an exception holds:
exception_class,message,code,file,line: the data of the exception.trace: a list of frames. Each frame has onlyfile,line,classandfunction.previous: the list of the previous exceptions, from the newest to the oldest. Each item has the same fields as the exception, withoutprevious.request_id,rpc_method: the id and the method of the request, when the request has them.
An id or a method that is not a scalar value is replaced by the name of its type, for example (array).
A PHP error while the plugin processes a request makes two entries: one for the PHP error and one for the exception Internal Error that the plugin throws for it.
Limits:
- The plugin does not examine the text of a message. If the message of an exception or of a PHP error repeats a value of the request, the log holds that value. Do not put the value of a param in the message of an exception.
- The framework adds the URL of the HTTP request to each log entry. If a client sends the request in the GET parameter
rawRequestor the token in the GET parametertoken, the URL in the log holds them. Send the request in the body and the token in the headerX-Authorizationto prevent this. See "Authentication".
Log of the entry point
The entry point install/rpc/rpc.php writes an exception that the plugin does not catch to the log rpc (the file rpc.log), for example a sign-in that fails or a URL that has no rule. If the constant SUPPORT_MAIL is defined, the framework also sends the entry to that address.
The entry point gives the text of LogSanitizer::getThrowableText() to the log, and not the exception. The message of the entry is thus the same in the log and in the mail: exception_class, message, code, file, line, trace and previous, as in an exception entry of the log rpc_errors. It has no request_id and no rpc_method, and no argument of a trace frame. The value of zend.exception_ignore_args does not change the entry.
The two limits above also apply to this entry and to the mail: the text of a message is not examined, and the framework adds the URL of the HTTP request.
Permissions
RPC methods can be protected using the @section annotation. The section name should match a permission section defined in your permissions system. If a user doesn't have access to the required section, a PermissionsException will be thrown.
For detailed information about the permissions system, see the Permissions documentation.
How Permission Checking Works
The permission system uses the following database tables:
festi_sections- Defines permission sections (identified by the@sectionannotation)festi_section_actions- Maps plugin methods to sections and required permission masksfesti_sections_user_permission- User-specific permissions (overrides user type permissions)festi_sections_user_types_permission- User type/role-based permissions
When an RPC method is called:
- The system looks up the method in
festi_section_actionsto find: - The associated section (
id_section) -
The required permission mask (2 = Read, 4 = Write, 6 = Execute)
-
The system then checks the user's permissions by querying:
festi_sections_user_permissionfor user-specific permissions (takes priority)-
festi_sections_user_types_permissionfor role-based permissions -
The user's granted mask must be greater than or equal to the required mask for the action.
Example
/**
* @rpc getProjects
* @section manage_projects
* @return array
*/
public function getProjects(): array
{
// Only users with 'manage_projects' permission can call this
}
To set up permissions for this method, you need to:
-
Create the section in
festi_sections(if it doesn't exist):INSERT INTO festi_sections (caption, ident, mask) VALUES ('Project Management', 'manage_projects', '6'); -
Register the action in
festi_section_actions:INSERT INTO festi_section_actions (id_section, plugin, method, mask, comment) VALUES ( (SELECT id FROM festi_sections WHERE ident = 'manage_projects'), 'MyPlugin', 'getProjects', '2', -- Read permission required 'Get projects list' ); -
Assign permissions to users or user types as needed.
Built-in RPC Methods
getDataGridStoreModel
Returns the DataGrid Store (DGS) model schema for a given plugin and store.
Parameters:
- pluginName (string) or [0] - Name of the plugin
- storeName (string) or [1] - Name of the store
Example:
{"jsonrpc":"2.0", "method":"getDataGridStoreModel", "params":["MyPlugin", "users"], "id":1}
Based on: RpcPlugin::onJsonDataGridStore
syncRpcMethods
Scans the project and reconciles the RPC methods registry in the database so it exactly mirrors the code. Call it after adding, renaming, or removing RPC methods.
Reconciliation is keyed on a method's identity (plugin, method) — not its rpc_method alias:
- a newly declared method is inserted;
- an existing method is updated in place, so renaming its
rpc_methodalias updates the row instead of creating a duplicate; - a row whose
(plugin, method)is no longer declared is deleted — this removes methods deleted from code and methods of plugins that are no longer active, keeping stale endpoints from remaining callable.
A row in festi_plugins whose ident has no matching directory at all under this entry point's plugins path (e.g. a host app that spreads its plugins across several plugin roots) does not abort the sync: that plugin is skipped, the skip is logged, and every other plugin is still scanned. Because that plugin never had a chance to re-declare its methods this run, its previously persisted rows are not deleted as stale — they are left exactly as they were until a sync that can resolve the plugin runs.
This is distinct from an ident whose directory does exist under this plugins path but has no <Ident>Plugin.php inside it — that plugin root belongs to this entry point, so a missing entry file is a broken deployment (file deleted, misnamed, or a failed copy), not a foreign ident. That case is not skipped: it fails the sync loudly, the same way it always has.
If the plugins path of the entry point (Core::OPTION_PLUGINS_PATH) is not a directory, the sync stops with the error Rpc plugins path is not a directory: <path>. It does not skip each plugin, and it does not change a stored row. Correct the option and call the sync again.
To retire a plugin for good (its code is gone and it is not coming back), set its festi_plugins row to a non-active status — the next sync then deletes its rows the same way it deletes any other inactive plugin's, since only active plugins are ever scanned or skipped.
Note for existing consumers upgrading past this change: on a project where syncRpcMethods previously failed outright the moment it hit an unresolvable plugin (and therefore never reconciled anything), the first successful sync after upgrading applies every stale-row deletion that had been accumulating since. That is correct behaviour, but worth expecting rather than discovering, especially on a project with a large rpc_methods registry.
Parameters: None
Example:
{"jsonrpc":"2.0", "method":"syncRpcMethods", "params":[], "id":1}
Based on: RpcPlugin::syncRpcMethods
getStructureMenu
Returns the menu structure for a given area.
Parameters:
- area (string) or [0] - Area identifier
Example:
{"jsonrpc":"2.0", "method":"getStructureMenu", "params":["backend"], "id":1}
Based on: Jimbo::getStructureMenu
getSchemeByUrl
Binds a backend page read-only and returns the DGS schema of every store on it (fields, actions, and the request descriptor). See Working with DGS over RPC.
Parameters:
- url (string) or [0] - Concrete page URL to introspect
- area (string|null) or [1] - Optional area identifier (defaults to backend)
- idParent (string|null) or [2] - Id of the parent row, for the page of a child store
Example:
{"jsonrpc":"2.0", "method":"getSchemeByUrl", "params":["/projects/", "backend"], "id":1}
Based on: RpcPlugin::onJsonSchemeByUrl
execUrl
Reads or writes DGS rows on a backend page. data is keyed by each store's request.key (from getSchemeByUrl) and names an action (list, insert, edit, remove) plus, for writes, the field values. Omit data to run list. See Working with DGS over RPC.
Parameters:
- url (string) or [0] - Concrete page URL to execute against
- data (object|null) or [1] - Request keyed by store request.key
- area (string|null) or [2] - Optional area identifier (defaults to backend)
- idParent (string|null) or [3] - Id of the parent row, for the page of a child store. An action for one row then runs only for a row of that parent row. A child store refuses each action but list when the call has no idParent. For a store that holds a tree, an empty text names the first level, and each action is refused when the call has no idParent.
Example:
{"jsonrpc":"2.0", "method":"execUrl", "params":["/projects/", {"projects":{"action":"list"}}, "backend"], "id":1}
Based on: RpcPlugin::onJsonExecUrl