README

此框架已被弃用，推荐使用https://github.com/Bigpoint/slim-bootstrap3/.

这些类提供了一种简单的方式来通过身份验证启动Slim应用程序。

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

安装

composer require bigpoint/slim-bootstrap

Web服务器配置

为了配置您的Web服务器以适当传递所有请求到Slim应用程序，请阅读Slim文档中的路由URL重写部分。

设置骨架API

为您的新的API创建一个文件夹，并在其中运行以下命令。

在以下单行中将<YOUR_NAMESPACE>设置为API命名空间（驼峰式命名）并执行此行。它将加载框架并创建骨架结构

NAMESPACE="<YOUR_NAMESPACE>" && composer init -n && composer require "bigpoint/slim-bootstrap:*" && ./vendor/bin/slim-bootstrap-generator "${NAMESPACE}" && composer dumpautoload

手动实现

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

├── composer.json
├── config
│   └── application.json
├── include
│   └── ###Namespace###
│       └── Endpoint
│           └── V1
│               ├── Collection
│               │   └── EndpointA.php
│               └── Resource
│                   └── EndpointA.php
└── www
    └── index.php

config/application.json

此文件包含实现和框架的主要配置。有关配置中的“monolog”块的文档，请参阅MonologCreator。

以下结构必须存在

    {
        "shortName": "###NAMESPACE_LOWER###",
        "cacheDuration": 900,
        "debug": false,
        "csv": {
            "delimiter": ",",
            "enclosure": "\"",
            "linebreak": "\r\n",
            "encloseAll": false,
            "null": "NULL"
        },
        "monolog": {
            "handler": {
                "udp": {
                    "host": "127.0.0.1",
                    "port": 6666,
                    "formatter": "logstash"
                }
            },
            "formatter": {
                "logstash": {
                    "type": "SlimBootstrap-###NAMESPACE_LOWER###"
                }
            },
            "logger": {
                "_default": {
                    "handler": ["udp"],
                    "level": "DEBUG"
                },
                "slim": {
                    "handler": ["udp"],
                    "level": "DEBUG"
                }
            }
        }
    }

shortName用于在欢迎端点中使用hal+json作为输出格式时，将端点名称作为前缀。

cacheDuration定义了响应缓存过期头的间隔（以秒为单位）。

如果将debug标志设置为true，则Slim框架在发生错误时将打印堆栈跟踪。否则，它将只显示500内部服务器错误。

include/文件夹

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

www/index.php

此文件是应用程序的主要入口点。以下是此文件应如何看起来的一个示例

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

$applicationConfig = json_decode(
    file_get_contents(__DIR__ . '/../config/application.json'),
    true
);

// create logger
$loggerFactory        = new \MonologCreator\Factory($applicationConfig['monolog']);
$authenticationLogger = $loggerFactory->createLogger('authentication');
$phpLogger            = $loggerFactory->createLogger('php');

// register php error logger
\Monolog\ErrorHandler::register($phpLogger);

$bootstrap      = new \SlimBootstrap\Bootstrap(
    $applicationConfig
);
$bootstrap->init();
$bootstrap->addResourceEndpoint(
    \SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
    '/dummy/:name',
    'dummy',
    array(
        'name' => '\w+',
    ),
    new \DummyApi\Endpoint\Resource\Dummy()
);
$bootstrap->addCollectionEndpoint(
    \SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
    '/dummy',
    'dummy',
    new \DummyApi\Endpoint\Collection\Dummy()
);
$bootstrap->run();

创建端点

集合端点

框架支持两种类型的端点。集合端点用于返回多个结果，资源端点用于返回/处理特殊结果。

集合端点

这些端点应实现位于 \SlimBootstrap\Endpoint 下的一个 CollectionEndpoint 接口。然后它将获得一个可以传递为GET参数的过滤器参数数组；如果不是GET端点，则是一个数据数组，该数据将作为请求的负载发送。端点应返回一个 \SlimBootstrap\DataObject 数组，每个 DataObject 包含一个结果。

资源端点

这些端点应实现位于 \SlimBootstrap\Endpoint 下的一个 ResourceEndpoint 接口。然后它将获取资源标识的URL参数数组；如果不是GET端点，则是一个数据数组，该数据将作为请求的负载发送。端点应返回一个 \SlimBootstrap\DataObject，并且如果端点遇到错误，它应抛出 \SlimBootstrap\Exception。当抛出异常时，可选的第三个参数定义了将以此异常记录的日志级别。默认为 "ERROR"。该异常的消息将作为结果打印出来，代码将用作HTTP状态码。

支持的HTTP方法

目前框架支持以下HTTP方法

DELETE
GET
POST
PUT

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

将端点注册到框架中

编写的端点必须注册到框架和底层的Slim实例，才能被访问。这可以通过在调用 init() 之后和调用 run() 之前，在 \SlimBootstrap\Bootstrap 实例的相应添加方法来实现。框架使用slim的基本形式来注册路由并将端点绑定到路由。为此，方法需要一些特定的参数，以下是对GET端点进行说明，但其他端点也非常相似。

addCollectionEndpoint

此方法需要一个端点应注册的HTTP协议。这应该是 \SlimBootstrap\Bootstrap::HTTP_METHOD_* 常量之一。作为第二个参数，它需要一个 route，这是可以调用的相对URL，例如 "/myendpoint"。作为第三个参数，它需要一个 name，该名称将用于标识路由，然后可以在ACL配置中用来配置对此路由/端点的访问。第四个参数是 \SlimBootstrap\Endpoint\Collection* 的一个实例。作为第六个参数，您可以可选地传递一个布尔值来定义是否为该端点启用或禁用身份验证。这会覆盖全局身份验证定义。

addResourceEndpoint

该方法需要HTTP协议，并且该端点应进行注册。这应该是在\SlimBootstrap\Bootstrap::HTTP_METHOD_*常量中的一个。作为第二个参数，它需要一个route，即可以调用的相对URL，例如"/myendpoint/:someId"。作为第三个参数，它需要一个name，该名称将用于识别路由，并且可以在ACL配置中用于配置对该路由/端点的访问。第四个参数是一个条件数组，可以定义传递的id（someId）的约束。这些约束是普通的PHP正则表达式。最后，第五个参数是\SlimBootstrap\Endpoint\Resource*的实例。作为第六个参数，您可以可选地传递一个布尔值，以定义是否为该端点启用或禁用身份验证。这将覆盖全局身份验证定义。

响应输出

Slim-Bootstrap支持多种响应输出类型，可以通过"Accept"头部属性请求。

application/hal+json (默认)
application/json
text/csv

可流式输出

为了处理大型响应输出，可以将响应体作为数据流发送。您必须将接口SlimBootstrap\Endpoint\Streamable添加到您的端点中，以启用此功能。接下来，您必须在注入的outputwriter中对每个数据条目/行调用方法writeToStream。输出编写器必须支持可流式输出。目前无法同时为同一端点同时使用普通和可流式输出编写器。

可流式输出类型

text/csv

示例

class SomeEndpoint implements SlimBootstrap\Endpoint\ResourceGet,
                              SlimBootstrap\Endpoint\Streamable
{
    public function setOutputWriter(
        SlimBootstrap\ResponseOutputWriterStreamable $outputWriter
    ) {
        $this->_outputWriter = $outputWriter;
    }

    ...

    public function get(array $parameters) {
        ...
        $dbResultStatement = $database->getDbResult(); //PDO Statement object

        // fetching single db rows here to save memory
        while (false !== ($entry = $dbResultStatement->fetch(
            \PDO::FETCH_ASSOC,
            \PDO::FETCH_ORI_NEXT
        ))) {
            $this->_outputWriter->writeToStream(
                $this->_createDataObject((int)$entry['id'], $entry)
            );
        }
        ...
    }
    ...
}

关于`text/csv`输出

CSV属性可以在application.json的'csv'部分中进行配置。如果不存在，则将使用以下默认值

配置值	默认值	描述
`delimiter`	`","`	字段分隔符
`enclosure`	`"\""`	字段封装
`linebreak`	`"\r\n"`	换行符
`encloseAll`	`false`	封装每个字段（true）或仅在必要时（false）
`null`	`"NULL"`	用此字符串替换数据集中的null值。

注意：CSV输出只能显示一层数据层次。具有另一层的字段将被忽略。此外，数据将不会被规范化，因此所有字段必须在所有数据条目中保持一致。

身份验证

您可以通过对oauth服务器进行身份验证，以保护您的API并设置端点特定的权限。oauth服务器必须在其分配令牌的/me端点中提供clientId作为entity_id，以正确与slim-bootstraps身份验证一起工作。

工作原理

当启用身份验证时，您必须在包含从您的oauth服务器提供的访问令牌的api调用中添加url参数access_token。身份验证逻辑将通过其/me端点验证此访问令牌与配置的oauth服务器。接下来，从/me端点收集的clientId将被验证与请求的端点和配置的acl。如果一切正常，则允许请求者访问。否则，请求将被中止，返回401或403错误。

启用身份验证

如果您想对oauth /me端点进行身份验证，您必须在配置字段authenticationUrl中定义到/me端点的URL。在该值的末尾将拼接传递的访问令牌。

https://myserver.com/me?access_token=

此外，您还需要添加一个config/acl.json文件，该文件定义了clientId的可访问端点。

    {
        "roles": {
            "role_dummy": {
                "index": true,
                "dummy": true
            }
        },
        "access": {
            "myDummyClientId": "role_dummy",
        }
    }

最后，您需要在您的ww/index.php文件中添加以下代码部分。

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

$applicationConfig = json_decode(
    file_get_contents(__DIR__ . '/../config/application.json'),
    true
);
+$aclConfig         = json_decode(
+    file_get_contents(__DIR__ . '/../config/acl.json'),
+    true
+);

// create logger
$loggerFactory        = new \MonologCreator\Factory($applicationConfig['monolog']);
$authenticationLogger = $loggerFactory->createLogger('authentication');
$phpLogger            = $loggerFactory->createLogger('php');

// register php error logger
\Monolog\ErrorHandler::register($phpLogger);

+$authFactory    = new \SlimBootstrap\Authentication\Factory(
+    $applicationConfig,
+    $authenticationLogger
+);
+$authentication = $authFactory->createOauth();

$bootstrap      = new \SlimBootstrap\Bootstrap(
    $applicationConfig,
+    $authentication,
+    $aclConfig
);
$bootstrap->init();
$bootstrap->addResourceEndpoint(
    \SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
    '/dummy/:name',
    'dummy',
    array(
        'name' => '\w+',
    ),
    new \DummyApi\Endpoint\Resource\Dummy()
);
$bootstrap->addCollectionEndpoint(
    \SlimBootstrap\Bootstrap::HTTP_METHOD_GET,
    '/dummy',
    'dummy',
    new \DummyApi\Endpoint\Collection\Dummy()
);
$bootstrap->run();

这是将clientId "myDummyClientId"映射到具有访问"index"和"dummy"端点的"role_dummy"角色的角色。

自定义身份验证

如果您愿意，您可以定义自己的身份验证类，例如从数据库读取。如果您想这样做，您必须实现身份验证接口。

许可协议 & 作者

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

Copyright:: 2015 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.

bigpoint / slim-bootstrap

维护者

详细信息

README

安装

Web服务器配置

设置骨架API

手动实现

config/application.json

include/文件夹

www/index.php

创建端点

集合端点

支持的HTTP方法

将端点注册到框架中

响应输出

可流式输出

关于`text/csv`输出

身份验证

工作原理

启用身份验证

自定义身份验证

许可协议 & 作者

bigpoint / slim-bootstrap

维护者

详细信息

README

安装

Web服务器配置

设置骨架API

手动实现

config/application.json

include/文件夹

www/index.php

创建端点

集合端点

支持的HTTP方法

将端点注册到框架中

响应输出

可流式输出

关于text/csv输出

身份验证

工作原理

启用身份验证

自定义身份验证

许可协议 & 作者

关于`text/csv`输出