From a6e9c08499f9f79dad88cb3ae9eacda0e0c34c96 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Tue, 27 Oct 2020 19:23:45 +0100 Subject: [PATCH] Plugin system: allow plugins to provide custom routes - each route will be prefixed by `/plugin/` - add a new template for plugins rendering - add a live example in the demo_plugin Check out the "Plugin System" documentation for more detail. Related to #143 --- application/container/ContainerBuilder.php | 17 ++--- application/plugin/PluginManager.php | 64 +++++++++++++++++++ .../exception/PluginInvalidRouteException.php | 26 ++++++++ doc/md/dev/Plugin-system.md | 25 ++++++++ index.php | 22 ++++++- phpcs.xml | 1 + plugins/demo_plugin/DemoPluginController.php | 24 +++++++ plugins/demo_plugin/demo_plugin.php | 19 +++++- tests/PluginManagerTest.php | 39 +++++++++++ tests/container/ContainerBuilderTest.php | 5 ++ tests/plugins/test/test.php | 16 +++++ .../test_route_invalid/test_route_invalid.php | 12 ++++ tpl/default/pluginscontent.html | 13 ++++ 13 files changed, 270 insertions(+), 13 deletions(-) create mode 100644 application/plugin/exception/PluginInvalidRouteException.php create mode 100644 plugins/demo_plugin/DemoPluginController.php create mode 100644 tests/plugins/test_route_invalid/test_route_invalid.php create mode 100644 tpl/default/pluginscontent.html diff --git a/application/container/ContainerBuilder.php b/application/container/ContainerBuilder.php index f0234eca..6d69a880 100644 --- a/application/container/ContainerBuilder.php +++ b/application/container/ContainerBuilder.php @@ -50,6 +50,9 @@ class ContainerBuilder /** @var LoginManager */ protected $login; + /** @var PluginManager */ + protected $pluginManager; + /** @var LoggerInterface */ protected $logger; @@ -61,12 +64,14 @@ public function __construct( SessionManager $session, CookieManager $cookieManager, LoginManager $login, + PluginManager $pluginManager, LoggerInterface $logger ) { $this->conf = $conf; $this->session = $session; $this->login = $login; $this->cookieManager = $cookieManager; + $this->pluginManager = $pluginManager; $this->logger = $logger; } @@ -78,12 +83,10 @@ public function build(): ShaarliContainer $container['sessionManager'] = $this->session; $container['cookieManager'] = $this->cookieManager; $container['loginManager'] = $this->login; + $container['pluginManager'] = $this->pluginManager; $container['logger'] = $this->logger; $container['basePath'] = $this->basePath; - $container['plugins'] = function (ShaarliContainer $container): PluginManager { - return new PluginManager($container->conf); - }; $container['history'] = function (ShaarliContainer $container): History { return new History($container->conf->get('resource.history')); @@ -113,14 +116,6 @@ public function build(): ShaarliContainer ); }; - $container['pluginManager'] = function (ShaarliContainer $container): PluginManager { - $pluginManager = new PluginManager($container->conf); - - $pluginManager->load($container->conf->get('general.enabled_plugins')); - - return $pluginManager; - }; - $container['formatterFactory'] = function (ShaarliContainer $container): FormatterFactory { return new FormatterFactory( $container->conf, diff --git a/application/plugin/PluginManager.php b/application/plugin/PluginManager.php index 3ea55728..7fc0cb04 100644 --- a/application/plugin/PluginManager.php +++ b/application/plugin/PluginManager.php @@ -4,6 +4,7 @@ use Shaarli\Config\ConfigManager; use Shaarli\Plugin\Exception\PluginFileNotFoundException; +use Shaarli\Plugin\Exception\PluginInvalidRouteException; /** * Class PluginManager @@ -26,6 +27,14 @@ class PluginManager */ private $loadedPlugins = []; + /** @var array List of registered routes. Contains keys: + * - `method`: HTTP method, GET/POST/PUT/PATCH/DELETE + * - `route` (path): without prefix, e.g. `/up/{variable}` + * It will be later prefixed by `/plugin//`. + * - `callable` string, function name or FQN class's method, e.g. `demo_plugin_custom_controller`. + */ + protected $registeredRoutes = []; + /** * @var ConfigManager Configuration Manager instance. */ @@ -86,6 +95,9 @@ public function load($authorizedPlugins) $this->loadPlugin($dirs[$index], $plugin); } catch (PluginFileNotFoundException $e) { error_log($e->getMessage()); + } catch (\Throwable $e) { + $error = $plugin . t(' [plugin incompatibility]: ') . $e->getMessage(); + $this->errors = array_unique(array_merge($this->errors, [$error])); } } } @@ -166,6 +178,22 @@ private function loadPlugin($dir, $pluginName) } } + $registerRouteFunction = $pluginName . '_register_routes'; + $routes = null; + if (function_exists($registerRouteFunction)) { + $routes = call_user_func($registerRouteFunction); + } + + if ($routes !== null) { + foreach ($routes as $route) { + if (static::validateRouteRegistration($route)) { + $this->registeredRoutes[$pluginName][] = $route; + } else { + throw new PluginInvalidRouteException($pluginName); + } + } + } + $this->loadedPlugins[] = $pluginName; } @@ -237,6 +265,14 @@ public function getPluginsMeta() return $metaData; } + /** + * @return array List of registered custom routes by plugins. + */ + public function getRegisteredRoutes(): array + { + return $this->registeredRoutes; + } + /** * Return the list of encountered errors. * @@ -246,4 +282,32 @@ public function getErrors() { return $this->errors; } + + /** + * Checks whether provided input is valid to register a new route. + * It must contain keys `method`, `route`, `callable` (all strings). + * + * @param string[] $input + * + * @return bool + */ + protected static function validateRouteRegistration(array $input): bool + { + if ( + !array_key_exists('method', $input) + || !in_array(strtoupper($input['method']), ['GET', 'PUT', 'PATCH', 'POST', 'DELETE']) + ) { + return false; + } + + if (!array_key_exists('route', $input) || !preg_match('#^[a-z\d/\.\-_]+$#', $input['route'])) { + return false; + } + + if (!array_key_exists('callable', $input)) { + return false; + } + + return true; + } } diff --git a/application/plugin/exception/PluginInvalidRouteException.php b/application/plugin/exception/PluginInvalidRouteException.php new file mode 100644 index 00000000..6ba9bc43 --- /dev/null +++ b/application/plugin/exception/PluginInvalidRouteException.php @@ -0,0 +1,26 @@ +message = 'trying to register invalid route.'; + } +} diff --git a/doc/md/dev/Plugin-system.md b/doc/md/dev/Plugin-system.md index f09fadc2..79654011 100644 --- a/doc/md/dev/Plugin-system.md +++ b/doc/md/dev/Plugin-system.md @@ -139,6 +139,31 @@ Each file contain two keys: > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. +### Register plugin's routes + +Shaarli lets you register custom Slim routes for your plugin. + +To register a route, the plugin must include a function called `function _register_routes(): array`. + +This method must return an array of routes, each entry must contain the following keys: + + - `method`: HTTP method, `GET/POST/PUT/PATCH/DELETE` + - `route` (path): without prefix, e.g. `/up/{variable}` + It will be later prefixed by `/plugin//`. + - `callable` string, function name or FQN class's method to execute, e.g. `demo_plugin_custom_controller`. + +Callable functions or methods must have `Slim\Http\Request` and `Slim\Http\Response` parameters +and return a `Slim\Http\Response`. We recommend creating a dedicated class and extend either +`ShaarliVisitorController` or `ShaarliAdminController` to use helper functions they provide. + +A dedicated plugin template is available for rendering content: `pluginscontent.html` using `content` placeholder. + +> **Warning**: plugins are not able to use RainTPL template engine for their content due to technical restrictions. +> RainTPL does not allow to register multiple template folders, so all HTML rendering must be done within plugin +> custom controller. + +Check out the `demo_plugin` for a live example: `GET /plugin/demo_plugin/custom`. + ### Understanding relative paths Because Shaarli is a self-hosted tool, an instance can either be installed at the root directory, or under a subfolder. diff --git a/index.php b/index.php index 1eb7659a..862c53ef 100644 --- a/index.php +++ b/index.php @@ -31,6 +31,7 @@ use Shaarli\Config\ConfigManager; use Shaarli\Container\ContainerBuilder; use Shaarli\Languages; +use Shaarli\Plugin\PluginManager; use Shaarli\Security\BanManager; use Shaarli\Security\CookieManager; use Shaarli\Security\LoginManager; @@ -87,7 +88,17 @@ $loginManager->checkLoginState(client_ip_id($_SERVER)); -$containerBuilder = new ContainerBuilder($conf, $sessionManager, $cookieManager, $loginManager, $logger); +$pluginManager = new PluginManager($conf); +$pluginManager->load($conf->get('general.enabled_plugins', [])); + +$containerBuilder = new ContainerBuilder( + $conf, + $sessionManager, + $cookieManager, + $loginManager, + $pluginManager, + $logger +); $container = $containerBuilder->build(); $app = new App($container); @@ -154,6 +165,15 @@ $this->get('/visibility/{visibility}', '\Shaarli\Front\Controller\Admin\SessionFilterController:visibility'); })->add('\Shaarli\Front\ShaarliAdminMiddleware'); +$app->group('/plugin', function () use ($pluginManager) { + foreach ($pluginManager->getRegisteredRoutes() as $pluginName => $routes) { + $this->group('/' . $pluginName, function () use ($routes) { + foreach ($routes as $route) { + $this->{strtolower($route['method'])}('/' . ltrim($route['route'], '/'), $route['callable']); + } + }); + } +})->add('\Shaarli\Front\ShaarliMiddleware'); // REST API routes $app->group('/api/v1', function () { diff --git a/phpcs.xml b/phpcs.xml index c559e35d..9bdc8720 100644 --- a/phpcs.xml +++ b/phpcs.xml @@ -18,5 +18,6 @@ index.php + plugins/* diff --git a/plugins/demo_plugin/DemoPluginController.php b/plugins/demo_plugin/DemoPluginController.php new file mode 100644 index 00000000..b8ace9c8 --- /dev/null +++ b/plugins/demo_plugin/DemoPluginController.php @@ -0,0 +1,24 @@ +assignView( + 'content', + '
' . + 'This is a demo page. I have access to Shaarli container, so I\'m free to do whatever I want here.' . + '
' + ); + + return $response->write($this->render('pluginscontent')); + } +} diff --git a/plugins/demo_plugin/demo_plugin.php b/plugins/demo_plugin/demo_plugin.php index 22d27b68..15cfc2c5 100644 --- a/plugins/demo_plugin/demo_plugin.php +++ b/plugins/demo_plugin/demo_plugin.php @@ -7,6 +7,8 @@ * Can be used by plugin developers to make their own plugin. */ +require_once __DIR__ . '/DemoPluginController.php'; + /* * RENDER HEADER, INCLUDES, FOOTER * @@ -60,6 +62,17 @@ function demo_plugin_init($conf) return $errors; } +function demo_plugin_register_routes(): array +{ + return [ + [ + 'method' => 'GET', + 'route' => '/custom', + 'callable' => 'Shaarli\DemoPlugin\DemoPluginController:index', + ], + ]; +} + /** * Hook render_header. * Executed on every page render. @@ -304,7 +317,11 @@ function hook_demo_plugin_render_editlink($data) function hook_demo_plugin_render_tools($data) { // field_plugin - $data['tools_plugin'][] = 'tools_plugin'; + $data['tools_plugin'][] = '
+ + Demo Plugin Custom Route + +
'; return $data; } diff --git a/tests/PluginManagerTest.php b/tests/PluginManagerTest.php index efef5e87..8947f679 100644 --- a/tests/PluginManagerTest.php +++ b/tests/PluginManagerTest.php @@ -120,4 +120,43 @@ public function testGetPluginsMeta(): void $this->assertEquals('test plugin', $meta[self::$pluginName]['description']); $this->assertEquals($expectedParameters, $meta[self::$pluginName]['parameters']); } + + /** + * Test plugin custom routes - note that there is no check on callable functions + */ + public function testRegisteredRoutes(): void + { + PluginManager::$PLUGINS_PATH = self::$pluginPath; + $this->pluginManager->load([self::$pluginName]); + + $expectedParameters = [ + [ + 'method' => 'GET', + 'route' => '/test', + 'callable' => 'getFunction', + ], + [ + 'method' => 'POST', + 'route' => '/custom', + 'callable' => 'postFunction', + ], + ]; + $meta = $this->pluginManager->getRegisteredRoutes(); + static::assertSame($expectedParameters, $meta[self::$pluginName]); + } + + /** + * Test plugin custom routes with invalid route + */ + public function testRegisteredRoutesInvalid(): void + { + $plugin = 'test_route_invalid'; + $this->pluginManager->load([$plugin]); + + $meta = $this->pluginManager->getRegisteredRoutes(); + static::assertSame([], $meta); + + $errors = $this->pluginManager->getErrors(); + static::assertSame(['test_route_invalid [plugin incompatibility]: trying to register invalid route.'], $errors); + } } diff --git a/tests/container/ContainerBuilderTest.php b/tests/container/ContainerBuilderTest.php index 3d43c344..04d4ef01 100644 --- a/tests/container/ContainerBuilderTest.php +++ b/tests/container/ContainerBuilderTest.php @@ -43,11 +43,15 @@ class ContainerBuilderTest extends TestCase /** @var CookieManager */ protected $cookieManager; + /** @var PluginManager */ + protected $pluginManager; + public function setUp(): void { $this->conf = new ConfigManager('tests/utils/config/configJson'); $this->sessionManager = $this->createMock(SessionManager::class); $this->cookieManager = $this->createMock(CookieManager::class); + $this->pluginManager = $this->createMock(PluginManager::class); $this->loginManager = $this->createMock(LoginManager::class); $this->loginManager->method('isLoggedIn')->willReturn(true); @@ -57,6 +61,7 @@ public function setUp(): void $this->sessionManager, $this->cookieManager, $this->loginManager, + $this->pluginManager, $this->createMock(LoggerInterface::class) ); } diff --git a/tests/plugins/test/test.php b/tests/plugins/test/test.php index 03be4f4e..34cd339e 100644 --- a/tests/plugins/test/test.php +++ b/tests/plugins/test/test.php @@ -27,3 +27,19 @@ function hook_test_error() { new Unknown(); } + +function test_register_routes(): array +{ + return [ + [ + 'method' => 'GET', + 'route' => '/test', + 'callable' => 'getFunction', + ], + [ + 'method' => 'POST', + 'route' => '/custom', + 'callable' => 'postFunction', + ], + ]; +} diff --git a/tests/plugins/test_route_invalid/test_route_invalid.php b/tests/plugins/test_route_invalid/test_route_invalid.php new file mode 100644 index 00000000..0c5a5101 --- /dev/null +++ b/tests/plugins/test_route_invalid/test_route_invalid.php @@ -0,0 +1,12 @@ + 'GET', + 'route' => 'not a route', + 'callable' => 'getFunction', + ], + ]; +} diff --git a/tpl/default/pluginscontent.html b/tpl/default/pluginscontent.html new file mode 100644 index 00000000..1e4f6b80 --- /dev/null +++ b/tpl/default/pluginscontent.html @@ -0,0 +1,13 @@ + + + + {include="includes"} + + + {include="page.header"} + + {$content} + + {include="page.footer"} + +