Classe de Notificações em PHP

Numa aplicação web, pode ser útil notificar os utilizadores de algo. Por exemplo, avisar sobre a recepção de uma mensagem privada, ou que algum registo foi actualizado, são notificações.

Com recurso a sessões, podemos facilmente criar uma classe que nos auxilie na criação de notificações que serão mostradas mais tarde ao utilizador.

Documentação

A classe requer que o PHP instalado seja igual ou superior à versão 5, devido ao uso de características exclusivas de POO introduzidas nesta versão.

A ideia da classe é usar uma metodologia semelhante à de uma fila de mensagens, em que conforme cada uma vai sendo lida, também é eliminada. A classe conta com 6 métodos públicos que podem ser usados para gerir a lista de mensagens:

• string getMessage() permite obter a mensagem mais antiga colocada na lista de mensagens, removendo-a em seguida. É retornado o valor FALSE caso não existam mensagens.
• string[] getAllMessages() permite obter todas as mensagens da lista de mensagens, eliminado-as de seguida. É retornado o valor FALSE caso não existam mensagens.
• int numMessages() permite obter o número de mensagens da lista de mensagens.
• bool hasMessages() permite verificar se existem mensagens na lista de espera: retorna TRUE se existirem uma ou mais mensagens, ou FALSE se não existirem mensagens.
• void putMessage(mixed message) permite passar uma string ou um array de strings para a lista de mensagens. No caso dos arrays, cada mensagem será extraída individualmente e armazenada na lista.
• void clearMessages() permite limpar toda a lista de mensagens, eliminado todas as mensagens existentes.

Código PHP

<?php
/**
 * Sistema de Notificações Simples
 * Dependências:
 *  -> funcionalidade de sessões do PHP
 *  -> PHP 5 ou superior
 */
class Notifications {

    private $notifications;

    /**
     * Construtor da classe, inicializa as sessões
     */
    function Notifications() {
        if (!@session_start())
            die ('Unable to start Notifications class!');

        if (!isset($_SESSION['Notifications']))
            $_SESSION['Notifications'] = array();

        $this->notifications = &$_SESSION['Notifications'];
    }

    /**
     * Obtém a mensagem mais antiga disponível, e remove-a da lista
     * Devolve FALSE se não existirem mensagens
     */
    function getMessage() {
        $result = $this->notifications;

        if (empty($result))
            return FALSE;

        return array_shift($this->notifications);
    }

    /**
     * Devolve todas as mensagens existentes e elimina-as da lista
     * Devolve FALSE se não existirem mensagens
     */
    function getAllMessages() {
        $result = $this->notifications;
        $this->notifications = array();

        return (!empty($result) ? $result : FALSE);
    }

    /**
     * Devolve o número de mensagens existentes na lista
     */
    function numMessages() {
        return count($this->notifications);
    }

    /**
     * Verifica se existem mensagens em espera
     */
    function hasMessages() {
        return ! empty($this->notifications);
    }

    /**
     * Coloca uma mensagem no fim da lista
     * Se for usado um array, as mensagens são adicionadas individualmente
     */
    function putMessage($theMessage) {
        if (is_array($theMessage))
            $this->putMessages($theMessage);
        else
            $this->notifications[] = $theMessage;
    }

    /**
     * Coloca várias mensagens de um array na lista
     * Se for usado um array multidimensional, cada campo será extraido e colocado na lista
     * Uma vez que esta função é privada, deve-se usar a função putMessage para colocar
     * mensagens em arrays
     */
    private function putMessages($messageArray) {
        foreach ($messageArray as $m)
            $this->putMessage($m);
    }

    /**
     * Limpa a lista de mensagens, eliminando mensagens exisitentes, sem as devolver
     */
    function clearMessages() {
        $this->notifications = array();
    }
}

Exemplo de uso

mostraNotificacoes.php

<h1>Página de notificações</h1>
<?php
  // incluir a classe de notificações
  include_once('Notifications.class.php');

  $notif = new Notifications();

  if ($notif->hasMessages()) {
    $total = $notif->numMessages();
    printf('Tem %d notificações<br/>', $total);

    echo '<ul>';
    foreach ($notif->getAllMessages() as $msg)
      printf('<li>%s</li>', $msg);

    echo '</ul>';

    echo '<p>As notificações foram apagadas</p>';

  } else {
    echo "Não tem notificações";

  }
?>
<a href="insereNotificacoes.php">Inserir notificações</a>

insereNotificaoes.php

<?php
  if (!empty($_POST['inserir'])) {
    // incluir a classe de notificações
    include_once('Notifications.class.php');

    $notif = new Notifications();

    $msgs = $_POST['messages'];
    $messages = explode(';', $msgs);

    $notif->putMessage($messages);

    echo '<p>As mensagens foram inseridas. <a href="mostraNotificacoes.php">Ver mensagens</a></p>';
  }
?>

<form method="POST">
<p>Introduza as notificações. Para passar várias mensagens, separe-as por ; (ponto e vírgula)</p>
<textarea name="messages"></textarea>
<input type="submit" name="inserir" value="Adicionar" />
</form>

Limitações

Quando o utilizador abre vários separadores ou páginas do mesmo site, pode haver mensagens em contextos errados porque as mensagens não estão orientadas em contextos, mas sim em ordem de requisições. Por isso, podem ser apresentadas mensagens que na verdade deveriam ser mostradas noutras páginas, porque a classe não distingue as mensagens que devem ser entregues em cada página.