optix-app / php-client
PHP Client to consume Optix GraphQL API
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.2
- illuminate/database: ^10.0
- illuminate/http: ^10.0
- illuminate/routing: ^10.0
- illuminate/support: ^10.0
Requires (Dev)
README
Optix PHP Library
This library enables your Laravel application to easily make requests to Optix GraphQL API.
This library is designed to use PHP 8.1 and Laravel 9
Installation
composer require optix-app/php-client
Use composer to install in your existing project. If you are starting a project from scratch, we recommend you to use our Laravel boilerplate.
Don't forget to publish the new configuration file.
php artisan vendor:publish --provider="Optix\OptixServiceProvider"
Usage
Using the OptixAPI
to query Optix GraphQL API
Create the file me.graphql
within a new project root folder called graphql-queries
. Separating queries from your code avoid a cluttered code, and most modern code editors allow .graphql
formatting.
# graphql-queries/me.graphql
query me {
me {
user {
name
user_id
}
}
}
Then at the PHP...
// Anywhere in your code
$optix_api = new \Optix\OptixAPI('<Your Optix GraphQL API Key>');
$response = $optix_api->query('graphql-queries/me.graphql');
print_r($response->getData());
If your query has variables you can declare them at the .graphql
file and provide the variables at
/*
# at your file graphql-queries/users.graphql
query users ($limit: Int) {
users(limit: $limit){
total
data {
user_id
name
}
}
}
*/
// Anywhere
$optix_api = new \Optix\OptixAPI('<Your Optix GraphQL API Key>');
$response = $optix_api->query('graphql-queries/users.graphql', [
'limit' => 5
]);
// Get entire response
print_r($response->getData());
// Get specific part of the response
print_r($response->getData('users.data'));
// Returns true if an "errors" key is found in the response
print_r($response->hasErrors());
// Get query errors
print_r($response->getErrors());
Using the EnsureOptixToken
to protect endpoints
At your route, use optix.token
middleware, it will check the token
and will add token_info
to the request.
// You can provide a role as parameter to protect the endpoint `admin` or `active_user` role
Route::middleware('optix.token:admin')->get('/test', function (Request $request) {
// You can read at $request->input('token_info')
/*
{
"organization": {
"organization_id": "0000",
"name": "Organization name",
"timezone": "America/Vancouver",
"logo": "https://url.to.image..."
},
"user": {
"user_id": "0000",
"fullname": "User name",
"email": "user@example.com",
"is_admin": true,
"is_active": true,
"image": {
"has_image": false,
"large": "https://url.to.image"
}
}
}
*/
// Return everything for this example
return $request->input();
});
Handling basic webhooks
This library also provides a basic handling for the most common webhooks related to platform apps:
- App installation (
app_install
) - App uninstall (
app_uninstall
) - Organization token updated (
organization_token_updated
)
You can check more details about these webhooks at Optix Webhooks List.
In order to save at the database the organizations that have installed the app, the service provider will register a few routes and create a migration file to create a table called optix_organizations
. The service provider do not create models for the table, feel free to create them as you wish.
Don't forget to set at the .env
file the OPTIX_SECRET=
parameter, with the signature secret generated at your Optix Web Dashboard > App > Develop page. At the same page you should save a basic settings file:
{
"webhooks": [
{
"event": "app_install",
"url": "https://example.com/optix-webhook/app_install"
},
{
"event": "app_uninstall",
"url": "https://example.com/optix-webhook/app_uninstall"
},
{
"event": "organization_token_updated",
"url": "https://example.com/optix-webhook/organization_token_updated"
}
]
}
You can use a tool like
ngrok
orexpose
to make your local environment accessible to the webhooks
Its also possible to listen for events related to the app installation, so you can handle additional actions directly into your app:
<?php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Event;
use Optix\Events\AppInstalled;
class AppServiceProvider extends ServiceProvider
{
/**
* Bootstrap any application services.
*
* @return void
*/
public function boot()
{
Event::listen(function (AppInstalled $event) {
// Handle $event->optix_organization_id ...
// you can fetch additional data or trigger internal actions in your app
});
}
}
For other Optix webhooks you can also use a generic listener url:
{
"webhooks": [
{
"event": "assignment_started",
"url": "https://example.com/optix-webhook/listener"
},
{
"event": "invoice_paid",
"url": "https://example.com/optix-webhook/listener"
}
]
}
For the /listener
url, all webhooks will trigger a generic webhook event:
use Optix\Events\GenericWebhook;
Event::listen(function (GenericWebhook $event) {
// Handle $event->event ...
// Handle $event->optix_organization_id ...
// Handle $event->payload ...
});
The generic listener will only validate the signature and dispatch the event, no other action will be executed by the library (persist at the database or check key validity).