Merge pull request #784 from Kit/add-devcontainer

Add `devcontainer` Configuration

Author: n7studios

.devcontainer/devcontainer.json

@@ -0,0 +1,73 @@
+{
+    "name": "WordPress Codespace",
+    "image": "ghcr.io/automattic/vip-codespaces/alpine-base:latest",
+    "overrideCommand": false,
+    "forwardPorts": [80, 81, 8025],
+    "portsAttributes": {
+        "80": {
+            "label": "Application",
+            "onAutoForward": "notify",
+            "elevateIfNeeded": true
+        },
+        "81": {
+            "label": "phpMyAdmin",
+            "onAutoForward": "notify",
+            "elevateIfNeeded": true
+        },
+        "3306": {
+            "label": "MySQL",
+            "onAutoForward": "ignore"
+        },
+        "9000": {
+            "label": "php-fpm",
+            "onAutoForward": "ignore"
+        },
+        "9003": {
+            "label": "Xdebug Client Port",
+            "onAutoForward": "notify"
+        }
+    },
+    "features": {
+        "ghcr.io/automattic/vip-codespaces/base:latest": {},
+        "ghcr.io/automattic/vip-codespaces/nginx:latest": {},
+        "ghcr.io/automattic/vip-codespaces/php:latest": {
+            "version": "8.2",
+            "composer": true
+        },
+        "ghcr.io/automattic/vip-codespaces/mariadb:latest": {
+            // Set to false to prevent the database content from persisting between rebuilds.
+            "installDatabaseToWorkspaces": true
+        },
+        "ghcr.io/automattic/vip-codespaces/wordpress:latest": {
+            // WordPress version: Accepts 'latest', 'nightly', or a version number.
+            "version": "latest",
+            // Set to false to prevent wp-content/uploads content from persisting between rebuilds.
+            "moveUploadsToWorkspaces": false,
+            // Set to true to create the environment as a WordPress multisite.
+            "multisite": false,
+            // GitHub Codespaces only supports the subdirectory network type for multisite; subdomain cannot be used.
+            "multisiteStyle": "subdirectory"
+        },
+        "ghcr.io/automattic/vip-codespaces/wp-cli:latest": {
+            // Set to true to enable nightly builds of WP-CLI.
+            "nightly": false
+        },
+        "ghcr.io/automattic/vip-codespaces/dev-tools:latest": {},
+        "ghcr.io/automattic/vip-codespaces/phpmyadmin:latest": {
+            // Set to false to disable phpMyAdmin.
+            "enabled": true
+        },
+        "ghcr.io/automattic/vip-codespaces/xdebug:latest": {
+            // Set to true to enable Xdebug.
+            // This setting can also be updated with CLI commands in the terminal.
+            "enabled": true,
+            // Set Xdebug mode. Accepted value options are listed here: https://xdebug.org/docs/all_settings#mode
+            "mode": "debug"
+        },
+        "ghcr.io/automattic/vip-codespaces/ssh:latest": {
+            // Set to true to enable an SSH server for the Codespaces environment.
+            "enabled": true
+        }
+    },
+    "postCreateCommand": "bash ./.devcontainer/post-create.sh"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+# Install Free Third Party WordPress Plugins 
+wp plugin install classic-editor custom-post-type-ui elementor forminator woocommerce
+
+# Install Default WordPress Theme
+wp theme install twentytwentyfive
+
+# Symlink Plugin
+ln -s /workspaces/convertkit-wordpress /wp/wp-content/plugins/convertkit
+
+# Run Composer in Plugin Directory to build
+cd /wp/wp-content/plugins/convertkit
+composer update
+
+# Activate Plugin
+wp plugin activate convertkit

.github/docs/dev-container-plugins.png

@@ -5,16 +5,18 @@ This document describes how to setup your development environment, so that it is
 Suggestions are provided for the LAMP/LEMP stack and Git client are for those who prefer the UI over a command line and/or are less familiar with 
 WordPress, PHP, MySQL and Git - but you're free to use your preferred software.
 
-## Setup
-
-### LAMP/LEMP stack
+## LAMP/LEMP stack
 
 Any Apache/nginx, PHP 7.x+ and MySQL 5.8+ stack running WordPress.  For example, but not limited to:
 - Local by Flywheel (recommended)
-- Docker
 - MAMP
 - WAMP
 - VVV
+- Docker
+
+## Local, MAMP, WAMP, VVV
+
+If using a non-Docker environment, follow the below steps:
 
 ### Composer
 
@@ -56,9 +58,9 @@ Create a blank `test` database in MySQL, with a MySQL user who can read and writ
 
 ### Configure Testing Environment
 
-Copy the `.env.example` file to `.env.testing` in the root of this repository, changing the `WORDPRESS_*` and `CHROMEDRIVER_*` variables as necessary to match your environment.
+Copy the `.env.example` file to `.env.testing` in the root of this repository, changing folder and database credentials as necessary.
 
-#### Codeception
+### Codeception
 
 Create a `codeception.yml` file in the root of the repository, with the following contents:
 ```yaml
@@ -68,10 +70,6 @@ params:
 
 This tells Codeception to read the above `.env.testing` file when testing on the local development enviornment.
 
-#### PHPStan
-
-Copy the `phpstan.neon.example` file to `phpstan.neon` in the root of this repository, changing the `scanDirectories` to point to your local WordPress installation.
-
 ### Install Packages
 
 In the Plugin's directory, at the command line, run `composer install`.
@@ -178,10 +176,79 @@ vendor/bin/phpstan --memory-limit=1G
 Again, don't worry if you don't understand these commands; if your output looks similar to the above screenshot, with no errors, your environment
 is setup successfully.
 
-### Add your API Key to the Plugin
+### Connect Plugin to Kit
+
+Refer to the [Kit Help Article](https://help.kit.com/en/articles/2502591-getting-started-the-wordpress-plugin) to get started with using the WordPress Plugin.
+
+## Docker
+
+Using the Development Container, and either GitHub Codespaces or VS Code, it's quick and easy to get started:
+
+### Clone Repository
+
+Using your preferred Git client or command line, clone this repository to your local machine.
+
+If you're new to this, use [GitHub Desktop](https://desktop.github.com/) or [Tower](https://www.git-tower.com/mac)
+
+### Install Docker and Visual Studio Code
+
+- Install [Docker Desktop](https://www.docker.com/products/docker-desktop/), or [Docker Engine](https://docs.docker.com/engine/) if you're developing on Linux
+- Install [Visual Studio Code]()
+
+### Install and Run Dev Containers
+
+- Open Visual Studio Code, and install the [Dev Containers]() extension
+- Open the Visual Studio Code Command Palette (`Ctrl + Shift + P`)
+- Type `>Dev Container: Rebuild and Reopen in Container`, pressing Enter
+
+Visual Studio Code will switch to the Dev Container, loading the preconfigured Docker image for WordPress development, with the Terminal in Visual Studio Code showing the progress:
+
+![Terminal](/.github/docs/dev-container.png?raw=true)
+
+After a few minutes, your development environment should be ready. 
+
+### Accessing WordPress
+
+Click on the `Ports` tab, and navigate to the "Application" URL by hovering over the `Forwarded Address` and clicking the globe icon:
+
+![Ports tab](/.github/docs/dev-container-ports.png?raw=true)
+
+To access the WordPress Administration interface, append `/wp-admin` to the URL, using the following credentials:
+- Username: `vipgo`
+- Password: `password`
+
+Once logged in, navigating to the Plugins screen will show the repository Plugin installed and active, along with some other common third party Plugins:
+
+![Ports tab](/.github/docs/dev-container-plugins.png?raw=true)
+
+### Running Codesniffer
+
+In Visual Studio Code's Terminal, navigate to `/workspaces/convertkit-wordpress`, and run the following command to run PHP_CodeSniffer, which will check the code meets WordPress' Coding Standards:
+
+```bash
+vendor/bin/phpcs ./ -v -s
+```
+
+If no Terminal instance is open, you can create a new one by clicking the `+` icon.
+
+![Terminal tab](/.github/docs/dev-container-terminal-plus.png?raw=true)
+
+### Running PHPStan
+
+In Visual Studio Code's Terminal, navigate to `/workspaces/convertkit-wordpress`, and run the following command to run PHPStan, which will perform static analysis on the code, checking it meets required
+standards, that PHP DocBlocks are valid, WordPress action/filter DocBlocks are valid etc:
+
+```bash
+vendor/bin/phpstan --configuration phpstan-dev.neon --memory-limit=1G
+```
+
+If no Terminal instance is open, you can create a new one by clicking the `+` icon.
+
+![Terminal tab](/.github/docs/dev-container-terminal-plus.png?raw=true)
+
+### Testing
 
-Refer to the [Kit Help Article](https://help.kit.com/en/articles/2502591-getting-started-the-wordpress-plugin) to get started with
-using the WordPress Plugin.
+Codeception testing is currently unavailable when using Dev Containers or GitHub Codespaces. This may be available in a future PR.
 
 ### Next Steps
 

.github/docs/dev-container-ports.png

@@ -0,0 +1,38 @@
+# PHPStan configuration for Dev Containers
+
+# Include PHPStan for WordPress configuration.
+includes:
+    - vendor/szepeviktor/phpstan-wordpress/extension.neon
+
+# Parameters
+parameters:
+    # Paths to scan
+    # This should comprise of the base Plugin PHP file, plus directories that contain Plugin PHP files
+    paths:
+        - wp-convertkit.php
+        - admin/
+        - includes/
+
+    # Files that include Plugin-specific PHP constants.
+    bootstrapFiles:
+        - wp-convertkit.php
+
+    # Location of WordPress Plugins for PHPStan to scan, building symbols.
+    scanDirectories:
+        - /wp/wp-content/plugins
+
+    # Location of constants, Kit helper functions and Kit WordPress Libraries for PHPStan to scan, building symbols.
+    scanFiles:
+        - /wp/wp-config.php
+
+    # Don't report unmatched ignored errors on older PHP versions (7.2, 7.3)
+    reportUnmatchedIgnoredErrors: false
+
+    # Ignore the following errors, as PHPStan and PHPStan for WordPress haven't correctly registered symbols,
+    # so they're false positives.
+    ignoreErrors:
+        - '#Function __ invoked with 2 parameters, 1 required.#'
+
+    # Should not need to edit anything below here
+    # Rule Level: https://phpstan.org/user-guide/rule-levels
+    level: 5