{"_id":"@bdwm/bdwm-wp-env","_rev":"1-9598fc72b629307efcdc413adc126fbe","name":"@bdwm/bdwm-wp-env","dist-tags":{"latest":"1.6.0"},"versions":{"1.6.0":{"name":"@bdwm/bdwm-wp-env","version":"1.6.0","description":"A zero-config, self contained local WordPress environment for development and testing. Based on wp-env","author":{"name":"Jules Colle"},"license":"GPL-2.0-or-later","keywords":["wordpress","gutenberg","environment","docker"],"repository":{"type":"git","url":"git+https://github.com/pwkip/bdwm-wp-env.git","directory":"packages/env"},"directories":{"lib":"lib","test":"tests"},"main":"lib/env.js","bin":{"bdwm-wp-env":"bin/bdwm-wp-env"},"dependencies":{"chalk":"^4.0.0","copy-dir":"^1.3.0","docker-compose":"^0.22.2","extract-zip":"^1.6.7","got":"^10.7.0","inquirer":"^7.1.0","js-yaml":"^3.13.1","nodegit":"^0.26.2","ora":"^4.0.2","rimraf":"^3.0.2","terminal-link":"^2.0.0","yargs":"^14.0.0"},"publishConfig":{"access":"public"},"scripts":{"test":"echo \"Error: run tests from root\" && exit 1"},"gitHead":"4af7c69b05d3e6523eeddeaa70b361ef2c3e6bb2","bugs":{"url":"https://github.com/pwkip/bdwm-wp-env/issues"},"homepage":"https://github.com/pwkip/bdwm-wp-env#readme","_id":"@bdwm/bdwm-wp-env@1.6.0","_nodeVersion":"12.16.2","_npmVersion":"6.14.4","dist":{"integrity":"sha512-XPeawWQoz3iCmjU7sd9RvzR/ekIfqTlRG7teh5GJzs38B8KXALuEd81X4WSyAEGR9CNpuSP5eWdhsNZsInVdEw==","shasum":"6d59a18a6209a9b4cb28bf84fee98b3b69c2bd7e","tarball":"https://registry.npmjs.org/@bdwm/bdwm-wp-env/-/bdwm-wp-env-1.6.0.tgz","fileCount":30,"unpackedSize":124216,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfIzGmCRA9TVsSAnZWagAApSEP/3SuJx/HcsbpOETBAliZ\nC5uWro1FeJ7LhMRVgfcy1vQF5xDKUh90L96zRKlAOcNpQLLVrM9nJ9zxfyiN\npDZH5U/x0NJer9Y4hSbxlPRfYlMsaWJ4YDHw5kEMQgfxW0T0zEPOegsGCeHc\nrgm0wyOugc4RXZTuCqcVYBvzi5iOpkpKeW7eiuGohVZW72eKO0+1fZm52rB0\nKY/0cGEQLfnQ50Y3Q38LiaaCcxHK6IlsV+dcLnr2d1e+GsWSgYij/CtLyLdk\nvqMltBHkEZNJc4Td5N3lzq7gZdYC6lC6o4TY2XVV/ExsqeBZerUZ5y3JEhmr\ngZYTwo2dgIpxpYYbBi00ocLYD0P5jzbKEd+0J+dbitdyDJ4bRpBPNaA2MxDp\nYp+Yb1OqrjpYhAzKORTNuBsGvWq0T5qm1PVvaaL42ky9WQQCI3iadzag36T3\n//Nihme2al3Kc2uWp6EjREvc+T9j3r1deutEPVDS3/j+Idsz4vGbWuV8efHw\nybbmevrwNP6JqceJ+Qv0uMjzGsXYrSRtYElSZWU74KF0wYRAXwc60OaQV7kY\njBfTDy4qa6unSW2dSYOAbHEVZ17dUJLG60k8JB2Sh8McQxKA6iBbW+xcMf0g\nay1lyXPuLFmUcMrD18s1I4E4NNiLwmqNIJ0M//VrFU/01Lmsxl1f5nnr7zNs\niVFq\r\n=HXvM\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIA3RWaQqv96Bc7rTNJKpLh/AEZW7NlLBE59Iel95rE/CAiEAslA3XCzLuAPe6ER/jkiqoF8FkGgfXAXT7YhnlfdL5Og="}]},"maintainers":[{"name":"julescolle","email":"jules.colle@gmail.com"}],"_npmUser":{"name":"julescolle","email":"jules.colle@gmail.com"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/bdwm-wp-env_1.6.0_1596141989731_0.9001064110031454"},"_hasShrinkwrap":false}},"time":{"created":"2020-07-30T20:46:29.487Z","1.6.0":"2020-07-30T20:46:29.830Z","modified":"2022-04-04T18:04:04.369Z"},"maintainers":[{"name":"julescolle","email":"jules.colle@gmail.com"}],"description":"A zero-config, self contained local WordPress environment for development and testing. Based on wp-env","homepage":"https://github.com/pwkip/bdwm-wp-env#readme","keywords":["wordpress","gutenberg","environment","docker"],"repository":{"type":"git","url":"git+https://github.com/pwkip/bdwm-wp-env.git","directory":"packages/env"},"author":{"name":"Jules Colle"},"bugs":{"url":"https://github.com/pwkip/bdwm-wp-env/issues"},"license":"GPL-2.0-or-later","readme":"# `bdwm-wp-env`\n\n`bdwm-wp-env` lets you easily set up a local WordPress environment for building and testing plugins and themes. It's simple to install and requires no configuration.\n\n## Quick (tl;dr) instructions\n\nEnsure that Docker is running, then:\n\n```sh\n$ cd /path/to/a/wordpress/plugin\n$ npm -g i @bdwm/bdwm-wp-env\n$ bdwm-wp-env start\n```\n\nThe local environment will be available at http://localhost:8888 (Username: `admin`, Password: `password`).\n\n## Prerequisites\n\n`bdwm-wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows 10 Pro](https://docs.docker.com/docker-for-windows/install/), [all other versions of Windows](https://docs.docker.com/toolbox/toolbox_install_windows/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/v17.12/install/linux/docker-ce/ubuntu/#install-using-the-convenience-script).\n\nNode.js and NPM are required. The latest LTS version of Node.js is used to develop `bdwm-wp-env` and is recommended.\n\n## Installation\n\n### Installation as a global package\n\nAfter confirming that the prerequisites are installed, you can install `bdwm-wp-env` globally like so:\n\n```sh\n$ npm -g i @bdwm/bdwm-wp-env\n```\n\nYou're now ready to use `bdwm-wp-env`!\n\n### Installation as a local package\n\nIf your project already has a package.json, it's also possible to use `bdwm-wp-env` as a local package. First install `bdwm-wp-env` locally as a dev dependency:\n\n```sh\n$ npm i @bdwm/bdwm-wp-env --save-dev\n```\n\nThen modify your package.json and add an extra command to npm `scripts` (https://docs.npmjs.com/misc/scripts):\n\n```json\n\"scripts\": {\n\t\"bdwm-wp-env\": \"bdwm-wp-env\"\n}\n```\n\nWhen installing `bdwm-wp-env` in this way, all `bdwm-wp-env` commands detailed in these docs must be prefixed with `npm run`, for example:\n\n```sh\n$ npm run bdwm-wp-env start\n```\n\ninstead of:\n\n```sh\n$ bdwm-wp-env start\n```\n\n## Usage\n\n### Starting the environment\n\nFirst, ensure that Docker is running. You can do this by clicking on the Docker icon in the system tray or menu bar.\n\nThen, change to a directory that contains a WordPress plugin or theme:\n\n```sh\n$ cd ~/gutenberg\n```\n\nThen, start the local environment:\n\n```sh\n$ bdwm-wp-env start\n```\n\nFinally, navigate to http://localhost:8888 in your web browser to see WordPress running with the local WordPress plugin or theme running and activated. Default login credentials are username: `admin` password: `password`.\n\n### Stopping the environment\n\nTo stop the local environment:\n\n```sh\n$ bdwm-wp-env stop\n```\n\n## Troubleshooting common problems\n\nMany common problems can be fixed by running through the following troubleshooting steps in order:\n\n### 1. Check that `bdwm-wp-env` is running\n\nFirst, check that `bdwm-wp-env` is running. One way to do this is to have Docker print a table with the currently running containers:\n\n```sh\n$ docker ps\n```\n\nIn this table, by default, you should see three entries: `wordpress` with port 8888, `tests-wordpress` with port 8889 and `mariadb` with port 3306.\n\n### 2. Check the port number\n\nBy default `bdwm-wp-env` uses port 8888, meaning that the local environment will be available at http://localhost:8888.\n\nYou can configure the port that `bdwm-wp-env` uses so that it doesn't clash with another server by specifying the `WP_ENV_PORT` environment variable when starting `bdwm-wp-env`:\n\n```sh\n$ WP_ENV_PORT=3333 bdwm-wp-env start\n```\n\nRunning `docker ps` and inspecting the `PORTS` column allows you to determine which port `bdwm-wp-env` is currently using.\n\nYou may also specify the port numbers in your `.bdwm-wp-env.json` file, but the environment variables take precedent.\n\n### 3. Restart `bdwm-wp-env`\n\nRestarting `bdwm-wp-env` will restart the underlying Docker containers which can fix many issues.\n\nTo restart `bdwm-wp-env`:\n\n```sh\n$ bdwm-wp-env stop\n$ bdwm-wp-env start\n```\n\n### 4. Restart Docker\n\nRestarting Docker will restart the underlying Docker containers and volumes which can fix many issues.\n\nTo restart Docker:\n\n1. Click on the Docker icon in the system tray or menu bar.\n2. Select _Restart_.\n\nOnce restarted, start `bdwm-wp-env` again:\n\n```sh\n$ bdwm-wp-env start\n```\n\n### 5. Reset the database\n\nResetting the database which the local environment uses can fix many issues, especially when they are related to the WordPress installation.\n\nTo reset the database:\n\n**⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.**\n\n```sh\n$ bdwm-wp-env clean all\n$ bdwm-wp-env start\n```\n\n### 6. Nuke everything and start again 🔥\n\nWhen all else fails, you can use `bdwm-wp-env destroy` to forcibly remove all of the underlying Docker containers and volumes. This will allow you to start from scratch.\n\nTo nuke everything:\n\n**⚠️ WARNING: This will permanently delete any posts, pages, media, etc. in the local WordPress installation.**\n\n```sh\n$ bdwm-wp-env destroy\n$ bdwm-wp-env start\n```\n\n## Command reference\n\n`bdwm-wp-env` creates generated files in the `bdwm-wp-env` home directory. By default, this is `~/.bdwm-wp-env`. The exception is Linux, where files are placed at `~/bdwm-wp-env` [for compatibility with Snap Packages](https://github.com/WordPress/gutenberg/issues/20180#issuecomment-587046325). The `bdwm-wp-env` home directory contains a subdirectory for each project named `/$md5_of_project_path`. To change the `bdwm-wp-env` home directory, set the `WP_ENV_HOME` environment variable. For example, running `WP_ENV_HOME=\"something\" bdwm-wp-env start` will download the project files to the directory `./something/$md5_of_project_path` (relative to the current directory).\n\n### `bdwm-wp-env start`\n\nThe start command installs and initalizes the WordPress environment, which includes downloading any specified remote sources. By default, `bdwm-wp-env` will not update or re-configure the environment except when the configuration file changes. Tell `bdwm-wp-env` to update sources and apply the configuration options again with `bdwm-wp-env start --update`. This will not overrwrite any existing content.\n\n```sh\nbdwm-wp-env start\n\nStarts WordPress for development on port 8888 (override with WP_ENV_PORT) and\ntests on port 8889 (override with WP_ENV_TESTS_PORT). The current working\ndirectory must be a WordPress installation, a plugin, a theme, or contain a\n.bdwm-wp-env.json file. After first insall, use the '--update' flag to download updates\nto mapped sources and to re-apply WordPress configuration options.\n\nOptions:\n  --update   Download source updates and apply WordPress configuration.\n                                                      [boolean] [default: false]\n```\n\n### `bdwm-wp-env stop`\n\n```sh\nbdwm-wp-env stop\n\nStops running WordPress for development and tests and frees the ports.\n```\n\n### `bdwm-wp-env clean [environment]`\n\n```sh\nbdwm-wp-env clean [environment]\n\nCleans the WordPress databases.\n\nPositionals:\n  environment  Which environments' databases to clean.\n            [string] [choices: \"all\", \"development\", \"tests\"] [default: \"tests\"]\n```\n\n### `bdwm-wp-env run [container] [command]`\n\n```sh\nbdwm-wp-env run <container> [command..]\n\nRuns an arbitrary command in one of the underlying Docker containers. For\nexample, it can be useful for running wp cli commands. You can also use it to\nopen shell sessions like bash and the WordPress shell in the WordPress instance.\nFor example, `bdwm-wp-env run cli bash` will open bash in the development WordPress\ninstance.\n\nPositionals:\n  container  The container to run the command on.            [string] [required]\n  command    The command to run.                           [array] [default: []]\n\nOptions:\n  --help     Show help                                                 [boolean]\n  --version  Show version number                                       [boolean]\n  --debug    Enable debug output.                     [boolean] [default: false]\n```\n\nFor example:\n\n```sh\nbdwm-wp-env run cli wp user list\n⠏ Running `wp user list` in 'cli'.\n\nID      user_login      display_name    user_email      user_registered roles\n1       admin   admin   wordpress@example.com   2020-03-05 10:45:14     administrator\n\n✔ Ran `wp user list` in 'cli'. (in 2s 374ms)\n```\n\n```sh\nbdwm-wp-env run tests-cli wp shell\nℹ Starting 'wp shell' on the tests-cli container. Exit the WordPress shell with ctrl-c.\n\nStarting 31911d623e75f345e9ed328b9f48cff6_mysql_1 ... done\nStarting 31911d623e75f345e9ed328b9f48cff6_tests-wordpress_1 ... done\nwp> echo( 'hello world!' );\nhello world!\nwp> ^C\n✔ Ran `wp shell` in 'tests-cli'. (in 16s 400ms)\n```\n\n### `bdwm-wp-env destroy`\n\n```sh\nbdwm-wp-env destroy\n\nDestroy the WordPress environment. Deletes docker containers, volumes, and\nnetworks associated with the WordPress environment and removes local files.\n```\n\n### `bdwm-wp-env logs [environment]`\n\n```sh\nbdwm-wp-env logs\n\ndisplays PHP and Docker logs for given WordPress environment.\n\nPositionals:\n  environment  Which environment to display the logs from.\n      [string] [choices: \"development\", \"tests\", \"all\"] [default: \"development\"]\n\nOptions:\n  --help     Show help                                                 [boolean]\n  --version  Show version number                                       [boolean]\n  --debug    Enable debug output.                     [boolean] [default: false]\n  --watch    Watch for logs as they happen.            [boolean] [default: true]\n```\n\n## .bdwm-wp-env.json\n\nYou can customize the WordPress installation, plugins and themes that the development environment will use by specifying a `.bdwm-wp-env.json` file in the directory that you run `bdwm-wp-env` from.\n\n`.bdwm-wp-env.json` supports six fields for options applicable to both the tests and development instances.\n\n| Field        | Type           | Default                                | Description                                                                                                                |\n| ------------ | -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| `\"core\"`     | `string\\|null` | `null`                                 | The WordPress installation to use. If `null` is specified, `bdwm-wp-env` will use the latest production release of WordPress.   |\n| `\"plugins\"`  | `string[]`     | `[]`                                   | A list of plugins to install and activate in the environment.                                                              |\n| `\"themes\"`   | `string[]`     | `[]`                                   | A list of themes to install in the environment. The first theme in the list will be activated.                             |\n| `\"port\"`     | `integer`      | `8888` (`8889` for the tests instance) | The primary port number to use for the installation. You'll access the instance through the port: 'http://localhost:8888'. |\n| `\"config\"`   | `Object`       | See below.                             | Mapping of wp-config.php constants to their desired values.                                                                |\n| `\"mappings\"` | `Object`       | `\"{}\"`                                 | Mapping of WordPress directories to local directories to be mounted in the WordPress instance.                             |\n\n_Note: the port number environment variables (`WP_ENV_PORT` and `WP_ENV_TESTS_PORT`) take precedent over the .bdwm-wp-env.json values._\n\nSeveral types of strings can be passed into the `core`, `plugins`, `themes`, and `mappings` fields.\n\n| Type              | Format                        | Example(s)                                               |\n| ----------------- | ----------------------------- | -------------------------------------------------------- |\n| Relative path     | `.<path>\\|~<path>`            | `\"./a/directory\"`, `\"../a/directory\"`, `\"~/a/directory\"` |\n| Absolute path     | `/<path>\\|<letter>:\\<path>`   | `\"/a/directory\"`, `\"C:\\\\a\\\\directory\"`                   |\n| GitHub repository | `<owner>/<repo>[#<ref>]`      | `\"WordPress/WordPress\"`, `\"WordPress/gutenberg#master\"`  |\n| ZIP File          | `http[s]://<host>/<path>.zip` | `\"https://wordpress.org/wordpress-5.4-beta2.zip\"`        |\n\nRemote sources will be downloaded into a temporary directory located in `~/.bdwm-wp-env`.\n\nAdditionally, the key `env` is available to override any of the above options on an individual-environment basis. For example, take the following `.bdwm-wp-env.json` file:\n\n```json\n{\n\t\"plugins\": [ \".\" ],\n\t\"config\": {\n\t\t\"KEY_1\": true,\n\t\t\"KEY_2\": false\n\t},\n\t\"env\": {\n\t\t\"development\": {\n\t\t\t\"themes\": [ \"./one-theme\" ]\n\t\t},\n\t\t\"tests\": {\n\t\t\t\"config\": {\n\t\t\t\t\"KEY_1\": false\n\t\t\t},\n\t\t\t\"port\": 3000\n\t\t}\n\t}\n}\n```\n\nOn the development instance, `cwd` will be mapped as a plugin, `one-theme` will be mapped as a theme, KEY_1 will be set to true, and KEY_2 will be set to false. Also note that the default port, 8888, will be used as well.\n\nOn the tests instance, `cwd` is still mapped as a plugin, but no theme is mapped. Additionaly, while KEY_2 is still set to false, KEY_1 is overriden and set to false. 3000 overrides the default port as well.\n\nThis gives you a lot of power to change the options appliciable to each environment.\n\n## .bdwm-wp-env.override.json\n\nAny fields here will take precedence over .bdwm-wp-env.json. This file is useful when ignored from version control, to persist local development overrides. Note that options like `plugins` and `themes` are not merged. As a result, if you set `plugins` in your override file, this will override all of the plugins listed in the base-level config. The only keys which are merged are `config` and `mappings`. This means that you can set your own wp-config values without losing any of the default values.\n\n## Default wp-config values.\n\nOn the development instance, these wp-config values are defined by default:\n\n```\nWP_DEBUG: true,\nSCRIPT_DEBUG: true,\nWP_PHP_BINARY: 'php',\nWP_TESTS_EMAIL: 'admin@example.org',\nWP_TESTS_TITLE: 'Test Blog',\nWP_TESTS_DOMAIN: 'http://localhost',\nWP_SITEURL: 'http://localhost',\nWP_HOME: 'http://localhost',\n```\n\nOn the test instance, all of the above are still defined, but `WP_DEBUG` and `SCRIPT_DEBUG` are set to false.\n\nAdditionally, the values referencing a URL include the specified port for the given environment. So if you set `testsPort: 3000, port: 2000`, `WP_HOME` (for example) will be `http://localhost:3000` on the tests instance and `http://localhost:2000` on the development instance.\n\n### Examples\n\n#### Latest production WordPress + current directory as a plugin\n\nThis is useful for plugin development.\n\n```json\n{\n\t\"core\": null,\n\t\"plugins\": [ \".\" ]\n}\n```\n\n#### Latest development WordPress + current directory as a plugin\n\nThis is useful for plugin development when upstream Core changes need to be tested.\n\n```json\n{\n\t\"core\": \"WordPress/WordPress#master\",\n\t\"plugins\": [ \".\" ]\n}\n```\n\n#### Local `wordpress-develop` + current directory as a plugin\n\nThis is useful for working on plugins and WordPress Core at the same time.\n\n```json\n{\n\t\"core\": \"../wordpress-develop/build\",\n\t\"plugins\": [ \".\" ]\n}\n```\n\n#### A complete testing environment\n\nThis is useful for integration testing: that is, testing how old versions of WordPress and different combinations of plugins and themes impact each other.\n\n```json\n{\n\t\"core\": \"WordPress/WordPress#5.2.0\",\n\t\"plugins\": [ \"WordPress/wp-lazy-loading\", \"WordPress/classic-editor\" ],\n\t\"themes\": [ \"WordPress/theme-experiments\" ]\n}\n```\n\n#### Add mu-plugins and other mapped directories\n\nYou can add mu-plugins via the mapping config. The mapping config also allows you to mount a directory to any location in the wordpress install, so you could even mount a subdirectory. Note here that theme-1, will not be activated, despite being the \"first\" mapped theme.\n\n```json\n{\n\t\"plugins\": [ \".\" ],\n\t\"mappings\": {\n\t\t\"wp-content/mu-plugins\": \"./path/to/local/mu-plugins\",\n\t\t\"wp-content/themes\": \"./path/to/local/themes\",\n\t\t\"wp-content/themes/specific-theme\": \"./path/to/local/theme-1\"\n\t}\n}\n```\n\n#### Avoid activating plugins or themes on the instance\n\nSince all plugins in the `plugins` key are activated by default, you should use the `mappings` key to avoid this behavior. This might be helpful if you have a test plugin that should not be activated all the time. The same applies for a theme which should not be activated.\n\n```json\n{\n\t\"plugins\": [ \".\" ],\n\t\"mappings\": {\n\t\t\"wp-content/plugins/my-test-plugin\": \"./path/to/test/plugin\"\n\t}\n}\n```\n\n#### Map a plugin only in the tests environment\n\nIf you need a plugin active in one environment but not the other, you can use `env.<envName>` to set options specific to one environment. Here, we activate cwd and a test plugin on the tests instance. This plugin is not activated on any other instances.\n\n```json\n{\n\t\"plugins\": [ \".\" ],\n\t\"env\": {\n\t\t\"tests\": {\n\t\t\t\"plugins\": [ \".\", \"path/to/test/plugin\" ]\n\t\t}\n\t}\n}\n```\n\n#### Custom Port Numbers\n\nYou can tell `bdwm-wp-env` to use a custom port number so that your instance does not conflict with other `bdwm-wp-env` instances.\n\n```json\n{\n\t\"plugins\": [ \".\" ],\n\t\"port\": 4013,\n\t\"env\": {\n\t\t\"tests\": {\n\t\t\t\"port\": 4012\n\t\t}\n\t}\n}\n```\n\n<br/><br/><p align=\"center\"><img src=\"https://s.w.org/style/images/codeispoetry.png?1\" alt=\"Code is Poetry.\" /></p>\n","readmeFilename":"README.md"}