README

This repository contains the open source PHP SDK for UCRM plugins.

Installation

The UCRM Plugin SDK can be installed with Composer. Run this command:

composer require ubnt/ucrm-plugin-sdk

Available classes

Class name	Description
Ubnt\UcrmPluginSdk\Service\UcrmApi	A service that handles calling UCRM API.
Ubnt\UcrmPluginSdk\Service\UnmsApi	A service that handles calling UNMS API.
Ubnt\UcrmPluginSdk\Service\UcrmSecurity	A service that handles getting data of user currently logged into UCRM.
Ubnt\UcrmPluginSdk\Service\PluginLogManager	A service that handles managing the plugin's log file.
Ubnt\UcrmPluginSdk\Service\UcrmOptionsManager	A service that handles loading automatically generated options available to the plugin.
Ubnt\UcrmPluginSdk\Service\PluginConfigManager	A service that handles loading configuration of the plugin as defined in the plugin's manifest file.

Usage

Simple example using available SDK classes:

require_once __DIR__ . '/vendor/autoload.php';

// Get UCRM log manager.
$log = \Ubnt\UcrmPluginSdk\Service\PluginLogManager::create();

// Check if there is a user logged into UCRM and has permission to view invoices.
// https://github.com/Ubiquiti-App/UCRM-plugins/blob/master/docs/security.md
$security = \Ubnt\UcrmPluginSdk\Service\UcrmSecurity::create();
$user = $security->getUser();
if (
    ! $user
    || ! $user->hasViewPermission(\Ubnt\UcrmPluginSdk\Security\PermissionNames::BILLING_INVOICES)
) {
    if (! headers_sent()) {
        header("HTTP/1.1 403 Forbidden");
    }

    $log->appendLog('Someone tried to access page only for admins with permission to view invoices.');

    die('You\'re not allowed to access this page.');
}

$log->appendLog('Starting invoice export.');

// Get export format from plugin's configuration.
// https://github.com/Ubiquiti-App/UCRM-plugins/blob/master/docs/manifest.md#configuration
$configManager = \Ubnt\UcrmPluginSdk\Service\PluginConfigManager::create();
$config = $configManager->loadConfig();
// the "exportFormat" key must be defined in plugin's manifest file, see the link above
$exportFormat = $config['exportFormat'];

// Get UCRM API manager.
$api = \Ubnt\UcrmPluginSdk\Service\UcrmApi::create();

// Load invoices from UCRM API ordered by created date in descending direction.
// https://ucrm.docs.apiary.io/#reference/invoices/invoicesclientidcreateddatefromcreateddateto/get
$invoices = $api->get(
    'invoices',
    [
        'order' => 'createdDate',
        'direction' => 'DESC',
    ]
);

foreach ($invoices as $invoice) {
    // some export implementation, using the $exportFormat
}

// Get plugin's public URL from automatically generated UCRM options.
// https://github.com/Ubiquiti-App/UCRM-plugins/blob/master/docs/file-structure.md#ucrmjson
$optionsManager = \Ubnt\UcrmPluginSdk\Service\UcrmOptionsManager::create();
$pluginPublicUrl = $optionsManager->loadOptions()->pluginPublicUrl;

$log->appendLog(sprintf('Finished invoice export. Take a look at %s.', $pluginPublicUrl));

Pack script

To pack your plugin for use in UCRM, you can use the provided pack script. Run this command from the root directory:

./vendor/bin/pack-plugin

The script will create ZIP archive of the plugin, which can be uploaded to UCRM. If you are using the directory structure of official UCRM plugins repository the archive will be created one level up, next to your README.md file and src/ directory. Otherwise it will be created in your root directory.

If the plugin's root directory is not detected correctly, you can give it to the script as an argument. For example:
./vendor/bin/pack-plugin /home/username/my-new-plugin

Tests

Unit tests can be executed by running this command from the root directory:

./vendor/bin/phpunit

Static analysis can be executed by running this command from the root directory:

./vendor/bin/phpstan analyse src tests --level max

Coding standard check can be executed by running this command from the root directory:

./vendor/bin/ecs check src tests

Disclaimer

The software is provided "as is", without any warranty of any kind. Read more in the licence.

ubnt / ucrm-plugin-sdk

Maintainers

Details