Playground CLI

@wp-playground/cli é uma ferramenta de linha de comando que simplifica o fluxo de desenvolvimento e teste do WordPress. O Playground CLI suporta a montagem automática de um diretório com um plugin, tema ou instalação WordPress. Mas se você precisa de flexibilidade, o CLI suporta comandos de montagem para personalizar seu ambiente local.

Principais recursos:

• Configuração rápida: Configure um ambiente WordPress local em segundos.
• Flexibilidade: Permite configuração para se adaptar a diferentes cenários.
• Ambiente simples: Sem configuração extra, apenas uma versão Node compatível e você está pronto para usar.

O Playground CLI inclui dois comandos principais para executar WordPress localmente:

• start (Simplificado): Detecta automaticamente o tipo do seu projeto, persiste sites entre sessões e abre o navegador automaticamente.
• server (Avançado): Oferece controle manual completo sobre a configuração. Ideal para setups personalizados, pipelines de CI/CD ou quando você precisa de controle refinado.

Requisitos

O Playground CLI requer Node.js 20.18 ou superior, que é a versão recomendada de Suporte de Longo Prazo (LTS). Você pode baixá-la no site do Node.js.

Início rápido

Para executar o Playground CLI, abra uma linha de comando e use um dos seguintes comandos:

Usando start (Simplificado)

O comando start é a forma mais fácil de começar. Ele detecta automaticamente o tipo do seu projeto, persiste seu site e abre o navegador:

npx @wp-playground/cli@latest start

Quando executado dentro de um diretório de plugin ou tema, start monta seu projeto automaticamente:

cd my-plugin
npx @wp-playground/cli@latest start

Principais diferenças em relação ao server:

• Login automático habilitado por padrão
• Abre o navegador automaticamente
• Monta o projeto automaticamente por padrão

Usando server (Avançado)

O comando server oferece controle total sobre a configuração:

npx @wp-playground/cli@latest server

Persistência automática do site: Por padrão, o comando start mantém seu site WordPress persistente entre sessões. Seus arquivos e banco de dados são armazenados em ~/.wordpress-playground/sites/<path-hash>/, onde <path-hash> é derivado do diretório do seu projeto. Assim você pode parar e reiniciar o CLI sem perder seu trabalho.

Isso é útil quando:

• Você quer uma instalação WordPress limpa
• Está testando cenários de instalação nova
• Os dados do seu site ficaram corrompidos ou inconsistentes

informação

A flag --reset funciona apenas com start. Para server, exclua manualmente o diretório do site persistido em ~/.wordpress-playground/sites/<path-hash>/.

Escolhendo uma versão do WordPress e do PHP

Por padrão, o CLI carrega a última versão estável do WordPress e PHP 8.3 devido ao desempenho melhorado. Para especificar suas versões preferidas, use as flags --wp=<version> e --php=<version>:

npx @wp-playground/cli@latest server --wp=6.8 --php=8.3

Carregando blueprints

Uma forma de levar sua experiência de desenvolvimento com o Playground CLI ao próximo nível é integrar com Blueprints. Para quem não conhece essa tecnologia, ela permite que desenvolvedores configurem o estado inicial de suas instâncias WordPress Playground.

Usando a flag --blueprint=<blueprint-address>, desenvolvedores podem executar um Playground com um estado inicial personalizado. Usaremos o exemplo abaixo para isso.

(my-blueprint.json)

{
  "landingPage": "/wp-admin/options-general.php?page=akismet-key-config",
  "login": true,
  "plugins": [
    "hello-dolly",
    "https://raw.githubusercontent.com/adamziel/blueprints/trunk/docs/assets/hello-from-the-dashboard.zip"
  ]
}

Comando CLI carregando um blueprint:

npx @wp-playground/cli@latest server --blueprint=my-blueprint.json

Montando pastas manualmente

Alguns projetos têm uma estrutura específica que exige configuração personalizada; por exemplo, seu repositório contém todos os arquivos na pasta /wp-content/. Nesse cenário, você pode indicar ao Playground CLI que ele montará seu projeto a partir dessa pasta usando a flag --mount.

npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/MY-PLUGIN-DIRECTORY

Montando antes da instalação do WordPress

Considere montar os arquivos do seu projeto WordPress antes do início da instalação do WordPress. Essa abordagem é útil se você quiser sobrescrever o processo de inicialização do Playground, pois pode ajudar a conectar o Playground ao WP-CLI. A flag --mount-before-install suporta esse processo.

npx @wp-playground/cli@latest server --mount-before-install=.:/wordpress/

informação

No Windows, o formato de caminho /host/path:/vfs/path pode causar problemas. Para resolver, use as flags --mount-dir e --mount-dir-before-install. Essas flags permitem especificar os caminhos do host e do sistema de arquivos virtual em um formato alternativo: "/host/path" "/vfs/path".

Entendendo persistência de dados e local do SQLite no modo server

Por padrão, o Playground CLI armazena os arquivos do WordPress e o banco SQLite em diretórios temporários do seu sistema operacional:

<OS-TEMP-DIR>/playground-<random-id>/
├── wordpress/          # Instalação WordPress
├── internal/           # Config do runtime do Playground
└── tmp/                # Arquivos temporários PHP

Encontrando seu diretório temporário:

A localização real depende do seu SO (estes são exemplos ou possibilidades comuns):

• macOS/Linux: Pode estar em /tmp/ ou /private/var/folders/ (varia conforme o sistema)
• Windows: C:\Users\<username>\AppData\Local\Temp\

Para ver o caminho exato do diretório temporário em uso, execute o CLI com a flag --verbosity=debug:

npx @wp-playground/cli@latest server --verbosity=debug

Isso exibirá algo como:

Native temp dir for VFS root:
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC
Mount before WP install: /home ->
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/home
Mount before WP install: /tmp ->
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/tmp
Mount before WP install: /wordpress ->
/private/var/folders/c8/mwz12ycx4s509056kby3hk180000gn/T/node-playground-cli-site-62926--62926-yQNOdvJVIgYC/wordpress

Onde fica o banco de dados SQLite?

A localização do banco depende do que você monta:

• Montagem automática de wp-content ou WordPress completo:

  • Banco: <seu-projeto-local>/wp-content/database/.ht.sqlite
  • ✅ Persistido localmente na pasta do seu projeto

• Montagem automática só de plugin/tema:

  • Banco: <OS-TEMP-DIR>/playground-<id>/wordpress/wp-content/database/.ht.sqlite
  • ⚠️ Perdido quando o servidor para (diretórios temporários são removidos)

• Montagens customizadas: A localização do banco segue sua configuração de montagem

Limpeza automática: O Playground CLI remove automaticamente diretórios temporários que:

• Tenham mais de 2 dias
• Não estejam mais associados a um processo em execução

Recomendação: Para persistir tanto seu código quanto o banco ao desenvolver plugins ou temas, monte o diretório wp-content inteiro em vez de só a pasta do plugin/tema.

Exemplo: Montando wp-content para persistência

# Mount your entire wp-content directory
cd my-wordpress-project
npx @wp-playground/cli@latest server --mount=./wp-content:/wordpress/wp-content

Persistência de dados no modo start

No modo start, o Playground CLI persiste automaticamente seu site WordPress em um diretório dedicado:

~/.wordpress-playground/sites/<path-hash>/
├── wordpress/          # Instalação WordPress
├── internal/          # Config do runtime do Playground
└── tmp/                # Arquivos temporários PHP

O <path-hash> é derivado do caminho do diretório do seu projeto. Isso garante isolamento entre projetos diferentes e persiste as alterações automaticamente.

Comportamento da persistência

• Padrão (sem montagem explícita): Arquivos e banco do WordPress persistem em ~/.wordpress-playground/sites/<path-hash>/. As alterações sobrevivem entre reinícios do CLI.
• Montagem explícita de /wordpress: Se você informar um caminho de montagem para /wordpress, a persistência automática é ignorada. Sua configuração de montagem tem precedência.

A localização do banco depende da sua configuração:

• Padrão (persistência automática):
  • Banco: ~/.wordpress-playground/sites/<path-hash>/wordpress/wp-content/database/.ht.sqlite
  • Persistido automaticamente entre sessões

Redefinindo um site persistido

Para começar do zero, use a flag --reset com o comando start:

npx @wp-playground/cli@latest start --reset

Comando e argumentos

O Playground CLI é simples, configurável e sem opiniões rígidas. Você pode configurá-lo de acordo com seu ambiente WordPress. Com o Playground CLI, você pode usar os seguintes comandos de nível superior:

• start: (Simplificado) Inicia um servidor WordPress local com detecção automática de projeto, persistência de site e abertura do navegador.
• server: (Avançado) Inicia um servidor WordPress local com controle manual completo da configuração.
• run-blueprint: Executa um arquivo Blueprint sem iniciar um servidor web.
• build-snapshot: Cria um snapshot ZIP de um site WordPress com base em um Blueprint.

O comando start tem um argumento dedicado:

• --reset: Exclui o site armazenado e começa do zero. Padrão: false.

O comando server suporta os seguintes argumentos opcionais:

• --port=<port>: Número da porta em que o servidor escuta. Padrão: 9400.
• --version: Exibe o número da versão.
• --outfile: Ao construir, grava neste arquivo de saída.
• --site-url=<url>: URL do site para o WordPress. Padrão: http://127.0.0.1:{port}.
• --wp=<version>: Versão do WordPress a usar. Padrão: a mais recente.
• --php=<version>: Versão do PHP. Opções: 8.5, 8.4, 8.3, 8.2, 8.1, 8.0, 7.4. Padrão: 8.5.
• --auto-mount[=<path>]: Monta um diretório automaticamente. Sem path, monta o diretório de trabalho atual. Você pode montar um diretório WordPress, de plugin, de tema, wp-content ou qualquer diretório com arquivos PHP e HTML.
• --mount=<mapping>: Monta um diretório manualmente (pode ser usado várias vezes). Formato: "/host/path:/vfs/path".
• --mount-before-install: Monta um diretório no runtime PHP antes da instalação do WordPress (pode ser usado várias vezes). Formato: "/host/path:/vfs/path".
• --mount-dir: Monta um diretório no runtime PHP (pode ser usado várias vezes). Formato: "/host/path" "/vfs/path".
• --mount-dir-before-install: Monta um diretório antes da instalação do WordPress (pode ser usado várias vezes). Formato: "/host/path" "/vfs/path".
• --blueprint=<path>: Caminho do arquivo JSON Blueprint a executar.
• --blueprint-may-read-adjacent-files: Flag de consentimento: permite que recursos "empacotados" em um blueprint local leiam arquivos no mesmo diretório do blueprint.
• --login: Faz login automático do usuário como administrador.
• --wordpress-install-mode <mode>: Controla como o Playground prepara o WordPress antes da inicialização. Padrão: download-and-install. Outras opções: install-from-existing-files, install-from-existing-files-if-needed, do-not-attempt-installing.
• --skip-sqlite-setup: Não configurar a integração do banco SQLite.
• --verbosity=<level>: Saída de logs e mensagens de progresso. Opções: quiet, normal, debug. Padrão: normal.
• --debug: Exibe o log de erros do PHP se ocorrer erro na inicialização.
• --follow-symlinks: Permite que o Playground siga symlinks montando automaticamente diretórios e arquivos com symlink encontrados nos diretórios montados.
• --internal-cookie-store: Habilita o gerenciamento interno de cookies. Quando habilitado, o Playground gerencia cookies internamente com HttpCookieStore que persiste cookies entre requisições. Quando desabilitado, os cookies são tratados externamente (ex.: pelo navegador em ambientes Node.js). Padrão: false.
• --phpmyadmin[=<path>]: Instala phpMyAdmin para gerenciamento do banco. A URL do phpMyAdmin será exibida após a inicialização. Opcionalmente especifique um caminho de URL customizado (padrão: /phpmyadmin).
• --xdebug: Habilita Xdebug. Padrão: false.
• --experimental-devtools: Habilita ferramentas de desenvolvimento experimentais no navegador. Padrão: false.
• --experimental-unsafe-ide-integration=<ide>: Configura a integração Xdebug no VS Code (vscode) e PhpStorm (phpstorm).
• --experimental-multi-worker=<number>: Habilita suporte experimental a múltiplos workers, que exige um diretório /wordpress em um sistema de arquivos real. Passe um número positivo para o número de workers; caso contrário, padrão é número de CPUs menos 1.

cuidado

Com a flag --follow-symlinks, symlinks podem expor arquivos fora dos diretórios montados ao Playground e podem representar risco de segurança.

Precisa de ajuda com o CLI?

Com o Playground CLI, você pode usar a flag --help para ver a lista completa de comandos e argumentos disponíveis.

npx @wp-playground/cli@latest --help

Uso programático

O Playground CLI também pode ser controlado de forma programática a partir de JavaScript/TypeScript usando a função runCLI. Consulte o guia de uso programático para detalhes sobre automação e testes.