nystudio107 / plugindev
nystudio107 Craft CMS plugin development environment scaffolding
Fund package maintenance!
khalwat
- dev-develop
- 1.2.4
- 1.2.3
- 1.2.2
- 1.2.1
- 1.2.0
- 1.1.27
- 1.1.26
- 1.1.25
- 1.1.24
- 1.1.23
- 1.1.22
- 1.1.21
- 1.1.20
- 1.1.19
- 1.1.18
- 1.1.17
- 1.1.16
- 1.1.15
- 1.1.14
- 1.1.13
- 1.1.12
- 1.1.11
- 1.1.10
- 1.1.9
- 1.1.8
- 1.1.7
- 1.1.6
- 1.1.5
- 1.1.4
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.39
- 1.0.38
- 1.0.37
- 1.0.36
- 1.0.35
- 1.0.34
- 1.0.33
- 1.0.32
- 1.0.31
- 1.0.30
- 1.0.29
- 1.0.28
- 1.0.26
- 1.0.25
- 1.0.24
- 1.0.23
- 1.0.22
- 1.0.21
- 1.0.20
- 1.0.19
- 1.0.18
- 1.0.17
- 1.0.16
- 1.0.15
- 1.0.14
- 1.0.13
- 1.0.12
- 1.0.11
- 1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- dev-master
This package is auto-updated.
Last update: 2024-10-18 21:14:09 UTC
README
About nystudio107/plugindev
This is a project scaffolding package for Craft CMS 3, 4 & 5 plugin development.
Read the A Craft CMS Plugin Local Development Environment article for full details on this project.
It gives you the following out of the box:
- Triple installs of both Craft CMS
^3.0.0
, Craft CMS^4.0.0
, and Craft CMS^5.0.0
running simultaneously craftcms/redactor
plugin is installedcraftcms/commerce
plugin is installed- A PHP 8.x environment with Imagick and other needed extensions pre-installed
- Code quality tools like
rector
,phpstan
, andecs
are all baked in - The Codeception PHP testing framework is installed and available for running tests
- A prefab database seed for both MySQL and Postgres databases
- The ability to switch between MySQL and Postgres easily
- A separate
test
database available for use during Codeception testing - Dual production/debug Docker containers for PHP, for improved performance while also supporting XDebug
- Multiple sites for testing
- Prefab content with a "blog" channel for testing
Creating nystudio107/plugindev
This project package works exactly the way Pixel & Tonic's craftcms/craft package works; you create a new project via Composer:
composer create-project nystudio107/plugindev --no-install
This will create a project named plugindev
which is a turnkey Craft CMS install for developing plugins.
We use --no-install
so that the composer packages for the root project are not installed.
It works this way so that you can take the basic scaffolding, and then modify it as you see fit.
Getting Started with nystudio107/plugindev
You'll need Docker desktop for your platform installed to run the project in local development
We also highly recommend that you use OrbStack if you're running MacOS; it's a drop-in replacement for Docker Desktop that is significantly faster and more reliable.
-
Craft CMS 3 runs out of the
cms_v3/
directory available athttp://plugindev.local:8003
with OrbStack (http://localhost:8003
with Docker Desktop) -
Craft CMS 4 runs out of the
cms_v4/
directory available athttp://plugindev.local:8004
with OrbStack (http://localhost:8004
with Docker Desktop) -
Craft CMS 5 runs out of the
cms_v5/
directory available athttp://plugindev.local:8005
with OrbStack (http://localhost:8005
with Docker Desktop)
Each version of Craft CMS runs in separate Docker containers, and uses a separate database running out of the database containers (MySQL and Postgres).
Composer will have already created a .env
file in the cms_v3/
, cms_v4
& cms_v5/
directories, based off of the respective example.env
files.
Setting up Local Dev
To set up your local dev environment, follow these steps:
- Edit the
cms_v3/composer.json
file and change the line"url": "/Users/andrew/webdev/craft_v3/*",
inrepositories
to point to your local plugin Git repositories for Craft CMS 3 - Edit the
cms_v4/composer.json
file and change the line"url": "/Users/andrew/webdev/craft_v4/*",
inrepositories
to point to your local plugin Git repositories for Craft CMS 4 - Edit the
cms_v5/composer.json
file and change the line"url": "/Users/andrew/webdev/craft_v5/*",
inrepositories
to point to your local plugin Git repositories for Craft CMS 5 - Edit the
docker-composer.yaml
file and change the line- /Users/andrew/webdev/craft_v3:/Users/andrew/webdev/craft_v3
to point to your local Craft CMS 3 plugin Git repositories - Edit the
docker-composer.yaml
file and change the line- /Users/andrew/webdev/craft_v4:/Users/andrew/webdev/craft_v4
to point to your local Craft CMS 4 plugin Git repositories - Edit the
docker-composer.yaml
file and change the line- /Users/andrew/webdev/craft_v5:/Users/andrew/webdev/craft_v5
to point to your local Craft CMS 4 plugin Git repositories
Setting up Plugin Git Repos
To make working on plugins from multiple versions of Craft CMS easier, clone each of your plugin repositories down to the appropriate separate directories: craft_v3
, craft_v4
, and craft_v5
.
These are two separate local repositories from the same remote git origin repository.
The path repositories
in your respective composer.json
files will cause Composer to install your plugins locally, rather than via Packagist, creating a symlink to the directories mentioned above.
This allows you to have all the repositories in the craft_v3
directory set to your Craft CMS 3 compatible branch, all the repositories in the craft_v4
directory set to your Craft CMS 4 compatible branch, and all the repositories in the craft_v5
directory set to your Craft CMS 4 compatible branch.
This makes working with multiple versions of your plugins for multiple versions of Craft CMS much easier.
Each directory will always have their branches set appropriately, and you can have separate Git Flow settings via Git Tower or other clients for each.
Using nystudio107/plugindev
Start up the plugindev
environment by typing make dev
in a terminal window (the first build will be somewhat lengthy).
To stop the plugindev
environment, type Control-C
in the terminal window you used to start it, which terminates the Docker containers.
N.B.: Since the containers need to be built, and Composer needs to install all of the packages, the initial make dev
can take some time. So before you attempt to load it in your web browser, wait until you see:
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
...and:
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
...and:
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
Login
- Navigate to
http://plugindev.local:8003
to use the Craft CMS 3 site - Navigate to
http://plugindev.local:8004
to use the Craft CMS 4 site - Navigate to
http://plugindev.local:8004
to use the Craft CMS 5 site
The default login for all plugindev
sites is:
User: admin
Password: password
Editor
You should open the craft_v3
, craft_v4
, and craft_v5
subdirectories in separate windows in your code editor of choice, rather than opening up the entire plugindev
project in a single window.
This allows your editor to index each Craft CMS install separately for things like code completion, and it also allows you to have separate PHP language level inspection settings (PHP 7.1 for Craft CMS 3, PHP 8 for Craft CMS 4, PHP 8.2 for Craft CMS 5).
You can also set up IDEs like PhpStorm to use the PHP interpreter inside the appropriate Docker container (plugindev_php_xdebug_v3
for Craft CMS 3, plugindev_php_xdebug_v4
for Craft CMS 4, and plugindev_php_xdebug_v5
for Craft CMS 5), and set up path mappings for XDebug.
Remember to enable the Symfony plugin if you're using PhpStorm for each project.
Exposed ports & services
plugindev
intentionally uses non-standard ports so you can run it side-by-side with another local dev environment, without risk of port conflicts.
The following ports are exposed on localhost
while plugindev
is running (these need to not be in use prior to starting up plugindev
):
8003
- The Craft CMS 3 website8004
- The Craft CMS 4 website8005
- The Craft CMS 5 website54320
- The Postgres database server33060
- The MySQL database server
The following databases are available in both the MySQL and Postgres database containers:
project_v3
- the database for Craft CMS 3. User:project
Password:project
project_v4
- the database for Craft CMS 4. User:project
Password:project
project_v5
- the database for Craft CMS 5. User:project
Password:project
test
- an entirely empty database that can be used for testing. User:project
Password:project
Internally, there are also containers that run the Craft CMS queue automatically, and a Redis container for caching.
make
Commands
This project uses Docker to shrink-wrap the devops it needs to run around the project.
To make using it easier, we're using a Makefile and the built-in make
utility to create a CLI API both for the project as a whole, and for the individual Craft CMS 3 & Craft CMS 4 site.
You can read more about it in the Using Make & Makefiles to Automate your Frontend Workflow article.
make
Project Commands
You can run the following from terminal in the root project directory:
make dev
- starts up the local dev server listening onhttp://plugindev.local:8003/
,http://plugindev.local:8004/
&http://plugindev.local:8005/
make clean
- removes thecomposer.lock
and the entirevendor/
directory from thecms_v3
,cms_v4
&cms_v5
projectsmake nuke
- restarts the project from scratch by runningmake clean
(above), then shuts down the Docker containers, removes any mounted volumes (including the database), and then rebuilds the containers from scratch
make
CMS Commands
composer craft ecs mysql phpstan postgres rector ssh
You can run the following from terminal in the cms_v3
or cms_v4
CMS directories:
make composer xxx
- runs thecomposer
command passed in, e.g.make composer install
in the php containermake craft xxx
- runs thecraft
console command passed in, e.g.:make craft project-config/apply
in the php containermake codecept xxx
- runs the Codeception testing framework with the passed in commands, e.g.:make codecept run -c ./vendor/putyourlightson/craft-blitz
in the php containermake ecs xxx
- runs Easy Coding Standard using the Craft CMS ECS config, with the passed in path, e.g.:make ecs check vendor/nystudio107/craft-seomatic/src
. To automatically fix, add the--fix
flag, e.g.:make -- ecs check vendor/nystudio107/craft-seomatic/src --fix
. Additional settings are available in theecs.php
filemake mysql
- switches the project to use the MySQL database container; just reload the browsermake phpstan xxx
- runs PHPStan using the Craft CMS PHPStan config, with the passed in path, e.g.:make phpstan analyze vendor/nystudio107/craft-seomatic/src
ormake -- phpstan analyze -c vendor/nystudio107/craft-seomatic/phpstan.neon
. Additional settings are available in thephpstan.neon
filemake postgres
- switches the project to use the Postgres database container; just reload the browsermake rector xxx
- runs Rector using the Craft CMS Rector config, with the passed in path, e.g.:make rector process vendor/nystudio107/craft-seomatic/src
. Additional settings are available in therector.php
filemake ssh
- opens up a Unix shell inside the PHP container for the project
Tip: If you try a command like make craft project-config/apply --force
you’ll see an error, because the shell thinks the --force
flag should be applied to the make
command. To side-step this, use the --
(double-dash) to disable further option processing, like this: make -- craft project-config/apply --force
Switching between MySQL & Postgres
The plugindev
environment supports both MySQL and Postgres out of the box. It spins up a container for each database, and seeds them with a starter db.
To use MySQL (the default) just type:
make mysql
To use Postgres just type:
make postgres
...and then just reload the page.
This is great for ensuring your db queries work properly on both MySQL and Postgres, without having to set up two separate environments.
OrbStack support
IF you use OrbStack as a faster, more efficient replacement for Docker Desktop on the Mac, you can take advantage of some local domain aliases:
plugindev.local:8003
,plugindev.local:8004
&plugindev.local:8005
- domain aliases for the respective web hostsmysql.plugindev.local
- local domain alias for the MySQL database containerpostgres.plugindev.local
- local domain alias for the Postgres database container
Dual PHP Containers for Xdebug
By default, all of your requests will be routed through the production PHP container, for speedy local development and testing.
However, there is a second Xdebug PHP container that's always running too, for the time that you need to use Xdebug on the really tough problems.
What happens is a request comes in, Nginx looks to see if there's an XDEBUG_SESSION
cookie set. If there's no cookie, it routes the request to the regular php container.
If however the XDEBUG_SESSION
cookie is set (with any value), it routes the request to the php_xdebug container.
You can set this cookie with a browser extension, your IDE, or via a number of other methods. Here is the Xdebug Helper browser extension for your favorite browsers: Chrome - Firefox - Safari
You can read more about it in the An Annotated Docker Config for Frontend Web Development article.
XDebug with VScode
To use Xdebug with VSCode install the PHP Debug extension and use the following configuration in your .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"] } ] }
Below is the entire intact, unmodified README.md
from Pixel & Tonic's craftcms/craft:
.....
About Craft CMS
Craft is a flexible and scalable CMS for creating bespoke digital experiences on the web and beyond.
It features:
- An intuitive Control Panel for administration tasks and content creation.
- A clean-slate approach to content modeling and front-end development.
- A built-in Plugin Store with hundreds of free and commercial plugins.
- A robust framework for module and plugin development.
Learn more about it at craftcms.com.
Tech Specs
Craft is written in PHP (7+), and built on the Yii 2 framework. It can connect to MySQL (5.5+) and PostgreSQL (9.5+) for content storage.
Installation
See the following documentation pages for help installing Craft 3:
Popular Resources
- Documentation – Read the official docs.
- Guides – Follow along with the official guides.
- #craftcms – See the latest tweets about Craft.
- Discord – Meet the community.
- Stack Exchange – Get help and help others.
- CraftQuest – Watch unlimited video lessons and courses.
- Craft Link List – Stay in-the-know.
- nystudio107 Blog – Learn Craft and modern web development.