README

⚠️ 此骨架是为 locomotivemtl/charcoal-* 构建的，已被 charcoal/boilerplate 弃用。

本项目目标是提供一个使用 Charcoal 框架的完整工作的“模板”（空项目骨架）。

它还可以选择性地设置 Locomotive 模板用于前端。

预期范围

尽管这个模板已经完全可用，但它仍然不完整。它还没有展示所有 Charcoal 功能，因此需要大量手动调整选项。

以下是本项目预期完成的简要“使命声明”

一个完全自动化的设置过程。
- （可选）为前端安装 locomotive-boilerplate。
完全工作的翻译（l10n）与 charcoal-translator。
- 默认数据也提供英文和法文。
- ...以及西班牙语等等...
一个带有 charcoal-admin 的工作“后端”。
- 用户自动设置。
- 带有默认配置，可以管理 CMS 对象（部分、新闻、事件、博客、位置等）
- 权限系统工作并启用。
- 通知系统工作并启用。
- 修订系统工作并启用。
- 媒体库工作并启用。
- 内置的帮助（文档）系统工作并启用。
内置了一些默认的、常见的模板（mustache）。
- 主页，带有一些选项和小工具（如轮播图）。
- 新闻列表/新闻详情，支持附件。
- 日历（事件列表），带有 AJAX 选项/事件详情，支持附件。
- 博客/文章详情，支持附件和启用评论、AJAX 动作的选项。
- 联系，带有保存到数据库并基于类别选项发送确认电子邮件的表单，支持 AJAX 动作。
- 地图，按类别显示位置。
在每个页面上以及每个对象上都完全工作着 100% 的元数据。
- 使用对象的元数据信息，这些信息都可以在 charcoal-admin 中编辑。
提供一组优化的 SEO 功能。
搜索已启用
- 返回所有类型 CMS 对象（部分、新闻、事件、博客、位置等）的结果
- 使用的关键字，所有这些都可以在 charcoal-admin 中编辑。
- 也在附件中搜索。
- 自动完成已启用并工作。
100% 通过 PHPUnit 测试。

如何安装

要使用此模板开始 Charcoal 项目，请

1. 安装模板

木炭使用Composer的create-project命令来安装样板代码

★ composer create-project --prefer-dist locomotivemtl/charcoal-project-boilerplate acme

将"acme"替换为您新项目期望的目录名。

关于文档根目录

👉 项目不应直接在可访问的Web目录中克隆。Web服务器应配置为直接提供www/文件夹（或通过符号链接）。其他文件夹（vendor/、src/、templates/、metadata/、config/等）因此不应通过Web服务器（保持在文档根目录外）访问。

2. 测试您的安装

可以使用PHP内置服务器快速启动一个服务器

★ cd www
★ php -S localhost:8080

将您的浏览器指向http://localhost:8080/，您应该会看到样板代码的默认主页。

稍后在本README中将解释如何更改默认页面和添加路由/模板。

提示：推荐的方式是从管理员界面，通过添加页面（部分）。

3. 设置数据库存储

下一步需要自定义配置文件。建议使用config/config.local.json，并确保它未提交到源代码管理。

★ cp config/config.sample.json config/config.local.json

然后使用以下信息编辑config/config.local.json文件。

如果您的项目不需要任何数据库存储，请使用SQLite等内存数据库，并将以下内容添加到config/config.local.json文件中

{
    "databases": {
        "default": {
            "type": "sqlite",
            "database": ":memory:"
        }
    },
    "default_database": "default"
}

如果您的项目使用MySQL，请创建一个空数据库，并确保有一个SQL用户具有此数据库的适当权限。然后，将以下内容添加到config/config.local.json文件中

{
    "databases": {
        "default": {
            "type": "mysql",
            "hostname": "127.0.0.1",
            "database": "foobar",
            "username": "foo_bar",
            "password": "F00$BâR123"
        }
    },
    "default_database": "default"
}

4. 设置项目名称

默认情况下，项目名称为"Acme"，在App命名空间下，并由Composer使用PSR-4自动加载标准自动加载。

样板代码中有多处出现"Acme"。

config/admin.json：请参阅admin.title。
config/config.json：请参阅project_name和cache.prefix。

您还应该更改Composer包的信息

composer.json：请参阅name。

5. 设置charcoal-admin

提供了一个快速脚本来自动安装charcoal-admin

★ sh ./build/scripts/install-charcoal-admin.sh

将您的浏览器指向http://localhost:8080/admin，您应该会看到Charcoal的管理员登录屏幕。

下一步是自定义后端，需要配置主菜单以及各种管理员选项。请参阅config/admin.json文件以获取详细信息。

请参阅charcoal-admin的帮助文档以获取更多信息。

6. （可选）安装`locomotive-boilerplate`）

提供了一个快速脚本来自动安装来自其GitHub仓库的locomotive前端。

★ sh ./build/scripts/install-locomotive-boilerplate.sh

有关locomotive-boilerplate前端模块的更多信息：请访问https://github.com/locomotivemtl/locomotive-boilerplate

依赖项和需求

PHP 7.4+
- ext-json
- ext-pdo
- ext-spl
- ext-mbstring

外部库

Charcoal的大部分功能都是建立在经过验证的开源技术之上

Composer（部署和自动加载）
Slim（PSR-7应用程序框架）
FastRoute（路由器）
Pimple（DI容器，来自symfony）
Mustache（模板引擎）
- 可选支持来自symfony的Twig
PDO / MySQL（数据库存储）
Stash（PSR-6缓存）
CLImate（终端工具，来自php league）
Flysystem（文件系统抽象，来自php league）
Symfony Translation（本地化工具）
Laminas ACL（权限管理）
PHPmailer（邮件传输）
Monolog（PSR-3 日志记录器）
PHPUnit（单元测试）
APIGen（API 文档）
PHP Code Sniffer（编码规范）
jQuery（JavaScript 框架）
Bootstrap（CSS 框架）
TinyMCE（HTML 编辑器）
elFinder（文件管理器）
Github（源代码控制）
Travis（持续集成）

Charcoal 模块

charcoal-admin
- 后端或控制面板。
charcoal-app
- 基于 Slim 的应用程序组件。
charcoal-attachment
- 内容对象的其他附件。
charcoal-cms
- CMS 对象（章节、新闻、事件等）
charcoal-config
- 基本配置系统。
charcoal-core
- 核心对象，模型，源。
charcoal-email
- 基于 phpmailer 的电子邮件实用工具。
charcoal-factory
- 动态对象创建。
charcoal-image
- 图像处理和效果。
charcoal-object
- 对象定义（内容和 UserData；基于模型），行为和工具。
charcoal-property
- 元数据的属性。
charcoal-translator
- 基于 Symfony 的翻译实用工具。
charcoal-ui
- UI 对象（表单、菜单、仪表盘、布局等）
charcoal-user
- 用户定义、身份验证和授权（基于 Laminas ACL）。
charcoal-validator
- 数据验证。
charcoal-view
- 视图渲染器。（mustache，twig 等）

状态矩阵

这个模板内部有什么？

就像所有 Charcoal 项目/模块一样，主要组件包括

自动加载器
- 由 Composer 提供。
配置
- 在 config/ 目录中以 JSON 或 PHP 文件的形式。
- 使用 locomotivemtl/charcoal-config
前端控制器
- 详细信息请参阅 www/.htaccess 和 www/index.php。
- 路由分发器
  - 请参阅 config/routes.json 了解路由配置。
脚本控制器（Charoal 二进制文件）
- 作为 charcoal-app 的一部分安装，作为 vendor/bin/charcoal。
- 许多有用的脚本随 charcoal-admin 模块提供。
PHP 脚本
- PSR-1、PSR-2 和 PSR-4 兼容的脚本位于 src/
- 通常有三种类型的控制器
  - 模板
  - 操作
  - 脚本
- ... 两种类型的对象
  - 基于 Content 的对象
  - 基于 UserData 的对象
- ... 以及所有其他类型的脚本（服务、助手、配置、工厂等）
资源
- 资源是需要放在 Web 服务器根目录的文件
- 脚本，在 src/scripts/ 中，并在 www/assets/scripts/ 中编译
- 样式，使用 Sass 在 src/styles/ 中，并在 www/assets/styles/ 中编译 CSS
- 图像，在 www/assets/images/ 中

开发

要安装开发环境

★ composer install --prefer-source

要运行脚本（phplint、phpcs 和 phpunit）

★ composer test

开发依赖

phpunit/phpunit
squizlabs/php_codesniffer
satooshi/php-coveralls

持续集成

编码风格

charcoal-project-boilerplate 模块遵循 Charcoal 编码风格

PSR-1
PSR-2
PSR-4，因此自动加载由 Composer 提供。
phpDocumentor 注释。
阅读 phpcs.xml 文件以获取所有代码风格的详细信息。

可以使用 composer phpcs 执行编码风格验证/强制执行。同时，也提供了一个自动修复工具，使用 composer phpcbf。

作者

洛科莫蒂夫，蒙特利尔网络代理商

locomotivemtl / charcoal-project-boilerplate

维护者

详细信息

README

目录

预期范围

如何安装

1. 安装模板

2. 测试您的安装

3. 设置数据库存储

4. 设置项目名称

5. 设置charcoal-admin

6. （可选）安装`locomotive-boilerplate`）

依赖项和需求

外部库

Charcoal 模块

状态矩阵

这个模板内部有什么？

开发

开发依赖

持续集成

编码风格

作者

locomotivemtl / charcoal-project-boilerplate

维护者

详细信息

README

目录

预期范围

如何安装

1. 安装模板

2. 测试您的安装

3. 设置数据库存储

4. 设置项目名称

5. 设置charcoal-admin

6. （可选）安装locomotive-boilerplate）

依赖项和需求

外部库

Charcoal 模块

状态矩阵

这个模板内部有什么？

开发

开发依赖

持续集成

编码风格

作者

6. （可选）安装`locomotive-boilerplate`）