Plugins

Documentación para sysPass 3.0.0 · Última revisión 05/01/2019

Estos documentos se revisaron por última vez para sysPass 3.0.0 y puede que no describan la versión actual.

sysPass permite el uso de plugins mediante una arquitectura que implementa el patrón de observador el cual se caracteriza por emitir un mensaje a todos los observadores registrados.

Los plugins se instalan en el directorio ‘sysPass/inc/Plugins’ y contienen la siguiente estructura básica:

Plugins/
└── NombrePlugin (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
    │
    └── NombrePluginPlugin.class.php (3)

Los nombres de los directorios y archivos deben de ser de la siguiente manera:

1. Nombre de directorio con el nombre del plugin. Ejemplo: Authenticator
2. Nombre de archivo con el nombre del plugin en minúscula. Ejemplo: authenticator.po
3. Nombre de archivo con el nombre del plugin seguido de “Plugin.class.php”. Ejemplo: AuthenticatorPlugin.class.php

La clase principal se debe de llamar igual que el plugin y tiene que extender a la clase PluginBase. Esta clase tiene que implementar los siguientes métodos.

Métodos

init

Método que se llama cada vez que se ejecuta el plugin

/**
 * Inicialización
 */
public function init() {}

updateEvent

Método que se llama cuando se emite un evento

/**
 * Evento de actualización
 *
 * @param string $event Nombre del evento
 * @param mixed  $object
 */
public function updateEvent($event, $object) {}

getEvents

Método que devuelve un array de strings con los eventos a los que se suscribe el plugin

/**
 * Devuelve los eventos que implementa el observador
 *
 * @return array
 */
public function getEvents()
{
    return ['user.preferences', 'main.prelogin.2fa', 'login.preferences'];
}

getJsResources

Método que devuelve un array de strings con los recursos Javascript que necesita el plugin

/**
 * Devuelve los recursos JS y CSS necesarios para el plugin
 *
 * @return array
 */
public function getJsResources()
{
    return ['plugin.min.js'];
}

getAuthor

Método que devuelve el nombre del autor del plugin

/**
 * Devuelve el autor del plugin
 *
 * @return string
 */
public function getAuthor()
{
    return 'Rubén D.';
}

getVersion

Método que devuelve un array de integers con la versión del plugin

/**
 * Devuelve la versión del plugin
 *
 * @return array
 */
public function getVersion()
{
    return [1, 0];
}

getCompatibleVersion

Método que devuelve un array de integers con la versión mínima de sysPass compatible

/**
 * Devuelve la versión compatible de sysPass
 *
 * @return array
 */
public function getCompatibleVersion()
{
    return [2, 0];
}

getCssResources

Método que devuelve un array de strings con los recursos CSS que requiere el plugin

/**
 * Devuelve los recursos CSS necesarios para el plugin
 *
 * @return array
 */
public function getCssResources()
{
    return [];
}

getName

Método que devuelve el nombre del plugin

/**
 * Devuelve el nombre del plugin
 *
 * @return string
 */
public function getName()
{
    return self::PLUGIN_NAME;
}

getData

Método que devuelve los datos del plugin

/**
 * @return array|AuthenticatorData[]
 */
public function getData()
{
    return (array)parent::getData();
}

Ejemplo

<?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();
  }
}

Eventos

Cuando se emite un evento se incluye la instancia de la clase donde se genera, por lo que es posible acceder a los métodos de dicha clase.

Actualmente, los eventos producidos son los siguientes: