xref: /plugin/dev/Skeletor.php (revision cde324c25eade52a46b205d6870d3f1b4fc22e18) 
1<?php
2
3namespace dokuwiki\plugin\dev;
4
5use RuntimeException;
6
7/**
8 * This class holds basic information about a plugin or template and uses the skeleton files to
9 * create new plugin or template specific versions of them.
10 *
11 * This class does not write any files, but only provides the data for the actual file creation.
12 */
13class Skeletor
14{
15    // FIXME this may change upstream we may want to update it via github action
16    const PLUGIN_TYPES = ['auth', 'admin', 'syntax', 'action', 'renderer', 'helper', 'remote', 'cli'];
17
18    const TYPE_PLUGIN = 'plugin';
19    const TYPE_TEMPLATE = 'template';
20
21    protected $type;
22    protected $base;
23    protected $author;
24    protected $desc;
25    protected $name;
26    protected $email;
27    protected $url;
28    protected $dir;
29
30    /** @var array The files to be created in the form of [path => content] */
31    protected $files = [];
32
33    /**
34     * Initialize the skeletor from provided data
35     *
36     * @param string $type
37     * @param string $base
38     * @param string $desc
39     * @param string $author
40     * @param string $email
41     * @param string $name
42     * @param string $url
43     */
44    public function __construct($type, $base, $desc, $author, $email, $name = '', $url = '')
45    {
46        $this->type = $type;
47        $this->base = $base;
48        $this->desc = $desc;
49        $this->author = $author;
50        $this->email = $email;
51        $this->name = $name ?: ucfirst($base . ' ' . $type);
52
53        if ($type == self::TYPE_PLUGIN) {
54            $this->url = $url ?: 'https://www.dokuwiki.org/plugin:' . $base;
55            $this->dir = 'lib/plugins/' . $base;
56        } else {
57            $this->url = $url ?: 'https://www.dokuwiki.org/template:' . $base;
58            $this->dir = 'lib/tpl/' . $base;
59        }
60    }
61
62    /**
63     * Create an instance using an existing plugin or template directory
64     *
65     * @param string $dir
66     * @return Skeletor
67     */
68    static public function fromDir($dir)
69    {
70        if (file_exists($dir . '/plugin.info.txt')) {
71            $type = self::TYPE_PLUGIN;
72        } elseif (file_exists($dir . '/template.info.txt')) {
73            $type = self::TYPE_TEMPLATE;
74        } else {
75            throw new RuntimeException('Not a plugin or template directory');
76        }
77
78        $data = file($dir . '/' . $type . '.info.txt', FILE_IGNORE_NEW_LINES);
79        $data = array_map(function ($item) {
80            return array_map('trim', explode(' ', $item, 2));
81        }, $data);
82        $data = array_combine(array_column($data, 0), array_column($data, 1));
83
84        return new self($type, $data['base'], $data['desc'], $data['author'], $data['email'], $data['url']);
85    }
86
87    /**
88     * Return the files to be created
89     *
90     * @return array [path => content]
91     */
92    public function getFiles()
93    {
94        return $this->files;
95    }
96
97    // region content creators
98
99    /**
100     * Add the basic files to the plugin
101     */
102    public function addBasics()
103    {
104        $this->loadSkeleton('info.txt', $this->type . '.info.txt');
105        $this->loadSkeleton('README');
106        $this->loadSkeleton('LICENSE');
107        $this->loadSkeleton('.gitattributes');
108    }
109
110    /**
111     * Add another component to the plugin
112     *
113     * @param string $type
114     * @param string $component
115     */
116    public function addComponent($type, $component = '', $options = [])
117    {
118        if ($this->type !== self::TYPE_PLUGIN) {
119            throw new RuntimeException('Components can only be added to plugins');
120        }
121
122        if (!in_array($type, self::PLUGIN_TYPES)) {
123            throw new RuntimeException('Invalid type ' . $type);
124        }
125
126        $plugin = $this->base;
127
128        if ($component) {
129            $path = $type . '/' . $component . '.php';
130            $class = $type . '_plugin_' . $plugin . '_' . $component;
131            $self = 'plugin_' . $plugin . '_' . $component;
132        } else {
133            $path = $type . '.php';
134            $class = $type . '_plugin_' . $plugin;
135            $self = 'plugin_' . $plugin;
136        }
137
138        if ($type === 'action') {
139            $replacements = $this->actionReplacements($options);
140        }
141        if ($type === 'renderer' && isset($options[0]) && $options[0] === 'Doku_Renderer_xhtml') {
142            $type = 'renderer_xhtml'; // different template then
143        }
144
145        $replacements['@@PLUGIN_COMPONENT_NAME@@'] = $class;
146        $replacements['@@SYNTAX_COMPONENT_NAME@@'] = $self;
147        $this->loadSkeleton($type . '.php', $path, $replacements);
148    }
149
150    /**
151     * Add test framework optionally with a specific test
152     *
153     * @param string $test Name of the Test to add
154     */
155    public function addTest($test = '')
156    {
157        $test = ucfirst(strtolower($test));
158        $this->loadSkeleton('.github/workflows/phpTestLinux.yml');
159        if ($test) {
160            $replacements = ['@@TEST@@' => $test];
161            $this->loadSkeleton('_test/StandardTest.php', '_test/' . $test . 'Test.php', $replacements);
162        } else {
163            $this->loadSkeleton('_test/GeneralTest.php');
164        }
165    }
166
167    /**
168     * Add configuration
169     *
170     * @param bool $translate if true the settings language file will be be added, too
171     */
172    public function addConf($translate = false)
173    {
174        $this->loadSkeleton('conf/default.php');
175        $this->loadSkeleton('conf/metadata.php');
176
177        if ($translate) {
178            $this->loadSkeleton('lang/settings.php', 'lang/en/settings.php');
179        }
180    }
181
182    /**
183     * Add language
184     *
185     * Currently only english is added, theoretically this could also copy over the keys from an
186     * existing english language file.
187     *
188     * @param bool $conf if true the settings language file will be be added, too
189     */
190    public function addLang($conf = false)
191    {
192        $this->loadSkeleton('lang/lang.php', 'lang/en/lang.php');
193        if ($conf) {
194            $this->loadSkeleton('lang/settings.php', 'lang/en/settings.php');
195        }
196    }
197
198    // endregion
199
200
201    /**
202     * Prepare the string replacements
203     *
204     * @param array $replacements override defaults
205     * @return array
206     */
207    protected function prepareReplacements($replacements = [])
208    {
209        // defaults
210        $data = [
211            '@@AUTHOR_NAME@@' => $this->author,
212            '@@AUTHOR_MAIL@@' => $this->email,
213            '@@PLUGIN_NAME@@' => $this->base, // FIXME rename to @@PLUGIN_BASE@@
214            '@@PLUGIN_DESC@@' => $this->desc,
215            '@@PLUGIN_URL@@' => $this->url,
216            '@@PLUGIN_TYPE@@' => $this->type,
217            '@@INSTALL_DIR@@' => ($this->type == self::TYPE_PLUGIN) ? 'plugins' : 'tpl',
218            '@@DATE@@' => date('Y-m-d'),
219        ];
220
221        // merge given overrides
222        return array_merge($data, $replacements);
223    }
224
225    /**
226     * Replacements needed for action components.
227     *
228     * @param string[] $event Event names to handle
229     * @return string[]
230     */
231    protected function actionReplacements($events = [])
232    {
233        if (!$events) $events = ['EXAMPLE_EVENT'];
234
235        $register = '';
236        $handler = '';
237
238        $template = file_get_contents(__DIR__ . '/skel/action_handler.php');
239
240        foreach ($events as $event) {
241            $event = strtoupper($event);
242            $fn = 'handle' . str_replace('_', '', ucwords(strtolower($event), '_'));
243
244            $register .= '        $controller->register_hook(\'' . $event .
245                '\', \'AFTER|BEFORE\', $this, \'' . $fn . '\');' . "\n";
246
247            $handler .= str_replace(['@@EVENT@@', '@@HANDLER@@'], [$event, $fn], $template);
248        }
249
250        return [
251            '@@REGISTER@@' => $register,
252            '@@HANDLERS@@' => $handler,
253        ];
254    }
255
256    /**
257     * Load a skeleton file, do the replacements and add it to the list of files
258     *
259     * @param string $skel Skeleton relative to the skel dir
260     * @param string $target File name in the final plugin/template, empty for same as skeleton
261     * @param array $replacements Non-default replacements to use
262     */
263    protected function loadSkeleton($skel, $target = '', $replacements = [])
264    {
265        $replacements = $this->prepareReplacements($replacements);
266        if (!$target) $target = $skel;
267
268
269        $file = __DIR__ . '/skel/' . $skel;
270        if (!file_exists($file)) {
271            throw new RuntimeException('Skeleton file not found: ' . $skel);
272        }
273        $content = file_get_contents($file);
274        $this->files[$target] = str_replace(
275            array_keys($replacements),
276            array_values($replacements),
277            $content
278        );
279    }
280}
281