Add `wp-env` Post-Install Command #49996

ObliviousHarmony · 2023-04-21T17:41:45Z

What?

This pull request will execute a user-defined postInstall command on wp-env start and, optionally, wp-env clean.

Why?

By allowing users to run their own command after installation, they will be able to define setup scripts and the like that perform additional processing on the environment post-setup.

How?

The user can set a postInstall configuration in .wp-env.json that will be executed after configuring WordPress. They can also use a WP_ENV_POST_INSTALL environment variable to override any configured scripts.

Testing Instructions

Create (or edit) a .wp-env.override.json to include:

{
  "postInstall": "echo \"Test\""
}

Run npm run env -- start --update and verify that Test is printed twice.
Run npm run env -- start --update --no-post-install and verify that Test is not printed.
Run WP_ENV_POST_INSTALL="ls -la" npm run env -- start --update and verify that the Gutenberg directory is printed.
Run npm run env -- clean and verify that Test is not printed.
Run npm run env -- clean --post-install and verify that Test is printed.
Change .wp-env.override.json:

{
    "postInstall": "echo \"$WP_ENV_POST_INSTALL_ENVIRONMENT:$WP_ENV_POST_INSTALL_CONTEXT:$WP_ENV_POST_INSTALL_DEBUG\""
}

Run npm run env -- start --update and verify that both development:start:false and tests:start:false are printed.
Run npm run env -- start --update --debug and verify that both development:start:true and tests:start:true are printed.
Change .wp-env.override.json:

{
  "postInstall": "echo 'Test' > /dev/null"
}

Run npm run env -- start --update and verify that there is no output.
Change .wp-env.override.json:

{
  "postInstall": "ech"
}

Run npm run env -- start --update and verify that there is an error.

While at the moment this doesn't do anything, it does, however, exist. You can also override it with the `WP_ENV_POST_INSTALL` environment variable.

This commit adds support for executing the post-install script when the user runs `wp-env start` and it re-configured WordPress.

This adds an optional flag for executing the post-install commands when the environment is cleaned.

noahtallen

Very nice! I have two broader thoughts:

IMO, post install could be run by default on wp-env clean.
I'm not convinced about having post-install run twice for each environment.

For the latter, I feel like most people aren't going to need a separate script. For example, if my goal is to add data to the test database, I might run wp-env run tests-cli "wp ...". And if I want to add the same for the main database, I'd do wp-env run cli "wp ...". (E.g. I'm still writing that out twice.)

So if I would just write a single post-install script, I wouldn't expect it to run multiple times like this, at least by default.

(A side note is whether there could be race conditions using execSync on the same file at the same)

Happy to be convinced otherwise, but I'm just not sure the ergonomics are that much different having it run twice.

packages/env/CHANGELOG.md

noahtallen · 2023-04-21T19:46:39Z

packages/env/README.md

+  --help          Show help                                            [boolean]
+  --version       Show version number                                  [boolean]
+  --debug         Enable debug output.                [boolean] [default: false]
+  --post-install  Execute the environments' configured post-install command if


I think this should be the default for clean. My reasoning is that we say post install gets run when WordPress is configured, which is also done during the clean step. 🤔 Plus, if someone has post-install configured, a common use case is making sure data exists in the database

I suppose that makes sense. This is an opt-in feature, so, you can operate under that expectation the first time you use it without concern.

packages/env/README.md

noahtallen · 2023-04-21T19:54:05Z

packages/env/lib/cli.js

@@ -43,6 +43,10 @@ const withSpinner =
 					// Error is a validation error. That means the user did something wrong.
 					spinner.fail( error.message );
 					process.exit( 1 );
+				} else if ( error instanceof env.PostInstallError ) {


Nit: could be handled in the same case as instance of env.ValidationError

That's true, I don't see a good reason not to do it.

packages/env/lib/wordpress.js

noahtallen · 2023-04-21T20:02:51Z

packages/env/README.md

@@ -668,6 +680,26 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin
 }
 ```

+#### Post-Install Command


I think it'd be nice to document pointing to your own script! (node or shell)

This might be a little superfluous since you can run arbitrary commands, but, more examples can't hurt!

True! I feel like it could be easy to miss if you aren't super familiar with it

Co-authored-by: Noah Allen <[email protected]>

ObliviousHarmony · 2023-04-21T21:35:34Z

Thanks for the feedback @noahtallen!

I'm not convinced about having post-install run twice for each environment.

To be fair, you're only running it twice if you use the top-level configuration option:

If you wanted to use a single script and have some special handling, you can use the WP_ENV_POST_INSTALL_ENVIRONMENT environment variable in your script pretty easily. They can also use the same variable to run the same commands on each environment if they want. Lots of choices!
You can alternatively use the environment-specific configuration to run it in a single environment. No need for any other complication.

As it stands, Gutenberg's own tests environment contains a significant number of plugins that the development environment does not. It feels aligned with that principle to have a separate postInstall file that addresses any concerns E2E tests may have.

I like the flexibility that this provides when treated like the rest of the configuration options. It would feel strange if this was the only .wp-env.json option that behaved this way. Would this be acceptable if it was documented and we switched out the examples for an environment-specific one against tests? That would push people towards their most-likely use-case while still providing that flexibility without more complication around options and commands.

A side note is whether there could be race conditions using execSync on the same file at the same

Depending on what the script is doing, this may be true. I would wager that most scripts aren't going to be doing anything contentious, since at worst, they would be doing the same thing. Given that the script is supposed to be written with multiple executions in mind, there shouldn't be issues.

noahtallen · 2023-04-21T22:09:47Z

Good points. What stands out to me with this option is that it's not actually unique to the environment, which is very different from the other options. For example, when I set the port or WordPress version, those are by definition unique to that environment. It can't possibly change something in the other environment. But with this script, you can do whatever you want! To me, that makes it less of an environment-specific thing, and more of a wp-env-tooling-specific thing. (E.g. "execute this code at this part of the lifecycle")

To me, having an environment level option implies that it will only do something to that environment. But you could easily write your development script to update tests, and your tests script to update development. (Not that that's really a problem -- but to me, that's why it feels different from the other options)

It just makes me wonder what having the environment-level option actually enables users to do:

# Pseodocode for script executed twice:
cmd="wp foo"
if ( WP_ENV_POST_INSTALL_ENVIRONMENT == 'tests' ) {
  npx wp-env tests-cli "$cmd"
} else {
  npx wp-env cli "$cmd"
}

# Script executed once:
cmd="wp foo"
npx wp-env tests-cli "$cmd"
npx wp-env cli "$cmd"

noahtallen · 2023-04-21T22:11:49Z

I think I see the value of specifying different scripts (especially for inline values) in the environment configs. But I still don't love that putting it in the root configuration executes it twice. I think folks won't expect that

ObliviousHarmony · 2023-04-21T23:16:42Z

My biggest concern here is consistency @noahtallen, but, I think you might be right. When you set a top-level "core", for example, it is singular conceptually because it's set once (but in both containers). It's possible that, on that principle, it might make sense to only run it a single time.

I acquiesce :)

ObliviousHarmony · 2023-04-22T01:50:46Z

I took a look at implementing this as a top-level option only and it seems like there's going to need to be a refactor of the config parsing and validating to accommodate. Once that's done I'll revisit this!

ObliviousHarmony · 2023-04-28T23:10:37Z

Now that the config refactor has landed I'm closing this in favor of #50196. This PR is not really actionable anymore, and given the change in scope (from environment-specific to root), it makes sense to just close it.

ObliviousHarmony added 6 commits April 21, 2023 08:17

Added postInstall Configuration Option

8b924fb

While at the moment this doesn't do anything, it does, however, exist. You can also override it with the `WP_ENV_POST_INSTALL` environment variable.

Execute postInstall On start

9ea741a

This commit adds support for executing the post-install script when the user runs `wp-env start` and it re-configured WordPress.

Execute postInstall On clean

6c86623

This adds an optional flag for executing the post-install commands when the environment is cleaned.

Documented postInstall Functionality

ce02810

Added Post-Install Debug Variable

9234d22

Prettified Post-Install Output/Errors

b9dff63

ObliviousHarmony requested a review from noahtallen as a code owner April 21, 2023 17:41

noahtallen assigned noahtallen and unassigned noahtallen Apr 21, 2023

noahtallen added [Tool] Env /packages/env [Type] Feature New feature to highlight in changelogs. labels Apr 21, 2023

noahtallen reviewed Apr 21, 2023

View reviewed changes

ObliviousHarmony and others added 4 commits April 21, 2023 14:17

Update packages/env/CHANGELOG.md

a8bd9aa

Co-authored-by: Noah Allen <[email protected]>

Update packages/env/README.md

925d788

Co-authored-by: Noah Allen <[email protected]>

Update packages/env/README.md

8a2121f

Co-authored-by: Noah Allen <[email protected]>

Update packages/env/lib/wordpress.js

1b12628

Co-authored-by: Noah Allen <[email protected]>

noahtallen mentioned this pull request Apr 21, 2023

Add post-install script to wp-env #43827

Closed

This was referenced Apr 22, 2023

Connect to wp-env DB host from external tooling #24772

Closed

wp-env: Add a config option for content import #29776

Open

ObliviousHarmony mentioned this pull request Apr 25, 2023

Refactored wp-env Config Parsing #50071

Merged

ObliviousHarmony closed this Apr 28, 2023

ObliviousHarmony deleted the try/env-post-install branch April 28, 2023 23:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `wp-env` Post-Install Command #49996

Add `wp-env` Post-Install Command #49996

ObliviousHarmony commented Apr 21, 2023

noahtallen left a comment

noahtallen Apr 21, 2023

ObliviousHarmony Apr 21, 2023

noahtallen Apr 21, 2023

ObliviousHarmony Apr 21, 2023

noahtallen Apr 21, 2023

ObliviousHarmony Apr 21, 2023

noahtallen Apr 21, 2023

ObliviousHarmony commented Apr 21, 2023 •

edited

Loading

noahtallen commented Apr 21, 2023

noahtallen commented Apr 21, 2023

ObliviousHarmony commented Apr 21, 2023

ObliviousHarmony commented Apr 22, 2023

ObliviousHarmony commented Apr 28, 2023

Add wp-env Post-Install Command #49996

Add wp-env Post-Install Command #49996

Conversation

ObliviousHarmony commented Apr 21, 2023

What?

Why?

How?

Testing Instructions

noahtallen left a comment

Choose a reason for hiding this comment

noahtallen Apr 21, 2023

Choose a reason for hiding this comment

ObliviousHarmony Apr 21, 2023

Choose a reason for hiding this comment

noahtallen Apr 21, 2023

Choose a reason for hiding this comment

ObliviousHarmony Apr 21, 2023

Choose a reason for hiding this comment

noahtallen Apr 21, 2023

Choose a reason for hiding this comment

ObliviousHarmony Apr 21, 2023

Choose a reason for hiding this comment

noahtallen Apr 21, 2023

Choose a reason for hiding this comment

ObliviousHarmony commented Apr 21, 2023 • edited Loading

noahtallen commented Apr 21, 2023

noahtallen commented Apr 21, 2023

ObliviousHarmony commented Apr 21, 2023

ObliviousHarmony commented Apr 22, 2023

ObliviousHarmony commented Apr 28, 2023

Add `wp-env` Post-Install Command #49996

Add `wp-env` Post-Install Command #49996

ObliviousHarmony commented Apr 21, 2023 •

edited

Loading