Differences

This shows you the differences between two versions of the page.

--- devel:remote_plugins [2013-01-22 02:52] – Klap-in
+++ devel:remote_plugins [2024-02-06 14:12] (current) – andi
@@ Line 1: / Line 1: @@
 ====== Remote Plugins ======
-Remote plugins enables you to add methods that can be accessed via various web services (currently xmlrpc only).
+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? =====
-You have to add the ''remote.php'' to your plugin folder. There are only three things you have to do there:
+A Remote Plugin //Example// needs:
-  * Your plugin class must inherit from [[xref>DokuWiki_Remote_Plugin]].
-  * Implement **''_getMethods()''** correctly.
+  * class name  ''remote_plugin_example''
-  * write your methods.
+  * 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):
-Remote plugins specific function:
+  * **''getApi()''** returns a [[xref>dokuwiki\Remote\Api]] object.
-  * **''getApi()''** returns a [[xref>RemoteApi]] 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 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() {
+<code php lib/plugins/time/remote.php>
-        return $this->getApi()->toDate(time());
+<?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();
     }
 }
@@ Line 39: / Line 49: @@
 ===== 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.
+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.
-The only thing you cannot use as parameter and return values are objects. The only allowed types are: ''array'' and primitive types.
+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.
-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.
+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]].
-Every more detailed access, like per page, has to be done by the plugin.
+Here's an example using the [[xref>auth_quickaclcheck()]] function to check the ACLs for read permissions before returning page data:
-Take a look at the ''rawPage()'' method from ''[[xref>inc/RemoteAPICore.php]]''
 <code php>
-function rawPage($id,$rev=''){
+/**
+ * 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){
+    if (auth_quickaclcheck($id) < AUTH_READ) {
-        throw new RemoteAccessDeniedException('You are not allowed to read this file', 111);
+        throw new RemoteAccessDeniedException(
-    }
+            'You are not allowed to read this file',
-    $text = rawWiki($id,$rev);
-    if(!$text) {
+        );
-        return pageTemplate($id);
-    } else {
-        return $text;
     }
+    return rawWiki($id);
 }
 </code>
-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.
+When an error occurs you have to throw an instance of [[xref>\dokuwiki\Remote\RemoteException]].
-===== The _getMethods Method =====
+For permission errors the above mentioned [[xref>\dokuwiki\Remote\AccessDeniedException]] should be thrown.
-The ''_getMethods()'' method returns an array with the following structure:
-<code php>
+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!
-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]
-)
-</code>
-  * ''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.
-===== Custom remote names =====
+===== Further reading =====
-In some circumstances you need a full custom name for the remote call.
+  * [[Plugin programming tips]]
-The [[devel:event:rpc_call_add|RPC_CALL_ADD]] event allows you to map a custom name to a remoteName of your plugin.
+  * [[plugins|Plugin Development]]
+  * [[devel:Remote API]]
+    * [[devel:xmlrpc|XML-RPC]]
+    * [[devel:jsonrpc|JSON-RPC]]
+  * [[plugintype>64#extension__table|Available remote plugins]]