diff --git a/.lando.yml b/.lando.yml index 8d321b54..5e60cb10 100644 --- a/.lando.yml +++ b/.lando.yml @@ -1,5 +1,6 @@ name: moose recipe: wordpress + config: php: '8.3' database: mariadb:11.5 @@ -7,14 +8,16 @@ config: via: nginx xdebug: false memcached: true + services: appserver: - run: - - composer install - - composer run copy-local-configs + build: + - composer create-local-configs overrides: environment: - XDEBUG_TRIGGER=1 + node: + type: node:22 # Enabling MailHog will cause an error on start: `/bin/sh: 1: curl: not found`. # Related GH Issue: https://github.com/lando/mailhog/issues/35 @@ -30,7 +33,14 @@ services: # - appserver_nginx # - appserver +events: + post-start: + - appserver: composer install + - node: npm install && npm run build + tooling: + npm: + service: node xdebug-on: service: appserver description: Enable xdebug for nginx. diff --git a/CHANGELOG.md b/CHANGELOG.md index c140da75..70315b35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ item (Added, Changed, Depreciated, Removed, Fixed, Security). ## [2025.01] +- Added: Node service to Lando so FE assets can be built automatically on start up. +- Updated: project start up scripts to automatically generate the correct contents of the lcoal config files. +- Updated: script to install WordPress so we can use a version constant and not install WP every time composer is + installed or updated. - Updated: ESLint config now supports browser environment variable such as `IntersectionObserver` - Added: ability for table blocks to utilize the `overflow-x` set on them by setting a `min-width` property for the `table` element within the table block. diff --git a/README.md b/README.md index ce74daa3..40868034 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ maintained by the folks at [Modern Tribe](https://tri.be). * [Git](https://git-scm.com/) * [Composer](https://getcomposer.org/) * [Node & NPM](https://nodejs.org/) - * [NVM](https://github.com/nvm-sh/nvm) is recommended for managing multiple versions of node on the same workstation. + * [NVM](https://github.com/nvm-sh/nvm) is recommended for managing multiple versions of node on the same + workstation. * [Lando](https://lando.dev/) (Optional) Provides a consistent local development environment for all team members. * [1Password CLI](https://developer.1password.com/docs/cli/) (Optional) Automates the creation of composer's `auth.json` file so that paid 3rd-party plugins like Advanced Custom Fields Pro and Gravity Forms can be installed via composer. @@ -28,12 +29,11 @@ maintained by the folks at [Modern Tribe](https://tri.be). [1Password CLI](#1password-cli). See the [Composer Docs](./docs/composer.md#creating-an-authjson-file) for manual instructions.) 3. Run `lando start` to create the local environment. -4. Run `nvm use` to ensure the correct version of node is in use. -5. Run `npm install` to install the required npm dependencies. -6. Run `npm run dist` to build the theme assets. -That should be it! After Lando starts the first time, it should automatically trigger a composer install and create the -necessary local config files for the project. +That should be it! After Lando starts the first time, it will automatically create the necessary local config files for +the project. Additionally, each time Lando starts it will automatically run `composer install` and +`npm install && npm run build` to make sure all the project dependencies are installed and the theme assets have been +built. ## Documentation @@ -47,6 +47,7 @@ members to use and provides a number of helpful features. Below are a number of * `lando poweroff` - Completely shuts down all running Lando services. * `lando composer ` - Runs a composer command within the project container. * `lando wp ` - Runs a WP-CLI command within the project container. +* `lando npm ` - Runs an npm command within the node container. Useful for rebuilding the theme assets. * `lando db-export` - Exports the project database to a file in the project root. * `lando db-import ` - Imports a database file into the project database. This file must be located within the project directory. It can be either an archived (`.zip`) or unarchived SQL (`.sql`) file. @@ -56,6 +57,8 @@ members to use and provides a number of helpful features. Below are a number of * `lando destroy` - Destroys the local development environment. *WARNING:* This is a destructive action and will delete the existing data within the project database and completely remove all the project containers. It will not delete the project files on your local machine. +* `lando xdebug-on` - Enables Xdebug in the project container (xDebug is disabled by default). +* `lando xdebug-off` - Disables Xdebug in the project container (xDebug is disabled by default). For further documentation on Lando, please visit the [Lando Docs](https://docs.lando.dev/). @@ -67,7 +70,8 @@ day-to-day PHP development. You can learn more about the available scripts and h #### Updating WordPress -To adjust the installed version of WordPress, change the `--version=` value in the `install-wordpress` composer script. +To adjust the installed version of WordPress, run `composer config extra.wordpress-version ` and then +`composer install-wordpress`. ### NPM Packages, Scripts & Building Frontend Assets diff --git a/composer.json b/composer.json index 60baa76f..9bd8fac5 100644 --- a/composer.json +++ b/composer.json @@ -22,11 +22,8 @@ "prefer-stable": true, "scripts": { "create-auth": "op inject -i auth.template.json -o auth.json", - "copy-local-configs": [ - "@php -r \"file_exists('local-config.php') || copy('local-config-sample.php', 'local-config.php');\"", - "@php -r \"file_exists('local-config.json') || copy('local-config-sample.json', 'local-config.json');\"" - ], - "install-wordpress": "./vendor/bin/wp core download --version=6.7.1 --skip-content --force", + "create-local-configs": "php ./dev/scripts/create-local-configs.php", + "install-wordpress": "./dev/scripts/install-wordpress.sh", "phpcbf": "./vendor/bin/phpcbf -s", "phpcs": "./vendor/bin/phpcs", "phpstan": "./vendor/bin/phpstan analyse --memory-limit=-1", @@ -40,8 +37,8 @@ }, "scripts-descriptions": { "create-auth": "Create or update the auth.json file for Composer via 1Password CLI.", - "copy-local-configs": "Copies the local-config.php and local-config.json files.", - "install-wordpress": "Runs the wpcli command to download and install core WordPress. To change the WordPress version, update the --version value.", + "create-local-configs": "Creates local config files for the project.", + "install-wordpress": "Runs the WP CLI command to download and install WordPress. To change the WordPress version, run `composer config extra.wordpress-version `.", "phpcs": "Run PHPCS on the project.", "phpcbf": "Run PHPCBF on the project.", "phpstan": "Run PHPStan on the project.", @@ -123,6 +120,7 @@ "wpengine/advanced-custom-fields-pro": "6.3.11" }, "extra": { + "wordpress-version": "6.7.1", "installer-paths": { "wp-content/plugins/{$name}": [ "type:wordpress-plugin" diff --git a/dev/scripts/create-local-configs.php b/dev/scripts/create-local-configs.php new file mode 100644 index 00000000..232f194d --- /dev/null +++ b/dev/scripts/create-local-configs.php @@ -0,0 +1,59 @@ +appserver->via === 'apache' ? $lando_info->appserver : $lando_info->appserver_nginx; + +// Get the cert directory by removing the root `/lando` directory from Lando's internal cert path +$cert_directory = str_replace( '/lando', '', dirname( getenv( 'LANDO_SERVICE_CERT' ) ) ); + +// Create the config array +$config = [ + // Append Lando's cert directory to Lando's local config directory path + 'certPath' => getenv( 'LANDO_CONFIG_DIR' ) . $cert_directory, + // Set the cert name to the base name of Lando's hostname without the `.internal` extension + 'certName' => basename( $http_service_info->hostnames[0], '.internal' ), + // Set the host from Lando's service URL + 'host' => parse_url( $http_service_info->urls[0] )['host'], + 'protocol' => 'https' +]; + +// Write the config values to local-config.json +file_put_contents( 'local-config.json', json_encode( $config, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) ); + +exit; diff --git a/dev/scripts/install-wordpress.sh b/dev/scripts/install-wordpress.sh new file mode 100755 index 00000000..b5e20154 --- /dev/null +++ b/dev/scripts/install-wordpress.sh @@ -0,0 +1,14 @@ +#!/bin/bash +# Simple bash script to check the current version of WordPress and update it if necessary. + +CURRENT_VERSION=$(wp core version) +REQUESTED_VERSION=$(composer config extra.wordpress-version) + +if [ "$CURRENT_VERSION" == "$REQUESTED_VERSION" ]; then + echo "WordPress is already at version $REQUESTED_VERSION. Skipping install." + exit 0 +fi + +echo "Updating WordPress to version $REQUESTED_VERSION..." +wp core download --version=$REQUESTED_VERSION --skip-content --force +exit 0; diff --git a/docs/composer.md b/docs/composer.md index fee0997b..46f45321 100644 --- a/docs/composer.md +++ b/docs/composer.md @@ -13,19 +13,19 @@ day-to-day PHP development. * `composer create-auth` - Create or update the auth.json file for Composer via 1Password CLI. (Cannot be run within a Lando container.) -* `composer copy-local-configs` - Creates the `local-config.php` and `local-config.json` files from the respective - sample file. -* `composer install-wordpress` - Runs the WP CLI command to download and install WordPress core. To change the WordPress - version, update the `--version` value for this script. +* `composer create-local-configs` - Creates the `local-config.php` and `local-config.json` files as needed for the + project. +* `composer install-wordpress` - Runs the WP CLI command to download and install WordPress core. * `composer phpcs` - Run PHPCS on the project. * `composer phpcbf` - Run PHPCBF on the project. * `composer phpstan` - Run PHPStan on the project. -* `composer update-db` - Runs the WP CLI command to update the WordPress database. This is often required after a +* `composer update-db` - Runs the WP CLI command to update the WordPress database. This is often required after a WordPress version update. ## Updating WordPress -To adjust the installed version of WordPress, change the `--version=` value in the `install-wordpress` composer script. +To adjust the installed version of WordPress, run `composer config extra.wordpress-version ` and then +`composer install-wordpress`. ## Adding a Paid or Premium WordPress Plugin @@ -34,28 +34,29 @@ WordPress plugin directory and thus can't be installed from `https://wpackagist. installing such premium plugins: 1. Check to see if the plugin maker provides its own composer-based installation method. This is the best option. -Many providers including Advanced Custom Fields (ACF), Gravity Forms, and Yoast SEO provide composer-based installation -options. This project is already configured to use composer for both ACF and Gravity Forms. + Many providers including Advanced Custom Fields (ACF), Gravity Forms, and Yoast SEO provide composer-based + installation + options. This project is already configured to use composer for both ACF and Gravity Forms. 1. Check the plugin files into the repository directly. This is the simplest option but is not ideal for a number of -reasons, including licensing, security, and ease of management. + reasons, including licensing, security, and ease of management. ### Creating an auth.json File -If the plugin maker provides a composer-based installation method, you will likely create an `auth.json` file to -store the required credentials. This file is used by composer to install the plugin. This project provides an +If the plugin maker provides a composer-based installation method, you will likely create an `auth.json` file to +store the required credentials. This file is used by composer to install the plugin. This project provides an auth.json template file that the 1Password CLI can use to automatically generate the required `auth.json` file. See the [1Password CLI Docs](./1password-cli.md) for more information on this integration. -To manually create the `auth.json` file, copy the `auth.template.json` file to `auth.json` and update the placeholder +To manually create the `auth.json` file, copy the `auth.template.json` file to `auth.json` and update the placeholder values within the file with the required credentials. > [!IMPORTANT] -> The populated `auth.json` file should never be checked into the git repository as it contains +> The populated `auth.json` file should never be checked into the git repository as it contains > project-specific secrets (software license keys) which should never be available in source control. ## Platform Dependencies There are several PHP platform dependencies added as composer requirements. These dependencies include the required version of PHP as well as several PHP extensions required by WordPress (`ext-exif`, `ext-gd`, `ext-intl`, & `ext-json`). -These PHP extensions are installed within a [project's Dokku env](actions.md#dokku-deployment-workflows) and should not +These PHP extensions are installed within a [project's Dokku env](actions.md#dokku-deployment-workflows) and should not be removed unless or until Dokku is not utilized by the project. diff --git a/docs/npm.md b/docs/npm.md index fd847b9c..9887d9af 100644 --- a/docs/npm.md +++ b/docs/npm.md @@ -1,26 +1,31 @@ # NPM Packages, Scripts & Building Assets NPM is used to manage frontend dependencies. There are also a number of npm scripts defined to assist in day-to-day -development. These npm scripts are based on WordPress's [WP-Scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) package. See the documentation there for -further details. +development. These npm scripts are based on +WordPress's [WP-Scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) +package. See the documentation there for further details. ## Building Assets -To build the theme assets for your local development environment, the following steps are sufficient: +If you are not working with the theme assets locally, and you are using Lando, you can skip this section. Lando will +automatically build the assets for you each time the project is started. To manually build the theme assets for your +local development environment, use the following steps: 1. In the root of the project, run `nvm use` to confirm the correct version of node is in-use. 1. Run `npm install` to install the required dependencies. -1. Run `npm run dist` to build the production assets +1. Run `npm run build` to build the non-production assets. ## Using Browsersync for Local Dev -To handle live-reload for changes, this project utilizes Browsersync to watch for asset file changes and reload the -browser. In addition, Browsersync can be configured via a `local-config.json` file to proxy your local environment's -SSL configuration to allow live-reloading from a specific local project URL rather than localhost. To use Browsersync -for local development follow the steps below: +To handle live-reload for changes, this project utilizes Browsersync to watch for asset file changes and reload the +browser. In addition, Browsersync can be configured via a `local-config.json` file to proxy your local environment's +SSL configuration to allow live-reloading from a specific local project URL rather than localhost. + +Lando will automatically generate an proper local-config.json file the first time a project is started. If you are not +using Lando, you'll need to manually create this file using the steps below: 1. Duplicate the `local-config-sample.json` file into a git-ignored `local-config.json` and update the `certsPath`, -`certName` and `host` values to match your local dev set up. Examples are provided for Lando and LocalWP. + `certName` and `host` values to match your local dev set up. Examples are provided for Lando and LocalWP. 1. In the root of the project, run `nvm use` to confirm the correct version of node is in-use. 1. Run `npm install` to install the required dependencies. 1. Run `npm run dev` to start the webpack watch & browsersync tasks. @@ -33,7 +38,8 @@ for local development follow the steps below: * `npm run format` - Runs Prettier on all theme assets (css, scss, js, & json files). * `npm run lint` - Prettifies, lints (and fixes) theme & root assets (css, scss, js, & json files). * `npm run create-block` - Starts an interactive shell script to generate a new block per WordPress's - [Create Block script](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) and the theme config. + [Create Block script](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/) + and the theme config. Several scripts have sub-tasks that can be run individually. Reference `package.json` for details. Additionally, there are several scripts aliased directly from wp-scripts that may be useful: