Gerenciar extensões do PHP é moleza

Acho que nunca houve um momento melhor para ser desenvolvedor de PHP. Talvez eu esteja vendo tudo através de lentes cor-de-rosa, ou talvez simplesmente não tenha passado por dificuldades suficientes no passado, mas o FrankenPHP proporcionou à linguagem um novo ambiente de execução extremamente rápido, e agora as aplicações PHP podem ser compiladas nativamente para dispositivos Android e iOS de graça com o NativePHP.  

Neste artigo, vamos abordar o Instalador de Extensões do PHP (PIE) e criaremos uma extensão PHP personalizada.

Gerenciadores de pacotes e extensões em PHP

Costumo perceber acenos de cabeça de compreensão quando o assunto é Composer surgir. Isso geralmente vem acompanhado da afirmação de que “o PHP tem o melhor gerenciador de pacotes”. Devido aos recursos robustos do Composer, acho que nunca tenho tive dificuldade com ele. Pensei: “Que circunstâncias do ecossistema nos proporcionam ferramentas como essa?”. Sem querer menosprezar o imenso trabalho de Nils e Jordi que tornaram isso possível, mas também percebi que o PHP tende a ter muitas ferramentas de fato, e que “menos é mais”. O Composer é nosso gerenciador de pacotes de fato. Compare isso com, digamos, o Node ou o Python, onde os desenvolvedores precisam estar sempre atentos para ver o que vem a seguir e o que a comunidade decide que “é o melhor”. Novas ferramentas surgem na tentativa de corrigir as limitações da situação atual.

Which JavaScript manager is it this week?Compositor substituído PEAR. Mas, para extensões em C no PHP, sempre foi o PECL. No mesmo ciclo de vida, parece que agora temos nossa nova “extensão de fato gerenciador de extensões ” na forma do PIE. Antes de mergulhar em como usá-lo e no que ele pode fazer, achei melhor fazer algumas perguntas urgentes que eu tinha ao seu autor, James Titcumb.

Do PEAR ao PECL e ao PIE: a perspectiva do autor

O PECL e o PEAR têm uma relação um tanto confusa. Como e quando surgiu o PECL?

O PEAR — Repositório de Extensões e Applications do PHP — foi fundado em 1999 como uma ferramenta e um sistema de distribuição de código PHP. Em termos de funcionalidade, ele faz o que o Composer faz atualmente, mas com uma abordagem ligeiramente diferente. O PECL foi um desdobramento disso; uma ferramenta independente para se conectar aos canais do PEAR e compilar extensões. Esse material é extremamente arcaico e, embora o PEAR tenha sido praticamente ofuscado pelo Composer, o PECL, até recentemente, ainda era a forma padrão de instalar extensões PHP. 

Visto que o PECL já existe há muito tempo, por que o PIE surge justamente agora?

O projeto PIE é parcialmente financiado pela Sovereign Tech Agency, um programa do governo alemão destinado a promover e garantir a sustentabilidade a longo prazo das tecnologias de código aberto. O PECL tem sido historicamente difícil de manter, é muito inferior em termos de gerenciamento de dependências quando comparado ao Composer e exige manutenção de infraestrutura. O número de pessoas que sabem como essa infraestrutura funciona é preocupantemente pequeno. Assim, em linha com o objetivo da PHP Foundation de reduzir o “fator ônibus” para o PECL e sua infraestrutura associada, surgiu o PIE, com o objetivo de resolver essas questões.

Minhas fontes confidenciais me informaram que você trabalha para a “Fundação PHP”. O que é isso e qual é a sua função lá?

A Fundação PHP é uma organização criada inicialmente porque um grupo de pessoas se reuniu, percebendo que o número de pessoas que trabalhavam ativamente com PHP era muito baixo — duas, e depois chegou a apenas uma em determinado momento. O objetivo é garantir a sustentabilidade a longo prazo da linguagem de programação PHP, o que é importante quando se considera a grande parte da web que funciona com sistemas PHP! Uma das atribuições da fundação é contratar desenvolvedores para trabalhar com o PHP e seu ecossistema próximo — e, por isso, a fundação está sempre em busca de patrocinadores. 

Que novos recursos podemos esperar ver em 2026?

Um grande foco na série PIE 1.4, atualmente em desenvolvimento, é garantir que o PIE funcione melhor com os sistemas de instalação de extensões já existentes — que antes utilizavam o PECL ou tinham sua própria maneira de operar (como no Docker) —, bem como aliviar um pouco o incômodo dos usuários finais que precisam instalar pré-requisitos (como ferramentas de compilação, bibliotecas do sistema etc.). Também disponibilizaremos, a título experimental, binários executáveis pré-compilados do próprio PIE usando uma ferramenta chamada Static PHP. Há muito mais por vir também. O objetivo final é que o PIE substitua completamente o PECL, e estamos trabalhando para alcançar isso.

Tutorial: Como usar o PIE para gerenciar extensões

Então, este tutorial é dividido em duas partes. Primeiro, vamos instalar o PIE e usá-lo para baixar uma extensão de exemplo. Depois, passaremos para os assuntos mais complexos, escrevendo nossa própria extensão e fazendo com que o PIE a compile.

Como está seu C?

É isso mesmo. C. Já conversei várias vezes com desenvolvedores de outras comunidades de linguagens, e eles costumam ficar bastante surpresos ao descobrir, pela primeira vez, que Rasmus Lerdorf criou o PHP como uma linguagem compilada a partir do C. Então, para escrever uma extensão PHP que será usada pelo PIE? Sim, ela será em C.

Instalando o PIE

O PIE é fornecido como um executável PHAR (Agradecimento especial a Davey Shafik daquela época pelo seu trabalho incrível ao trazer isso para o PHP). Você pode baixar o PHAR em aquie, em seguida, colocá-lo no PATH dos executáveis da linha de comando do sistema operacional que você estiver usando.

Depois de definir um alias no arquivo RC do seu shell ou adicionar o PIE ao seu caminho, você poderá usá-lo para instalar uma extensão de exemplo. Faremos isso primeiro, antes de criarmos a nossa própria.

pie install asgrim/example_pie_extension

Composer, but slightly different!Ótimo, já está instalado. É hora de verificar se funciona: crie um novo arquivo PHP e adicione o seguinte:

test.php

<?php
    example_pie_extension_test();

Resultados:

php test.php

Hello, world!

Ah, o velho clássico. Agora é que a coisa está ficando interessante.

Criando nossa própria extensão PHP

Quem está familiarizado com o Laravel sabem que existe o famoso dd() helper. Ele é executado tanto var_dump()e, em seguida, die(). Esse código está no núcleo do Laravel, mas e se decidíssemos criar nossa própria extensão para ter essa função nativamente no tempo de execução do PHP? É exatamente isso que vamos fazer!

Comece criando uma pasta para o projeto. Por exemplo:

mkdir native_dd
cd native_dd && touch native_dd.c

Espero que você já tenha instalado as extensões de linguagem C no seu IDE!

Criamos native_dd.c. Como agora estamos no mundo do C, é hora de começar a programar com o mecanismo Zend!

#include "php.h"
#include <ext/standard/php_var.h>
#include "php_native_dd.h"

PHP_FUNCTION(native_dd)
{
   zval *value;

   ZEND_PARSE_PARAMETERS_START(1, 1)
       Z_PARAM_ZVAL(value)
   ZEND_PARSE_PARAMETERS_END();

   php_var_dump(value, 0);
  
   php_printf("\n");
   php_output_flush();

   zend_bailout();
}

ZEND_BEGIN_ARG_INFO(arginfo_native_dd_test, 0)
ZEND_END_ARG_INFO()

static const zend_function_entry native_dd_functions[] = {
   PHP_FE(native_dd, arginfo_native_dd_test)
   PHP_FE_END
};

zend_module_entry native_dd_module_entry = {
   STANDARD_MODULE_HEADER,
   "native_dd",
   native_dd_functions,
   NULL,
   NULL,
   NULL,
   NULL,
   NULL,
   "0.1.0",
   STANDARD_MODULE_PROPERTIES
};

ZEND_GET_MODULE(native_dd)

Há vários pontos a serem observados aqui. Em primeiro lugar, para programar uma função em PHP, é preciso seguir a estrutura utilizada pelo Zend Engine. Você pode ler mais sobre esses requisitos aqui: https://www.phpinternalsbook.com/php5/build_system/building_extensions.html.

Quando tivermos todos os arquivos necessários, a estrutura de arquivos do seu projeto deverá ficar assim:

pietest/
  composer.json
  composer.lock
  config.m4
  native_dd.c
  php_native_dd.h
  test.php

Não se preocupe se ainda estiver faltando algum arquivo neste momento; vamos tratar disso mais tarde.

O resumo da história é o seguinte:

• É necessário incluir o PHP primeiro, pois a ordem de inclusão em C é importante

• Este módulo utiliza parte da biblioteca padrão (php_var_dump()) e, portanto, precisa ser importada: #include <ext/standard/php_var.h>

• Você precisa incluir um arquivo de cabeçalho para a função; falaremos mais sobre isso em breve

• A nomenclatura utilizada para a camada de API do PHP em C é PHP_FUNCTION() para a definição, ZEND_BEGIN_ARG_INFO() e ZEND_END_ARG_INFO() para mais detalhes nos argumentos. zend_function_entry <your-module-name> com o sufixo <your-module-name>_functions[] é usada com uma macro, PHP_FE, que compila sua função em uma função interna do Zend. Os últimos passos consistem em definir a função como um módulo com zend_module_entry e ZEND_GET_MODULE.

• php_var_dump, a mesma função subjacente utilizada pelo var_dump é importada e utilizada

• É utilizado um equivalente a die() é usado, que é zend_bailout()

É compreensível que a maior parte disso possa parecer estranha para desenvolvedores de PHP como eu. Entender as peculiaridades do Zend Engine e as definições da API não é para os fracos de coração, mas a parte realmente legal vem com o PIE.

O módulo requer um arquivo de cabeçalho e um arquivo de configuração; portanto, crie um config.m4 arquivo e um php_native_dd.h arquivo.

config.m4

PHP_ARG_ENABLE(native_dd, whether to enable native_dd,
[  --enable-native-dd   Enable native_dd])

if test "$PHP_NATIVE_DD" != "no"; then
    PHP_NEW_EXTENSION(native_dd, native_dd.c, $ext_shared)
fi


php_native_dd.h

#ifndef PHP_NATIVE_DD_H
#define PHP_NATIVE_DD_H

extern zend_module_entry native_dd_module_entry;
#define phpext_native_dd_ptr &native_dd_module_entry

#endif

Lembro-me de, há alguns anos, ter tentado compilar meu próprio módulo e ter fracassado miseravelmente na plataforma em que estava tentando compilá-lo. Acho que, naquela época, eu nem sabia como funcionavam coisas como o GCC e os arquivos MAKEFILE.

Então, adivinha o que vamos fazer agora? Isso mesmo, usar o PIE para que ele faça todo o trabalho pesado.

A compilação incrivelmente fácil…

… se você tiver tudo configurado corretamente. 

O PIE requer várias bibliotecas no nível do sistema operacional; portanto, certifique-se de ter tudo o que for necessário.

Para os autores de extensões, tratem seu código C como qualquer outra dependência — usando o Composer. O código de nós composer.json é assim:

{
   "name": "jimseconde/nativedd",
   "description": "A Native dd() helper for core PHP to be installed with PIE",
   "authors": [
       {
           "name": "jimseconde",
           "email": "jim.seconde@googlemail.com"
       }
   ],
   "require": {
       "php": "^8.3"
   },
   "type": "php-ext",
   "php-ext": {
       "extension-name": "native_dd"
   },
   "license": "MIT"
}

O importante aqui é type, que informa ao Composer que essa não é uma dependência do PHP, mas php-ext a define como uma extensão. É preciso acompanhar isso com o chave php-ext , que define o extension-name. Ao executar o PIE com pie install, o código do PIE consultará o arquivo composer.json e, a partir daí, irá compilá-lo:

pie install

Built, enabled, and loaded!Agora, crie um arquivo PHP de teste e utilize-o.

<?php

$myVariable = "test string";
native_dd($myVariable);

Execute o programa e:

php test.php

string(11) "test string"

Pronto.

Conclusão

Tenho que admitir que nunca imaginei que chegaria o dia em que eu mesmo poderia programar minhas próprias funções em PHP. Você vai perceber isso no processo de compilação ao executar o PIE (é possível adicionar filtros de detalhamento à linha de comando com -v -vv etc. para obter mais registros) que ele cuida de muitas coisas para tornar tão fácil baixar extensões existentes ou compilar as suas próprias. Para outros usos interessantes, imagino (por exemplo) extensões personalizadas usadas em compilações do NativePHP que permitirão o acesso a todos os tipos de APIs nativas dentro de um dispositivo ou máquina.