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:

  1. Directory name within the plugin name: Example: Authenticator
  2. Filename within the plugin name in lowercase: Example: authenticator.po
  3. 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)