README

安装

composer require faaren-tech/faaren-sdk

// choose FaarenTech/AuthSdk/AuthSdkServiceProvider
php artisan vendor:publish

在配置文件 auth-sdk.php 中自定义 service_url 参数，或在 .env 文件中设置 FAAREN_AUTH_SERVICE_URL 的值。

使用方法

重要！如果您在 Docker 环境中使用此库，则 FAAREN_AUTH_SERVICE_URL 必须是您机器的 IP 地址。否则，它将尝试在其自己的 Docker 网络中查找主机。作为替代方案，您可以在 docker-compose-container 中添加 external_hosts 选项。

您可以通过简单地初始化它来在所有地方使用此包

use FaarenTech\FaarenSDK\FaarenSdk;

class SomeClass {
    
    public function someFunction()
    {
        $sdk = FaarenSdk::init("yourApiToken");
        $token = $sdk->apiToken()->details();
        $permissions = $sdk->apiToken()->permissions();
    }
    
}

Token-Object 包含以下详细信息，例如

{
    "uuid": "tok_22j8HPsYoOKXEMIPHNpHQeBdhKFP",
    "subsidiary_uuid": "subsi_3mz4r520mPr770ZUYtCRdJtFHz",
    "user_uuid": "null OR user_uuid",
    "name": "null OR name",
    "type": "APP_TOKEN OR PERSONAL_TOKEN",
    "permissions": [
        "user:delete",
        "apiToken:create",
        "apiToken:read",
        "apiToken:list",
        "user:update"
    ],
    "plainTextToken": "55|mySecretToken"
}

列出的权限、subsidiary_uuid 和 user_uuid 可以用于制作您应用程序特定的授权。

通知

邮件

您可以通过通知服务简单触发通知

use FaarenTech\FaarenSDK\FaarenSdk;

class SomeClass {
    
    public function someFunction()
    {
        $sdk = FaarenSdk::init("yourApiToken");
        $mailing = $sdk
            ->notification()
            ->mail()
            ->setMailing('example')
            ->setMailData([
                "to" => "fabian@faaren.com",
                "from" => "example@faaren.com",
                "bcc" => "it@faaren.com",
                "whitelabel_config" => [
                    "foo" => "bar"
                ]
            ])
            ->send();
    }
    
}

如果在调用通知服务时发生错误，则会抛出 \FaarenTech\FaarenSDK\Exceptions\NotificationServiceException。异常消息将包含错误提示，例如验证错误

"message": "状态 422：无法发送通知，因为：收件人字段是必需的。",

您可以通过 .env 文件自定义使用的令牌和端点。可用的密钥列在供应商目录中的 /config/faaren-sdk.php 内或，如果您已发布配置，则在您的应用程序配置文件夹中。

中间件

AcceptsJsonMiddleware

HasValidTokenMiddleware

您可以将中间件组 faaren 添加到所有您喜欢的路由。此中间件组包含以下中间件

HasValidTokenMiddleware => 检查给定的令牌是否有效并将令牌详细信息附加到当前请求。详细信息可通过 $request->api_token 获取。

使用此中间件可以轻松地与令牌一起工作。您可以通过请求对象在所有地方访问令牌详细信息

// Route
// Assign middleware
Route::middleware('faaren')
    ->get('/your-endpoint', [SomeController::class, 'someAction']);

// Access in SomeController.php
class SomeController {
    public function someAction(\Illuminate\Http\Request $request) 
    {
        // The provided api token is valid
        // The ApiToken can be accessed via
        $token = $request->api_token;
    }
}

// Access in SomeFormRequest.php
class SomeFormRequest extends \Illuminate\Foundation\Http\FormRequest {
    public function authorize()
    {
        $token = $this->api_token;
    }
}

// Or everywhere via request() helper

表单请求

此包提供了一个基类请求，即 FaarenRequest。此请求通过 Illuminate\Foundation\Auth\Access\Authorizable 特性实现了 Illuminate\Contracts\Auth\Access\Authorizable。它可用于您在服务中创建的任何 FormRequest。

这样就可以在表单请求中直接授权传入的请求

use FaarenTech\FaarenSDK\Request\FaarenRequest;

class YourRequest extends FaarenRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return $this->can('index', SomeModel::class);
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            //
        ];
    }
}

在您的策略中，您不会传入用户实例。相反，您传入表单请求的实例。底层策略

class YourPolicy
{
    use HandlesAuthorization;

    public function index(TemplateIndexRequest $request)
    {
        // Here you can access the methods from the FaarenRequest
        // Access the AppToken via $request->api_token;
        return true;
    }

    public function show(TemplateIndexRequest $request, SomeModel $someModel)
    {
        return true;
    }
}

定义资源

从版本 1.1.0 开始，我们在资源定义中使用 "ResponseCollection" 和 "ResourceCollection"。

要使用您自己的资源与我们的模式一起使用，您需要从 "ResponseResource" 扩展您的资源，而不是从 "JsonResource" 扩展。然后，您需要将您的 "toArray" 方法更改为 "toPayload"。示例

class YourAwesomeResource extends ResponseResource
{
    /**
     * @return array[]
     */
    public function toPayload()
    {
        return [
            'awesome' => true
        ];
    }
}

资源集合

因此，您的资源被映射为 YourAwesomeResourceCollection

class YourAwesomeResourceCollection extends \FaarenTech\FaarenSDK\Resources\ResponseCollection
{
    public $collects = YourAwesomeResource::class;
}

在我们的响应模式中以 JSON 格式进行验证

您的类需要从 "FaarenRequest" 扩展，并且每个验证错误都使用模式

use FaarenTech\FaarenSDK\Request\FaarenRequest;

class ShowVehiclePoolRequest extends FaarenRequest
{
    /**
     * Determine if the user is authorized to make this request.
     *
     * @return bool
     */
    public function authorize()
    {
        return true;
    }

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            //
        ];
    }

}

以 JSON 格式处理异常

简单地将 AcceptsJsonMiddleware 添加到相关的中间件组或作为全局中间件。

使用自定义 Handler 已弃用，并且在使用它时会导致错误！

faaren-tech / faaren-sdk

维护者

详细信息