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.
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.
<?php
namespace Addons\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()
{
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()
{
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()
{
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()
{
// Create related service custom field if it doesn't exist.
$this->createField();
return true;
}
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()
{
$this->deleteField(false);
// Remove settings
$this->removeSettings();
return true;
}
Additional Controllers
Additional controllers can be stored in the Controllers folder and used alongside the main controller. These classes have no constraints.
Web Controller
Below is an example web controller. See Web Route Files for defining routes.
<?php
namespace Addons\Plugins\HelloWorld\Controllers;
use App\Modules\Core\Controllers\Controller;
class WebController extends Controller
{
public function foo()
{
return response()->make('Foo');
}
}
To return a view or template file, see Views.
API Controller
API controllers must return a JSON response, below is an example API controller. See API Route Files for defining API routes.
<?php
namespace Addons\Plugins\HelloWorld\Controllers;
use App\Modules\Core\Controllers\BaseApiController;
class ApiController extends BaseApiController
{
public function foo()
{
return response()->json([
'status' => 'success',
'data' => 'foo',
]);
}
}
To return an error message, there are several available exceptions:
// General resource error.
throw new \App\Exceptions\Api\ResourceException('message');
// Store failed error.
throw new \App\Exceptions\Api\StoreResourceFailedException('message');
// Update failed error.
throw new \App\Exceptions\Api\UpdateResourceFailedException('message');
// Delete failed error.
throw new \App\Exceptions\Api\DeleteResourceFailedException('message');
// Not found error.
throw new \Symfony\Component\HttpKernel\Exception\HttpException(404, 'message');
// Custom HTTP error, set a HTTP error code (int).
throw new \Symfony\Component\HttpKernel\Exception\HttpException($code, 'message');
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}."
]);