Estender o SPIP

Organisação das fontes

Pode-se modificar o comportamento do SPIP sem alterar as suas fontes, graças ao caminho de acesso definido pela constante SPIP_PATH. Qualquer extensão do SPIP deve funcionar assim, para que um teste de integração possa ser desativado simplesmente ao redefinir o caminho de acesso, devido à distribuição do SPIP ser apenas de leitura.

Se está convencido que um certo comportamento não pode ser obtido desta forma, escreva no espaço de discussão.

As contribuições para o SPIP devem ser descritas num artigo em Spip-Contrib e o seu conteúdo deve ser enviado como anexos do artigo, ou, de preferência, para o servidor GIT comunitário.

Para estender o SPIP assim, precisa perceber corretamente a organização dos seus diretórios e o papel dos seus ficheiros. A raiz de uma distribuição do SPIP compõe-se essencialmente de:

-  um ficheiro spip.php, aliás index.php, gerindo a compatibilidade com as versões anteriores, carregando o ficheiro de inicialização ecrire/inc_version.php e passando imediatamente o controle ao script principal ecrire/public.php;

-  um diretório ecrire que contém exclusivamente ficheiros interpretáveis no lado do servidor (PHP e SQL);

-  um ou mais (a depender das versões) diretórios que contêm ficheiros interpretáveis no lado do cliente (HTML, Javascript, folhas de estilo, imagens de diferentes formatos) bem como os modelos de layout chamados templates (ou squelettes). Estes templates são interpretados de dois lados: são ficheiros compostos de um formato MIME complementado por algumas diretivas SPIP, diretivas tratadas no lado do servidor para enviar ao cliente um texto puramente MIME (a maior parte do tempo HTML, mas também RSS, SVG, ICS etc).

-  dois diretórios vazios, na instalação (locale tmp), que conterão os dados, temporários ou permanentes, necessários ao funcionamento do site.

Funções dos diretórios prive e squelettes-dist e seus subdiretórios

Contêm os ficheiros que determinam a apresentação do SPIP, respectivamente na área restrita e no espaço público. Incluem vários subdiretórios com as funções abaixo:

Funções do diretório ecrire e seus subdiretórios

O diretório ecrire contém diversos subdiretórios compostos de ficheiros PHP que definem funções e procedem ocasional mas raramente a uma inicialização no seu carregamento (essas excepções tendem a desaparecer). Os ficheiros que se encontram no nível do diretório principal são os mais importantes a compreender, para contribuir com o SPIP, especialmente inc_version.php, public.php e index.php.

O ficheiro ecrire/inc_version.php inicializa as constantes e sas variáves globais necessárias ao funcionamento do SPIP, especialmente aquelas que asseguram a portabilidade em diferentes plataformas. Bem cedo, no seu carregamento, inclui o ficheiro inc/utils.php, onde se encontram as funções indispensáveis ao SPIP, um ficheiro fora da distribuição chamado mes_options.php que permite modular essa inicialização sem precisar alterar o ficheiro inc_version.php. Em particular, pode-se, nesse ficheiro pessoal, invocar a função spip_initialisation para definir os diretórios de dados e dispor assim de vários sites SPIP usando uma única distribuição (a chamada padrão desta função, mais à frente em inc_version.php, será automaticamente neutralizada). Uma outra função indispensável ao SPIP é find_in_path, que explora o caminho de acesso, bem como include_spip que depende da find_in_path, e charger_fonction que depende de include_spip. Todos os ficheiros do SPIP são carregados por estas duas últimas funções.

O ficheiro ecrire/public.php, chamado por spip.php, tem o papel essencial de disponibilizar as página do espaço público, solicitadas na requisição HTTP contendo (após uma eventual reescrita) o parâmetro page. Esse script aplica então o template tendo por nome o valor desse parâmetro. Envia os cabeçalhos HTTP e o conteúdo obtido, trata eventuais erros e inicia as tarefas de segundo plano com a ajuda da função cron. Contribuir para o espaço público do SPIP consiste, portanto, simplesmente em fornecer novos templates com, eventualmente suas folhas de estilos e suas imagens.

O outro papel do ecrire/public.php refere-se ao caso em que a requisição HTTP contém o argumento action. Ele aplica a função charger_fonction ao valor v desse parâmetro action. Isso tem o efeito de carregar o ficheiro homónimo do diretório action, cuja função principal action_v_dist é então invocada. Esses scripts realizam essencialmente operações de escrita (na base ou em ficheiro) e não retorna, em geral, nenhum resultado, escapando assim à problemática da formatação da página.

O ficheiro index.php é o ficheiro central de acesso aos formulários da área restrita. Ele autentica o visitante, inicializa os seus dados pessoais e aplica a função charger_fonction com o valor v do parâmetro exec. Esta aplicação resulta no carregamento do ficheiro homónimo do diretório exec, cuja função principal exec_v_dist é então invocada. Essa função encarrega-se de entregar todo o fluxo de saída, incluindo os cabeçalhos HTTP. Pode-se estender o SPIP simplesmente adicionando um ficheiro PHP num subdiretório chamado exec de um diretório presente em SPIP_PATH.

O diretório exec contém exclusivamente os ficheiros que definem as funções invocáveis pelo parâmetro do URL exec. O código PHP desses ficheiros jamais devem aceder à base de dados com autorização de escrita (as exceções a esta regra estão em vias de desaparecer). Ao contrário, acede abundantemente em leitura, para verificar as permissões do requerente e determinar os dados a exibir. Se quisermos ver o SPIP pelo arquétipo Modelo-Visão-Controlador, os ficheiros de exec cumprem o papel de Controlador. Se olharmos o SPIP pelo arquétipo (Print(Eval(Read))) do Lisp, correspondem a Read. A longo prazo, este deverá tornar-se um diretório de templates. Pede-se às novas contribuições do SPIP que levem em conta este objetivo em suas redações.

O diretório action, já abordado, contém essencialmente os scripts que acedem em modo de escrita à base de dados. Se olharmos o SPIP pelo arquétipo Modelo-Visão-Controlador, os ficheiros de action correspondem ao papel de Modelo. Se olharmos o SPIP pelo arquético (Print(Eval(Read))) do Lisp, correspondem a Eval. Aqui, novamente, contribuir com o SPIP consistem em escrever esses scripts e invocá-los via formulários construídos com a função generer_action_auteur garantindo a segurança do acesso a esses scripts que, por su vez invocarão a função securiser_action para verificar os direitos do solicitante.

Esta arquitetura permite calcular esses direitos apenas na construção dos formulários que chamam os scripts de acesso em modo de escrita: em vez de recalcular todos os direitos, estes scripts verificarão simplesmente se a chave presente nos argumentos é a mesma da que eles calcularam a partir dos outros argumentos, da identidade do solicitante e de um valor aleatório renovado periodicamente.

Esses scripts geralmente não retornam resultados, não havendo neles, portanto, código HTML nem chamadas à função echo (as excepções deverão desaparecer). No entanto, eles são frequentemente chamadoscom um parâmetro HTTP chamado redirect, que solicita um redirecionamento que será operado automaticamente por public.php, que envia um status HTTP 204 na ausência desse parâmetro.

No caso dos formulários construídos com a função ajax_action_auteur, este redirecionamento leva ao script homónimo no diretório exec. Este segundo script em geral resume-se a carregar o ficheiro homónimo no diretório inc, chamar a sua função principal e retornar o resultado ao cliente com a função ajax_retour. Assim, é muito fácil estender o SPIP em modo AJAX usando esta infraestrutura.

O diretório inc, o mais volumoso, contém essencialmente as funções que constróem as páginas da área restrita enviadas ao cliente. No longo prazo, essas funções deverão tornar-se filtros usados pelos ficheiros de exec, quando estes passarem a ser templates.

Se olharmos o SPIP pelo arquétipo Modelo-Visão-Controlador, os ficheiros de inc correspondem a Vue. Se olharmos o SPIP pelo arquétipo (Print(Eval(Read))) do Lisp, trata-se da parte Print. No entanto, esse diretório contém igualmente diversas funções relevantes para o Controle e precisará ser reorganizado. A maioria dos ficheiros de inc são carregados por meio de charger_fonction e, nofuturo, todos deverão ser carregados desse modo. Nenhuma das funções deste diretório deve usar echo. As contribuições ao SPIP devem respeitar essas regras desde agora.

O diretório install contém exclusivamente as funções necessárias à instalação do SPIP. Cada etapa pode ser substituída ou complementada por outras; a função principal de exec/install.php usa este diretório segundo o mesmo princípio que ecrire/index.php com o diretório exec.

O diretório urls contém ficheiros que definem o mesmo jogo de funções de reescrita de URL. Elas calculam, a partir de um índice numérico numa tabela da base de dados, um URL substituto mais fácil de ler e escrever do que a chamada do script PHP realmente usado pelo servidor HTTP para esse índice e essa tabela. Aqui, novamente, basta incluir um ficheiro nesse diretório para obter um novo conjunto de regras, cujo nome estará presente no painel de configuração da área restrita que gere os tipos de URLs.

O diretório lang contém exclusivamente arquivos de dados, matrizes indicando a tradução, para todos os idiomas conhecidos do SPIP, de todos os argumentosque a função _T, definida em inc/utils.php, é passível de receber. Os ficheiros são carregados exclusivamente pelas funções de inc/lang.php. Traduzir os ficheiros de referência *fr* dando um nome convencional aos ficheiros obtidos é o que basta para declarar um novo idioma ao SPIP.

O diretório charset contém, ele também, exclusivamente ficheiros de dados, matrizes que permitem passar de uma codificação de carateres a outra (UTF, ISO, ASCII, entidades HTML etc). São lidos exclusivamente pelas funções de inc/charsets.php. Basta, igualmente, incluir um ficheiro para dispor de uma nova codificação, mas o SPIP já oferece todas correntemente usadas, sendo raríssimo precisar de intervenção.

O diretório base contém as funções de interface entre o PHP e os servidores SQL que o SPIP pode chamar. Em particular, o ficheiro genérico abstract_sql.php contém as funções que ele precisa usar para dialogar com os servidores SQL, as funções básicas do PHP para isso não devem ser usadas diretamente para garantir a portabilidade. Nenhum código MIME deve estar presente nesse diretório.

O diretório req contém as implementações do servidor SQL virtual do SPIP para os servidores reais (MySQL, PG) e equivalente (SQLite).

O diretório balise contém os ficheiros PHP associados às tags dinâmicas do SPIP. Os seus nomes são homónimos do template de squelettes-dist/formulaires. Complementar o espaço público do SPIP com um formulário F consiste em criar um ficheiro F.html no seu SPIP_PATH e um ficheiro F.php num subdiretório balise do seu SPIP_PATH. A função desse ficheiro PHP é de receber os dados de entrada informados por esse formulário e, eventualmente, reapresentá-lo para correção de entradas inválidas. É sem dúvida o tipo de contribuição ao espaço público mais dificil de realizar, pois a mecânica subjacente exige dois passos de execução do PHP, cujos papéis é fundamental compreender.

Antes da introdução desse mecanismo, a estratégia de desenvolvimento de formulários consistia em escrever templates que incluíam instruções PHP. Embora isso ainda seja possível, o resultado será pouco eficaz, pois nunca será armazenado em cache, além de não dispensar a compreensão dos dois passos do PHP inerentes ao processo.

O diretório public contém o compilador dos templates. É uma parte do código bem complicada, mas que se beneficia de uma interface de programação que torna o compilador totalmente estensível sem exigir que se compreenda todos os detalhes.

O diretório lib destina-se a conter os subdiretórios de bibliotecas desenvolvidas fora do SPIP mas que este pode precisar.

Último ponto: a maioria dos ficheiros do SPIP são usados via charger_fonction, que carrega um ficheiro e chama a sua função homónima que se pressupõe estar definida nele. Por consequência, o nome de um ficheiro PHP deve ser composto exclusivamente de caracteres permitidos para nomear funções PHP: devendo-se evitar, assim, caracteres como hífen, ponto etc.

Regras de programação

O SPIP começou na época em que o PHP transformava automaticamente os parâmetros HTTP em variáveis globais. Este estilo de progrmação suicida foi abandonado no PHP4. O SPIP seguiu uma evolução paralela, mas com um ceto defassamento no tempo. Assim, embora o código atual nem sempre siga as regras abaixo, espera-se que as novas contribuições as respeitem desde agora, sem aguardar que o SPIP deixe de as contornar aqui ou ali. Recomenda-se ler atentamente o ficheiro ecrire/articles.php, o mais próximo das especificações recomendadas.

-  Privilegiar a codificação baseada em funções. A filosofia do software livre é possibilitar o seu uso no maior número possível de contextos diferentes; consequentemente, o código deve ser escrito com uma abordagem que permita o reuso além do seu contexto inicial de desenvolvimento. A codificação baseada em funções que não referenciem nenhuma variável global e não recorram a nenhuma chamada echo ou print garante um carregamento silencioso e uma chamada sem efeitos secundários indesejáveis.

-  Evitar ao máximo o uso de variáveis globais. Elas são responsáveis por inúmeras falhas de segurança e impossibilidades de reuso do código. As alternativas ao seu uso são:

• constante, que tem a vantagem de assinalar ao leitor que este valor não será alterado por toda a duração do script;
• variável estática, que tem a vantagem de assinalar ao leitor que trata-se de um valor de vida longa mas que só é relevante para a função que a declarou.

-  O código escrito não produz nenhum erro ou aviso em modo error_reporting(E_ALL). Isto facilita a depuração no caso de variáveis involuntariamente indefinidas. Se for realmente necessário executar um código fora deste modo, deve-se usar o artifício @, limitando-o, no máximo, à porção de código problemático, e prever uma mensagem de erro no log, usando a função spip_log.

-  Comentar o contexto, não o texto. Não é útil parafrasear o nome das suas variáveis e funções, nem as funções PHP descritas no seu manual: comentários como loop na matriz de valores antes de um foreach só engordam desnecessariamente os ficheiros. Por outro lado, é desejável indicar o tipo dos argumentos (como o PHP é uma linguagem tipada dinamicamente, essa informação nem sempre é óbvia) e quais as propriedades esperadas na entrada da função (por exemplo, não-nulo). Quando um bug difícil é corrigido ou antecipado, é útil explicar porque o código inicial estava incorreto, para evitar que uma alteração posterior introduza o problema, acreditando-se otimizar o código. Por fim, como o SPIP é desenvolvido em francês, deve-se evitar termos ausentes dos dicionários do idioma, para facilitar a compreensão por parte dos que não falam a língua nativamente.

-  Nomear racionalmente as funções e variáveis. A organização do código do SPIP baseia-se principalmente na estruturação de diretórios dedicados do que em regras rígidas de nomenclatura; ainda assim, deve-se evitar incoerências como multilinguísmo num mesmo nome. As funç#oes de um mesmo ficheiro tenderão a ter um prefixo ou sufixo comum, inspirado no nome do ficheiro.

-  Testar no máximo de configurações posível. Não se esqueça que o SPIP deve funcionar em todas as plataformas, tanto do lado cliente como do servidor. Há, necessariamente, diversos navegadores no seu computador, teste o seu código em pelo menos dois deles. Na medida do possível, teste também em diferentes alojamentos. Quando uma plataforma obriga a uma codificação peculiar, mencione explicitamente o facto, especificando a sua versão e a data do teste.

Regras de codificação

Consulte a seção Regras de codificação

Ver também

Em programmer.spip.net

• a seção Estender o SPIP

E o site sobre a documentação do código do SPIP