# Easy WordPress Bootstrap

Spin up a complete WordPress development site on macOS with Laravel Herd and DBngin (or any MySQL/MariaDB server) in one pass. For the Windows/PowerShell workflow, see [`windows/README-Windows.md`](windows/README-Windows.md).

## What You Get

- Project directory under your Herd workspace with sanitized slug and host mapping.
- MySQL database + user created after verifying the supplied root credentials.
- Latest WordPress core, `wp-config.php` with fresh salts, permalinks set to `/%postname%/`, and Home/News pages.
- Plugin install/activation from `plugins.json`, resolved from the project folder first then the repository default.
- Starter theme cloned with shallow history, `.git` stripped, repo reinitialized, remote optionally set, and Composer/NPM build steps run when available.
- `.htaccess` seeded when Apache rewrites are missing, `bootstrap-summary.txt` written, and plugin install logs stored at `wp-content/plugin-bootstrap.log`.
- Automatic WP-CLI detection with a bundled `wp-cli.phar` fallback (`WP_CLI_PHAR` env/config override).

## Prerequisites

- macOS with [Laravel Herd](https://herd.laravel.com/) configured (default workspace `~/Herd`).
- MySQL or MariaDB available locally (DBngin recommended) and the `mysql` client in `PATH`.
- CLI tools: `php`, `git`, `curl`, `openssl`, `composer`, `npm`, `mysql`, and optionally `jq` for pretty plugin output.
- Either `wp` in `PATH` or a downloadable `wp-cli.phar` placed beside the script (or in `windows/wp-cli.phar`).

## Quick Start (Interactive)

1. Copy the sample configuration (one time):

   ```bash
   cp wp-bootstraprc.example ~/.wp-bootstraprc
   ```

2. Review `plugins.json` (optional override per project; place your own copy in the project root if needed).
3. Make the script executable, then run it and answer prompts:

   ```bash
   chmod +x wp-bootstrap.sh
   ./wp-bootstrap.sh
   ```

When the bootstrap completes, open the URL printed in the summary and check `bootstrap-summary.txt` under the project root.

## Non-Interactive Usage

Pass values via flags (help output lists every option):

```bash
./wp-bootstrap.sh \
  --project-name "Client Site" \
  --admin-user admin \
  --admin-email dev@example.com \
  --theme-starter-repo git@github.com:vendor/theme.git \
  --herd-workspace "$HOME/Herd" \
  --local-tld test \
  --mysql-host 127.0.0.1 \
  --mysql-port 3306 \
  --mysql-root-user root \
  --mysql-root-pass secret
```

Any value omitted from the CLI falls back to `~/.wp-bootstraprc` or the script defaults. Supply `--help` to print the full usage guide.

## Configuration with `.wp-bootstraprc`

The script sources `~/.wp-bootstraprc` on start. Key entries include:

- `HERD_WORKSPACE`, `LOCAL_TLD`
- `MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_ROOT_USER`, `MYSQL_ROOT_PASS`
- `DEFAULT_ADMIN_USER`, `DEFAULT_ADMIN_EMAIL`
- `THEME_STARTER_REPO`, `DEFAULT_THEME_REMOTE_ORIGIN`
- `WP_CLI_PHAR` to point at a custom `wp-cli.phar`

Environment variables exported before running the script take precedence over both CLI flags and rc defaults when they share the same name.

## Plugin Manifest

`plugins.json` accepts WordPress.org slugs or zip URLs. The script first looks for `./plugins.json` inside the target project (useful for site-specific manifests) and falls back to the repository version when absent. Premium/private zips can point to signed URLs or local files; make sure the executing user has access.

## Logs & Files Created

- `bootstrap-summary.txt` – high-level run output, stored in the project root.
- `wp-content/plugin-bootstrap.log` – detailed plugin installation results.
- `.htaccess` – created only when missing, populated with standard WordPress rewrite rules.

## Troubleshooting

- **WP-CLI missing** – install `wp` globally, or download `wp-cli.phar` into the script directory and set `WP_CLI_PHAR=/path/to/wp-cli.phar`.
- **MySQL connection failures** – confirm DBngin (or your server) is running, credentials match your `.wp-bootstraprc`, and the root user can create databases/users.
- **Composer/NPM not installed** – the script skips dependency installation but leaves a warning in the output; install the tooling and rerun if theme assets are required.
- **Permissions** – ensure the Herd workspace and MySQL socket/port are accessible to your user account.

---
DIY-first policy: keep `plugins.json` minimal; add heavier stacks only when a project truly needs them.