A técnica de manipulação de URL utilizando o MOD_REWRITE, ou muitas vezes chamada de URLs amigáveis, está sendo amplamente utilizada em sites de blogs e notícias entre outros por facilitar a memorização da URL pelo visitante do site e também por facilitar a indexação dos artigos pelas ferramentas de buscas como o GoogleBot.

Esta técnica permite ao desenvolvedor maior flexibilidade e facilidade na criação e manutenção do site. As configurações do MOD_REWRITE são feitas diretamente no arquivo .htaccess e dependem da configuração do arquivo httpd.conf, que é o arquivo de configurações do servidor Apache.

Para ilustrar a idéia de URLs amigáveis temos as duas URLs abaixo sendo a primeira a URL padrão utilizada em sites PHP pelo mundo todo, a segunda é a URL amigável que aponta para a mesma página da primeira URL. Então, qual delas você prefere?

Se você gostou do resultado então continue lendo que agora eu vou mostrar como você pode implementar o MOD_REWRITE em seu site.

Começaremos editando o arquivo de configurções do Apache, o httpd.conf. Neste arquivo vamos habilitar o módulo de reescrita dos diretórios e para isso siga os passos:

Localize as seguintes linhas neste aquivo: (note que elas podem não estar uma abaixo da outra)

Ao encontrar estas linhas remova o # (este que é o caracter de comentário do arquivo). Caso Não encontre estas linhas no arquivo, adicione-as.

Agora localize no arquivo de configuração as seguintes linhas:

Localizada as linhas, substitua a palavra None por All, isso irá permitir a reescrita de diretórios. Agora essas linhas devem ter ficado da seguine maneira:

Após realizadas as operações vamos salvar o arquivo e reiniciar o servidor Apache, para que as novas configurações entrem em funcionamento.

Agora vamos criar o arquivo .htaccess, note que este arquivo não tem um nome, somente uma extensão. É este arquivo que manipula as propriedades do diretório atual e de seus subdiretórios. Começaremos o arquivo com a instrução: "RewriteEngine on".

Coloque este arquivo na raiz do seu site.

O padrão utilizado para o comando RewriteRule é o seguinte:

RewriteRule URL_VIRTUAL URL_FÍSICA

A URL_VIRTUAL é a digitada no navegador, que será reescrita de acordo com uma expressão regular. A presença do [L] no final da linha indica que se a expressão digitada no navegador encaixar na espressã do RewriteRule ele para por ali, se não tiver este [L] o servidor continua testando pra ver se encaixa em mais alguma outra regra.

Prontinho, agora o URL amigável já deve estar funcionando no seu site, no padrão de URL mostrado no início deste artigo. Agora você precisa testar no arquivo artigo.php se as variáveis $cod e $pag estão vazias, para evitar que apareça algum erro.

Documentar bem um código é essencial para o desenvolvimento e manutenção de projetos, principalmente quando esses projetos têm uma equipe de desenvolvimento por trás.

Para projetos em PHP existe uma poderosa ferramenta, o PHPDoc, que é baseado no JAVADoc (ferramenta de documentação da Sun). O objetivo desta ferramenta é padronizar a documentação dos códigos criados em PHP.

O PHPDoc é um projeto Open Source e é distribuído sobre PHP Licence, o que significa que você pode utilizá-lo comercialmente em seus projetos.

Como o PHPDoc funciona?

Basicamente o PHPDoc lê todo o código fonte do projeto procurando por tags especiais (segue uma lista logo abaixo). Com base nessas tags a ferramenta cria a documentação do projeto em diversos formatos como: chm (Windows help), html, pdf, xml.
As tags sempre devem iniciar com @(arroba) dentro dos comentários. Estes comentários, para serem legíveis para o PHPDoc, seguem o seguinte modelo:

Segue a lista com a maioria das tags aceitas pelo PHPDoc:

  •@access - controle de acesso para um elemento. Se for definido como private o elemento não constará na documentação
  •@author - utilizado para indicar o autor de qualquer elemento que possa ser documentado (variáveis globais, funções, classes, métodos, etc.). Nesta tag pode-se adicionar o e-mail entre os sinais de < e >
  •@category - especifica a categoria para organizar os pacotes dos elementos documentados
  •@copyright - informações de copyright do elemento.
  •@deprecated - indica que o elemento está depreciado, sendo assim não deve ser utilizado por pode ser removido posteriormente
  •@example - inclui um arquivo externo de exemplo com sintaxe destacada
  •@final - indica que um método de uma classe nunca deve ser sobrescrito em uma classe filha
  •@filesource - cria a referência cruzada para o arquivo que contem o código fonte
  •@global - documenta uma variável global. Também é utilizado para métodos/funções
  •@ignore - previne o elemento de ser documentado, normalmente utilizado para elementos duplicados
  •@internal - define a documentação como privada, ou seja interna ao projeto
  •@licence - exibe o link para a url que referencia a licença de uso
  •@link - exibe um link na documentação
  •@package - define um pacote para agrupar as classes ou funções
  •@param - documenta um parâmetro da função
  •@return - documenta o retorno de uma função
  •@see - exibe um link para a documentação de um elemento
  •@since - indica desde qual versão o elemento foi adicionado ao projeto
  •@static - documenta uma variável ou método estático
  •@todo - indica as mudanças que serão realizadas no futuro
  •@version - indica a versão do elemento
  •inline {@internal}
  •inline {@inheritdoc}
  •inline {@link}

Bom agora que já conhecemos a maioria das tags do PHPDoc fica extremamente fácil aplicar esse padrão de documentação visando o bom entendimento e relacionamento entre as partes envolvidas na codificação do projeto.

O que vou mostrar agora é um exemplo de código que será documentados pelo PHPDoc.

A instalação do PHPDoc é muito tranqüila, segue o link com o tutorial de instalação: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/ric_INSTALL.html

Bom é isso pessoal, documentar é uma coisa simples mas de suma importância para o desenvolvimento de nossos projetos. Espero que tenham gostado do artigo e que passem a utilizar esse método de documentação em seus projetos.

Referência: PHPDocumentator (http://manual.phpdoc.org/)