====== Remote Plugins ======

Remote plugins allow the registration of custom methods that can be accessed through the [[devel:Remote API]].

You can check the list of extensions for available [[plugintype>64#extension__table|Remote Plugins]].

===== How to write a remote plugin? =====

A Remote Plugin //Example// needs:

  * class name  ''remote_plugin_example''
  * which extends [[xref>RemotePlugin]]
  * to be stored in a file ''lib/plugins/example/remote.php''.

Moreover, a [[plugin_info|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 [[xref>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:

<code php 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();
    }
}
</code>

===== 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 [[wp>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 [[xref>\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 [[xref>\dokuwiki\Remote\AccessDeniedException]].

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

<code php>
/**
 * 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);
}
</code>


==== Errors ====

When an error occurs you have to throw an instance of [[xref>\dokuwiki\Remote\RemoteException]].

For permission errors the above mentioned [[xref>\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 =====

  * [[Plugin programming tips]]
  * [[plugins|Plugin Development]]
  * [[devel:Remote API]]
    * [[devel:xmlrpc|XML-RPC]]
    * [[devel:jsonrpc|JSON-RPC]]
  * [[plugintype>64#extension__table|Available remote plugins]]