Plugin Development: Controllers

Previous Section: Getting Started


Controllers contain the logic of the plugin and is where most of your code will go. SupportPal is built on top of the Laravel framework, and thus most of the features available in the framework are also available to you to use in plugins, such as caching and the query builder.

Contents

Main Plugin Controller

Your plugin must have a PHP class and file with the same name in the Controllers folder. The namespace must be set correctly and the class should extend the Plugin class like in our example controller below. The class should have a constructor where parent::__construct(); and setIdentifier('PluginName') is called and must also have declared activate, deactivate and uninstall functions that are described in more detail below.

Controllers/HelloWorld.php

    <?php

    namespace App\Plugins\HelloWorld\Controllers;

    use App\Modules\Core\Controllers\Plugins\Plugin;

    class HelloWorld extends Plugin
    {
        /**
         * Initialise the plugin
         */
        public function __construct()
        {
            parent::__construct();

            $this->setIdentifier('HelloWorld');
        }

        /**
         * Plugins can run an installation routine when they are activated. This
         * will typically include adding default values, initialising database tables
         * and so on.
         *
         * @return boolean
         */
        public function activate()
        {
            // Do nothing
            return true;
        }

        /**
         * Deactivating serves as temporarily disabling the plugin, but the files still
         * remain. This function should typically clear any caches and temporary directories.
         *
         * @return boolean
         */
        public function deactivate()
        {
            // Do nothing
            return true;
        }

        /**
         * When a plugin is uninstalled, it should be completely removed as if it never
         * was there. This function should delete any created database tables, and any files
         * created outside of the plugin directory.
         *
         * @return boolean
         */
        public function uninstall()
        {
            // Do nothing
            return true;
        }
    }

Activation

The activate function is called when the plugin is activated in the operator panel, it must return a Boolean to determine if it was activated successfully. In this function you may wish to set up any settings and/or database tables used for this plugin. Our example below calls a function we've declared later in the class that adds a custom field.


    public function activate()
    {
        try {
            // Create related service custom field if it doesn't exist
            $this->createField();

            return true;
        } catch (Exception $e) {
            return false;
        }
    }

Deactivation

The deactivate function is called when the plugin is deactivated in the operator panel, it must return a Boolean to determine if it was deactivated successfully. In this function you may wish to revert any data saved or changed by the plugin when it was activated.

Uninstalling

The uninstall function is called when the plugin is uninstalled in the operator panel, it must return a Boolean to determine if it was uninstalled successfully. In this function you should remove any data that was added by the plugin. The uninstall option will also remove the plugin folder from the file system. Our example below calls a function we've declared later in the class that deletes the custom field it originally added and removes all settings related to the plugin (described later in this guide).


    public function uninstall()
    {
        try {
            $this->deleteField(false);

            // Remove settings
            $this->removeSettings();

            return true;
        } catch (Exception $e) {
            return false;
        }
    }

Additional Controllers

Additional controllers can be stored in the Controllers folder and used alongside the main controller. These classes have no constraints.

Authenticated Operator

The logged in operator's model can be fetched with the auth_user helper function.


    $operator = auth_user();

    $name = $operator->formatted_name;
    $settings = $operator->opsettings;

Activity Logging

You may wish to add an activity log entry when the plugin completes an action automatically so it's more visible that the action has happened. Below is a simple example of this using our activity log model.


    \App\Modules\Core\Models\ActivityLog::addEntry([
        'type'       => \App\Modules\Core\Models\ActivityLog::SYSTEM,
        'event_text' => "Sent a ticket status updated Slack notification for #{$ticket->number}."
    ]);

Next Section: Routes