Skip to content

Commit f11a6c0

Browse files
fellyphfellyph
authored
[Docs] Adding data persistence information (#2798)
This pull request adds new documentation to clarify how data persistence works and where the SQLite database is stored when using the Playground CLI. This helps developers understand how to ensure their data is saved between sessions, especially when working with plugins or themes. Documentation improvements: * Added a new section explaining the default locations for WordPress files and the SQLite database when using Playground CLI, including details on how mounting different directories affects database persistence.
1 parent 1943f03 commit f11a6c0

File tree

3 files changed

+634
-2
lines changed

3 files changed

+634
-2
lines changed

‎packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,75 @@ npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/
8888
On Windows, the path format `/host/path:/vfs/path` can cause issues. To resolve this, use the flags `--mount-dir` and `--mount-dir-before-install`. These flags let you specify host and virtual file system paths in an alternative format`"/host/path"` `"/vfs/path"`.
8989
:::
9090

91+
### Understanding Data Persistence and SQLite Location
92+
93+
By default, Playground CLI stores WordPress files and the SQLite database in **temporary directories on your operating system**:
94+
95+
```
96+
<OS-TEMP-DIR>/playground-<random-id>/
97+
├── wordpress/ # WordPress installation
98+
├── internal/ # Playground runtime config
99+
└── tmp/ # Temporary PHP files
100+
```
101+
102+
**Finding Your Temp Directory:**
103+
104+
The actual location depends on your OS (these are examples or common possibilities):
105+
106+
- **macOS/Linux**: May be under `/tmp/` or `/private/var/folders/` (varies by system)
107+
- **Windows**: `C:\Users\<username>\AppData\Local\Temp\`
108+
109+
To see the exact temp directory path being used, run the CLI with the `--verbosity=debug` flag:
110+
111+
```bash
112+
npx @wp-playground/cli@latest server --verbosity=debug
113+
```
114+
115+
This will output something like:
116+
117+
```
118+
Native temp dir for VFS root:
119+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC
120+
Mount before WP install: /home ->
121+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/home
122+
Mount before WP install: /tmp ->
123+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/tmp
124+
Mount before WP install: /wordpress ->
125+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/wordpress
126+
```
127+
128+
**Where is the SQLite Database Stored?**
129+
130+
The database location depends on what you mount:
131+
132+
- **Auto-mounting wp-content or full WordPress**:
133+
134+
- Database: `<your-local-project>/wp-content/database/.ht.sqlite`
135+
- ✅ **Persisted locally** in your project folder
136+
137+
- **Auto-mounting plugin/theme only**:
138+
139+
- Database: `<OS-TEMP-DIR>/playground-<id>/wordpress/wp-content/database/.ht.sqlite`
140+
- ⚠️ **Lost when server stops** (temp directories are cleaned up)
141+
142+
- **Custom mounts**: Database location follows your mount configuration
143+
144+
**Automatic Cleanup:**
145+
Playground CLI automatically removes temp directories that are:
146+
147+
- Older than 2 days
148+
- No longer associated with a running process
149+
150+
**Recommendation:** To persist both your code and database when developing plugins or themes, mount the entire `wp-content` directory instead of just the plugin/theme folder.
151+
152+
**Example: Mounting wp-content for persistence**
153+
154+
```bash
155+
# Mount your entire wp-content directory
156+
cd my-wordpress-project
157+
npx @wp-playground/cli@latest server --mount=./wp-content:/wordpress/wp-content
158+
```
159+
91160
## Command and Arguments
92161

93162
Playground CLI is simple, configurable, and unopinionated. You can set it up according

‎packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/developers/05-local-development/04-wp-playground-cli.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
---
2+
title: Playground CLI
3+
slug: /developers/local-development/wp-playground-cli
4+
---
5+
6+
# Playground CLI
7+
8+
[@wp-playground/cli](https://www.npmjs.com/package/@wp-playground/cli) es una herramienta de línea de comandos que simplifica el flujo de desarrollo y pruebas de WordPress.
9+
Playground CLI soporta el montaje automático de un directorio con un plugin, tema o instalación de WordPress. Pero si necesitas flexibilidad, el CLI soporta comandos de montaje para personalizar tu entorno local.
10+
11+
**Características principales:**
12+
13+
- **Configuración Rápida**: Configura un entorno WordPress local en segundos.
14+
- **Flexibilidad**: Permite la configuración para adaptarse a diferentes escenarios.
15+
- **Entorno Simple**: Sin configuración extra, solo una versión compatible de Node, y estás listo para usarlo.
16+
17+
## Requisitos
18+
19+
El Playground CLI requiere Node.js 20.18 o superior, que es la versión recomendada de Soporte a Largo Plazo (LTS). Puedes descargarlo desde el [sitio web de Node.js](https://nodejs.org/en/download).
20+
21+
## Inicio Rápido
22+
23+
Para ejecutar el Playground CLI, abre una línea de comandos y usa el siguiente comando:
24+
25+
```bash
26+
npx @wp-playground/cli@latest server
27+
```
28+
29+
![Playground CLI en Acción](@site/static/img/developers/npx-wp-playground-server.gif)
30+
31+
Con el comando anterior, solo obtienes una instancia fresca de WordPress para probar. La mayoría de los desarrolladores querrán probar su propio trabajo. Para probar un plugin o un tema, navega a la carpeta de tu proyecto y ejecuta el CLI con la bandera `--auto-mount`:
32+
33+
```bash
34+
cd my-plugin-or-theme-directory
35+
npx @wp-playground/cli@latest server --auto-mount
36+
```
37+
38+
### Elegir una Versión de WordPress y PHP
39+
40+
Por defecto, el CLI carga la última versión estable de WordPress y PHP 8.3 debido a su rendimiento mejorado. Para especificar tus versiones preferidas, puedes usar las banderas `--wp=<version>` y `--php=<version>`:
41+
42+
```bash
43+
npx @wp-playground/cli@latest server --wp=6.8 --php=8.3
44+
```
45+
46+
### Cargar Blueprints
47+
48+
Una forma de llevar tu experiencia de desarrollo con Playground CLI al siguiente nivel es integrar con [Blueprints](/blueprints/getting-started/). Para aquellos que no estén familiarizados con esta tecnología, permite a los desarrolladores configurar el estado inicial para sus instancias de WordPress Playground.
49+
50+
Usando la bandera `--blueprint=<blueprint-address>`, los desarrolladores pueden ejecutar un Playground con un estado inicial personalizado. Usaremos el ejemplo a continuación para hacer esto.
51+
52+
**(my-blueprint.json)**
53+
54+
```bash
55+
{
56+
"landingPage": "/wp-admin/options-general.php?page=akismet-key-config",
57+
"login": true,
58+
"plugins": [
59+
"hello-dolly",
60+
"https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
61+
]
62+
}
63+
```
64+
65+
Comando CLI cargando un blueprint:
66+
67+
```bash
68+
npx @wp-playground/cli@latest server --blueprint=my-blueprint.json
69+
```
70+
71+
### Montar carpetas manualmente
72+
73+
Algunos proyectos tienen una estructura específica que requiere una configuración personalizada; por ejemplo, tu repositorio contiene todos los archivos en la carpeta `/wp-content/`. Entonces en este escenario, puedes especificar al Playground CLI que montará tu proyecto desde esa carpeta usando la bandera `--mount`.
74+
75+
```bash
76+
npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY
77+
```
78+
79+
### Montar antes de la instalación de WordPress
80+
81+
Considera montar tus archivos de proyecto de WordPress antes de que comience la instalación de WordPress. Este enfoque es beneficioso si quieres sobrescribir el proceso de arranque de Playground, ya que puede ayudar a conectar Playground con `WP-CLI`. La bandera `--mount-before-install` soporta este proceso.
82+
83+
```bash
84+
npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/
85+
```
86+
87+
:::info
88+
En Windows, el formato de ruta `/host/path:/vfs/path` puede causar problemas. Para resolver esto, usa las banderas `--mount-dir` y `--mount-dir-before-install`. Estas banderas te permiten especificar rutas del host y del sistema de archivos virtual en un formato alternativo `"/host/path"` `"/vfs/path"`.
89+
:::
90+
91+
### Entender la Persistencia de Datos y Ubicación de SQLite
92+
93+
Por defecto, Playground CLI almacena archivos de WordPress y la base de datos SQLite en **directorios temporales en tu sistema operativo**:
94+
95+
```
96+
<OS-TEMP-DIR>/playground-<random-id>/
97+
├── wordpress/ # Instalación WordPress
98+
├── internal/ # Configuración del runtime de Playground
99+
└── tmp/ # Archivos temporales PHP
100+
```
101+
102+
**Encontrar tu Directorio Temporal:**
103+
104+
La ubicación real depende de tu SO (estos son ejemplos o posibilidades comunes):
105+
106+
- **macOS/Linux**: Puede estar bajo `/tmp/` o `/private/var/folders/` (varía según el sistema)
107+
- **Windows**: `C:\Users\<username>\AppData\Local\Temp\`
108+
109+
Para ver la ruta exacta del directorio temporal que se está usando, ejecuta el CLI con la bandera `--verbosity=debug`:
110+
111+
```bash
112+
npx @wp-playground/cli@latest server --verbosity=debug
113+
```
114+
115+
Esto mostrará algo como:
116+
117+
```
118+
Native temp dir for VFS root:
119+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC
120+
Mount before WP install: /home ->
121+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/home
122+
Mount before WP install: /tmp ->
123+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/tmp
124+
Mount before WP install: /wordpress ->
125+
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/wordpress
126+
```
127+
128+
**¿Dónde se Almacena la Base de Datos SQLite?**
129+
130+
La ubicación de la base de datos depende de lo que montes:
131+
132+
- **Montaje automático de wp-content o WordPress completo**:
133+
134+
- Base de datos: `<tu-proyecto-local>/wp-content/database/.ht.sqlite`
135+
- ✅ **Persistido localmente** en la carpeta de tu proyecto
136+
137+
- **Montaje automático solo de plugin/tema**:
138+
139+
- Base de datos: `<OS-TEMP-DIR>/playground-<id>/wordpress/wp-content/database/.ht.sqlite`
140+
- ⚠️ **Perdido cuando el servidor se detiene** (los directorios temporales se limpian)
141+
142+
- **Montajes personalizados**: La ubicación de la base de datos sigue tu configuración de montaje
143+
144+
**Limpieza Automática:**
145+
Playground CLI elimina automáticamente los directorios temporales que son:
146+
147+
- Más antiguos de 2 días
148+
- Ya no están asociados con un proceso en ejecución
149+
150+
**Recomendación:** Para persistir tanto tu código como la base de datos al desarrollar plugins o temas, monta el directorio `wp-content` completo en lugar de solo la carpeta del plugin/tema.
151+
152+
**Ejemplo: Montar wp-content para persistencia**
153+
154+
```bash
155+
# Monta tu directorio wp-content completo
156+
cd my-wordpress-project
157+
npx @wp-playground/cli@latest server --mount=./wp-content:/wordpress/wp-content
158+
```
159+
160+
## Comandos y Argumentos
161+
162+
Playground CLI es simple, configurable y sin opiniones. Puedes configurarlo de acuerdo
163+
a tu configuración única de WordPress. Con el Playground CLI, puedes usar los siguientes comandos de nivel superior:
164+
165+
- **`server`**: (Por defecto) Inicia un servidor WordPress local.
166+
- **`run-blueprint`**: Ejecuta un archivo Blueprint sin iniciar un servidor web.
167+
- **`build-snapshot`**: Construye una instantánea ZIP de un sitio WordPress basado en un Blueprint.
168+
169+
El comando `server` soporta los siguientes argumentos opcionales:
170+
171+
- `--port=<port>`: El número de puerto para que el servidor escuche. Por defecto es 9400.
172+
- `--outfile`: Al construir, escribir en este archivo de salida.
173+
- `--wp=<version>`: La versión de WordPress a usar. Por defecto es la última.
174+
- `--auto-mount`: Montar automáticamente el directorio actual (plugin, tema, wp-content, etc.).
175+
- `--mount=<mapping>`: Montar manualmente un directorio (puede usarse múltiples veces). Formato: `"/host/path:/vfs/path"`.
176+
- `--mount-before-install`: Montar un directorio al runtime PHP antes de la instalación de WordPress (puede usarse múltiples veces). Formato: `"/host/path:/vfs/path"`.
177+
- `--mount-dir`: Montar un directorio al runtime PHP (puede usarse múltiples veces). Formato: `"/host/path"` `"/vfs/path"`.
178+
- `--mount-dir-before-install`: Montar un directorio antes de la instalación de WordPress (puede usarse múltiples veces). Formato: `"/host/path"` `"/vfs/path"`
179+
- `--blueprint=<path>`: La ruta a un archivo JSON Blueprint para ejecutar.
180+
- `--blueprint-may-read-adjacent-files`: Bandera de consentimiento: Permitir que recursos "empaquetados" en un blueprint local lean archivos en el mismo directorio que el archivo blueprint.
181+
- `--login`: Iniciar sesión automáticamente del usuario como administrador.
182+
- `--skip-wordpress-setup`: No descargar ni instalar WordPress. Útil si estás montando un directorio WordPress completo.
183+
- `--skip-sqlite-setup`: No configurar la integración de base de datos SQLite.
184+
- `--verbosity`: Salida de logs y mensajes de progreso. Las opciones son "quiet", "normal" o "debug". Por defecto es "normal".
185+
- `--debug`: Imprimir el log de errores de PHP si ocurre un error durante el arranque.
186+
187+
## ¿Necesitas ayuda con el CLI?
188+
189+
Con el Playground CLI, puedes usar la bandera `--help` para obtener la lista completa de comandos y argumentos disponibles.
190+
191+
```bash
192+
npx @wp-playground/cli@latest --help
193+
```
194+
195+
## Uso Programático con JavaScript
196+
197+
El Playground CLI también puede ser controlado programáticamente desde tu código JavaScript/TypeScript usando la función `runCLI`. Esto te da acceso directo a todas las funcionalidades del CLI dentro de tu código, lo cual es útil para automatizar pruebas end-to-end. Cubramos los conceptos básicos del uso de `runCLI`.
198+
199+
### Ejecutar una instancia de WordPress con una versión específica
200+
201+
Usando la función `runCLI`, puedes especificar opciones como las versiones de PHP y WordPress. En el ejemplo a continuación, solicitamos PHP 8.3, la última versión de WordPress, y iniciar sesión automáticamente. Todos los argumentos soportados están definidos en el tipo `RunCLIArgs`.
202+
203+
```TypeScript
204+
import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";
205+
206+
let cliServer: RunCLIServer;
207+
208+
cliServer = await runCLI({
209+
command: 'server',
210+
php: '8.3',
211+
wp: 'latest',
212+
login: true
213+
} as RunCLIArgs);
214+
```
215+
216+
Para ejecutar el código anterior, el desarrollador puede establecer su método preferido. Una forma simple de ejecutar este código es guardarlo como un archivo `.ts` y ejecutarlo con una herramienta como `tsx`. Por ejemplo: `tsx my-script.ts`
217+
218+
### Configurar un Blueprint
219+
220+
Puedes proporcionar un blueprint de dos maneras: ya sea como un objeto literal pasado directamente a la propiedad `blueprint`, o como una cadena que contiene la ruta a un archivo `.json` externo.
221+
222+
```TypeScript
223+
import { runCLI, RunCLIServer } from "@wp-playground/cli";
224+
225+
let cliServer: RunCLIServer;
226+
227+
cliServer = await runCLI({
228+
command: 'server',
229+
wp: 'latest',
230+
blueprint: {
231+
steps: [
232+
{
233+
"step": "setSiteOptions",
234+
"options": {
235+
"blogname": "Blueprint Title",
236+
"blogdescription": "A great blog description"
237+
}
238+
}
239+
],
240+
},
241+
});
242+
```
243+
244+
Para una seguridad de tipos completa al definir tu objeto blueprint, puedes importar y usar el tipo `BlueprintDeclaration` del paquete `@wp-playground/blueprints`:
245+
246+
```TypeScript
247+
import type { BlueprintDeclaration } from '@wp-playground/blueprints';
248+
249+
const myBlueprint: BlueprintDeclaration = {
250+
landingPage: "/wp-admin/",
251+
steps: [
252+
{
253+
"step": "installTheme",
254+
"themeData": {
255+
"resource": "wordpress.org/themes",
256+
"slug": "twentytwentyone"
257+
},
258+
"options": {
259+
"activate": true
260+
}
261+
}
262+
]
263+
};
264+
```
265+
266+
### Montar un plugin programáticamente
267+
268+
Es posible montar directorios locales programáticamente usando `runCLI`. Las opciones `mount` y `mount-before-install` están disponibles. La propiedad `hostPath` espera una ruta a un directorio en tu máquina local. Esta ruta debe ser relativa a donde se está ejecutando tu script.
269+
270+
```TypeScript
271+
cliServer = await runCLI({
272+
command: 'server',
273+
login: true,
274+
'mount-before-install': [
275+
{
276+
hostPath: './[my-plugin-local-path]',
277+
vfsPath: '/wordpress/wp-content/plugins/my-plugin',
278+
},
279+
],
280+
});
281+
```
282+
283+
Con esas opciones podemos combinar el montaje de partes del proyecto con blueprints, por ejemplo:
284+
285+
```TypeScript
286+
287+
import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";
288+
289+
let cliServer: RunCLIServer;
290+
291+
cliServer = await runCLI({
292+
command: 'server',
293+
php: '8.3',
294+
wp: 'latest',
295+
login: true,
296+
mount: [
297+
{
298+
"hostPath": "./plugin/",
299+
"vfsPath": "/wordpress/wp-content/plugins/playwright-test"
300+
}
301+
],
302+
blueprint: {
303+
steps: [
304+
{
305+
"step": "activatePlugin",
306+
"pluginPath": "/wordpress/wp-content/plugins/playwright-test/plugin-playwright.php"
307+
}
308+
]
309+
}
310+
} as RunCLIArgs);
311+
```

0 commit comments

Comments
 (0)