115 lines
5.0 KiB
Markdown
Executable File
115 lines
5.0 KiB
Markdown
Executable File
# UCRM Plugin SDK
|
|
[](https://coveralls.io/github/Ubiquiti-App/UCRM-Plugin-SDK)
|
|
[](https://packagist.org/packages/ubnt/ucrm-plugin-sdk)
|
|
[](https://packagist.org/packages/ubnt/ucrm-plugin-sdk)
|
|
|
|
This repository contains the open source PHP SDK for [UCRM plugins](https://github.com/Ubiquiti-App/UCRM-plugins).
|
|
|
|
## Installation
|
|
The UCRM Plugin SDK can be installed with [Composer](https://getcomposer.org/). Run this command:
|
|
```
|
|
composer require ubnt/ucrm-plugin-sdk
|
|
```
|
|
|
|
## Available classes
|
|
|
|
Class name | Description
|
|
---------- | -----------
|
|
[Ubnt\UcrmPluginSdk\Service\UcrmApi](src/UcrmPluginSdk/Service/UcrmApi.php) | A service that handles calling UCRM API.
|
|
[Ubnt\UcrmPluginSdk\Service\UnmsApi](src/UcrmPluginSdk/Service/UnmsApi.php) | A service that handles calling UNMS API.
|
|
[Ubnt\UcrmPluginSdk\Service\UcrmSecurity](src/UcrmPluginSdk/Service/UcrmSecurity.php) | A service that handles getting data of user currently logged into UCRM.
|
|
[Ubnt\UcrmPluginSdk\Service\PluginLogManager](src/UcrmPluginSdk/Service/PluginLogManager.php) | A service that handles managing the plugin's log file.
|
|
[Ubnt\UcrmPluginSdk\Service\UcrmOptionsManager](src/UcrmPluginSdk/Service/UcrmOptionsManager.php) | A service that handles loading automatically generated options available to the plugin.
|
|
[Ubnt\UcrmPluginSdk\Service\PluginConfigManager](src/UcrmPluginSdk/Service/PluginConfigManager.php) | A service that handles loading configuration of the plugin as defined in the plugin's manifest file.
|
|
|
|
## Usage
|
|
Simple example using available SDK classes:
|
|
```php
|
|
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](https://github.com/Ubiquiti-App/UCRM-plugins) 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](https://github.com/Ubiquiti-App/UCRM-Plugin-SDK/blob/master/LICENSE.md).
|