lib/plugins/remote.php
This is an old revision of the document!
Table of Contents
Remote Plugins
Remote plugins enables you to add methods to the RemoteAPI that can be accessed via various web services (currently XMLRPC only). Available Remote Plugins are listed.
How to write a remote plugin?
A Remote Plugin Example needs:
- class name
remote_plugin_example
- which extends DokuWiki_Remote_Plugin1).
- to be stored in a file
lib/plugins/example/remote.php
.
Moreover, a plugin.info.txt file is needed. For full details of plugins and their files and how to create more remote components refer to plugin file structure.
- Implement
_getMethods()
correctly. - write your methods.
Remote plugins specific function:
getApi()
returns a RemoteApi object.
Inherited functions
- See common plugin functions for inherited functions available to all plugins. e.g. localisation, configuration and introspection.
A simple skeleton is:
- remote.php
<?php class remote_plugin_time extends DokuWiki_Remote_Plugin { function _getMethods() { return array( 'plugin.time.getTime' => array( 'args' => array(), 'return' => 'date' ) ); } function getTime() { return $this->getApi()->toDate(time()); } }
Writing your methods
Simple write your methods. You can take parameters and give results back. DokuWiki will take care that you get the right parameter and your result will be handled correctly.
The only thing you cannot use as parameter and return values are objects. The only allowed types are: array
and primitive types.
Beside these types there are two special types, file and date. These type have to be encoded using the $this->getApi()->toDate()
respectively $this->getApi()->toFile()
.
The toDate()
method takes an unix timestamp. The toFile()
method takes a string with the file content.
Security
The API will take care of basic security checks, i.e. user is logged in and user can access the web service. Every more detailed access, like per page, has to be done by the plugin.
Take a look at the rawPage()
method from inc/RemoteAPICore.php
function rawPage($id,$rev=''){ $id = cleanID($id); if(auth_quickaclcheck($id) < AUTH_READ){ throw new RemoteAccessDeniedException('You are not allowed to read this file', 111); } $text = rawWiki($id,$rev); if(!$text) { return pageTemplate($id); } else { return $text; } }
Here is the auth_quickaclcheck()
function used to check the permission on a page id.
Errors
When an error occurs you have to throw an instance of RemoteException
. Beside the RemoteException
is the RemoteAccessDeniedException
to signal wrong permissions.
The _getMethods Method
The _getMethods()
method returns an array with the following structure:
array( '<remoteName>' => array( 'args' => array('type eg. string|int|...|date|file',), ['name' => 'method name in class',] 'return' => 'type', 'public' => 1/0 - method bypass default group check (used by login) ['doc' = 'method documentation'], ), [next method] )
<remoteName>
– Name of the method on remote interface.
Your call will look likeplugin.<your plugin name>.<given remoteName>
.args
– array of possible parameter types. types can be: string, int, double, bool, date, file.name
(optional) – if the real name of the method divides from the remoteName you have to set it in the name field.return
– return type of the method.public
– possible values 1 or 0: on 1 it will bypass the default group check and allow access to the call. This is used i.e. by the remote login method. Leaving out is equal to 0.doc
(optional) – Optional documentation string.
Note: It is possible to have two entries in the _getMethods()
array for one method.
Example See first code snippet on this page for an example.
Custom remote names
In some circumstances you need a full custom name for the remote call. The RPC_CALL_ADD event allows you to write an action plugin to map a custom name to a remoteName of your plugin.