locomotive-charcoal / charcoal
Requires
- php: ^7.4 || ^8.0
- ext-fileinfo: *
- ext-json: *
- ext-mbstring: *
- ext-pdo: *
- ext-simplexml: *
- ext-spl: *
- barryvdh/elfinder-flysystem-driver: ^0.3
- erusev/parsedown: ^1.7
- guzzlehttp/guzzle: ^6.0 || ^7.0
- kriswallsmith/assetic: ^1.4
- laminas/laminas-permissions-acl: ^2.8
- league/climate: ^3.2
- league/flysystem: ^1.0
- mcaskill/php-html-build-attributes: ^1.0
- monolog/monolog: ^1.17
- phpmailer/phpmailer: ~6.0
- pimple/pimple: ^3.0
- psr/cache: ^1.0
- psr/container: ^1.0
- psr/http-message: ^1.0
- psr/log: ^1.0
- seld/jsonlint: ^1.9
- slim/slim: ^3.7
- studio-42/elfinder: 2.1.64
- symfony/translation: ^3.4
- tedivm/stash: ~0.16
- vlucas/phpdotenv: ^5.4
Requires (Dev)
- cache/void-adapter: ^1.0
- league/csv: ^9.5
- league/flysystem-aws-s3-v3: ^1.0
- league/flysystem-memory: ^1.0
- league/flysystem-sftp: ^1.0
- mockery/mockery: ^1.0
- mustache/mustache: ^2.11
- php-coveralls/php-coveralls: ^2.2
- phpstan/phpstan: ^1.6
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.5
- symfony/yaml: ^3.0
- symplify/monorepo-builder: ^10.2
- twig/twig: ^3.4
Replaces
- charcoal/admin: v5.0.0
- charcoal/app: v5.0.0
- charcoal/attachment: v5.0.0
- charcoal/cache: v5.0.0
- charcoal/cms: v5.0.0
- charcoal/config: v5.0.0
- charcoal/core: v5.0.0
- charcoal/email: v5.0.0
- charcoal/factory: v5.0.0
- charcoal/image: v5.0.0
- charcoal/object: v5.0.0
- charcoal/property: v5.0.0
- charcoal/queue: v5.0.0
- charcoal/translator: v5.0.0
- charcoal/ui: v5.0.0
- charcoal/user: v5.0.0
- charcoal/view: v5.0.0
- locomotivemtl/charcoal-admin: *
- locomotivemtl/charcoal-app: *
- locomotivemtl/charcoal-attachment: *
- locomotivemtl/charcoal-cache: *
- locomotivemtl/charcoal-cms: *
- locomotivemtl/charcoal-config: *
- locomotivemtl/charcoal-core: *
- locomotivemtl/charcoal-email: *
- locomotivemtl/charcoal-factory: *
- locomotivemtl/charcoal-image: *
- locomotivemtl/charcoal-object: *
- locomotivemtl/charcoal-property: *
- locomotivemtl/charcoal-queue: *
- locomotivemtl/charcoal-translator: *
- locomotivemtl/charcoal-ui: *
- locomotivemtl/charcoal-user: *
- locomotivemtl/charcoal-view: *
- dev-main / 5.x-dev
- v5.0.0
- v4.1.0
- v4.0.8
- v4.0.7
- v4.0.6
- v4.0.5
- v4.0.4
- v4.0.3
- v4.0.2
- v4.0.1
- v4.0.0
- v3.1.7
- v3.1.6
- v3.1.5
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v3.0.16
- v3.0.15
- v3.0.14
- v3.0.13
- v3.0.12
- v3.0.11
- v3.0.10
- v3.0.9
- v3.0.8
- v3.0.7
- v3.0.6
- v3.0.5
- v3.0.4
- v3.0.3
- v3.0.2
- v3.0.1
- v3.0.0
- v2.3.0
- v2.2.5
- v2.2.4
- v2.2.3
- v2.2.2
- v2.2.1
- v2.2.0
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.1
- v2.0.0
- v1.3.4
- v1.3.3
- v1.3.2
- v1.3.1
- v1.3.0
- v1.2.0
- v1.2.0-beta.25
- v1.2.0-beta.24
- v1.2.0-beta.23
- v1.2.0-beta.22
- v1.2.0-beta.21
- v1.2.0-beta.20
- v1.2.0-beta.19
- v1.2.0-beta.18
- v1.2.0-beta.17
- v1.2.0-beta.16
- v1.2.0-beta.15
- v1.2.0-beta.14
- v1.2.0-beta.13
- v1.2.0-beta.12
- v1.2.0-beta.11
- v1.2.0-beta.10
- v1.2.0-beta.9
- v1.2.0-beta.8
- v1.2.0-beta.7
- v1.2.0-beta.6
- v1.2.0-beta.5
- v1.2.0-beta.4
- v1.2.0-beta.3
- v1.2.0-beta.2
- v1.2.0-beta.1
- v1.1.1
- v1.1.1-beta.1
- v1.1.0
- v1.1.0-beta.4
- v1.1.0-beta.3
- v1.1.0-beta.2
- v1.1.0-beta.1
- v1.0.1-beta.5
- v1.0.1-beta.4
- v1.0.1-beta.3
- v1.0.1-beta.2
- v1.0.1-beta.1
- v1.0.0
- v1.0.0-beta.3
- v1.0.0-beta.2
- v1.0.0-beta.1
- dev-joel/feature/tabulator-input
- dev-feature/tabulator-input
- dev-feature/slim4
- dev-fix/gruntfile-path
- dev-joel_feat_event-dispatcher
- dev-beta
- dev-feature/admin-view
- dev-fix-paths
- dev-develop
- dev-joel/feat/migrate-tool
- dev-joel/feat/package-mapping
This package is auto-updated.
Last update: 2024-03-13 17:56:42 UTC
README
由Locomotive 🚂
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 | 支持Mustache、Twig等的视图层。 |
安装
首选(也是唯一支持)方法是使用 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 — 如果您想用全栈框架包替换所有包
-
在您的
composer.json
文件中删除核心包(locomotivemtl/charcoal-*
)的要求。 -
在您的
composer.json
文件中,将贡献包(locomotivemtl/charcoal-contrib-*
)的要求替换为来自charcoal/contrib-*
的等效包。 -
运行
composer require charcoal/charcoal
来安装框架。 -
运行
composer update
以确保所有要求都是最新的。 -
运行以下迁移脚本
./vendor/charcoal/charcoal/build/script/migrate-project
migrate-project
脚本将更新您项目配置文件中的所有元数据路径。之后,它将编辑或创建一个.env
环境变量文件,其中PACKAGES_PATH
键设置为:vendor/charcoal/charcoal/packages
。这允许
%packages.path%
字符串模板扩展到charcoal/charcoal
中的包位置,否则它将导致在vendor
目录中。
选项B — 如果您想用新的独立包替换所有包
- 在您的
composer.json
文件中替换核心包(locomotivemtl/charcoal-*
)的要求。 - 在您的
composer.json
文件中,将贡献包(locomotivemtl/charcoal-contrib-*
)的要求替换为来自charcoal/contrib-*
的等效包。 - 运行
composer require charcoal/config charcoal/core…
来安装包。 - 运行
composer update
以确保所有要求都是最新的。 - 将配置文件中的
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 标准,因此您可以全局安装它以简化编写提交的过程。
或者,有一些代码编辑器插件可以帮助创建常规提交
vscode
phpstrom
以下是基于一些提交信息的发布类型示例
-
补丁(修复)发布
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
开发依赖项
- symplify/monorepo-builder
- 保持包版本同步。
- 配置位于monorepo-builder。它允许定义更多依赖项
- semantic-release
- 使用Github action处理发布过程。
开发历史
此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)
错误修复
贡献
与 Charcoal 互动的每个人都应遵守《行为准则》。
请参阅我们的《贡献指南》,了解如何为 Charcoal 做出贡献。
如果您正在尝试报告 Charcoal 中的潜在安全漏洞,请参阅我们的《安全策略》以获取更多信息。
✍🏻 作者
- Locomotive 🚂
- Mathieu Ducharme 👨🏻💻
- Chauncey McAskill 👨🏻💻
- Joel Alphonso 👨🏻💻
- Dominic Lord 👨🏻💻
- Benjamin Roch 👨🏻💻
🎉 贡献者
Made with 《contrib.rocks》.
变更日志
查看《CHANGELOG》。
变更日志符合《Keep a Changelog》规范,并自动从自动发布中生成。
许可证
Charcoal 采用 MIT 许可证。有关详细信息,请参阅《LICENSE》。