DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:remote_plugins

Remote Plugins

Remote plugins allow the registration of custom methods that can be accessed through the Remote API.

You can check the list of extensions for available Remote Plugins.

How to write a remote plugin?

A Remote Plugin Example needs:

  • class name remote_plugin_example
  • which extends RemotePlugin
  • 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.

All public methods defined in the plugin's class will be automatically registered as remote API call in the form plugin.<pluginname>.<methodname>.

Remote plugins have access to API specific methods (even though they are usually not required):

  • getApi() returns a dokuwiki\Remote\Api object.
  • getMethods() can be overwritten if the automatic registration of methods shall be changed or influenced.

Inherited functions

  • See common plugin functions for inherited functions available to all plugins. e.g. localisation, configuration and introspection.

A simple skeleton is:

lib/plugins/time/remote.php
<?php
 
use dokuwiki\Extension\AdminPlugin;
 
class remote_plugin_time extends RemotePlugin {
 
    /**
     * Returns the current Server time as timestamp
     * 
     * @return int timestamp
     */
    public function getTime() {
        return return time();
    }
}

Writing your methods

Simply write your methods. All methods declared public will be added to the API. 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.

It is recommended to use primitive types for input only, do not expect the API user to provide structured data if it can be avoided.

  • Dates should always be passed as Unix timestamps (seconds as Integer)
  • Binary data should always be passed as Base64 encoded strings

For example, instead of having a method createUser($userdata) and expect the API user to know how to pass a correctly defined array of user information, write a method createUser($login, $name, $password, $groups=[]).

Use docblocks to document your methods, especially your parameter and return types. This info is used to auto generate the API documentation. When returning complex data, consider returning \dokuwiki\Remote\ApiResponse objects.

Security

The API will take care of basic security checks giving access to your methods only if a authenticated request is made. However if your method require specific permissions you need to implement these checks yourself. Authentication errors should throw a \dokuwiki\Remote\AccessDeniedException.

Here's an example using the auth_quickaclcheck() function to check the ACLs for read permissions before returning page data:

/**
 * Get page contents
 * @param string $id The page ID
 * @return string The page content
 */
public function getPage($id) {
    $id = cleanID($id);
    if (auth_quickaclcheck($id) < AUTH_READ) {
        throw new RemoteAccessDeniedException(
            'You are not allowed to read this file', 
            111
        );
    }
    return rawWiki($id);
}

Errors

When an error occurs you have to throw an instance of \dokuwiki\Remote\RemoteException.

For permission errors the above mentioned \dokuwiki\Remote\AccessDeniedException should be thrown.

Your plugin should use unique (for your plugin) error codes that you should list in your plugin's documentation. Use positive Integer codes, greater than zero!

Further reading

devel/remote_plugins.txt · Last modified: 2024-02-06 14:12 by andi

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki