README

关于nystudio107/plugindev

这是一个Craft CMS 3、4 & 5插件开发的框架包。

阅读Craft CMS 插件本地开发环境文章以获取此项目的详细信息。

它提供以下功能

• 同时运行Craft CMS ^3.0.0、Craft CMS ^4.0.0和Craft CMS ^5.0.0的三个安装
• craftcms/redactor插件已安装
• craftcms/commerce插件已安装
• 带有预安装Imagick和其他所需扩展的PHP 8.x环境
• 包含如rector、phpstan和ecs等代码质量工具
• 已安装并可用Codeception PHP测试框架进行测试
• 适用于MySQL和Postgres数据库的预制数据库种子
• 可以轻松在MySQL和Postgres之间切换
• 在Codeception测试期间可用的单独test数据库
• PHP的双重生产/调试Docker容器，以改善性能并支持XDebug
• 多个测试网站
• 带有“博客”频道的预制内容进行测试

创建nystudio107/plugindev

此项目包与Pixel & Tonic的craftcms/craft包一样工作；您通过Composer创建一个新项目

composer create-project nystudio107/plugindev --no-install

这将创建一个名为plugindev的项目，这是一个用于开发插件的即用型Craft CMS安装。

我们使用--no-install，以便不安装根项目的Composer包。

这样，您可以取基本的框架，然后根据需要修改它。

nystudio107/plugindev 入门

您需要为您的平台安装Docker桌面以在本地开发中运行项目

如果您使用MacOS，我们强烈推荐您使用OrbStack；它是Docker Desktop的替代品，速度更快，更可靠。

• Craft CMS 3从OrbStack的cms_v3/目录运行（使用Docker Desktop为http://localhost:8003）

• Craft CMS 4从OrbStack的cms_v4/目录运行（使用Docker Desktop为http://localhost:8004）

• Craft CMS 5从OrbStack的cms_v5/目录运行（使用Docker Desktop为http://localhost:8005）

每个Craft CMS版本都在单独的Docker容器中运行，并使用数据库容器（MySQL和Postgres）中的单独数据库。

Composer已在cms_v3/、cms_v4 & cms_v5/目录中创建了一个.env文件，基于各自的example.env文件。

设置本地开发环境

要设置您的本地开发环境，请按照以下步骤操作

• 编辑 cms_v3/composer.json 文件，并将 repositories 中的 "url": "/Users/andrew/webdev/craft_v3/*", 行修改为指向您的本地 Craft CMS 3 插件 Git 仓库
• 编辑 cms_v4/composer.json 文件，并将 repositories 中的 "url": "/Users/andrew/webdev/craft_v4/*", 行修改为指向您的本地 Craft CMS 4 插件 Git 仓库
• 编辑 cms_v5/composer.json 文件，并将 repositories 中的 "url": "/Users/andrew/webdev/craft_v5/*", 行修改为指向您的本地 Craft CMS 5 插件 Git 仓库
• 编辑 docker-composer.yaml 文件，并将 - /Users/andrew/webdev/craft_v3:/Users/andrew/webdev/craft_v3 行修改为指向您的本地 Craft CMS 3 插件 Git 仓库
• 编辑 docker-composer.yaml 文件，并将 - /Users/andrew/webdev/craft_v4:/Users/andrew/webdev/craft_v4 行修改为指向您的本地 Craft CMS 4 插件 Git 仓库
• 编辑 docker-composer.yaml 文件，并将 - /Users/andrew/webdev/craft_v5:/Users/andrew/webdev/craft_v5 行修改为指向您的本地 Craft CMS 5 插件 Git 仓库

设置插件 Git 仓库

为了使同时处理多个版本的 Craft CMS 插件更加容易，将每个插件的仓库克隆到相应的独立目录中：craft_v3、craft_v4 和 craft_v5。

这些是来自同一个远程 Git 仓库的独立本地仓库。

您各自的 composer.json 文件中的 repositories 路径将导致 Composer 在本地安装您的插件，而不是通过 Packagist，并创建到上述提到的目录的符号链接。

这允许您将所有位于 craft_v3 目录下的仓库设置为与 Craft CMS 3 兼容的分支，将所有位于 craft_v4 目录下的仓库设置为与 Craft CMS 4 兼容的分支，以及将所有位于 craft_v5 目录下的仓库设置为与 Craft CMS 5 兼容的分支。

这使得处理多个版本的 Craft CMS 插件变得容易得多。

每个目录都会适当地设置分支，并且您可以为每个目录通过 Git Tower 或其他客户端设置独立的 Git Flow 设置。

使用 nystudio107/plugindev

通过在终端窗口中输入 make dev 来启动 plugindev 环境（第一次构建可能需要一些时间）。

要停止 plugindev 环境，在您启动它的终端窗口中输入 Control-C，这将终止 Docker 容器。

注意：由于容器需要构建，Composer 需要安装所有包，因此初始的 make dev 可能需要一些时间。所以在您尝试在浏览器中加载它之前，请等待您看到

plugindev-php_v3-1         | [09-Mar-2022 04:05:33] NOTICE: fpm is running, pid 8
plugindev-php_v3-1         | [09-Mar-2022 04:05:33] NOTICE: ready to handle connections

...

plugindev-php_v4-1         | [09-Mar-2022 04:05:33] NOTICE: fpm is running, pid 8
plugindev-php_v4-1         | [09-Mar-2022 04:05:33] NOTICE: ready to handle connections

...

plugindev-php_v5-1         | [09-Mar-2022 04:05:33] NOTICE: fpm is running, pid 8
plugindev-php_v5-1         | [09-Mar-2022 04:05:33] NOTICE: ready to handle connections

登录

• 导航到 http://plugindev.local:8003 以使用 Craft CMS 3 网站
• 导航到 http://plugindev.local:8004 以使用 Craft CMS 4 网站
• 导航到 http://plugindev.local:8004 以使用 Craft CMS 5 网站

所有 plugindev 网站的默认登录凭证是

用户： admin
密码： password

编辑器

您应该在代码编辑器中分别打开 craft_v3、craft_v4 和 craft_v5 子目录，而不是在单个窗口中打开整个 plugindev 项目。

这允许您的编辑器分别对每个 Craft CMS 安装进行索引，例如代码补全，并且还可以允许您为每个项目设置独立的 PHP 语言级别检查设置（Craft CMS 3 使用 PHP 7.1，Craft CMS 4 使用 PHP 8，Craft CMS 5 使用 PHP 8.2）。

您还可以设置类似 PhpStorm 的 IDE，以使用适当 Docker 容器内的 PHP 解释器（Craft CMS 3 使用 plugindev_php_xdebug_v3，Craft CMS 4 使用 plugindev_php_xdebug_v4，Craft CMS 5 使用 plugindev_php_xdebug_v5），并设置 XDebug 的路径映射。

请记住，如果您在项目中使用 PhpStorm，则必须为每个项目启用 Symfony 插件。

暴露的端口与服务

plugindev 故意使用非标准端口，这样您可以在不影响其他本地开发环境的情况下，与它并行运行，而不用担心端口冲突。

当 plugindev 运行时，以下端口在 localhost 上暴露（在启动 plugindev 之前，这些端口不应被占用）

• 8003 - Craft CMS 3 网站
• 8004 - Craft CMS 4 网站
• 8005 - Craft CMS 5 网站
• 54320 - Postgres 数据库服务器
• 33060 - MySQL 数据库服务器

以下数据库在 MySQL 和 Postgres 数据库容器中都可用

• project_v3 - Craft CMS 3 的数据库。用户：project 密码：project
• project_v4 - Craft CMS 4 的数据库。用户：project 密码：project
• project_v5 - Craft CMS 5 的数据库。用户：project 密码：project
• test - 一个完全空的数据库，可以用于测试。用户：project 密码：project

内部还有运行 Craft CMS 队列的容器，以及用于缓存的 Redis 容器。

make 命令

该项目使用 Docker 将运行所需的 devops 缩小包装在项目周围。

为了使用它更方便，我们使用 Makefile 和内置的 make 工具创建了一个 CLI API，用于整个项目和单独的 Craft CMS 3 及 Craft CMS 4 网站。

您可以在使用 Make & Makefiles 自动化前端工作流程文章中了解更多信息。

make 项目命令

您可以从根项目目录的终端运行以下命令

• make dev - 在 http://plugindev.local:8003/、http://plugindev.local:8004/ 和 http://plugindev.local:8005/ 上启动本地开发服务器
• make clean - 从 cms_v3、cms_v4 和 cms_v5 项目中删除 composer.lock 和整个 vendor/ 目录
• make nuke - 通过运行上面的 make clean 重新启动项目，然后关闭 Docker 容器，删除任何挂载的卷（包括数据库），然后从头开始重新构建容器

make CMS 命令

composer craft ecs mysql phpstan postgres rector ssh

您可以从 cms_v3 或 cms_v4 CMS 目录的终端运行以下命令

• make composer xxx - 在 php 容器中运行传入的 composer 命令，例如：在 php 容器中运行 make composer install
• make craft xxx - 在 php 容器中运行传入的 craft 控制台命令，例如：在 php 容器中运行 make craft project-config/apply
• make codecept xxx - 使用传入的命令运行 Codeception 测试框架，例如：在 php 容器中运行 make codecept run -c ./vendor/putyourlightson/craft-blitz
• make ecs xxx - 使用 Easy Coding Standard 和 Craft CMS ECS 配置运行，传入路径，例如：运行 make ecs check vendor/nystudio107/craft-seomatic/src。要自动修复，请添加 --fix 标志，例如：运行 make -- ecs check vendor/nystudio107/craft-seomatic/src --fix。额外的设置可以在 ecs.php 文件中找到
• make mysql - 将项目切换到使用 MySQL 数据库容器；只需重新加载浏览器即可
• make phpstan xxx - 使用PHPStan，并通过Craft CMS PHPStan配置进行运行，传入路径，例如：make phpstan analyze vendor/nystudio107/craft-seomatic/src 或 make -- phpstan analyze -c vendor/nystudio107/craft-seomatic/phpstan.neon。在phpstan.neon文件中还有其他设置。
• make postgres - 将项目切换到使用Postgres数据库容器；只需重新加载浏览器。
• make rector xxx - 使用Rector，通过Craft CMS Rector配置，传入路径，例如：make rector process vendor/nystudio107/craft-seomatic/src。在rector.php文件中还有其他设置。
• make ssh - 在PHP容器内打开Unix shell。

提示：如果您尝试执行类似于make craft project-config/apply --force的命令，您将看到一个错误，因为shell认为--force标志应该应用于make命令。为了避免这种情况，请使用--（双横线）来禁用进一步选项处理，如下所示：make -- craft project-config/apply --force

在MySQL和Postgres之间切换

plugindev环境默认支持MySQL和Postgres。它为每个数据库启动一个容器，并用启动数据库进行初始化。

要使用MySQL（默认），只需键入

make mysql

要使用Postgres，只需键入

make postgres

...然后重新加载页面。

这非常适合确保您的数据库查询在MySQL和Postgres上都能正常工作，而无需设置两个独立的环境。

OrbStack支持

如果您使用OrbStack作为Mac上Docker Desktop的更快速、更高效的替代品，您可以利用一些本地域名别名

• plugindev.local:8003、plugindev.local:8004 和 plugindev.local:8005 - 分别对应不同Web托管服务的域名别名
• mysql.plugindev.local - MySQL数据库容器的本地域名别名
• postgres.plugindev.local - Postgres数据库容器的本地域名别名

双PHP容器用于Xdebug

默认情况下，所有请求都会通过生产PHP容器路由，以实现快速的本地开发和测试。

但是，还有一个始终运行的第二个Xdebug PHP容器，用于解决真正困难的问题。

当请求到来时，Nginx会检查是否有设置XDEBUG_SESSION cookie。如果没有cookie，则将请求路由到常规php容器。

然而，如果设置了XDEBUG_SESSION cookie（任何值都可以），则将请求路由到php_xdebug容器。

您可以使用浏览器扩展，您的IDE或通过其他多种方法来设置此cookie。以下是您 favorite 浏览器中的Xdebug Helper浏览器扩展：Chrome - Firefox - Safari

您可以在An Annotated Docker Config for Frontend Web Development文章中了解更多信息。

Xdebug与VScode

要使用Xdebug与VSCode，请安装PHP Debug扩展，并在您的.vscode/launch.json中使用以下配置

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "log": true,
            "externalConsole": false,
            "pathMappings": {
                "/var/www/project/cms": "${workspaceRoot}/cms"
            },
            "ignore": ["**/vendor/**/*.php"]
        }
    ]
}

以下是从Pixel & Tonic的craftcms/craft项目中提取的完整、未修改的README.md。

.....

关于Craft CMS

Craft是一个灵活可扩展的CMS，用于在网络上创建定制的数字体验。

它具有以下特点：

• 一个直观的控制面板，用于管理任务和内容创建。
• 对内容模型和前端开发采用全新的方法。
• 内置插件商店，提供数百个免费和商业插件。
• 强大的框架，用于模块和插件开发。

更多关于Craft CMS的信息，请访问craftcms.com。

技术规格

Craft是用PHP（7+）编写的，基于Yii 2框架构建。它可以通过MySQL（5.5+）和PostgreSQL（9.5+）进行内容存储。

安装

有关安装Craft 3的帮助，请参阅以下文档页面：

• 服务器要求
• 安装说明
• 从Craft 2升级

常用资源

• 文档 – 阅读官方文档。
• 指南 – 跟随官方指南。
• #craftcms – 查看关于Craft的最新推文。
• Discord – 加入社区。
• Stack Exchange – 获取帮助并帮助他人。
• CraftQuest – 观看无限的视频课程和课程。
• Craft Link List – 保持最新。
• nystudio107博客 – 学习Craft和现代网络开发。