Plugins¶
sysPass allows to use plugins through an architecture that implements observer pattern which is characterized by emitting a message to all subscribed observers.
The plugins are installed in ‘sysPass/inc/Plugins’ directory and they contain the following basic structure:
Plugins/
└── PluginName (1)
├── ajax
├── js
│ ├── plugin.js
│ └── plugin.min.js
├── locales
│ ├── en_US
│ │ └── LC_MESSAGES
│ │ ├── NombrePlugin.mo (2)
│ │ └── NombrePlugin.po (2)
├── themes
│ └── material-blue
│ └── views
│ ├── main
│ │ └── login.inc
│ └── userpreferences
│ └── preferences.inc
│
└── PluginNamePlugin.class.php (3)
The directory and file names need to be set in the following way:
- Directory name within the plugin name: Example: Authenticator
- Filename within the plugin name in lowercase: Example: authenticator.po
- Filename within the plugin name followed by “Plugin.class.php”. Example: AuthenticatorPlugin.class.php
The main class need to be named like the plugin and extends PluginBase class. This class must implement the following methods.
Methods¶
init¶
Method that is called every time the plugin is executed
/**
* Inicialización
*/
public function init() {}
updateEvent¶
Method that is called when an event is emitted
/**
* Evento de actualización
*
* @param string $event Nombre del evento
* @param mixed $object
*/
public function updateEvent($event, $object) {}
getEvents¶
Method that returns an strings array with the events that the plugin will be subscribed to
/**
* Devuelve los eventos que implementa el observador
*
* @return array
*/
public function getEvents()
{
return ['user.preferences', 'main.prelogin.2fa', 'login.preferences'];
}
getJsResources¶
Method that returns an strings array with the Javascript resources required by the plugin
/**
* Devuelve los recursos JS y CSS necesarios para el plugin
*
* @return array
*/
public function getJsResources()
{
return ['plugin.min.js'];
}
getAuthor¶
Method that returns the plugin author
/**
* Devuelve el autor del plugin
*
* @return string
*/
public function getAuthor()
{
return 'Rubén D.';
}
getVersion¶
Method that returns an integers array with the plugin version
/**
* Devuelve la versión del plugin
*
* @return array
*/
public function getVersion()
{
return [1, 0];
}
getCompatibleVersion¶
Method that returns an integers array with the minimum sysPass compatible version
/**
* Devuelve la versión compatible de sysPass
*
* @return array
*/
public function getCompatibleVersion()
{
return [2, 0];
}
getCssResources¶
Method that returns an strings array with the CSS resources required by the plugin
/**
* Devuelve los recursos CSS necesarios para el plugin
*
* @return array
*/
public function getCssResources()
{
return [];
}
getName¶
Method that returns the plugin name
/**
* Devuelve el nombre del plugin
*
* @return string
*/
public function getName()
{
return self::PLUGIN_NAME;
}
getData¶
Method that returns the plugin data
/**
* @return array|AuthenticatorData[]
*/
public function getData()
{
return (array)parent::getData();
}
Example¶
<?php
namespace Plugins\Authenticator;
use SP\Core\DiFactory;
use SP\Core\Plugin\PluginBase;
use SplSubject;
/**
* Class Plugin
*
* @package Plugins\Authenticator
*/
class AuthenticatorPlugin extends PluginBase
{
const PLUGIN_NAME = 'Authenticator';
/**
* Receive update from subject
*
* @link http://php.net/manual/en/splobserver.update.php
* @param SplSubject $subject <p>
* The <b>SplSubject</b> notifying the observer of an update.
* </p>
* @return void
* @since 5.1.0
*/
public function update(SplSubject $subject)
{
}
/**
* Inicialización del plugin
*/
public function init()
{
if (!is_array($this->data)) {
$this->data = [];
}
$this->base = __DIR__;
$this->themeDir = __DIR__ . DIRECTORY_SEPARATOR . 'themes' . DIRECTORY_SEPARATOR . DiFactory::getTheme()->getThemeName();
$this->setLocales();
}
/**
* Evento de actualización
*
* @param string $event Nombre del evento
* @param mixed $object
* @throws \SP\Core\Exceptions\FileNotFoundException
* @throws \SP\Core\Exceptions\SPException
*/
public function updateEvent($event, $object)
{
switch ($event){
case 'user.preferences':
$Controller = new PreferencesController($object, $this);
$Controller->getSecurityTab();
break;
case 'main.prelogin.2fa':
$Controller = new LoginController($this);
$Controller->get2FA($object);
break;
case 'login.preferences':
$Controller = new LoginController($this);
$Controller->checkLogin();
break;
}
}
/**
* Devuelve los eventos que implementa el observador
*
* @return array
*/
public function getEvents()
{
return ['user.preferences', 'main.prelogin.2fa', 'login.preferences'];
}
/**
* Devuelve los recursos JS y CSS necesarios para el plugin
*
* @return array
*/
public function getJsResources()
{
return ['plugin.min.js'];
}
/**
* Devuelve el autor del plugin
*
* @return string
*/
public function getAuthor()
{
return 'Rubén D.';
}
/**
* Devuelve la versión del plugin
*
* @return array
*/
public function getVersion()
{
return [1, 0];
}
/**
* Devuelve la versión compatible de sysPass
*
* @return array
*/
public function getCompatibleVersion()
{
return [2, 0];
}
/**
* Devuelve los recursos CSS necesarios para el plugin
*
* @return array
*/
public function getCssResources()
{
return [];
}
/**
* Devuelve el nombre del plugin
*
* @return string
*/
public function getName()
{
return self::PLUGIN_NAME;
}
/**
* @return array|AuthenticatorData[]
*/
public function getData()
{
return (array)parent::getData();
}
}
Events¶
When an event is emitted the generating class instance is included as an argument, so it could be possible to access to the class events.
Currently, the generated events are the following:
Event | Class | Description |
---|---|---|
show.account.new | AccountController | Generated when new account view is displayed |
show.account.copy | AccountController | Generated when copy account view is displayed |
show.account.edit | AccountController | Generated when account edit view is displayed |
show.account.editpass | AccountController | Generated when account’s password edit view is displayed |
show.account.view | AccountController | Generated when account details view is displayed |
show.account.viewhistory | AccountController | Generated when account’s history view is displayed |
show.account.delete | AccountController | Generated when account delete view is displayed |
show.account.request | AccountController | Generated when request for account modification view is displayed |
show.account.search | AccountSearchController | Generated when accounts searching view is displayed |
show.config | ConfigController | Generated when configuration view is displayed |
show.eventlog | EventlogController | Generated when event log view is displayed |
show.itemlist.accounts | ItemListController | Generated when items and customizations view is displayed |
show.itemlist.accesses | ItemListController | Generated when accesses view is displayed |
show.itemlist.notices | ItemListController | Generated when notifications view is displayed |
login.preferences | LoginController | Generated when preferences are loaded on login |
main.prelogin.* | MainController | Generated when an action before login is performed (from URL) |
main.postlogin.* | MainController | Generated when an action after login is performed (from URL) |