README

这些类提供了一种简单的方法来使用认证启动 slim v3 应用程序。

它是对 Slim 框架 v3 的一种抽象，处理一些事情，如不同格式的输出生成和身份验证/ acl 处理。

安装

slim-bootstrap3 通过 packagist 提供

composer require bigpoint/slim-bootstrap3

Web服务器配置

为了配置您的Web服务器以适当的方式将所有请求传递给slim应用程序，请阅读slim文档中的Web服务器部分。

手动实现方法

为了创建基于此框架的REST API，您需要在项目中创建以下类似的结构

├── composer.json
├── config
│   └── application.json
├── include
│   └── DummyApi
│       └── Endpoint
│           └── V1
│               ├── EndpointA.php
│               └── EndpointB.php
└── www
    └── index.php

config/application.json

此文件包含框架实现的JSON格式的配置。此文件不必位于此位置，只是默认位置。如果您更改它，您必须调整稍后显示的 www/index.php 示例。

以下键是可能的，但都是可选的（以下显示默认值）

{
  "displayErrorDetails": false,
  "cacheDuration": 900
}

cacheDuration 定义了用于响应缓存过期头的间隔（秒）（默认：900）。

如果将 displayErrorDetails 标志设置为 true，则在发生错误时，slim 框架将打印堆栈跟踪。否则，它将只显示“500内部服务器错误”（默认：false）。

include/ 文件夹

此文件夹应包含您的端点实现。下面将介绍如何定义端点。

www/index.php

此文件是应用程序的主要入口点。以下是此文件应具有的最小示例

<?php
require(__DIR__ . '/../vendor/autoload.php');

$endpoints = [
    [
        'type'           => SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
        'route'          => '/dummy/test/{id:[0-9]+}',
        'name'           => 'dummy',
        'instance'       => new DummyApi\Endpoint\V1\Dummy(),
        'authentication' => false,
    ],
];

$slimBootstrap = new \SlimBootstrap\Bootstrap();
$slimBootstrap->run($endpoints);

日志记录

如果您想为API启用日志记录，可以通过在 \SlimBootstrap\Bootstrap 对象上调用 setLogger() 将 \Monolog\Logger 实例注入到框架中（此方法可链式调用）

-$slimBootstrap->run($endpoints);
+$slimBootstrap->setLogger(new \Monolog\Logger('dummyApi'))->run($endpoints);

创建端点

端点是一个PHP类，它必须实现至少一个 \SlimBootstrap\Endpoint\* 接口，具体取决于它应该支持哪些HTTP方法（下面有更多详细信息）。所有端点都必须返回一个PHP数组，该数组包含它们最终想要输出的数据。然后框架将负责将其渲染为正确的输出格式。

支持的HTTP方法

目前，框架支持以下HTTP方法

• DELETE
• GET
• POST
• PUT

对于这些方法中的每一个，框架都为端点提供了在 \SlimBootstrap\Endpoint\ 下的接口。

将端点注册到框架中

必须将编写的端点注册到框架和底层Slim实例，以便访问。这是通过将数组传递到\SlimBootstrap\Bootstrap实例的run()方法来完成的。框架使用Slim的基本形式来注册路由并将端点绑定到路由。然而，目前slim-bootstrap3不允许端点分组。数组必须具有以下结构

$endpoints = [
    [
        'type'     => SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
        'route'    => '/dummy/test/{id:[0-9]+}',
        'name'     => 'dummy',
        'instance' => new DummyApi\Endpoint\Dummy(),
    ],
    [
        'type'           => SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
        'route'          => '/dummy/test/{id:[0-9]+}',
        'name'           => 'dummy-other',
        'instance'       => new DummyApi\Endpoint\DummyOther(),
        'authentication' => false
    ],
];

响应输出

Slim-bootstrap3支持多种输出格式，可以通过“Accept”头属性请求。这些是目前支持的格式

• application/json (默认)

身份验证

当启用身份验证时，您需要根据所使用的身份验证方法，向配置文件中添加一些额外的条目。

身份验证更改

config/application.json的更改

您必须在application.json配置中添加一个“acl”键，它定义了client_id可以访问的端点。

{
    ...
    "acl": {
        "roles": {
            "role_dummy": {
                "dummy": true
            }
        },
        "access": {
            "myDummyClientId": "role_dummy"
        }
    }
    ...
}

这是将client_id "myDummyClientId"映射到具有对"dummy"端点访问权限的"role_dummy"角色。

OAuth

您必须将来自您的oauth服务器的访问令牌的url参数access_token添加到api调用中。身份验证逻辑将此访问令牌与配置的oauth服务器的/me端点进行验证。接下来，从/me端点收集的client_id将根据请求的端点和配置的ACL进行验证。如果一切正常，则向请求者授予访问权限。否则，请求将使用401或403 HTTP状态码终止。

config/application.json的附加值

 {
  ...
  "oauth": {
    "authenticationUrl": "https://myserver.com/me?access_token=",
    "clientIdField": "entity_id"
  },
  ...
}

clientIdField值是可选的，用于定义在OAuth响应结果的哪个字段中可以找到client_id。默认是"entity_id"。

www/index.php的更改

-    $slimBootstrap->run($endpoints);
+    $slimBootstrap->setAuthentication('oauth')->run($endpoints);

JWT

您必须将JWT作为授权承载头添加到API请求中。框架将使用从jwt.publicKey提供的JWT提供者的公钥验证和验证JWT。验证时，必须将配置的jwt.claims块的所有字段与JWT匹配。默认情况下，验证iat（颁发时间）、nbf（无效之前）和exp（过期时间）字段。

之后，框架将提取声明中的"名称"字段的client_id和"角色"字段的角色。然后，收集到的client_id和角色将根据请求的端点和配置的ACL进行验证。如果一切正常，则向请求者授予访问权限。否则，请求将使用401或403 HTTP状态码终止。

config/application.json的附加值

{
  ...
  "jwt": {
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAElAfxdt6MZxXc4TsZROhm8QPnoDm5\nILVK9el6kU9xd+3Pnb3yOBsLTnuX9/x2c8HIQIoxEs8IlreBQndy3CvRJQ==\n-----END PUBLIC KEY-----\n",
    "encryption": "ES256",
    "clientDataClaims": {
      "clientId": "name",
      "role": "role"
    },
    "claims": {
      "issuer": "sombra_development"
    }
  },
  ...
}

jwt.encryption选项键是可选的，并定义了用于签名令牌的加密类型。如果此键不存在，则使用后备"ES256"。此库支持所有lcobucci/jwt版本3.*支持的算法。

jwt.clientDataClaims选项键是可选的，并定义了在哪些声明中可以找到用户的client_id和角色。如果没有指定此键，字段为"名称"（用于client_id）和"角色"（用于角色）。

jwt.claims设置用于验证令牌的内容。支持以下来自lcobucci/jwt的约束值

• audience - Lcobucci\JWT\Validation\Constraint\PermittedFor
• issuer - Lcobucci\JWT\Validation\Constraint\IssuedBy

www/index.php的更改

-    $slimBootstrap->run($endpoints);
+    $slimBootstrap->setAuthentication('jwt')->run($endpoints);

Sombra

这是一个专门编写来与Sombra实例一起工作的JWT提供程序。它与常规JWT提供程序执行相同的操作，但它从提供的jwt.sombraUrl主机读取公钥。

自定义身份验证

如果您愿意，您可以定义自己的认证类，例如从数据库中读取。如果您想这样做，您必须实现认证接口。这个实现可以作为调用\SlimBootstrap\Bootstrap对象的setAuthentication方法的参数，而不是字符串。

许可协议 & 作者

• 作者：Peter Ahrens (pahrens@bigpoint.net), Andreas Schleifer (aschleifer@bigpoint.net), Hendrik Meyer (hmeyer@bigpoint.net)

Copyright:: 2016 Bigpoint GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.