/plugindev

nystudio107 Craft CMS plugin development environment scaffolding

Primary LanguagePHPBSD Zero Clause License0BSD

nystudio107

About nystudio107/plugindev

This is a project scaffolding package for Craft 3 CMS 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:

  • Craft CMS ^3.6.7 is installed
  • craftcms/redactor plugin is installed
  • craftcms/commerce plugin is installed
  • A PHP 8.x environment with Imagick and other needed extensions pre-installed
  • A prefab database seed for both MySQL and Postgres databases
  • The ability to switch between MySQL and Postgres easily
  • 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

Using nystudio107/plugindev

This project package works exactly the way Pixel & Tonic's craftcms/craft package works; you create a new project by first creating & installing the project:

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.

Setting Up Local Dev

You'll need Docker desktop for your platform installed to run the project in local development

  • Composer will have already created a .env file in the cms/ directory, based off of the provided example.env

  • Edit the cms/composer.json file and change the line "url": "/Users/andrew/webdev/craft/*", in repostories to point to your local plugin Git repositories

  • Edit the docker-composer.yaml file and change the line - /Users/andrew/webdev/craft:/Users/andrew/webdev/craft to point to your local plugin Git repositories

  • Start up the site with make dev (the first build will be somewhat lengthy)

  • Navigate to http://localhost:8000 to use the site

Login

The default login is:

User: admin
Password: password

Updating

To update to the latest Composer packages (as constrained by the cms/composer.json semvers), do:

make update

To start from scratch by removing cms/vendor/, then update to the latest Composer packages (as constrained by the cms/composer.json semvers), do:

make update-clean

Switching between MySQL & Postgres

The plugindev project 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.

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 Dual An Annotated Docker Config for Frontend Web Development article.

Makefile Project 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 local aliases. You can run the following from terminal in the project directory:

  • make dev - starts up the local dev server listening on http://localhost:8000/
  • make clean - shuts down the Docker containers, removes any mounted volumes (including the database), and then rebuilds the containers from scratch
  • make mysql - switches the project to use the MySQL database container; just reload the browser
  • make postgres - switches the project to use the Postgres database container; just reload the browser
  • make update - causes the project to update to the latest Composer dependencies
  • make update-clean - completely removes node_modules/ & vendor/, then causes the project to update to the latest Composer dependencies
  • make composer xxx - runs the composer command passed in, e.g. make composer install in the php container
  • make craft xxx - runs the craft console command passed in, e.g. make craft project-config/apply in the php container

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:

.....

Craft CMS

About Craft CMS

Craft is a flexible and scalable CMS for creating bespoke digital experiences on the web and beyond.

It features:

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