DokuWiki

It's better when it's simple

User Tools

Site Tools


Sidebar

Translations of this page?:

Learn about DokuWiki

Advanced Use

Corporate Use

Our Community


Follow us on Facebook, Twitter and other social networks.

devel:remote_plugins

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:

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 {
    public function _getMethods() {
        return array(
            'getTime' => array(
                'args' => array(),
                'return' => 'date'
            )
        );
    }
 
    public 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

public 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 like plugin.<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.

Further reading

1)
defined in lib/plugins/remote.php
devel/remote_plugins.txt · Last modified: 2013-11-15 13:01 by Klap-in