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 auto-montagem 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.

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

Executar o Playground CLI é tão simples quanto ir para uma linha de comando e executar:

npx @wp-playground/cli@latest server

Com o comando anterior, você obtém apenas uma instância WordPress fresca para testar. A maioria dos desenvolvedores quer ver seu trabalho rodando. Se este é o seu caso, teste um plugin ou tema. Você pode executar o CLI na pasta do seu projeto e executar o Playground CLI com a flag --auto-mount:

cd my-plugin-or-theme-directory
npx @wp-playground/cli@latest server --auto-mount

Escolhendo uma Versão do WordPress e PHP

Por padrão, o CLI carrega a versão estável mais recente do WordPress e PHP 8.3 devido ao seu desempenho melhorado. Para especificar suas versões preferidas, você pode usar as flags --wp=<version> e --php=<version>:

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

Carregando Blueprints

Uma maneira de levar sua experiência de desenvolvimento do Playground CLI para o próximo nível é integrar com Blueprints. Para aqueles não familiarizados com esta tecnologia, ela permite que desenvolvedores configurem o estado inicial para 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 fazer isso.

(meu-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 requer uma configuração personalizada; por exemplo, seu repositório contém todos os arquivos na pasta /wp-content/. Então neste cenário, você pode especificar 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 seus arquivos de projeto WordPress antes da instalação do WordPress começar. Esta abordagem é benéfica se você quer sobrescrever o processo de inicialização do Playground, pois pode ajudar a conectar o Playground com WP-CLI. A flag --mount-before-install suporta este 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 isso, use as flags --mount-dir e --mount-dir-before-install. Estas flags permitem que você especifique caminhos do host e do sistema de arquivos virtual em um formato alternativo "/host/path" "/vfs/path".

Entendendo a Persistência de Dados e Localização do SQLite

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

<OS-TEMP-DIR>/playground-<random-id>/
├── wordpress/          # Instalação WordPress
├── internal/          # Configuração 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 por sistema)
• Windows: C:\Users\<username>\AppData\Local\Temp\

Para ver o caminho exato do diretório temporário sendo usado, 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 o Banco de Dados SQLite é Armazenado?

A localização do banco de dados depende do que você montar:

• Auto-montagem de wp-content ou WordPress completo:

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

• Auto-montagem apenas de plugin/tema:

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

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

Limpeza Automática:

O Playground CLI remove automaticamente diretórios temporários que são:

• Mais antigos que 2 dias
• Não mais associados com um processo em execução

Recomendação: Para persistir tanto seu código quanto o banco de dados ao desenvolver plugins ou temas, monte o diretório wp-content inteiro em vez de apenas 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

Comandos e Argumentos

O Playground CLI é simples, configurável e sem opiniões. Você pode configurá-lo de acordo com sua configuração WordPress única. Com o Playground CLI, você pode usar os seguintes comandos de nível superior:

• server: (Padrão) Inicia um servidor WordPress local.
• run-blueprint: Executa um arquivo Blueprint sem iniciar um servidor web.
• build-snapshot: Constrói um snapshot ZIP de um site WordPress baseado em um Blueprint.

O comando server suporta os seguintes argumentos opcionais:

• --port=<port>: O número da porta para o servidor escutar. Padrão é 9400.
• --version: Mostrar número da versão.
• --outfile: Ao construir, escrever neste arquivo de saída.
• --site-url=<url>: URL do site a usar para WordPress. Padrão é http://127.0.0.1:{port}.
• --wp=<version>: A versão do WordPress a usar. Padrão é a mais recente.
• --php=<version>: Versão do PHP a usar. Opções: 8.4, 8.3, 8.2, 8.1, 8.0, 7.4, 7.3, 7.2. Padrão é 8.3.
• --auto-mount[=<path>]: Montar automaticamente um diretório. Se nenhum caminho for fornecido, monta o diretório de trabalho atual. Você pode montar um diretório WordPress, um diretório de plugin, um diretório de tema, um diretório wp-content, ou qualquer diretório contendo arquivos PHP e HTML.
• --mount=<mapping>: Montar manualmente um diretório (pode ser usado múltiplas vezes). Formato: "/host/path:/vfs/path".
• --mount-before-install: Montar um diretório no runtime PHP antes da instalação do WordPress (pode ser usado múltiplas vezes). Formato: "/host/path:/vfs/path".
• --mount-dir: Montar um diretório no runtime PHP (pode ser usado múltiplas vezes). Formato: "/host/path" "/vfs/path".
• --mount-dir-before-install: Montar um diretório antes da instalação do WordPress (pode ser usado múltiplas vezes). Formato: "/host/path" "/vfs/path"
• --blueprint=<path>: O caminho para um arquivo JSON Blueprint para executar.
• --blueprint-may-read-adjacent-files: Flag de consentimento: Permitir que recursos "empacotados" em um blueprint local leiam arquivos no mesmo diretório do arquivo blueprint.
• --login: Fazer login automaticamente do usuário como administrador.
• --skip-wordpress-setup: Não baixar ou instalar WordPress. Útil se você está montando um diretório WordPress completo.
• --skip-sqlite-setup: Não configurar a integração do banco de dados SQLite.
• --verbosity=<level>: Saída de logs e mensagens de progresso. Opções: quiet, normal, debug. Padrão é normal.
• --debug: Imprimir o log de erro do PHP se um erro ocorrer durante a inicialização.
• --follow-symlinks: Permitir que o Playground siga links simbólicos montando automaticamente diretórios e arquivos vinculados simbolicamente encontrados em diretórios montados.
• --internal-cookie-store: Habilitar tratamento interno de cookies. Quando habilitado, o Playground gerenciará cookies internamente usando um HttpCookieStore que persiste cookies entre requisições. Quando desabilitado, cookies são tratados externamente (por exemplo, por um navegador em ambientes Node.js). Padrão é false.
• --xdebug: Habilitar Xdebug. Padrão é false.
• --experimental-devtools: Habilitar ferramentas de desenvolvimento experimentais do navegador. Padrão é false.
• --experimental-multi-worker=<number>: Habilitar suporte experimental multi-worker que requer um diretório /wordpress apoiado por um sistema de arquivos real. Passe um número positivo para especificar o número de workers a usar. Caso contrário, padrão é o número de CPUs menos 1.

cuidado

Com a flag --follow-symlinks, os seguintes links simbólicos irão expor arquivos fora dos diretórios montados ao Playground e podem ser um risco de segurança.

Precisa de ajuda com o CLI?

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

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

Uso Programático com JavaScript

O Playground CLI também pode ser controlado programaticamente a partir do seu código JavaScript/TypeScript usando a função runCLI. Isso fornece acesso direto a todas as funcionalidades do CLI dentro do seu código, o que é útil para automatizar testes end-to-end. Vamos cobrir o básico do uso de runCLI.

Executando uma instância WordPress com uma versão específica

Usando a função runCLI, você pode especificar opções como as versões do PHP e WordPress. No exemplo abaixo, solicitamos PHP 8.3, a versão mais recente do WordPress, e para fazer login automaticamente. Todos os argumentos suportados são definidos no tipo RunCLIArgs.

import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
    command: 'server',
    php: '8.3',
    wp: 'latest',
    login: true
} as RunCLIArgs);

Para executar o código acima, o desenvolvedor pode definir seu método preferido. Uma maneira simples de executar este código é salvá-lo como um arquivo .ts e executá-lo com uma ferramenta como tsx. Por exemplo: tsx meu-script.ts

Definindo um Blueprint

Você pode fornecer um blueprint de duas maneiras: como um objeto literal passado diretamente para a propriedade blueprint, ou como uma string contendo o caminho para um arquivo .json externo.

import { runCLI, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
  command: 'server',
  wp: 'latest',
  blueprint: {
    steps: [
        {
          "step": "setSiteOptions",
          "options": {
              "blogname": "Blueprint Title",
              "blogdescription": "A great blog description"
          }
        }
    ],
  },
});

Para total segurança de tipo ao definir seu objeto blueprint, você pode importar e usar o tipo BlueprintDeclaration do pacote @wp-playground/blueprints:

import type { BlueprintDeclaration } from '@wp-playground/blueprints';

const myBlueprint: BlueprintDeclaration = {
  landingPage: "/wp-admin/",
  steps: [
    {
      "step": "installTheme",
      "themeData": {
        "resource": "wordpress.org/themes",
        "slug": "twentytwentyone"
      },
      "options": {
        "activate": true
      }
    }
  ]
};

Montando um plugin programaticamente

É possível montar diretórios locais programaticamente usando runCLI. As opções mount e mount-before-install estão disponíveis. A propriedade hostPath espera um caminho para um diretório na sua máquina local. Este caminho deve ser relativo a onde seu script está sendo executado.

	cliServer = await runCLI({
      command: 'server',
      login: true,
      'mount-before-install': [
        {
          hostPath: './[my-plugin-local-path]',
          vfsPath: '/wordpress/wp-content/plugins/my-plugin',
        },
      ],
    });

Com essas opções podemos combinar a montagem de partes do projeto com blueprints, por exemplo:

import { runCLI, RunCLIArgs, RunCLIServer } from "@wp-playground/cli";

let cliServer: RunCLIServer;

cliServer = await runCLI({
    command: 'server',
    php: '8.3',
    wp: 'latest',
    login: true,
    mount: [
        {
            "hostPath": "./plugin/",
            "vfsPath": "/wordpress/wp-content/plugins/playwright-test"
        }
    ],
    blueprint: {
        steps: [
            {
                "step": "activatePlugin",
                "pluginPath": "/wordpress/wp-content/plugins/playwright-test/plugin-playwright.php"
            }
        ]
    }
} as RunCLIArgs);