i-MSCP SamplePlugin entry point class

SamplePlugin.php

<?php
/**
 * i-MSCP SamplePlugin plugin
 *
 * @author        Laurent Declercq <l.declercq@nuxwin.com>
 * @copyright (C) 2019 Laurent Declercq <l.declercq@nuxwin.com>
 * @license       i-MSCP License <https://www.i-mscp.net/license-agreement.html>
 */

/** @noinspection PhpUnhandledExceptionInspection PhpDocMissingThrowsInspection */

declare(strict_types=1);

use iMSCP\SamplePlugin\ServiceProvider;
use Pimple\ServiceProviderInterface;

/**
 * Class iMSCP_Plugin_SamplePlugin
 *
 * This class represents the entry point of the plugin. Every
 * plugin *MUST* provide this class.
 *
 * The class name of a plugin *MUST* follow a specific naming convention:
 * iMSCP_Plugin_<plugin_name>, and *MUST* extends the iMSCP_Plugin_Action
 * class.
 * 
 * Depending on the plugin API version for which the plugin is developed,
 * <plugin_name> *MUST* match with the plugin directory name
 * (API < 1.5.1), or with the plugin' name info field (API >= 1.5.1).
 */
class iMSCP_Plugin_SamplePlugin extends iMSCP_Plugin_Action
{
    /**
     * Initialization routine.
     *
     * This method is OPTIONAL.
     *
     * This method is automatically called on the plugin instantiation.
     * This is the best place to perform plugin initialization tasks such
     * as registering translation resources, additional autoloaders and so
     * on...
     *
     * @inheritDoc
     */
    public function init()
    {
        if ($this->getPluginManager()->pluginIsEnabled($this->getName())) {
            // Add plugin translation resources
            /*l10n_addTranslations(
                __DIR__ . '/resources/l10n',
                'Array',
                $this->getName()
            );*/

            // Add plugin autoloader (composer)
            // Not needed since packages are added into control panel (frontEnd)
            // composer.json...
            // require __DIR__ . '/vendor/autoload.php';
        }
    }

    /**
     * Register plugin event listeners.
     *
     * This method is automatically called by the plugin manager, after the
     * plugin instantiation. This is the place to register the plugin event
     * listeners.
     *
     * @inheritDoc
     */
    public function register(iMSCP_Events_Manager_Interface $events)
    {
        if ($this->getPluginManager()->pluginIsInstalled($this->getName())) {
            // Return early if the plugin is already installed. Even if the
            // registration of event listeners is cheap, there is no reasons
            // to register an event listener for an event that would be never
            // triggered for that plugin.
            return;
        }

        // Register an event listener that is responsible to check
        // for the plugin requirements when it is being installed.
        $events->registerListener(
            iMSCP_Events::onBeforeInstallPlugin,
            [$this, 'checkForPluginRequirements']
        );
    }

    /**
     * Event listener responsible to check for the plugin requirements.
     *
     * This is the implementation of the plugin event listener that we have
     * registered through the register() method above.
     *
     * @param iMSCP_Events_Event $event
     * @return void
     */
    public function checkForPluginRequirements(iMSCP_Events_Event $event)
    {
        if ($event->getParam('pluginName') != $this->getName()) {
            // The iMSCP_Events::onBeforeInstallPlugin event is a general event
            // that's triggered by the plugin manager when a plugin is being
            // installed. All plugins that listen on that event will receive
            // it, and that why we need make sure the event has been triggered
            // for this plugin, by checking the value of the 'pluginName'
            // parameter. Not doing this could lead to unexpected behavior,
            // unless really expected.
            //
            // Return early if the event hasn't been triggered for this plugin.
            return;
        }

        // Check for plugin requirements
        if (
            // You need of course replace the condition by your own code...
            // For this example, the condition will always evaluate to FALSE,
        false
        ) {
            // If one of the requirements for this plugin isn't met, we stop
            // the event propagation. For the plugin manager, this means that
            // the installation need to be aborted...
            $event->stopPropagation(true);
        }
    }

    /**
     * Plugin installation routine.
     *
     * This method is OPTIONAL, unless the plugin provides a backend-side that
     * defines the install() method. In such a case, this method need to be
     * defined, even with an empty body, to tell the plugin manager that the
     * plugin provides a backend-side installation routine.
     *
     * When defined, this method is automatically called by the plugin manager
     * when the plugin is being installed. This method is the best place to
     * perform plugin installation tasks such as database schema initialization
     * and so on....
     *
     * On failure, this method *MUST* throw an iMSCP_Plugin_Exception exception.
     *
     * WARNING: This method *MUST* be idempotent, that is, *MUST* produce the
     * same result on multiple invocations without failing.
     *
     * @inheritDoc
     */
    public function install(iMSCP_Plugin_Manager $pm)
    {
        try {
            // The migrateDb() method is part of the iMSCP_Plugin base class.
            // This method provides a convenient way to alter plugins's
            // database schema over the time in a consistent and easy way.
            // Here, we're executing all migrations (database schema
            // initialization).
            $this->migrateDb('up', __DIR__ . '/migrations');
        } catch (Exception $e) {
            throw new iMSCP_Plugin_Exception(
                $e->getMessage(), $e->getCode(), $e
            );
        }
    }

    /**
     * Plugin uninstallation routine.
     *
     * This method is OPTIONAL, unless the plugin provides a backend-side that
     * defines the uninstall() method. In such a case, this method need to be
     * defined, even with an empty body, to tell the plugin manager that the
     * plugin provides a backend-side uninstallation routine.
     *
     * When defined, this method is automatically called by the plugin manager
     * when the plugin is being uninstalled. This method is the best place to
     * perform plugin uninstallation tasks such as database migrations rollback
     * and so on...
     *
     * On failure, this method *MUST* throw an iMSCP_Plugin_Exception exception.
     *
     * WARNING: This method *MUST* be idempotent, that is, *MUST* produce the
     * same result on multiple invocations without failing.
     *
     * @inheritDoc
     */
    public function uninstall(iMSCP_Plugin_Manager $pm)
    {
        try {
            // The migrateDb() method is part of the iMSCP_Plugin base class.
            // This method provides a convenient way to alter plugins's
            // database schema over the time in a consistent and easy way.
            // Here, we're rolling back all migrations.
            $this->migrateDb('down', __DIR__ . '/migrations');
        } catch (Exception $e) {
            throw new iMSCP_Plugin_Exception(
                $e->getMessage(), $e->getCode(), $e
            );
        }
    }

    /**
     * Plugin update routine.
     *
     * This method is OPTIONAL.
     *
     * When defined, this method is automatically called by the plugin manager
     * when the plugin is being updated. This method is the best place to
     * perform plugin update tasks such as database schema upgrade and so on...
     *
     * On failure, this method *MUST* throw an iMSCP_Plugin_Exception exception.
     *
     * WARNING: This method *MUST* be idempotent, that is, *MUST* produce the
     * same result on multiple invocations without failing.
     *
     * @inheritDoc
     */
    public function update(iMSCP_Plugin_Manager $pm, $fromVersion, $toVersion)
    {
        try {
            // The migrateDb() method is part of the iMSCP_Plugin base class.
            // This method provides a convenient way to alter plugins's
            // database schema over the time in a consistent and easy way.
            // Here, we're executing all migrations (database schema upgrade).
            $this->migrateDb('up', __DIR__ . '/migrations');
        } catch (Exception $e) {
            throw new iMSCP_Plugin_Exception(
                $e->getMessage(), $e->getCode(), $e
            );
        }
    }

    /**
     * Plugin deletion routine.
     *
     * This method is OPTIONAL.
     *
     * When defined, this method is automatically called by the plugin manager
     * when the plugin is being deleted. This method is the best place to
     * perform plugin deletion tasks such as directory deletion and so on...
     *
     * On failure, this method *MUST* throw an iMSCP_Plugin_Exception exception.
     *
     * WARNING: This method *MUST* be idempotent, that is, *MUST* produce the
     * same result on multiple invocations without failing.
     *
     * @inheritDoc
     */
    public function delete(iMSCP_Plugin_Manager $pm)
    {
        try {
            // TODO Implement your deletion tasks here if any ....
        } catch (Exception $e) {
            throw new iMSCP_Plugin_Exception(
                $e->getMessage(), $e->getCode(), $e
            );
        }
    }

    /**
     * Activation routine
     *
     * This method is OPTIONAL.
     *
     * When defined, this method is automatically called by the plugin manager
     * when the plugin is being activated. This method is the best place to
     * perform plugin activation tasks.
     *
     * On failure, this method *MUST* throw an iMSCP_Plugin_Exception exception.
     *
     * WARNING: This method *MUST* be idempotent, that is, *MUST* produce the
     * same result on multiple invocations without failing.
     *
     * @inheritDoc
     */
    public function enable(iMSCP_Plugin_Manager $pm)
    {
        try {
            // TODO Implement your plugin activation tasks here if any ...
        } catch (Exception $e) {
            throw new iMSCP_Plugin_Exception(
                $e->getMessage(), $e->getCode(), $e
            );
        }
    }

    /**
     * Deactivation routine
     *
     * This method is OPTIONAL.
     *
     * When defined, this method is automatically called by the plugin manager
     * when the plugin is being deactivated. This method is the best place to
     * perform plugin deactivation tasks.
     *
     * On failure, this method *MUST* throw an iMSCP_Plugin_Exception exception.
     *
     * WARNING: This method *MUST* be idempotent, that is, *MUST* produce the
     * same result on multiple invocations without failing.
     *
     * @inheritDoc
     */
    public function disable(iMSCP_Plugin_Manager $pm)
    {
        try {
            // TODO Implement your plugin deactivation tasks here if any...
        } catch (Exception $e) {
            throw new iMSCP_Plugin_Exception(
                $e->getMessage(), $e->getCode(), $e
            );
        }
    }

    /**
     * Return the plugin service provider (since plugin API 1.5.1)
     *
     * This method is OPTIONAL.
     *
     * When defined, and if the plugin is activated, this method is
     * automatically called by the i-MSCP plugin service providers injector
     * which inject the plugin service provide into the Slim dependency
     * container.
     *
     * A plugin service provider make it possible to prepare, manage and
     * inject the plugin dependencies.
     *
     * See also: http://www.slimframework.com/docs/v3/concepts/di.html
     *
     * @inheritDoc
     */
    public function getServiceProvider(): ServiceProviderInterface
    {
        return new ServiceProvider();
    }

    /**
     * Return the plugin routes
     *
     * This method is OPTIONAL.
     *
     * When defined, and if the plugin is activated and that a plugin request
     * is involved, this method is automatically called by the i-MSCP plugin
     * routes injector which inject the plugin routes into the Slim router.
     *
     * In the Slim documentation, routes are added programmatically. The i-MSCP
     * plugin routes injector provides the so-called configuration-driven
     * routing.
     *
     * See also: http://www.slimframework.com/docs/v3/objects/router.html
     *
     * @inheritDoc
     */
    public function getRoutes()
    {
        return include __DIR__ . '/routes.php';
    }

    /**
     * Return list of plugin item (entities) that are in inconsistent (error)
     * state.
     *
     * This method *MUST* be implemented each time a plugin manages its own
     * items (entities) for which state can change, that is, those for which a
     * backend-side processing is involved.
     *
     * When defined, this method is automatically called by the i-MSCP debugger
     * component to get the list of plugin items (entities) that are in an
     * inconsistent (error) state.
     *
     * The returned list *MUST* be as follows:
     * <code>
     * [
     *  [
     *      'item_id'   => <the item (entity) unique identifier>,
     *      'status'    => <the item (entity status string)>
     *      'item_name' => <the item (entity) name. This is an arbitrary name for the entity>
     *      'table'     => <the database table for the item (entity)>
     *      'field'     => <the database table column name for the item (entity)>
     *  ],
     *  ...
     * ]
     * <code>
     *
     * @inheritDoc
     */
    public function getItemWithErrorStatus()
    {
        return [];
    }

    /**
     * Schedule change of the given plugin item (entity).
     *
     * This method *MUST* be implemented each time a plugin manages its own
     * items (entities) for which state can change, that is, those for which a
     * backend-side processing is involved.
     *
     * When defined, this method is automatically called by the i-MSCP debugger
     * component, when the administrator schedule change of an item (entity).
     *
     * This method receives the following arguments:
     *  - $table  : The table that holds the item (entity)
     *  - $field  : The name of the status column for that item (entity)
     *  - $itemId : The unique identifier of the item (entity)
     *
     * When you implement this method, you need not forget to check the value
     * of the $table and $field arguments, as the i-MSCP debugger component
     * acts without making any distinction between the various entities, that
     * is, without check that the entities belong to this plugin.
     *
     * @inheritDoc
     */
    public function changeItemStatus($table, $field, $itemId)
    {
    }

    /**
     * Return count of backend requests for the plugin items (entities).
     *
     * This method *MUST* be implemented each time a plugin manage its own
     * items (entities) for which state can change, that is, those for which a
     * processing on the backend-side is involved.
     *
     * If defined, this method is automatically called by the i-MSCP debugger
     * component to get the count of plugin items (entities) for which a
     * backend request is pending.
     *
     * @inheritDoc
     */
    public function getCountRequests()
    {
        return 0;
    }
}