# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A **Roots Bedrock** WordPress install (WP 6.1.1, PHP 7.4) for PatrimOffice, with a
**Roots Sage 10** starter theme (`web/app/themes/patrimoffice`) using **Acorn** (Laravel
container + Blade), **bud.js** for asset compilation, and **Tailwind CSS**. It is a
separate, newer codebase from the legacy Symfony API / Vue.js apps described in the
parent `web/CLAUDE.md` — those do **not** apply here. Development runs under DDEV.

The working branch `feature/migrate-roots` is migrating the site onto the Roots stack.

## Architecture

Bedrock restructures WordPress so the web root is `web/`, not the project root:

- `web/wp/` — WordPress core (managed by Composer via `roots/wordpress`; never edit).
- `web/app/` — the `wp-content` equivalent: `themes/`, `plugins/`, `mu-plugins/`.
- `config/application.php` — replaces most of `wp-config.php`; reads from `.env`.
- `config/environments/{development,staging}.php` — per-`WP_ENV` config overrides.
- `.env` — secrets and environment (`WP_ENV`, `WP_HOME`, `DB_*`, salts). Not committed.

Plugins and themes are installed **via Composer**, not the WP admin. `composer.json`
maps `wpackagist-plugin/*` and `wpackagist-theme/*` (from wpackagist.org) into
`web/app/` through `installer-paths`. Add a plugin by requiring its wpackagist package,
not by uploading through wp-admin.

### Theme (`web/app/themes/patrimoffice`)

Sage 10 — Blade views compiled by Acorn, PHP namespaced `App\` (PSR-4 → `app/`).

- `app/setup.php` — `after_setup_theme`, asset enqueue (`Roots\bundle('app')`), menus,
  sidebars, Soil features.
- `app/filters.php` — WordPress filter hooks.
- `app/Providers/ThemeServiceProvider.php` — Acorn service provider (registered in
  `composer.json` `extra.acorn.providers`).
- `app/View/Composers/` — Blade view composers (e.g. `App.php`, `Post.php`) that bind
  data to views. `app/View/Components/` — Blade components.
- `resources/views/` — Blade templates (`*.blade.php`); `resources/scripts/`,
  `resources/styles/` — JS/CSS entrypoints; `resources/images/`, `resources/fonts/`.
- `theme.json` is **generated by bud on every build** from `bud.config.js`
  (`.wpjson.settings(...)` + Tailwind tokens). Edit `bud.config.js` / `tailwind.config.cjs`,
  not `theme.json` directly — manual edits are overwritten.

## Commands

All PHP/WP commands run inside DDEV (`ddev start` first). Site: https://patrimoffice-wordpress.ddev.site

```bash
# Project root (Bedrock)
ddev start
ddev composer install                 # installs core, plugins, themes into web/
ddev wp <args>                         # WP-CLI (wp-cli.yml sets path=web/wp)
composer test                          # runs phpcs (PSR-2, Roots ruleset)
vendor/bin/phpcs                       # lint PHP (config in phpcs.xml)
```

```bash
# Theme: web/app/themes/patrimoffice (Node >=16, see .nvmrc — Node 16)
yarn dev                               # bud dev server + HMR, proxies the DDEV site on :3000
yarn build                             # production build → resources compiled to public/
composer lint                          # phpcs --standard=PSR12 app
yarn translate                         # regenerate .pot and update .po files
```

There is no PHP unit-test suite; `composer test` is lint only. Both `yarn.lock` and
`package-lock.json` exist in the theme — this repo uses **yarn** (matches Sage upstream);
prefer `yarn` to keep the lockfile consistent.

## Conventions & gotchas

- **PHP style is PSR-2** at the Bedrock root (`phpcs.xml`) and **PSR-12** inside the theme
  (`composer lint`). Run the relevant linter before considering PHP work done.
- Bedrock excludes `web/wp` and `web/app/themes/twentytwentythree/` from phpcs; don't lint
  or edit core or the bundled default theme.
- The theme has been rebranded from the Sage starter to `patrimoffice`: text domain is
  `patrimoffice` (use it in all `__()`/`_x()` calls), `setPublicPath` points at
  `/app/themes/patrimoffice/public/`, and `package.json` `name` / the `translate` scripts
  use `patrimoffice`. Note `add_theme_support('sage')` in `functions.php` is the Acorn boot
  signal — leave it as `sage`.
- DDEV here pins **PHP 7.4** and **MariaDB 11.8**; the WordPress requirement is `php >=7.4`.
- `WP_SITEURL` is `${WP_HOME}/wp` — WordPress lives in a subdirectory, a Bedrock default.
  Don't "fix" the `/wp` in URLs.
- mu-plugins (`bedrock-autoloader`, `bedrock-disallow-indexing`) are Composer-managed; the
  autoloader lets you drop conventional plugins in `web/app/mu-plugins/`.