此软件包已被弃用且不再维护。作者建议使用charcoal/charcoal软件包。

Charcoal 框架单体仓库

v5.0.0 2024-03-13 15:04 UTC

README


Charcoal
Locomotive 🚂

License Latest Stable Version Uses Semantic Release with Conventional Commits Commitizen-friendly Supported PHP Version

Charcoal 是一个适应所有项目需求的 Web 框架和内容管理系统。

此仓库是一个单体仓库,包含整个 Web 框架。Charcoal 可以作为一个完整的栈框架使用,也可以作为独立的软件包使用。

Charcoal 软件包

核心软件包位于packages目录。

目录 分发 描述
admin charcoal/admin Charcoal 的管理仪表板。
app charcoal/app 基于Slim的 Web 应用层(容器、路由、控制器等)。
attachment charcoal/attachment 提供处理模型之间关系的支持。
cache charcoal/cache 基于Stash的缓存层。
cms charcoal/cms 提供内容管理系统(CMS)工具和扩展。
config charcoal/config 大多数软件包构建在基础配置和实体层。
core charcoal/core 模型、存储库和数据库层。
email charcoal/email 提供基于PHPMailer的发送邮件支持。
factory charcoal/factory 提供对象创建(工厂、构建器、类解析等)支持。
image charcoal/image 提供图像处理和操作支持。
object charcoal/object 提供高级建模支持(可路由、可修订、作者身份等)。
property charcoal/property 模型元数据层。
queue charcoal/queue 提供构建队列支持。
translator charcoal/translator 提供国际化支持,基于Symfony
ui charcoal/ui 提供布局工具(仪表板、布局、表单、菜单等)。
user charcoal/user 用户建模、身份验证和授权层。
view charcoal/view 支持MustacheTwig等的视图层。

安装

首选(也是唯一支持)方法是使用 Composer

composer require charcoal/charcoal

从工作骨架开始

composer create-project charcoal/boilerplate

独立软件包

Charcoal 框架被分割成可以独立使用的独立软件包。例如,一个项目可能不需要管理面板、队列系统或发送电子邮件。

composer require charcoal/app charcoal/api custom/admin 

将项目迁移到 charcoal/charcoal

以下将帮助将项目从 locomotivemtl/charcoal-* 转换为 charcoal/*

ℹ️ 之前所有核心软件包都独立维护自己的版本号。

单体仓库框架使用共享版本号对所有核心软件包,以实现一致和预期的互操作性。

ℹ️ contrib 软件包继续维护其现有的独立版本号。

选项A — 如果您想用全栈框架包替换所有包
  1. 在您的 composer.json 文件中删除核心包(locomotivemtl/charcoal-*)的要求。

  2. 在您的 composer.json 文件中,将贡献包(locomotivemtl/charcoal-contrib-*)的要求替换为来自 charcoal/contrib-* 的等效包。

  3. 运行 composer require charcoal/charcoal 来安装框架。

  4. 运行 composer update 以确保所有要求都是最新的。

  5. 运行以下迁移脚本

    ./vendor/charcoal/charcoal/build/script/migrate-project

    migrate-project 脚本将更新您项目配置文件中的所有元数据路径。之后,它将编辑或创建一个 .env 环境变量文件,其中 PACKAGES_PATH 键设置为:vendor/charcoal/charcoal/packages

    这允许 %packages.path% 字符串模板扩展到 charcoal/charcoal 中的包位置,否则它将导致在 vendor 目录中。

选项B — 如果您想用新的独立包替换所有包
  1. 在您的 composer.json 文件中替换核心包(locomotivemtl/charcoal-*)的要求。
  2. 在您的 composer.json 文件中,将贡献包(locomotivemtl/charcoal-contrib-*)的要求替换为来自 charcoal/contrib-* 的等效包。
  3. 运行 composer require charcoal/config charcoal/core… 来安装包。
  4. 运行 composer update 以确保所有要求都是最新的。
  5. 将配置文件中的 vendor/locomotivemtl/charcoal-* 替换为 vendor/charcoal/*

依赖项

⚠️ 必需

  • PHP 7.4 或 8.0

⚙️ 配置

[待办]

用法

[待办]

开发

开发在从 main 分支分离的分支中进行。

⚠️ main 分支受保护,不允许直接推送更改。

要安装开发环境

composer install

要运行脚本(phplint、phpcs 和 phpunit)

composer test

提交信息格式

Charcoal 使用 semantic-release 来处理发布过程。

它使用提交信息来确定代码库中更改的消费者影响。遵循提交信息的正式化约定,semantic-release 自动确定下一个 Semantic Version 号码,生成变更日志并发布发行版。

当前设置使用提交信息的 Conventional Commits。您可以查阅它以获取更多信息。

此存储库对 Commitizen 友好,并配置为使用 Conventional Commits 标准,因此您可以全局安装它以简化编写提交的过程。

或者,有一些代码编辑器插件可以帮助创建常规提交

以下是基于一些提交信息的发布类型示例

  • 补丁(修复)发布

    fix(pencil): stop graphite breaking when too much pressure applied
  • 次要(功能)发布

    feat(pencil): add 'graphiteWidth' option
  • 主要(破坏性)发布

    perf(pencil): remove graphiteWidth option
    
    BREAKING CHANGE: The graphiteWidth option has been removed.
    The default graphite width of 10mm is always used for performance reasons.

    ✍🏻 注意,BREAKING CHANGE: 标记必须在提交的底部。

开发指南

开发应该是基于分支的,并且提交信息应遵循 Conventional Commits。

步骤 备注
1. 从 main 分支创建分支或检出 develop 确保 develop 分支与 main 保持最新。如果您需要的工作时间不短,您应该优先选择一个新的分支。在个人分支上,您应该优先使用 rebase 方法来与 main 分支保持同步
2. 做你的事情 编写一些代码
3. 使用 Conventional Commits 标准提交您的更改 您可以使用Commitizen或代码编辑器插件来帮助您完成这个过程。有关更多信息,请参阅提交信息格式部分。
4. 推送到远程分支并运行./create-pr脚本。 使用./create-pr脚本创建PR不是强制性的。您始终可以手动创建,但脚本会更快,生成变更日志消息并从@charcoalphp/reviewers分配审阅者。
5. 等待审阅和合并 喝☕️,吃🍕
6. 合并完成后,GitHub工作流将处理发布过程、打标签、更新依赖项和更新变更日志。 干得好!🤘

维护和自动化

Symplify的MonorepoBuilder用于处理核心仓库与其包之间的兼容性。它将同步composer.json文件和包版本。

[待办] .releaserc中的语义发布配置

[待办] Conventional Commits

[待办] Commitizen

开发依赖项

开发历史

此monorepo使用多对一方法创建,使用此指南和工具

Github Actions

动作 触发器 描述
发布 在支持的分支上推送 使用semantic-release触发GitHub发布
拆分Monorepo main上发布 拆分动作将包拆分为单独的仓库。仅在推送标签时触发。基于symplify/monorepo-split-github-action
更新变更日志 main上发布 使用changelog-updater-action更新main分支的变更日志

脚本

create-pr

此脚本简化了创建Pull Request的过程。当您的分支准备好被拉入main或其他[目标]分支时,此工具会为您生成它,请求来自@charcoalphp/reviewers的审阅,并添加一个漂亮的、可读的发布说明,该说明基于两个分支之间的差异。

文档

Description
  Create a pull request on the github repository on the requested branch.
  Default branch: main

Usage
  ./create-pr

Options
  -b, --base          The base branch to merge into for the pull request. [Default: main]
  -h, --head          The branch to compare against the base branch. [Default: The current branch]

示例

# target: the target branch for the pull request. Defaults to [main]
./create-pr -b main -h user:feat-branch

create-release-notes可选工具

此脚本在请求时生成发布说明,返回基于请求的提交范围分支的变更日志。

文档

./build/script/create-release-notes --help

示例

./build/script/create-release-notes -g --from main

输出

变更

功能

  • create-pr: 添加脚本以在远程触发pull request(3016115

错误修复

  • create-pr: 从脚本中删除个人访问令牌,并用$GITHUB_TOKEN替换(f2aaac6
  • 包:添加缺失的 semantic-release 插件(《59bd1b1》)

贡献

与 Charcoal 互动的每个人都应遵守《行为准则》。

请参阅我们的《贡献指南》,了解如何为 Charcoal 做出贡献。

如果您正在尝试报告 Charcoal 中的潜在安全漏洞,请参阅我们的《安全策略》以获取更多信息。

✍🏻 作者

🎉 贡献者

List of contributors

Made with 《contrib.rocks》.

变更日志

查看《CHANGELOG》。

变更日志符合《Keep a Changelog》规范,并自动从自动发布中生成。

许可证

Charcoal 采用 MIT 许可证。有关详细信息,请参阅《LICENSE》。