Skip to content

Commit dea770d

Browse files
sirrealsirreal
committed
More readme simplification
1 parent 097a657 commit dea770d

1 file changed

Lines changed: 41 additions & 131 deletions

File tree

‎tools/local-env/README.md‎

Lines changed: 41 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -1,157 +1,67 @@
11
# envlite
22

3-
A zero-daemon local environment for `wordpress-develop`. Brings a clean
4-
checkout to a state where:
3+
A zero-daemon local environment for `wordpress-develop`. Runs WordPress
4+
on SQLite via PHP's built-in server. No MySQL, no Docker, no MAMP.
5+
Unrelated to the `npm run env:*` Docker stack that shares this
6+
directory.
57

6-
- `php tools/local-env/envlite.php serve` serves WordPress against a
7-
file-backed SQLite database, and
8-
- `./vendor/bin/phpunit --group html-api` runs green on host PHP.
8+
## Quickstart
99

10-
No system MySQL, no Docker, no MAMP. Unrelated to the `npm run env:*`
11-
Docker stack that shares this directory.
12-
13-
---
14-
15-
## Requirements
16-
17-
envlite checks these at startup; missing requirements abort early.
18-
19-
- PHP ≥ 7.4 with extensions: `pdo_sqlite`, `sqlite3`, `openssl`,
20-
`simplexml`, `zip`. Unix also requires `pcntl`.
21-
- Node ≥ 20.10, npm ≥ 10.2.3 (matching `package.json` `engines`).
22-
- Composer ≥ 2.
23-
24-
On Ubuntu/Debian, the SQLite/SimpleXML/Zip extensions are typically split
25-
out: `apt install php-sqlite3 php-xml php-zip`. Homebrew's `php` and most
26-
distro PHP builds include them by default.
27-
28-
The first `init` needs network access. Subsequent runs are
29-
offline-friendly.
30-
31-
## Quick start
32-
33-
Run from the repo root:
10+
From the repo root:
3411

3512
```sh
36-
php tools/local-env/envlite.php init # one-shot setup
37-
php tools/local-env/envlite.php serve # foreground dev server
13+
php tools/local-env/envlite.php up
3814
```
3915

40-
`init` is idempotent — safe to re-run. For an all-in-one:
16+
That sets up the environment and starts the dev server in the
17+
foreground. Open the URL it prints; log in at `/wp-login.php` with
18+
`admin` / `password`. Ctrl-C shuts it down.
4119

42-
```sh
43-
php tools/local-env/envlite.php up # init, then serve
44-
```
20+
The first run needs network access. Subsequent runs are offline. Re-run
21+
`up` any time — envlite **never drops tables**, so your local content
22+
survives.
4523

46-
To confirm setup, in one terminal:
24+
## Requirements
4725

48-
```sh
49-
php tools/local-env/envlite.php serve
50-
```
26+
- PHP ≥ 7.4 with `pdo_sqlite`, `sqlite3`, `openssl`, `simplexml`, `zip`.
27+
Unix also requires `pcntl`.
28+
- Node ≥ 20.10, npm ≥ 10.2.3.
29+
- Composer ≥ 2.
30+
31+
Ubuntu/Debian extensions are usually split out:
32+
`apt install php-sqlite3 php-xml php-zip`. Homebrew's `php` bundles
33+
them.
5134

52-
…and in another:
35+
## Other commands
5336

5437
```sh
55-
./vendor/bin/phpunit --group html-api # ~5 s, ~1365 tests
56-
curl -sI "http://127.0.0.1:$(cat .envlite/port)/"
38+
php tools/local-env/envlite.php init # setup only, no server
39+
php tools/local-env/envlite.php serve # server only (after init)
40+
php tools/local-env/envlite.php clean # remove envlite-created files
5741
```
5842

59-
A green phpunit + a 2xx (not a 3xx redirect to `/wp-admin/install.php`)
60-
means the environment is ready. Log in at `/wp-login.php` with `admin` /
61-
`password`.
62-
63-
## Subcommands
64-
65-
| Subcommand | Behavior |
66-
|---|---|
67-
| `init` | Set up the environment. Idempotent. |
68-
| `up` | `init`, then `serve` in the foreground. |
69-
| `serve` | Launch `php -S` on the cached port. Foreground; Ctrl-C shuts down. |
70-
| `clean` | Remove envlite's files after a single confirmation prompt. Does not touch `node_modules/`, `vendor/`, build artifacts, or anything envlite didn't create. |
71-
| `help` (or no args, `-h`, `--help`) | Print usage. |
72-
73-
## Flags
74-
75-
- `--force` (global) — answer `y` to every prompt envlite would
76-
otherwise raise this invocation. Required for non-interactive use
77-
(CI, scripts) and for `clean` without a prompt. You won't need it on
78-
a normal first run.
79-
- `init [--port=N] [--no-build]`
80-
- `--port=N` picks a specific port (1–65535) and caches it. envlite
81-
still bind-probes; aborts if N is taken.
82-
- `--no-build` skips `npm run build:dev`. Use only when you know your
83-
changes don't affect build outputs.
84-
- `up` accepts the same `--port` / `--no-build` as `init`.
85-
- `serve` takes no flags. The cached port is the source of truth — to
86-
change it, run `init --port=N`.
87-
88-
## Re-runs and your data
89-
90-
`init` is safe to re-run on a half-configured repo. envlite **never
91-
drops tables** — local posts, pages, uploads, and uninstalled plugins
92-
under `src/wp-content/` survive any number of re-`init`s. If envlite
93-
would touch a file you've modified, it prompts first; `--force`
94-
answers yes.
95-
96-
`clean` removes only the files envlite created, after a single
97-
confirmation prompt. The live SQLite DB
98-
(`src/wp-content/database/.ht.sqlite`) is included in that prompt
99-
because it may hold your work. To wipe everything else (`node_modules/`,
100-
`vendor/`, build artifacts), use `git clean -fdx`.
101-
102-
## State directory
103-
104-
`.envlite/` at the repo root holds envlite's state. It's gitignored
105-
upstream; you don't normally need to touch it.
106-
107-
| File | Purpose |
108-
|---|---|
109-
| `.envlite/port` | The site port. Auto-picked from 8100–8899 the first time, then reused. |
110-
| `.envlite/manifest` | Internal — tracks files envlite owns. Don't hand-edit. |
111-
112-
## Exit codes
113-
114-
| Code | Meaning |
115-
|---|---|
116-
| 0 | Success. |
117-
| 1 | Setup failed. The cause is on stderr. |
118-
| 2 | Unknown subcommand or invalid argument. |
119-
| 3 | Environment doesn't satisfy requirements (see above). |
120-
| 5 | A prompt was declined, or non-interactive context without `--force`. |
43+
`init` and `up` accept `--port=N` (1–65535) and `--no-build` (skip
44+
`npm run build:dev`). The chosen port is cached and reused. Pass
45+
`--force` to skip prompts in non-interactive contexts.
12146

122-
All diagnostic output goes to stderr, prefixed `envlite: …` or
123-
`envlite <subcommand>: …`.
47+
`./vendor/bin/phpunit --group html-api` runs the green-bar test contract
48+
(~5 s, ~1365 tests). Other groups may surface deprecations on newer PHP.
12449

12550
## Use `127.0.0.1`, not `localhost`
12651

127-
envlite binds, redirects, and cookies on the literal IPv4. `php -S` is
128-
IPv4-only, but `localhost` resolves to `::1` first on modern
129-
macOS/Linux — a browser hitting `http://localhost:<port>/` can get
130-
`ECONNREFUSED` before any IPv4 fallback. Use `127.0.0.1` everywhere or
131-
admin login will break on cookie-domain mismatch.
52+
envlite binds IPv4 only. `localhost` resolves to `::1` first on modern
53+
macOS/Linux, so a browser hitting `http://localhost:<port>/` can get
54+
`ECONNREFUSED`. Use `127.0.0.1` and admin cookies will work too.
13255

13356
## Troubleshooting
13457

13558
| Symptom | Fix |
13659
|---|---|
137-
| `not in a wordpress-develop checkout` | `cd` to the repo root and re-run. |
138-
| `extension X not loaded` | Install it. Ubuntu/Debian: `apt install php-sqlite3 php-xml php-zip`. Homebrew's `php` already bundles them. |
60+
| `not in a wordpress-develop checkout` | `cd` to the repo root. |
61+
| `extension X not loaded` | Install it. Ubuntu/Debian: `apt install php-sqlite3 php-xml php-zip`. |
13962
| `<tool> below minimum` | Upgrade node/npm/composer. |
140-
| `SHA256 mismatch on plugin zip` | Retry once. If persistent, the pinned SQLite drop-in needs a deliberate update — file an issue. |
141-
| Corrupt-DB error after an interrupted run | Delete `src/wp-content/database/.ht.sqlite` and re-run `init`. |
142-
| phpunit error `ABSPATH constant ... non-existent path` | You ran `init --no-build` on a fresh checkout. Re-run `init` without `--no-build`. |
143-
| phpunit fails with deprecation-as-exception in a non-`html-api` group | Only `--group html-api` is the green-bar contract; other groups may surface deprecations on newer PHP. Per-group fix, not envlite's contract. |
144-
| `failed to bind 127.0.0.1:<port>` | Another process holds the port. `lsof -nP -iTCP:<port> -sTCP:LISTEN` to find it; kill it, or run `init --port=N` to relocate. |
145-
| Browser hangs / `ECONNREFUSED` on `http://localhost:<port>/` | IPv6 resolution won. Use `http://127.0.0.1:<port>/`. |
146-
147-
## What envlite does not do
148-
149-
- Run anything in the background. `serve` is foreground; Ctrl-C is the
150-
shutdown.
151-
- Install or upgrade global tools, or modify `PATH`, `COMPOSER_HOME`, or
152-
your shell profile.
153-
- Manage `node_modules/`, `vendor/`, or build artifacts.
154-
- Auto-update the pinned SQLite drop-in.
155-
- Configure HTTPS, a reverse proxy, or any production-shaped stack.
156-
- Manage worktrees. envlite operates on whatever directory it's invoked
157-
in.
63+
| `SHA256 mismatch on plugin zip` | Retry once; if persistent, the pinned SQLite drop-in needs an update — file an issue. |
64+
| `failed to bind 127.0.0.1:<port>` | Another process holds the port. `lsof -nP -iTCP:<port> -sTCP:LISTEN`; kill the holder, or `init --port=N` to relocate. |
65+
| Browser hangs / `ECONNREFUSED` on `localhost` | Use `http://127.0.0.1:<port>/`. |
66+
| phpunit `ABSPATH constant ... non-existent path` | You ran with `--no-build` on a fresh checkout. Re-run without it. |
67+
| Corrupt-DB error after an interrupted run | Delete `src/wp-content/database/.ht.sqlite` and re-run. |

0 commit comments

Comments
 (0)