The Blog of a WebDeveloper

O PHP-SimpleEventsSystem é uma simples classe em PHP que permite a qualquer programador criar uma aplicação orientada a eventos em PHP. Sendo assim, esta classe possibilita a criação mais facilmente de aplicações web com possibilidade de adicionar plugins, sem que estes tenham de mexer com o código interno da aplicação, permite que uma framework use internamente a classe PHP-SES e melhorando consideravelmente a interacção entre a framework e a aplicação. Mas permite muito mais, permite até onde a sua imaginação chegar.

Basic Overview

Quem quiser ver a documentação completa da framework, pode aceder aqui. No entanto, aqui vai ficar uma explicação da classe e de como ela funciona, que é bastante simples.

A classe cria um array multi-dimensional onde guarda as funções e o respectivo evento a que elas foram anexadas. Sempre que se anexa uma função, a classe pode ou não verificar se a função existe, conforme os parâmetros que o programador introduzir. Se passar nesse teste, verifica se a função já está anexada a esse mesmo evento, e só depois anexa a função (as funções caso seja um array).

Ao executar-mos um determinado evento, a classe verifica se este existe, e em caso afirmativo, percorre o array com as funções anexadas a esse evento, e executa-as a todas pela ordem com que forma anexadas. Caso a opção Auto_run esteja activa, a função vai ainda percorrer todas as funções definidas pelo utilizador (programador da aplicação, utilizador da classe entenda-se) e verifica se alguma coincide com a formatação obrigatória e com o nome do evento em questão (um_nome_qualquer_handles_nome_do_evento). Se essa função já estiver anexada ao array, e por consequente já tiver sido executada, a classe não a executa novamente. Se ainda não estiver anexada, a classe executa-a e, caso a opção Auto_index esteja activa, indexa a função ao array do respectivo evento.

Sugestões de sintaxe dos nomes dos eventos

Numa aplicação de grandes dimensões torna-se importante a sintaxe que usamos e a forma como organizamos os nomes dos eventos, para que não existam conflitos e seja mais fácil memorizar o grande número de eventos que uma aplicação possa ter. Para isso os nomes dos eventos necessitam de ter lógica, e apesar de serem um pouco compridos, serão óbvios. Primeiro teremos de ter em conta algumas considerações.
Os nomes dos eventos podem conter qualquer carácter, incluindo pontos, que podem servir de separador entre as várias “secções virtuais” do nome do evento. No entanto nomes de eventos com pontos não serão possíveis de aceder através da funcionalidade Auto-Index e Auto-Run pois as funções não suportam, obviamente, este tipo de caracteres no seu nome. Assim sendo, sugiro o uso do underscore como separador.
Em todas as aplicações há uma “secção” que deve existir em todos os eventos, que indica se o evento retrata alguma acção em PHP ou HTML. Ou seja, e apesar de todas as instruções em código PHP sejam de PHP, poderão existir eventos que retratam a impressão de texto para o browser, e assim sendo, o nome do evento deve começar por html_, senão, caso retratem acções PHP, como uma conexão a uma Base de Dados, a leitura de um ficheiro, o fim de um ciclo, a execução de uma qualquer estrutura de controlo, etc., deverão começar por php_.
Para a secção de HTML, podemos ainda destinguir se nos estamos a referir a alguma parte genérica do HTML, como por exemplo, um menu, que seja constituído por vários elementos HTML, deve-se adicionar um generic_ a seguir ao html_, ou seja, ficaria html_generic_menu, por exemplo.
Caso seja em PHP, deve-se adicionar o nome da “categoria” da acção que se está a utilizar. Por exemplo se for uma acção qualquer relacionada com a base de dados MySQL, como inserir um registo, coloca-se o mysq_ depois do php_, ficando, por exemplo, php_mysql_query_insert_user.

Nota: Isto é apenas um exemplo de nomenclatura dos eventos, nada de obrigatório.

Exemplos e Demos

Plugins

Actualmente, é quase obrigatório qualquer aplicação, seja ela Web ou Desktop, suportar plugins. Só que isto é muitas vezes uma fonte de dor de cabeça para quem programa em PHP, criar um sistema versátil suficiente para suportar plugins. O PHP-SES permite a criação de Aplicações Web que facilmente suportam plugins. Vamos ver o seguinte exemplo.

require("..\..\Events.php");
 
//Inicia a configuração
Events::setConf("Auto_run", true);
Events::setConf("Auto_index", true);
 
//Carrega os nomes ficheiros dos plugins.
$plugins = scandir("plugins");
 
//Percorre o array com todos os ficheiros de plugins
foreach ($plugins as $index=> $file_name){
        //Verifica se o index actual é um ficheiro e não uma pasta
        if (is_file("plugins/".$file_name)){
                //Inclui e executa o plugin
                require("plugins/".$file_name);
                //Por uma questão de segurança e para não comprometer o funcionamento da aplicação
                //Depois de se carregar um plugin deve-se sempre habilitar a classe
                //Para não se dar o caso de algum plugin a desabilitar e não a habilitar novamente.
                Events::Enable();
        }
}
 
 
echo '< !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8856-16" />';
        //Declara uma variável que permitirá adicionar conteúdo dentro dos plugins para a página
        $content = "";
        //Corre todos os eventos anexados para quando os headers HTML são mostrados
        //Esta é apenas um exemplo da sintaxe para o nome dos eventos.
        Events::Run("html_headers");
        echo $content;
        echo '<title>';
 
        $content = "PHP-SES Plugins Example";
 
        Events::Run("html_show_title");
        echo $content.'</title>
</head><body>';
 
echo "<h1>Título</h1>";
 
$content = "<a href=\"#\">Link1</a><br />";
//Aqui corre os eventos que permitem alterar o menu
Events::Run("html_generic_body_menu");
 
echo $content;
echo '</body>
</html>
'

JavaScript Events

Muitas vezes torna-se cansativo estar a chamar vários exemplos por AJAX, ou até fazer a verificação no PHP através de QueryStrings. Assim sendo, e com este exemplo aplicado, basta, no evento JavaScript, chamar uma função, JavaScript também, o nome do evento em PHP, e depois é só ir adicionando funções PHP ao código PHP.

index.php

< ?php 
require("..\..\Events.php");
 
?>
< !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8856-16" />
        <script type="text/javascript">
        function RunEvent(event_name){
 
                if (window.XMLHttpRequest){// code for IE7+, Firefox, Chrome, Opera, Safari
                        xmlhttp=new XMLHttpRequest();
                } else {// code for IE6, IE5
                        xmlhttp=new ActiveXObject("Microsoft.XMLHTTP");
                }
 
                xmlhttp.onreadystatechange=function(){
                        if (xmlhttp.readyState==4 && xmlhttp.status==200){
                                document.getElementById("count_number").innerHTML=xmlhttp.responseText;
                        }
                }
 
                xmlhttp.open("GET","run.php?event=" + event_name + "",true);
                xmlhttp.send();
        }
        </script>
        <title>JavaScript Buttons Example</title>
        </head>
        <body>
        <input type="button" name="btn_sample" id="btn_sample" onclick="RunEvent('html_buttons_click_btn_sample')"  value="Test me. Click me." />
        <div id="count_number">0</div>
        </body>
        </html>

run.php

 
require("..\..\Events.php");
 
if (!defined(IS_AUTH)){
        exit;
}
 
//Se a variável $_GET["event"] não estiver declarada, termina a execução da página.
if (!isset($_GET["event"])){
        echo "Não foi definido nenhum evento.";
        exit;
}
 
//Define algumas configurações para não ser necessário anexar a função.
Events::setConf("Auto_run", true);
Events::setConf("Auto_index", true);
 
//Declara uma função anexada ao clique do botão
function update_file_handles_html_buttons_click_btn_sample (){
        //Vai buscar o número de clicks que o botão já tem
        $number_clicks = file_get_contents("clicks.txt");
 
        //Escreve outra vez para o ficheiro adicionando um clique
        file_put_contents("clicks.txt", $number_clicks + 1);
        echo $number_clicks + 1;
}
 
//Corre todos os eventos associados ao clique do botão.
Events::Run($_GET["event"]);

Pode ver os exemplos em funcionamento, aceda aqui.