From cbcbec15888a40f3105f3f66fd1560f63a9a7d8a Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Thu, 20 Jun 2024 08:45:34 -0600 Subject: [PATCH] [CMSP-386] update WordPress (Composer Managed) docs (#9031) * add that wp core can be managed as a dependency * change complete to review users don't need to complete all the steps. they should be aware of the docs and the configuration * add link to roots bedrock docs * add contributor this might not display anymore * add missing closing parenthesis * update docs about application.php * fix typo * add wordpress core location * additional composer best practices inc updating * remove known issue with lando and rephrase issue with subdirectory * change the link for reporting issues back to the pantheon-systems repo * update community slack info * add the link for "alternate implementations" * fix prop * add note that WPCM is not supported by Build Tools * explain what the WordPress Composer repository is * remove whitespace * update link * use code formatting * change the title and add contrib * point to wpcm for forking not wordpress-project * remove warning to not use in production * note that only upstream maintainers should not edit composer.json * link to upstream management repo * update upstream name * upstream-config/ to upstream-configuration/ * include composer upstream-require * spacing * Update source/content/guides/wordpress-composer/01-introduction.md --------- Co-authored-by: Phil Tyler --- .../wordpress-composer/01-introduction.md | 15 +++---- .../02-wordpress-composer-managed.md | 37 +++++++++++++---- ...03-create-wp-site-composer-ci-auto-test.md | 19 ++++----- .../wordpress-composer/06-wordpress-ic.md | 41 ++++++------------- 4 files changed, 55 insertions(+), 57 deletions(-) diff --git a/source/content/guides/wordpress-composer/01-introduction.md b/source/content/guides/wordpress-composer/01-introduction.md index a3ae41f62e..5e8ce60e68 100644 --- a/source/content/guides/wordpress-composer/01-introduction.md +++ b/source/content/guides/wordpress-composer/01-introduction.md @@ -10,12 +10,12 @@ audience: [development] product: [--] integration: [--] tags: [wordpress] -contributors: [whitneymeredith] +contributors: [whitneymeredith,jazzsequence] showtoc: true permalink: docs/guides/wordpress-composer --- -[Composer](https://getcomposer.org/) is a widely-used PHP dependency and package manager that provides a simplified method to manage the external (non-core) code used by a WordPress site. +[Composer](https://getcomposer.org/) is a widely-used PHP dependency and package manager that provides a simplified method to manage packages (plugins, themes and -- with the [WordPress (Composer Managed) upstream](/wordpress-composer-managed), WordPress core itself) used by a WordPress site. At the most basic level, Composer requires: @@ -25,15 +25,13 @@ At the most basic level, Composer requires: There are different cases for using Composer to manage dependencies on a WordPress site, including: - Manage dependencies for themes and plugins you’re currently developing - - Manage the themes and plugins currently used on the site - +- Manage WordPress core updates - Total site dependency management, including custom code - ## First Steps -Complete the steps below before using this guide to create or manage updates on your Pantheon Composer-managed WordPress site. +Review the steps below before using this guide to create or manage updates on your Pantheon Composer-managed WordPress site. @@ -47,10 +45,7 @@ Please reach out to our [Professional Services](https://pantheon.io/professional 1. Review [Managing Core as Project Dependency](/guides/composer#managing-core-as-a-project-dependency). -1. Review [Custom Upstream Workflow](/guides/composer#custom-upstream-workflow). - ## More Resources - [Composer Fundamentals and WebOps Workflows](/guides/composer) - -- [Convert a Standard Drupal Site to a Composer-Managed Site](/guides/composer-convert) \ No newline at end of file +- [Roots Bedrock](https://roots.io/bedrock/) \ No newline at end of file diff --git a/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md b/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md index 123fe36579..99f8a21aa2 100644 --- a/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md +++ b/source/content/guides/wordpress-composer/02-wordpress-composer-managed.md @@ -19,7 +19,7 @@ anchorid: wordpress-composer-managed -The WordPress Composer Managed upstream is available for [Early Access](/oss-support-levels#early-access) participants. Features for WordPress Composer Managed are in active development. Pantheon's development team is rolling out new functionality often while this product is in Early Access. Visit [our community Slack](https://pantheon-community.slack.com/) if you don't already have an account) to connect with other Pantheon users also using the upstream (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/). Please review Pantheon's [Software Evaluation Licensing Terms](https://legal.pantheon.io/#contract-hkqlbwpxo) for more information about access to our software. +The WordPress Composer Managed upstream is available for [Early Access](/oss-support-levels#early-access) participants. Features for WordPress Composer Managed are in active development. Pantheon's development team is rolling out new functionality often while this product is in Early Access. Visit [our community Slack](https://pantheon-community.slack.com/) if you don't already have an account) to connect with other Pantheon users also using the upstream (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/)). Please review Pantheon's [Software Evaluation Licensing Terms](https://legal.pantheon.io/#contract-hkqlbwpxo) for more information about access to our software. @@ -30,7 +30,6 @@ WordPress does not natively support [Composer](https://getcomposer.org/), howeve ## Requirements - [PHP version](/guides/php/php-versions#verify-current-php-versions) 8.0 or greater - - [Composer](https://getcomposer.org/) ## Create Your Site @@ -57,7 +56,7 @@ Bedrock makes use of an `.env` file to store environment variables. Pantheon tak ### WordPress Config -The `wp-config.php` file is located in the `web` directory. As with other WordPress sites on Pantheon, much of this is taken care of for you in `wp-config-pantheon.php`. Application-level configuration takes place in `config/application.php`. This can be referenced as a guide to understand how the constants are set up and how the `.env` files work, but modifying this file may result in merge conflicts and is not recommended. Any configuration changes should be made to your `wp-config.php` file directly. +The `wp-config.php` file is located in the `web` directory. As with other WordPress sites on Pantheon, much of this is taken care of for you in `wp-config-pantheon.php`. Application-level configuration takes place in `config/application.php` while platform-specific updates are made in `config/application.pantheon.php`. This means that `config/application.php` can be modified for your WordPress configuration settings without fear of conflicts with the upstream. Any configuration changes should be made to your `config/appliction.php` **not** your `wp-config.php` file directly. You can learn more about WordPress configuration with Bedrock in the [Bedrock Configuration docs](https://docs.roots.io/bedrock/master/configuration/). @@ -65,9 +64,10 @@ You can learn more about WordPress configuration with Bedrock in the [Bedrock Co Bedrock installs WordPress as a required package so updates can be managed by Composer. As such, the contents of the `wp-content` directory have been moved outside the WordPress codebase so changes can be made safely to files within those directories without conflicts. Learn more about [Bedrock's folder structure here](https://docs.roots.io/bedrock/master/folder-structure/). -* Theme are installed into `web/app/themes/` +* Themes are installed into `web/app/themes/` * Plugins are installed into `web/app/plugins` * Must-use plugins are installed into `web/app/mu-plugins` +* WordPress core is installed into `web/wp` * The WordPress admin dashboard is available at `https://example.com/wp/wp-admin/` ### Using Composer to manage plugins and themes @@ -102,19 +102,38 @@ composer require wpackagist-theme/twentytwentytwo composer require wpackagist-plugin/advanced-custom-fields ``` +#### Check first +It's generally a good idea when using either Packagist or WPackagist to check the repository before `require`ing the package. If you search Packagist for a WordPress plugin or theme and don't see it, you can be sure that if it exists in the WordPress plugin or theme repository, it will be available on WPackagist. Checking WPackagist for the package can be beneficial if you want to check what versions are available. + +### Updating dependencies + +To update all Composer dependencies, run: + +```bash{promptUser: user} +composer update +``` + +This will update all Composer-managed packages according to the version constraints in your `composer.json` file. For more information on Composer version constraints, see the [Composer documentation](https://getcomposer.org/doc/articles/versions.md). + +To update a specific package, run: + +```bash{promptUser: user} +composer update vendor/package +``` + +Replace `vendor/package` with the package name you want to update. This will update only the named package to the latest version that matches the version constraints in your `composer.json` file. + ## Known Issues -- The WordPress Composer Managed upstream is not yet compatible with WordPress Multisite with subdirectories. -- There is a bug with WordPress Multisite with subdomains when running the site locally with Lando and running WP-CLI commands. There is a [gist](https://gist.github.com/jazzsequence/8b68c35aa7668b77776fc1b9df216304) to fix this, which will eventually be incorporated into the upstream. +- There is currently a known issue with WordPress Composer Managed not supporting WordPress Multisite with subdirectories. [Alternative implementations](/wordpress-ic) of WordPress with Composer may be used for this use case. ## Report an Issue -Create an [issue in the Github repo](https://github.com/pantheon-upstreams/wordpress-composer-managed/issues) for the team to review and address if you discover an issue with the WordPress Composer Managed upstream. +Create an [issue in the Github repo](https://github.com/pantheon-systems/wordpress-composer-managed/issues) for the team to review and address if you discover an issue with the WordPress Composer Managed upstream. -Visit [#wordpress in our community Slack](https://pantheon-community.slack.com/archives/CT8MC5Y0K) (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/) if you don't already have an account) to learn how you can enroll in our Early Access program. +Visit [our community Slack](https://pantheon-community.slack.com/archives/CT8MC5Y0K) (you can sign up for the [Pantheon Slack channel here](https://slackin.pantheon.io/) if you don't already have an account). ## More Resources - [Bedrock Documentation](https://roots.io/bedrock/) - - [Install and Configure Lando for WordPress](/guides/local-development/lando-wordpress) diff --git a/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md b/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md index fcf1d927c2..fcb778aad3 100644 --- a/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md +++ b/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md @@ -10,7 +10,7 @@ audience: [development] product: [--] integration: [--] tags: [wordpress] -contributors: [whitneymeredith] +contributors: [whitneymeredith,jazzsequence] showtoc: true permalink: docs/guides/wordpress-composer/create-wp-site-composer-ci-auto-test --- @@ -19,16 +19,14 @@ This section provides steps to create a new Pantheon WordPress site that will us -Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. This upstream is currently in EA. +Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. This upstream is currently in EA and **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream. ## Requirements - [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin) - - You must use the [Build Tools 3.x release](https://github.com/pantheon-systems/terminus-build-tools-plugin/tree/3.x) if you are using **Terminus 3**. - - [PHP version](/guides/php/php-versions#verify-current-php-versions) 7.2 or greater ## Create Your Site @@ -49,27 +47,28 @@ Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpre ``` - This site will be based on the Pantheon-maintained [WordPress Composer repository](https://github.com/pantheon-systems/example-wordpress-composer). + - This repository has a similar structure to the [Bedrock-based WordPress (Composer Managed) upstream](https://github.com/pantheon-upstreams/wordpress-composer-managed) but does not use Bedrock. This repository will be deprecated in the future in favor of integrating the Bedrock-based upstream into Build Tools. 1. Review the sections below for important information about your site, including an explanation of the directory structure, Continuous Integration functions, and essential configuration actions. ## Review Important Directories and Update File Paths -### /web Directory +### `/web` Directory Your site is stored and served from the `/web` subdirectory located next to the `pantheon.yml` file. You must store your website in this subdirectory for a Composer-based workflow. Placing your website in the subdirectory also allows you to store tests, scripts, and other files related to your project in your repo without affecting your web document root. It also provides additional security by preventing web access to files outside of the document root through Pantheon. Your files may still be accessible from your version control project if it is public. See the [`pantheon.yml` documentation](/pantheon-yml#nested-docroot) for details. 1. Verify that your website is stored in the `/web` subdirectory. -### /web/wp Directory +### `/web/wp` Directory -Your directories and files within the `/web` directory are stored in different locations compared to a default WordPress installation. [WordPress allows installing WordPress core in its own directory](https://wordpress.org/support/article/giving-wordpress-its-own-directory/), which is necessary when installing WordPress with Composer. The overall layout of directories in the repo is similar to [Bedrock](https://github.com/roots/bedrock). +Your directories and files within the `/web` directory are stored in different locations compared to a default WordPress installation. [WordPress allows installing WordPress core in its own directory](https://developer.wordpress.org/advanced-administration/server/wordpress-in-directory/), which is necessary when installing WordPress with Composer. The overall layout of directories in the repo is similar to [Bedrock](https://github.com/roots/bedrock). 1. Verify that the `WP_SITEURL` file is in the `/web/wp` directory to allow WordPress core functions to work correctly. 1. Review the `/web/wp-config.php` file for key settings and move other files to the to the `/web/wp` directory as necessary. -### composer.json File +### `composer.json` File This project uses Composer to manage third-party PHP dependencies. Some files, such as `web/wp`, may not be visible in the repository. This is because WordPress core and its plugins are installed via Composer and ignored in the `.gitignore` file. @@ -101,7 +100,7 @@ The scripts are organized into subdirectories according to their function: - `.ci/build/php` installs PHP dependencies with Composer. -### Build Scripts .ci/deploy +### Build Scripts `.ci/deploy` All scripts stored in the `.ci/deploy` directory facilitate code deployment to Pantheon. @@ -109,7 +108,7 @@ All scripts stored in the `.ci/deploy` directory facilitate code deployment to P - `.ci/deploy/pantheon/dev-multidev` deploys the built artifact to either the Pantheon Dev or a Multidev environment, depending on the Git branch. -## Automated Test Scripts .ci/tests +## Automated Test Scripts `.ci/tests` The `.ci/tests` scripts run automated tests. You can add or remove scripts depending on your testing needs. diff --git a/source/content/guides/wordpress-composer/06-wordpress-ic.md b/source/content/guides/wordpress-composer/06-wordpress-ic.md index 833a6b7e53..08d4885780 100644 --- a/source/content/guides/wordpress-composer/06-wordpress-ic.md +++ b/source/content/guides/wordpress-composer/06-wordpress-ic.md @@ -1,7 +1,7 @@ --- title: WordPress with Composer on Pantheon -subtitle: Create a Composer-managed WordPress Site with Integrated Composer -description: Learn how to use Integrated Composer with WordPress on Pantheon. +subtitle: Create a Composer-managed WordPress Site with Integrated Composer and Custom Upstreams +description: Learn how to use Integrated Composer and Custom Upstreams with WordPress on Pantheon. contenttype: [guide] innav: [false] categories: [dependencies] @@ -10,7 +10,7 @@ audience: [development] product: [--] integration: [--] tags: [wordpress] -contributors: [whitneymeredith] +contributors: [whitneymeredith,jazzsequence] showtoc: true permalink: docs/guides/wordpress-composer/wordpress-ic --- @@ -19,21 +19,21 @@ permalink: docs/guides/wordpress-composer/wordpress-ic ## WordPress with Integrated Composer on Pantheon -Pantheon maintains a [Composer-enabled WordPress Upstream](https://github.com/pantheon-upstreams/wordpress-project) repository. This is the recommended starting point for forking new upstreams that work with Pantheon's Integrated Composer build process. +Pantheon maintains a [Composer-enabled WordPress Upstream](https://github.com/pantheon-upstreams/wordpress-composer-managed) repository. This is the recommended starting point for forking new upstreams that work with Pantheon's Integrated Composer build process. -This repository is still under active development, and you should not create permanent/production sites from it. There is no guarantee of backwards compatibility. +This repository is still under active development. As with all custom upstreams, you are responsible for maintaining your custom upstream and making sure it is up-to-date with the source upstream. There is no guarantee of backwards compatibility. Pantheon upstreams influence the Composer packages that are included in downstream sites by including two `composer.json` files in this repository: -- The root `/composer.json` file is owned by the downstream site. Upstream maintainers should avoid editing this file. This allows the downstream site maintainer to adjust the `/composer.json` file without creating potential conflicts when merging upstream updates. +- The root `/composer.json` file is owned by the downstream site. Maintainers of _custom upstreams_ should avoid editing this file. This allows the downstream site maintainer to adjust the `/composer.json` file without creating potential conflicts when merging upstream updates. -- The `upstream-config/composer.json` file is owned by the upstream maintainer. It is included by the root `composer.json` file, and allows upstreams to add or remove packages from downstream sites. Changes are automatically incorporated into the downstream site whenever upstream updates are applied. +- The `upstream-configuration/composer.json` file is owned by the upstream maintainer. It is included by the root `composer.json` file, and allows upstreams to add or remove packages from downstream sites. Changes are automatically incorporated into the downstream site whenever upstream updates are applied. Pantheon has developed a tool to help you work with upstream configuration called [upstream-management](https://packagist.org/packages/pantheon-systems/upstream-management), which you can install by using `composer require pantheon-systems/upstream-management:^1`. ## Create Your WordPress Integrated Composer Site Follow the steps in this section to create a new WordPress site using Integrated Composer and Upstream. -1. Fork the [Pantheon-maintained WordPress Upstream repository](https://github.com/pantheon-upstreams/wordpress-project). +1. Fork the [Pantheon-maintained WordPress Upstream repository](https://github.com/pantheon-upstreams/wordpress-composer-managed). 1. [Connect your repository](/guides/custom-upstream/create-custom-upstream#connect-repository-to-pantheon) to Pantheon. @@ -41,55 +41,40 @@ Follow the steps in this section to create a new WordPress site using Integrated ## Add and Remove Packages -1. Use `composer require`in the `upstream-config` directory to edit the upstream `composer.json` file. - +1. Use `composer require`in the `upstream-configuration` directory (or `composer upstream-require` if using `upstream-management`) to edit the upstream `composer.json` file. - The repository template places a theme in the upstream `composer.json` file. This works well for downstream sites that all use the same theme. You should remove themes from the upstream `composer.json` file if you do not intend to use the upstream to lock downstream sites into a particular theme. You cannot remove installed packages from downstream sites if the packages were included from the upstream site. ## Maintain Your Integrated Composer Fork There are some special considerations to keep in mind if you intend to make modifications to your upstream based on this repository. -1. Increase the version number listed in the `upstream-config/composer.json` file each time you make edits. - +1. Increase the version number listed in the `upstream-configuration/composer.json` file each time you make edits. - Composer checks the contents of the root `/composer.json` file for changes that should be pushed to your upstream configuration. -1. Verify your changes to the `upstream-config/composer.json` file by running `composer install` or `composer update` in the `upstream-config` directory. - +1. Verify your changes to the `upstream-configuration/composer.json` file by running `composer install` or `composer update` in the `upstream-configuration` directory. - Be careful not to rely on ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md). ## Manage Your WordPress Integrated Composer Site 1. Review the [Integrated Composer Guide](/guides/integrated-composer) for information on how to: - - [Manage Core as a Project Dependency](/guides/composer#managing-core-as-a-project-dependency) - - [Serve Sites from the Web Subdirectory](/nested-docroot) - - [Add a Dependency to an Individual Site](/guides/integrated-composer#add-a-dependency-to-an-individual-site) - - [Add a Package from a Private Repository](/guides/integrated-composer/private-repo-package) - - [Apply One-click Updates](/guides/integrated-composer/one-click-updates) - - [Add dependencies to your Upstream](/guides/integrated-composer/ic-upstreams) - + 1. Review the [Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) documentation to learn how to: - - [Test and Release Pantheon Core Updates](/guides/custom-upstream/maintain-custom-upstream#test-and-release-pantheon-core-updates) - - [Automatically Resolve Conflicts from the Command Line](/guides/custom-upstream/maintain-custom-upstream#automatically-resolve-from-the-command-line) - - [Tips and Tricks for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream#delete-custom-upstream) - - [Delete a Custom Upstream](/guides/custom-upstream/maintain-custom-upstream#delete-custom-upstream) 1. Review the [Pantheon YAML Configuration Files](/pantheon-yml) documentation to learn about: - - [Custom Upstream Configurations](/pantheon-yml#custom-upstream-configurations) - ## More Resources - [Best Practices for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) - - [Composer Fundamentals and WebOps Workflows](/guides/composer) +- [Create a Composer-managed WordPress Site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed)