Download the PHP package spinen/n-central-php-rest-client without Composer
On this page you can find all versions of the php package spinen/n-central-php-rest-client. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package n-central-php-rest-client
NOTE: This is VERY early. This is changing as N-central updates their API & as we get a better understanding of the API. There are broken tests & some missing code, but we will firm this up over the next few weeks.
SPINEN's N-central PHP Client
PHP package to interface with N-able's N-central Server. We strongly encourage you to review N-central's API docs to get a feel for what this package can do, as we are just wrapping their API. We have based the majority of this code from our Halo PHP Client.
We solely use Laravel for our applications, so this package is written with Laravel in mind. We have tried to make it work outside of Laravel. If there is a request from the community to split this package into 2 parts, then we will consider doing that work.
Build Status
Branch | Status | Coverage | Code Quality |
---|---|---|---|
Develop | |||
Master |
Table of Contents
- Installation
- Laravel Setup
- Configuration
- Generic PHP Setup
- Examples
- Authentication
- JWT
- Usage
- Supported Actions
- Using the Client
- Getting the Client object
- Models
- Relationships
- Collections
- Filtering using "where"
- Search
- Limit records returned
- Order By
- Pagination
- More Examples
- Known Issues
Installation
Install N-central PHP Package via Composer:
Laravel Setup
-
Add the appropriate values to your file
Keys
-
[Optional] If you would like to use the client with API calls per user in your application, you will need to make your
User
object implement includes theSpinen\Ncentral\Concerns\HasNcentral
trait which will allow it to access the Client as an attribute like this:$user->ncentral
-
[Optional] Publish config & migration
Config
A configuration file named
ncentral.php
can be published toconfig/
by running...Migration
Migrations files can be published by running...
You'll need the migration to set the N-central API token on your
User
model.
Generic PHP Setup
-
You need to build up an array of configs to pass into the N-central object. You review the
ncentral.php
file in theconfigs
directory. All of the properties are documented in the file. -
Depending on your needs, you can either work with the N-central client or the Builder
To get a
Spinen\Ncentral\Api\Client
instance for Client Credentials...To get a
Spinen\Ncentral\Support\Builder
instance...If using the
ncentral
property from theuser
model, it the will work exactly like all of the examples below where$builder
is used.
Authentication
N-central uses a JWT token for a user that is limited to only API calls. This prevents ths account from being able to log directly into the application. To obtain the "N-central User-API Token (JWT)", visit the N-central UI. Then navigate to Administration → User Management → Users → Click on user → API Access → GENERATE JSON WEB TOKEN.
Usage
Supported Actions for Spinen\Ncentral\Api\Client
-
[NOT YET SUPPORTED BY API]
delete(string $path)
- Shortcut to therequest()
method with 'DELETE' as the last parameter -
get(string $path)
- Shortcut to therequest()
method with 'GET' as the last parameter getToken()
- Get, return, or refresh the token.
NOTE: This is the best way to get a token as it handles expiration
-
post(string $path, array $data)
- Shortcut to therequest()
method with 'POST' as the last parameter -
[NOT YET SUPPORTED BY API]
put(string $path, array $data)
- Shortcut to therequest()
method with 'PUT' as the last parameter -
refreshToken()
- Refresh a token -
request(?string $path, ?array $data = [], ?string $method = 'GET')
- Make an API call to N-central to$path
with the$data
using the JWT for the logged in user. -
requestToken()
- Request a token -
setConfigs(array $configs)
- Validate & set the configs -
setDebug(bool $debug)
- Set Guzzle to debug -
setToken(Token|string $token)
- Set the token for the N-central API -
uri(?string $path = null, ?string $url = null)
- Generate a full uri for the path to the N-central API. validToken()
- Is the token valid & if provided a scope, is the token approved for the scope
Using the Client
The Client is meant to emulate Laravel's models with Eloquent. When working with N-central resources, you can access properties and relationships just like you would in Laravel.
Models
The API responses are cast into models with the properties cast into the types as defined in the N-central API documentation. You can review the models in the src/
folder. There is a property named casts
on each model that instructs the Client on how to cast the properties from the API response. If the casts
property is empty, then the properties are not defined in the API docs, so an array is returned.
NOTE: The documented properties on the models are likely to get stale as N-central is in active development
Relationships
NOTE: Not yet setup
Some of the responses have links to the related resources. If a property has a relationship, you can call it as a method and the additional calls are automatically made & returned. The value is stored in place of the original data, so once it is loaded it is cached.
You may also call these relationships as attributes, and the Client will return a Collection
for you (just like Eloquent).
Collections
Results are wrapped in a Spinen\Ncentral\Support\Collection
, which extends Illuminate\Support\Collection
, so you can use any of the collection helper methods documented Laravel Collection methods.
Filtering using "where"
You can do filters by using where
on the models. The first parameter is the property being filtered. The second is optional, and is the value to filter the property. If it is left null, then is it true, so it becomes where('<property', true)
. All of these values are passed in the query string.
There are a few "helper" methods that are aliases to the where
filter, to make the calls more expressive.
whereId('<id>')
is an alias towhere('id', '<id>')
whereNot('<property>')
is an alias towhere('<property', false)
Limit records returned
You can call the take
or limit
methods (take is an alias to limit) on the builder to limit the records returned to the count parameter.
Pagination
Several of the endpoints support pagination. You can use simple pagination by chaining pagination
with an optional size value to the builder. You can get a specific page with the page
method that takes page number as a parameter. You can condense the call by passing pagination size as the second parameter to the page
method.
More Examples
Open Items
- Setup the relationships in the models
- Add getters to models
- Add scopes on models
Known Issues
- They are refining the API, so things may break
All versions of n-central-php-rest-client with dependencies
ext-json Version *
guzzlehttp/guzzle Version ^7.0
laravel/framework Version ^9.19|^10|^11
nesbot/carbon Version ^2.62.1|^3
spinen/laravel-version Version ^1.5