README

Charcoal Slim 是一个 PHP 框架，用于使用 Charcoal 组件创建 Web 应用程序和 API。

依赖项

PHP 7.4+
slim/slim 和 slim/psr7 用于主要的 PSR-7 应用。
pimple/pimple 用于从服务提供者生成（PSR-11）依赖注入容器。
charcoal/config 用于配置格式。
charcoal/view 用于模板（mustache、twig）支持。
guzzlehttp/guzzle 用于 HTTP 客户端（用于代理请求）。

它是如何工作的？

查看 mducharme/slim4-boilerplate 了解示例实现。

Bootstrap 类

Bootstrap 类可以用来设置 Charcoal 配置对象和 Pimple 容器，用于设置 slim 应用程序。Charcoal 配置对象可以用 PHP 和 JSON 设置。Pimple 容器通常用作依赖注入容器，并通过服务提供者设置。

通常，Bootstrap 将传递一些回调函数，当启动应用程序时将执行这些回调函数。

可以添加 4 种类型的回调方法，具体取决于需要修改的对象。

配置回调可以添加为 $bootstrap->addConfig(function (\Charcoal\Config\ConfigInterface $config) : \Charcoal\Config\ConfigInterface { /* */ });
- 这是向应用程序添加自定义配置的方式，通常在每个项目中使用，通常用于加载 JSON（和 PHP）配置文件。
容器回调可以添加为 $bootstrap->addContainer(function (\Pimple\Container $container) : \Pimple\Container { /* */ });
- 这是在 Pimple DI 容器上注册自定义服务提供者的方式。
Bootstrap 回调可以添加为 $bootstrap->addBootstrap(function (\Charcoal\Slim\Bootstrap $bootstrap) : \Charcoal\Slim\Bootstrap { /* */ });
- 这是添加 Charcoal 模块或任何需要添加更多配置、容器或应用程序回调的系统的方法。
应用程序 回调可以添加为 $bootstrap->addApp(function \Slim\App $app): \Slim\App { /* */ });
- 这是向 Slim 应用程序添加任何（PSR-15）中间件或路由/路由处理程序的方式。

以下是典型的 Charcoal 项目的入口控制器（index.php）可能的样子

$bootstrap = new \Charcoal\Slim\Bootstrap();
$bootstrap->addConfig((require __DIR__ . '/../app/config.php'));
$bootstrap->addContainer((require __DIR__ . '/../app/services.php'));
$bootstrap->addBootstrap((require __DIR__ . '/../app/modules.php'));
$bootstrap->addApp((require __DIR__ . '/../app/middlewares.php'));
$bootstrap->addApp((require __DIR__ . '/../app/routes.php'));
$app = $bootstrap();
$app->run();

（所有 app/*.php 文件都应该返回一个匹配适当签名的回调函数。）

路由映射器

路由映射器是该库提供的一个基本服务。它将“路由定义”数组转换为应用程序的实际 Slim 路由。

以下是不同路由定义的 JSON 示例。

{
    "routes": {
        "home": {
            "type": "view",
            "view": "contexts/views/home",
            "template": "view/home"
        },
        "redirect-example": {
            "type": "redirect",
            "target" "https://foo.com/"
        },
        "json-api-example": {
            "type": "json",
            "context": "contexts/foobar"
        }
    }
    
}

type 是必需的。它必须匹配定义的路由处理器。下面是默认提供的 5 个处理器。

要在应用程序上设置这些路由

$routeMapper = new RouteMapper();
$routeMapper($app, $config['routes']);

手动添加路由

5 种核心（默认）类型的处理器

控制器 (\Charcoal\Slim\Handlers\Controller)
- 配置
  - controller
JSON (\Charcoal\Slim\Handlers\Controller)
- 配置
  - context
代理 (\Charcoal\Slim\Handlers\Controller)
- 配置
  - url
  - requestOptions
  - proxyMethod（可选，如果未指定，则使用当前请求方法）
重定向 (\Charcoal\Slim\Handlers\Redirection)
- 配置
  - target
  - code（默认 = 301）
视图 (\Charcoal\Slim\Handlers\View)
- 配置
  - 引擎（可选，如未指定，则使用应用程序默认设置）
  - 模板
  - 视图（可选视图控制器）

默认服务提供者

有2个可用的服务提供者

\Charcoal\Slim\Services\ControllersProvider
- 提供（空的）app/controllers和app/contexts。
\Charcoal\Slim\Services\HandlersProvider
- 提供（空的）app/handlers。

重要提示：请注意，这些提供者必须手动注册到应用程序容器中，使用

$bootstrap->addToContainer(function callback(Container $container) {
   $container->register(new \Charcoal\Slim\Services\HandlersProvider());
   $container->extends(
       'app/handlers', 
       function(array $handlers, Container $container) : array {
          // Add custom route handlers here
          $handlers['custom'] = \App\Handlers\CustomHandler::class;
          return $handlers;
       }
   );
    
   $container->register(new ControllersProvider());
   $container->extend(
       'app/controllers',
       function (array $controllers, Container $container): array {
           // Add custom route controllers here
           $controllers['custom'] = \App\Controllers\Custom::class;
           return $controllers;
       }
   );
   $container->extend(
       'app/contexts',
       function (array $contexts, Container $container): array {
           // Add custom json or view contexts here
           $contexts['custom'] = \App\Contexts\Custom::class;
           $contexts['views/custom'] = \App\Contexts\Views\Custom::class;
           return $contexts;
       }
   );
});

开发

安装开发环境

$ composer install

运行脚本（phplint、phpcs、phpunit、phpstan和psalm）

$ composer test

开发依赖

编码风格

charcoal-slim模块遵循Charcoal编码风格

[PSR-4][psr-4]，因此自动加载由Composer提供。
[PSR-12][psr-12]
phpDocumentor注释。
phpcs.xml.dist和.editorconfig用于编码标准。

编码风格验证/执行可以使用composer phpcs进行。还有一个自动修复器，可以通过composer phpcbf使用。

鸣谢

Locomotive

许可证

Charcoal遵循MIT许可证。有关详细信息，请参阅LICENSE。

locomotivemtl / charcoal-slim

维护者

详细信息