Execute exemplos em PHP em qualquer lugar com o WordPress Playground

O WordPress Playground vai além dos sites WordPress completos. Um conjunto recente de mudanças transforma o Playground em um runtime PHP leve e útil para documentação, tutoriais, exemplos e demos compartilháveis.

O principal destaque é o novo componente web . Ele permite incorporar exemplos de PHP executáveis em qualquer página web com uma única tag de script. Os leitores podem editar o código, clicar em Run, ver a saída no próprio local e experimentar sem instalar o PHP, configurar um servidor ou sair da página.

Isso abre uma nova forma de ensinar APIs do WordPress e do PHP: agora os exemplos podem ser legíveis e executáveis.

O que mudou

Em uma página HTML, como index.html, a nova incorporação de snippets é carregada a partir do Playground:

    
<?php
echo "Hello from PHP " . phpversion();
    

Este exemplo deve ser servido como HTML, não como PHP no servidor. Se você colar a mesma marcação em um modelo .php, o interpretador PHP do servidor verá a tag de abertura <?php bruta antes do navegador. Nesse caso, escape a tag de abertura como <?php, carregue o snippet a partir de um arquivo externo com src ou garanta de outra forma que o navegador receba o código PHP como texto literal.

O componente renderiza um bloco de código editável, com realce de sintaxe e um botão Run.

Quando o leitor clica em Run pela primeira vez, o Playground carrega o runtime sob demanda em um iframe oculto, executa o PHP e exibe a saída abaixo do snippet.

Vários snippets na mesma página podem compartilhar o mesmo runtime. Isso significa que um tutorial pode incluir vários exemplos sem precisar baixar e inicializar um ambiente PHP separado para cada um.

As APIs do WordPress também funcionam

Por padrão, os snippets são executados em um ambiente WordPress real. Isso significa que os exemplos podem chamar APIs do WordPress, não apenas funções PHP comuns.

Por exemplo, uma página de documentação pode demonstrar a HTML API:

    
<?php
require '/wordpress/wp-load.php';

$html = '

    
    
';

$tags = new WP_HTML_Tag_Processor( $html );
while ( $tags->next_tag( 'img' ) ) {
    $tags->set_attribute( 'loading', 'lazy' );
    $tags->add_class( 'responsive' );
}

echo $tags->get_updated_html();
    

Isso altera o papel dos exemplos de código na documentação do WordPress. Em vez de pedir que os leitores copiem o código para um site local, o exemplo pode ser executado onde eles já estão lendo.

Modo somente PHP

Nem todo exemplo precisa do WordPress. Para recursos da linguagem PHP pura, os snippets podem dispensar completamente baixar o WordPress:

    
<?php
echo "PHP " . phpversion() . "n";
echo "WordPress installed: " .
    ( file_exists( '/wordpress/wp-includes/version.php' ) ? 'yes' : 'no' );
    

Por baixo dos panos, isso corresponde à nova opção de Blueprint:

{
    "preferredVersions": {
        "php": "latest",
        "wp": false
    }
}

Quando preferredVersions.wp é false, o Playground inicializa o PHP sem baixar ou instalar o WordPress. Campos e etapas de Blueprint específicos do WordPress são rejeitados, o que mantém os exemplos somente em PHP explícitos e previsíveis.

Da página de demonstração ao guia de documentação

O trabalho com snippets também vai além da página original de teste/demonstração. O guia de snippets PHP está se tornando a referência canônica para este recurso, com exemplos renderizados em tempo real ao lado de código que pode ser copiado.

Isso é importante porque o guia pode mostrar o recurso no mesmo formato em que os autores vão usá-lo: incorporações básicas, saída pré-computada, snippets baseados em seletores, snippets do WordPress, snippets em PHP puro e uso opção por opção. A página de demonstração antiga redireciona os leitores para o guia, e o link de atribuição do componente também aponta para ele.

Como usar

Adicione o script do módulo uma vez na página e coloque cada exemplo em um elemento . O padrão recomendado é colocar o PHP dentro de um elemento filho quando o documento ao redor for HTML, MDX ou outro formato que entregue o código PHP ao navegador sem alterações:

    
<?php
require '/wordpress/wp-load.php';

update_option( 'blogname', 'Snippet Docs' );
echo get_bloginfo( 'name' );
    
    
Snippet Docs
    

O wrapper application/x-php é útil porque os navegadores ignoram tipos de script desconhecidos. Isso permite que autores incluam strings PHP contendo HTML sem escapar todos os caracteres <.

Para exemplos muito curtos, texto embutido também funciona, mas a tag de abertura PHP precisa ser escapada:

    <?php echo 20 + 22;

Mostrar a saída antes do Run

Use a saída esperada quando quiser que o resultado apareça imediatamente. O espaço reservado é substituído pela saída real do runtime depois que o leitor clica em Run.

    
<?php
echo "2 + 2 = " . ( 2 + 2 );
    
    
2 + 2 = 4
    

Para saída em uma única linha, use o atributo expected-output:

    
<?php echo "Ready";
    

Preparar exemplos com um Blueprint

Use blueprint quando os snippets precisarem de preparação antes da execução do código PHP. O Blueprint pode criar arquivos, adicionar um mu-plugin, configurar opções, instalar plugins ou preparar conteúdo de exemplo.

{
    "steps": [
        {
            "step": "writeFile",
            "path": "/wordpress/wp-content/mu-plugins/helpers.php",
            "data": "<?phpnfunction docs_greet($name) { return 'Hello, ' . $name; }n"
        }
    ]
}



    
<?php
require '/wordpress/wp-load.php';
echo docs_greet( 'Ada' );
    
    
Hello, Ada
    

O atributo blueprint aceita um ID de elemento ou um seletor CSS. Use para o Blueprint porque o conteúdo dele é tratado como texto bruto, o que mantém previsíveis as strings PHP incorporadas.

Carregar PHP de outro arquivo

Use src quando o código-fonte PHP deve ficar em um arquivo separado:

O URL é resolvido a partir da página que contém o snippet. Se o arquivo PHP estiver hospedado em outra origem, esse servidor precisa permitir acesso entre origens. Use um Blueprint quando o exemplo precisar de arquivos de apoio, plugins, opções ou outra preparação.

Fixar versões ou auto-hospedar o runtime

A versão padrão do PHP é 8.4, e a versão padrão do WordPress é latest. Use os atributos php e wp quando o exemplo depender de uma versão específica:

    
<?php
require '/wordpress/wp-load.php';
echo get_bloginfo( 'version' );
    

A maioria das páginas deve usar o runtime hospedado em https://playground.wordpress.net. Para desenvolvimento local, auto-hospedagem ou infraestrutura com versões fixadas, use playground-origin:

    
<?php
echo phpversion();
    

Mais controle para autores

O componente de snippets inclui algumas ferramentas de autoria que o tornam prático para documentação real:

• Os snippets são editáveis por padrão, o que permite que os leitores alterem o código antes de executá-lo.
• Use Ctrl+Enter ou Cmd+Enter para executar um snippet editável em foco pelo teclado.
• Use readonly em exemplos executáveis que devem permanecer bloqueados.
• Use editable="false" como alias de compatibilidade para exemplos antigos que já usam esse padrão.
• Use src para carregar PHP a partir de um arquivo separado.
• Use expected-output ou um filho para mostrar a saída esperada antes que o leitor clique em Run.
• Use runnable="false" em exemplos com realce de sintaxe que não devem ser executados.
• Use os atributos php e wp para escolher as versões do PHP e do WordPress para um snippet.
• Use um Blueprint compartilhado quando vários snippets precisarem da mesma preparação, como um mu-plugin, uma opção do site ou um arquivo.

Esse último ponto é especialmente útil em tutoriais mais longos. Uma página pode definir um Blueprint JSON e apontar vários snippets para ele. O Playground inicializa o ambiente compartilhado apenas uma vez e, depois disso, cada snippet é executado no mesmo runtime já preparado.

Compartilhamento de runtime e solução de problemas

O primeiro clique em Run em uma página carrega o cliente do Playground, cria um iframe oculto, inicializa o PHP e instala o WordPress, a menos que o snippet use wp="none". Execuções posteriores reutilizam um runtime existente quando playground-origin, php, wp E o JSON do Blueprint resolvido é o mesmo.

Esse compartilhamento mantém os snippets relacionados rápidos, sem deixar de isolar exemplos que precisam de uma versão diferente do PHP, uma versão diferente do WordPress ou uma preparação de Blueprint diferente.

Se um snippet não for renderizado, verifique se o script do módulo foi carregado e se o navegador é compatível com elementos personalizados. Se Run nunca terminar, abra o DevTools e procure requisições com falha para remote.html, arquivos .wasm do PHP, arquivos ZIP do WordPress, recursos de Blueprint ou arquivos src de origem cruzada.

Sites com uma Content Security Policy rígida precisam permitir o script do módulo e o iframe oculto de https://playground.wordpress.net, além dos ativos de runtime que o Playground baixa. Para ambientes mais restritos, auto-hospede o script de snippets e aponte playground-origin para essa implantação.

PHP Playground independente

Para exemplos de página inteira, o Playground também inclui um editor PHP independente:

playground.wordpress.net/php-playground.html

Ele oferece um editor e uma prévia lado a lado, com seletores de versões do PHP e do WordPress. O código atual e as escolhas de versão são codificados no fragmento do URL, então os exemplos podem ser compartilhados como links ou incorporados em um iframe.

Use o editor independente para uma única demonstração mais extensa. Use quando um post, uma página de handbook ou um tutorial precisar de vários exemplos pequenos executáveis embutidos.

Por que isso importa

Snippets executáveis tornam o Playground útil em uma nova camada da experiência de aprendizado do WordPress.

Para autores de documentação, isso reduz a distância entre a explicação e a verificação. Um leitor pode executar o exemplo imediatamente.

Para colaboradores, cria uma forma de baixo atrito para demonstrar APIs do WordPress, comportamento do PHP, etapas de preparação de Blueprint ou reproduções de bugs.

Para quem está aprendendo, remove a barreira de configuração. As pessoas podem testar código PHP e WordPress no navegador primeiro e, depois, migrar para um ambiente local quando estiverem prontas.

Isso também amplia o significado do Playground. Ele continua sendo um runtime completo do WordPress no navegador, mas agora também pode atuar como uma pequena camada de execução do PHP incorporável para a web.

Teste e compartilhe seu feedback

Teste a incorporação de snippets em um arquivo HTML local, uma página de documentação ou um rascunho de tutorial:

Para exemplos mais aprofundados, consulte o novo guia de snippets PHP na documentação do Playground:

PHP code snippets and embeds

Feedback é bem-vindo no canal #playground no Slack Making WordPress ou no repositório do WordPress Playground no GitHub.