1 <?php
2 
3 namespace dokuwiki\Extension;
4 
5 /**
6  * DokuWiki Plugin Interface
7  *
8  * Defines the public contract all DokuWiki plugins will adhere to. The actual code
9  * to do so is defined in dokuwiki\Extension\PluginTrait
10  *
11  * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
12  * @author     Christopher Smith <chris@jalakai.co.uk>
13  */
14 interface PluginInterface
15 {
16     /**
17      * General Info
18      *
19      * Needs to return a associative array with the following values:
20      *
21      * base   - the plugin's base name (eg. the directory it needs to be installed in)
22      * author - Author of the plugin
23      * email  - Email address to contact the author
24      * date   - Last modified date of the plugin in YYYY-MM-DD format
25      * name   - Name of the plugin
26      * desc   - Short description of the plugin (Text only)
27      * url    - Website with more information on the plugin (eg. syntax description)
28      */
29     public function getInfo();
30 
31     /**
32      * The type of the plugin inferred from the class name
33      *
34      * @return string  plugin type
35      */
36     public function getPluginType();
37 
38     /**
39      * The name of the plugin inferred from the class name
40      *
41      * @return string  plugin name
42      */
43     public function getPluginName();
44 
45     /**
46      * The component part of the plugin inferred from the class name
47      *
48      * @return string component name
49      */
50     public function getPluginComponent();
51 
52     /**
53      * Access plugin language strings
54      *
55      * to try to minimise unnecessary loading of the strings when the plugin doesn't require them
56      * e.g. when info plugin is querying plugins for information about themselves.
57      *
58      * @param   string $id id of the string to be retrieved
59      * @return  string in appropriate language or english if not available
60      */
61     public function getLang($id);
62 
63     /**
64      * retrieve a language dependent file and pass to xhtml renderer for display
65      * plugin equivalent of p_locale_xhtml()
66      *
67      * @param   string $id id of language dependent wiki page
68      * @return  string parsed contents of the wiki page in xhtml format
69      */
70     public function locale_xhtml($id);
71 
72     /**
73      * Prepends appropriate path for a language dependent filename
74      * plugin equivalent of localFN()
75      *
76      * @param string $id id of localization file
77      * @param  string $ext The file extension (usually txt)
78      * @return string wiki text
79      */
80     public function localFN($id, $ext = 'txt');
81 
82     /**
83      * Reads all the plugins language dependent strings into $this->lang
84      * this function is automatically called by getLang()
85      *
86      * @todo this could be made protected and be moved to the trait only
87      */
88     public function setupLocale();
89 
90     /**
91      * use this function to access plugin configuration variables
92      *
93      * @param string $setting the setting to access
94      * @param mixed $notset what to return if the setting is not available
95      * @return mixed
96      */
97     public function getConf($setting, $notset = false);
98 
99     /**
100      * merges the plugin's default settings with any local settings
101      * this function is automatically called through getConf()
102      *
103      * @todo this could be made protected and be moved to the trait only
104      */
105     public function loadConfig();
106 
107     /**
108      * Loads a given helper plugin (if enabled)
109      *
110      * @author  Esther Brunner <wikidesign@gmail.com>
111      *
112      * @param   string $name name of plugin to load
113      * @param   bool $msg if a message should be displayed in case the plugin is not available
114      * @return  PluginInterface|null helper plugin object
115      */
116     public function loadHelper($name, $msg = true);
117 
118     /**
119      * email
120      * standardised function to generate an email link according to obfuscation settings
121      *
122      * @param string $email
123      * @param string $name
124      * @param string $class
125      * @param string $more
126      * @return string html
127      */
128     public function email($email, $name = '', $class = '', $more = '');
129 
130     /**
131      * external_link
132      * standardised function to generate an external link according to conf settings
133      *
134      * @param string $link
135      * @param string $title
136      * @param string $class
137      * @param string $target
138      * @param string $more
139      * @return string
140      */
141     public function external_link($link, $title = '', $class = '', $target = '', $more = '');
142 
143     /**
144      * output text string through the parser, allows dokuwiki markup to be used
145      * very ineffecient for small pieces of data - try not to use
146      *
147      * @param string $text wiki markup to parse
148      * @param string $format output format
149      * @return null|string
150      */
151     public function render_text($text, $format = 'xhtml');
152 
153     /**
154      * Allow the plugin to prevent DokuWiki from reusing an instance
155      *
156      * @return bool   false if the plugin has to be instantiated
157      */
158     public function isSingleton();
159 }
160