README

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

该框架基于 Slim 3 和 Pimple 构建。

Charcoal App 是一系列 模块、路由（模板、动作和脚本）、处理器和服务的集合，通过配置、服务容器和服务提供者相互关联。

该框架具有以下特性（内部和外部）

• PSR-3 日志记录器
• PSR-6 缓存系统^†
• PSR-7 内核（Web、API、CLI）
• PSR-11 容器
• 翻译层^†
• 文件系统层
• 数据库层
• 视图层^†

† 由外部 Charcoal 组件提供

目录

• 安装
  • 从样板开始
  • 依赖项
  • 推荐模块
• 组件
  • 配置
  • 应用程序
  • 路由和 RequestController
    • 动作请求控制器
    • 脚本请求控制器
    • 模板请求控制器
    • 路由 API
    • 可路由对象
  • 中间件
  • Charcoal 二进制
  • PHPUnits 测试
• 服务提供者
• 使用方法
• 开发
  • 开发依赖
  • 持续集成
  • 编码风格
  • 作者

安装

安装 charcoal-app 的首选（且唯一支持的）方法是使用 composer

★ composer require locomotivemtl/charcoal-app

从样板开始

此模块旨在作为 Web 应用程序（如网站）的基础。

对于完整、可立即使用的项目，请从官方样板开始。

★ composer create-project locomotivemtl/charcoal-project-boilerplate

依赖项

要求

• PHP 5.6+: 推荐使用 PHP 7。
• locomotivemtl/charcoal-cache: 用于 PSR-6 兼容缓存系统的服务提供者，使用 Stash。
• locomotivemtl/charcoal-config: 用于配置应用程序和设计控制器的数据对象。
• locomotivemtl/charcoal-factory: 用于创建提供者、处理器和控制器的工厂接口。
• locomotivemtl/charcoal-translator: 用于国际化应用程序的工具的服务提供者，使用 Symfony Translation。
• locomotivemtl/charcoal-view: 用于视图渲染和模板引擎适配器的服务提供者，适配 Mustache 和 Twig。
• league/climate: 用于设计应用程序控制台命令的命令行抽象。
• league/flysystem：用于处理本地和远程存储空间的文件系统抽象。
• monolog/monolog：符合PSR-3规范的日志记录客户端，用于记录应用请求、错误和信息。
• pimple/pimple：符合PSR-11规范的服务容器和提供者库。
• slim/slim：符合PSR-7规范的HTTP客户端和路由器。

PSR

• PSR-3：日志库的通用接口。由Monolog实现。
• PSR-6：缓存库的通用接口。由Stash实现。
• PSR-7：HTTP消息的通用接口。由Slim实现。
• PSR-11：依赖容器的通用接口。由Pimple实现。

👉 在项目中使用 charcoal-app 时，开发依赖是可选的，它们在README文件的“开发”部分中描述。

阅读 composer.json 文件以获取更多依赖详情。

推荐模块

除了上述依赖项之外，这里还有推荐添加到项目中的模块列表。

• locomotivemtl/charcoal-email：用于邮件管理的服务提供者，使用 PHPMailer（模板、队列、发送、跟踪）。
• locomotivemtl/charcoal-cms：内容管理（页面、新闻、事件）的预设计模型和基本实用工具。
• locomotivemtl/charcoal-admin：Charcoal应用的行政界面（添加/编辑/删除对象、文件管理器）。

使用 charcoal-project-boilerplate 确保完整的Charcoal应用设置确实是推荐的做法。

安装

★ composer create-project locomotivemtl/charcoal-project-boilerplate

组件

Charcoal App 的主要组件包括

• 配置
• 应用程序
• 模块
• 路由和请求控制器
  • 动作
  • 脚本
  • 模板
  • 路由 API
• 可路由对象
• Charcoal 二进制
• PHPUnit 测试

了解更多关于 组件 的信息。

服务提供者

依赖和扩展由依赖容器处理，使用 Pimple，可以通过 服务提供者（Pimple\ServiceProviderInterface）定义。

包含的服务提供者

Charcoal App 默认附带了一些服务提供者。所有这些都在 Charcoal\App\ServiceProvider 命名空间中。

• AppServiceProvider
• DatabaseServiceProvider
• FilesystemServiceProvider
• LoggerServiceProvider

外部服务提供者

Charcoal App 需要从独立组件中获取一些服务提供者。以下使用它们自己的命名空间，并且通过 AppServiceProvider 自动注入

• CacheServiceProvider
• TranslatorServiceProvider
• ViewServiceProvider

了解更多关于 服务提供者 的信息。

使用方法

典型的前端控制器 (www/index.php)

use \Charcoal\App\App;
use \Charcoal\App\AppConfig;
use \Charcoal\App\AppContainer;

include '../vendor/autoload.php';

$config = new AppConfig();
$config->addFile(__DIR__.'/../config/config.php');
$config->set('ROOT', dirname(__DIR__) . '/');

// Create container and configure it (with charcoal-config)
$container = new AppContainer([
    'settings' => [
        'displayErrorDetails' => true
    ],
    'config' => $config
]);

// Charcoal / Slim is the main app
$app = App::instance($container);
$app->run();

有关使用 charcoal-app 的完整项目示例，请参阅 charcoal-project-boilerplate。

开发

安装开发环境

$ composer install

运行脚本（phplint、phpcs 和 phpunit）

$ composer test

API 文档

• 自动生成的 phpDocumentor API 文档可在以下地址访问：
  https://locomotivemtl.github.io/charcoal-app/docs/master/
• 自动生成的 apigen API 文档可在以下地址访问：
  https://codedoc.pub/locomotivemtl/charcoal-app/master/

开发依赖

• php-coveralls/php-coveralls
• phpunit/phpunit
• squizlabs/php_codesniffer

编码风格

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

• PSR-1
• PSR-2
• PSR-4，因此自动加载由 Composer 提供。
• phpDocumentor 注释。
• 有关编码标准的 phpcs.xml.dist 和 .editorconfig。

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

致谢

• Mathieu Ducharme
• Chauncey McAskill
• Benjamin Roch
• Locomotive

许可

Charcoal 在 MIT 许可下发布。有关详细信息，请参阅 LICENSE。