diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..6d01f3195 --- /dev/null +++ b/.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" +} \ No newline at end of file diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100644 index 000000000..f1d39bea6 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.github/docs/dev-container-plugins.png b/.github/docs/dev-container-plugins.png new file mode 100644 index 000000000..a247020d4 Binary files /dev/null and b/.github/docs/dev-container-plugins.png differ diff --git a/.github/docs/dev-container-ports.png b/.github/docs/dev-container-ports.png new file mode 100644 index 000000000..5bbdf0668 Binary files /dev/null and b/.github/docs/dev-container-ports.png differ diff --git a/.github/docs/dev-container-terminal-plus.png b/.github/docs/dev-container-terminal-plus.png new file mode 100644 index 000000000..ebb3c75dc Binary files /dev/null and b/.github/docs/dev-container-terminal-plus.png differ diff --git a/.github/docs/dev-container.png b/.github/docs/dev-container.png new file mode 100644 index 000000000..ce8743e7f Binary files /dev/null and b/.github/docs/dev-container.png differ diff --git a/SETUP.md b/SETUP.md index 9bb1844bc..31762fbc6 100644 --- a/SETUP.md +++ b/SETUP.md @@ -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 diff --git a/phpstan-dev.neon b/phpstan-dev.neon new file mode 100644 index 000000000..447c4a334 --- /dev/null +++ b/phpstan-dev.neon @@ -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 \ No newline at end of file