README

Optix PHP 库

此库使您的 Laravel 应用程序能够轻松地向 Optix GraphQL API 发送请求。

此库旨在使用 PHP 8.1 和 Laravel 9

安装

composer require optix-app/php-client

使用 composer 在现有项目中安装。如果您是从零开始的项目，我们建议您使用我们的 Laravel 烧录板。

别忘了发布新的配置文件。

php artisan vendor:publish --provider="Optix\OptixServiceProvider"

用法

使用 OptixAPI 查询 Optix GraphQL API

在名为 graphql-queries 的新项目根目录中创建文件 me.graphql。将查询与您的代码分开可以避免代码混乱，并且大多数现代代码编辑器都允许 .graphql 格式化。

# graphql-queries/me.graphql
query me {
  me {
    user {
      name
      user_id
    }
  }
}

然后在 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());

如果您的查询有变量，您可以在 .graphql 文件中声明它们，并在

/*
# 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());

使用 EnsureOptixToken 保护端点

在您的路由中，使用 optix.token 中间件，它将检查 token 并将 token_info 添加到请求。

// 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();
});

处理基本 Webhooks

此库还提供对与平台应用相关的最常见 Webhooks 的基本处理

• 应用安装 (app_install)
• 应用卸载 (app_uninstall)
• 组织令牌更新 (organization_token_updated)

您可以在 Optix Webhooks 列表 中查看更多有关这些 Webhooks 的详细信息。

为了在数据库中保存已安装应用的机构，服务提供者将注册一些路由并创建一个迁移文件来创建一个名为 optix_organizations 的表。服务提供者不会为表创建模型，您可以根据需要自由创建它们。

别忘了在 .env 文件中设置 OPTIX_SECRET= 参数，使用在 Optix Web Dashboard > App > Develop 页面生成的签名密钥。在同一页面上，您应该保存一个基本的 设置文件

{
  "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"
    }
  ]
}

您可以使用类似 ngrok 或 expose 的工具使您的本地环境可被 Webhooks 访问

还可能监听与应用安装相关的事件，因此您可以直接在您的应用程序中处理其他操作

<?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
        });
    }
}

对于其他 Optix Webhooks，您也可以使用通用的监听器 URL

{
  "webhooks": [
    {
      "event": "assignment_started",
      "url": "https://example.com/optix-webhook/listener"
    },
    {
      "event": "invoice_paid",
      "url": "https://example.com/optix-webhook/listener"
    }
  ]
}

对于 /listener URL，所有 Webhooks 都会触发一个通用的 Webhook 事件

use Optix\Events\GenericWebhook;

Event::listen(function (GenericWebhook $event) {
    // Handle $event->event ...
    // Handle $event->optix_organization_id ...
    // Handle $event->payload ...
});

通用监听器将仅验证签名并分发事件，库不会执行其他操作（在数据库中持久化或检查密钥的有效性）。