Skip to content

Latest commit

 

History

History
89 lines (62 loc) · 4.36 KB

Plugins.md

File metadata and controls

89 lines (62 loc) · 4.36 KB

Plugins

The following is valid for Neucore 1.42.0 and neucore-plugin 0.10.0 and above.

Intro

Plugins add functionality to Neucore. They are most commonly used to create external service accounts and/or link them to a Neucore user account (like Mumble or Discord). They can also have their own user interface.

A plugin can be added multiple times to Neucore with different configuration data (via GUI, it only has to be installed once). For example the Neucore Discord Plugin is added once for every Discord server that should be available to users.

Install a plugin

The following steps are the same for all plugins. See the respective plugin documentation for further steps.

  • Set the NEUCORE_PLUGINS_INSTALL_DIR environment variable (e.g. /home/user/neucore-plugins).
  • Copy the plugin into that directory within its own subdirectory (so that the plugin.yml file is e.g. at /home/user/neucore-plugins/discord/plugin.yml - do not edit this file!).
  • If the plugin contains frontend files (see the respective plugin documentation), make them available below [Neucore installation directory]/web/plugin/{name}, e.g. by creating a symlink or by mounting the directory in the Docker container. See the documentation of the plugin for the name of the {name} directory.
  • In Neucore, go to Administration -> Plugins and add a new plugin.
  • Configure the plugin, at the very least choose the plugin from the dropdown list. Don't forget to save your changes.

Overview for plugin creators

For each plugin that was created in Neucore there is one distinct URL /plugin/{plugin_id}/{name}. The {name} part can be anything and is passed to the method that implements the request. This method will also get information about the logged-in user.

All plugins have access to a couple object from Neucore, e.g. to parse YAML files, get various data like group members or make ESI requests with tokens from any character that is available on Neucore.

General plugins

They can have their own frontend, add items to the navigation menu that point to their own URL and implement console commands via Neucore (backend/bin/console plugin {plugin_id} [args] [--opts]).

See this example plugin for a simple demo.

Service plugins

They are available to users from the "Services" menu. They provide configuration data to customize the user interface and implement a couple methods to create and update external service accounts via Neucore.

Create a plugin

  • Create a new PHP application with composer and install the neucore-plugin package: 
    composer init
composer require tkhamez/neucore-plugin
  • Copy vendor/tkhamez/neucore-plugin/plugin.yml to plugin.yml in the root directory of the new plugin and adjust values.
  • Create a new PHP class that implements Neucore\Plugin\ServiceInterface or Neucore\Plugin\GeneralInterface, depending on what kind of plugin (general or service) you want to create. It is also possible to implement both in the same class. Not all methods need to be implemented, most can throw an exception instead.
  • If you have a frontend, place all frontend files in a dedicated directory so that they can be deployed below web/plugin/{name} in the document root of the Neucore installation. Mention the name of the {name} directory in your documentation, it must be unique among all installed Neucore plugins with a frontend.

Neucore automatically loads all classes from the namespace that is configured with the psr4_prefix and psr4_path values from the plugin.yml file.

You can also use all classes and libraries provided by the neucore-plugin package and by the FactoryInterface object that is provided by Neucore in the plugin class constructor. However, note that libraries can be updated with each Neucore release.

Besides that, do not use any class from Neucore or any library that Neucore provides. Those can change or be removed without notice. Also, do not access the Neucore database directly.