Importante: este artigo esta bastante incompleto, além de listar os módulos preciso colocar como configura-los.

Primeiro, o que é SEO? Search Engine Optimization, significa fazer o seu site mais amigável para as ferramentas de busca, para que eles possam indexar o seu site de maneira mais fácil e completa, isso faz com que ele aparece mais próximo aos resultados iniciais em uma pesquisa, por exemplo, no google ou no yahoo.

Aparecer mais próximo do início tem uma vantagem obvia, que é a de trazer mais visitantes para o seu site, objetivo de quase todos os sites .

Não é uma tarefa complicada, mais uma questão de várias pequenas tarefas, e no Drupal estamos muito bem servidos de ferramentas para isso, na minha opinião, muito mais do que no Joomla, isso também é devido a maneira que o Drupal esta organizado, onde cada conteúdo corresponde a um node, e é possível especificar um endereço próprio para cada node.

URLs Limpas

O Drupal possui uma configuração chamada URLs limpas, esta configuração muda a maneira com que os endereços são usados pelo Drupal. O padrão é algo como exemplo.com/index.php?q=node/10. Este padrão é muito ruim em termos de SEO, porque a ferramenta de busca precisa entender que "q=node/10" é uma pagina de conteúdo e não apenas um parâmetro passado via GET.

Há muito tempo atrás eu e o Guilherme jogávamos o Poring, um jogo para o celular. Com a intenção de colocar guias diversos criamos um subdomínio para o jogo. Ficou algo bom e na época que cuidávamos ativamente teve visitas e participação, mas com o tempo a desenvolvedora abandonou o servidor BR, que ficou sempre esteve atrasado nas atualizações, mas acabou ficando um jogo moribundo sem ninguém cuidar. No final do ano passado o jogo foi finalmente retirado do ar, então não tem mais sentido em ter um site com guias para ele.

Obrigado a todos que visitaram e participaram dele.

Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.

Escrevendo documentação externa e criando links da documentação do código fonte.

Mesmo sendo a documentação interpretada direto do fonte muito útil, ela não pode suportar por sí só. Em adição, documentação verdadeiramente útil deve ser sucinta o suficiente, se não o código fonte é obscurecido pela documentação. Documentação externa é um dever para uma solução de documentação completa. Entretanto, a documentação externa deve ser ligações com a documentação da API para ser útil. Com as constantes mudanças da documentação da API, é muito fácil para a documentação externa se tornar desatualizada. Além disso, a documentação externa deve estar em um formato que possa ser convertido para outros formatos como HTML, PDF e XML.

phpDocumentor prove uma simples e elegante solução para este problema. Documentação externa do formato DocBook pode ser facilmente convertida para outros formatos. Usando tags inline, o  phpDocumentor pode gerar um manual consistente em vários formatos combinando a saída da interpretação do código fonte com a documentação externa.

Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.

Usando tags HTML

A partir do phpDocumentor 1.2.0, a descrição longa e curta do bloco de documentação é interpretada para algumas poucas tags HTML que determinam formatação adicional. Devido a natureza de múltiplos formatos de saída do phpDocumentor, HTML puro não é permitido em um bloco de documentação, e será convertido para texto simples por todos os conversores a menos que seja uma das seguintes tags:

Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.

Esta é uma lista das opções em linha de comando aceitas pelo phpdoc, várias destas opções podem ter mais de um argumento como nomes de arquivos e diretórios, neste caso são separados por "," (vírgula).

-c --config

Faz com que seja utilizado um arquivo de configuração. Vou explicar mais sobre isso em outra pagina, para mim essa é a melhor maneira de usar do que ficar especificando a cada vez as opções que eu quero.

-cp --converterparams

Define dinamicamente parâmetros para um conversor, separe os valores com virgulas

-ct --customtags

Uma lista separada por virgula de @tags que não sejam padrões para passar para o conversor como válidas(quando você adiciona suas próprias tags)

-d     --directory  

Nome do diretório(s) a serem interpretados

-dc     --defaultcategoryname  

Nome da categoria padrão, se não for especificado usa 'default'

-dh     --hidden

Define como on (-dh on) para que diretórios ocultos também sejam interpretados (diretórios que começam com "."), o padrão é off (diretórios ocultos não serão interpretados).

-dn     --defaultpackagename

Nome do pacote padrão, se não for especificado será usado 'default'

-ed     --examplesdir

Caminho completo do diretório onde procurar os arquivos de exemplo das tags @example.

-f     --filename

Nome dos arquivos a interpretar. Pode ser um caminho completo e pode se utilizar os coringas * e ?.

Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.

Existem dois métodos oficiais. O primeiro e através de copiar e extrair um dos arquivos disponíveis em http://sourceforge.net/projects/phpdocu/files (atualmente na versão 1.4.3), e a outra é através do instalador PEAR. É importante notar que a instalação funciona da mesma maneira, tanto no Windows quanto no Linux, para as duas opções existentes.

Instalação através de um arquivo copiado

Para instalar o phpDocumentor a partir de um arquivo zip copiado diretamente de sourceforge.net, primeiro determine se você estará usando a interface via web ou a interface de linha de comando(acho a interface de linha de comando bem mais pratica de usar, embora levemente mais complicada de usar)

Para usar a interface de linha de comando, descompacte o arquivo em qualquer diretório, por exemplo, /home/myuser/phpdoc ou C:\phpdoc, e adicione este diretório ao seu PATH. Para executar, use o comando "phpdoc". No windows você vai precisar editar o arquivo the phpdoc.bat, e mudar a primeira linha para o caminho da versão CLI do seu PHP (normalmente C:\php4\cli\php.exe por padrão).

Você também pode fazer assim, supondo que você tenha o php instalado em c:\php, e que tenha descompactado o arquivo zip do phpdoc em c:\phpdoc, abra uma janela do prompt de comando, nesta janela do prompt de comando digite:

Importante: escrevi toda esta documentação há um tempo atrás para a versão 1.4.3 do phpDocumentor. No entanto agora existe a versão 2. Acredito que quase tudo escrito aqui se aplica também a versão 2, mas ainda preciso revisar todo este conteúdo para corrigir qualquer eventual diferença.

Aqui estão todas as tags, ainda preciso descrever melhor algumas delas, assim como pretendo logo colocar exemplo em todas.

Esta é uma lista das tags e o que elas descrevem:

@abstract

Use a tag @abstract para declarar um método, variável de classe, ou classe que deva ser redefinida em uma classe filho para ser válida.

@access

Controla o acesso ao próximo elemento. Se @access é private, o elemento não será documentado a menos que a opção de linha de comando --parseprivate seja especificada.

@author

A tag @author é usada para documentar o autor de qualquer elemento que possa ser documentado. O phpDocumentor irá pegar qualquer texto entre maior que e menor que (< and >) e tentar interpretar como um endereço de email criando um link na pagina para enviar email, exemplo:

/**   
*@author Fernando Conceição <conceicao.fernando@gmail.com>
*/

@category

A tag @category é usada para organizar grupos de pacotes juntos. Isto é diretamente aplicável ao conversor XML:DocBook/peardoc2 e pode ser usado pelos outros conversores. Outros conversores embutidos no phpDocumentor ignoram a categoria, mas isso pode mudar em versões futuras. Também é possível especificar dinamicamente a categoria usando a opção de linha de comando -dn, --defaultcategoryname

@copyright

A tag @copyright é usada para documentar as informações de direitos autorais de qualquer elemento que possa ser documentado. O phpDocumentor irá exibir o conteúdo desta tag sem nenhuma alteração.

Documentando seu fonte PHP com comentários

Todos os blocos de documentação são um comentário no estilo C com dois asteriscos após a barra, como mostrado abaixo:

/**  
 *
 */

Todos os outros comentários são ignorados pelo interpretador da documentação. Note que mesmo sendo quase toda a documentação escrita em texto puro, existem alguns caracteres "@" flutuando pelo código fonte. Este símbolo é usado como um comando especial para o interpretador, e é chamado de tag. Se o símbolo esta no início da linha, é uma tag padrão, se esta contido em {chaves}, é uma tag inline.

/**
 * {@inlinetag}
 * esta @não é uma tag padrão - deve iniciar uma linha.
 * isto é valido também {@inlinetag}
 * @tagpadrão
 */

Documentando variáveis globais

Veja este exemplo de código:

/**
 * Bloco de documentação especial para variáveis globais
 * @global integer $GLOBALS['_myvar']
 * @name $_myvar
 */ 
$GLOBALS['_myvar'] = 6;

Neste segmento, você pode ver duas tags importantes ao documentar variáveis globais. A tag $global é usada para indicar ao interpretador como encontrar a declaração de uma variável global. Sem esta tag, não será gerada documentação para $_myvar. A tag @global pode ter várias formas - tenha certeza de especificar o tipo e o nome global, sem descrição, ou o interpretador irá gerar um aviso e falhar na interpretação da variável global. Avisos de bloco de documentação a nível de pagina

O Phing( PHing Is Not GNU make ) é uma ferramenta de build que foi baseada no ant (uma ferramenta de build bastante conhecida para java). São utilizados arquivos xml com as configurações das tarefas.

Pode parecer exagero ir criando tarefas, mas conformo você for utilizando verá que ajuda bastante, principalmente quando você tem que fazer a mesma coisa repetidas vezes, então você irá acabando por criar scripts em php ou bash para estas tarefas. Acredito que criar estes mesmos scripts usando o Phing seja mais pratico.

O próprio Phing possui muitas tarefas que você pode executar facilmente, e também você pode criar as suas próprias, por exemplo, eu uso uma tarefa que facilita o uso do Drush.

Mais adiante vou colocar exemplos de algumas tarefas que eu utilizo aqui no site, alguns exemplos práticos e reais vão ajudar a entender melhor as vantagens dele.

Gosto muito de usar o Phing, mas uma coisa que não entendo é porque ele não possui como passar argumentos pela linha de comando, isto é, você pode passar várias opções do próprio Phing, mas se quiser passar uma opção para a sua tarefa não pode.

Alias, não poder é um pouco incorreto, é possível definir variáveis na linha de comando usando -D, por exemplo: phing minhatarefa -Dvariavel=valor mas para isso você precisa conhecer qual variável quer mudar.

Optei então por fazer uma mudança que me permitisse passar argumentos pela linha de comando de maneira mais simples. Um caso de uso real: quero executar uma tarefa do phpunit, e nessa tarefa preciso passar qual modulo vou testar, então agora em vez de eu precisar escrever phing phpunit -Dmodulo=geshifilter e precisar lembrar a cada vez que o nome da variável é modulo, eu posso simplesmente escrever phing phpunit -- geshifilter para executar a mesma tarefa. Pode não ser tão importante assim escrever um pouco a menos, mas é mais fácil de lembrar e usar.

Em vez de modificar algum arquivo do Phing, o que tornaria necessário fazer a mesma modificação a cada instalação ou versão nova do Phing, eu criei uma cópia com modificações de um que já existia. O Phing possui um arquivo que executa duas linhas de comandos e após inclui o arquivo com o seu código. Neste arquivo eu adicionei algumas linhas que mudam os meus argumentos para os argumentos que o Phing usa(com -D).
Fiz este arquivo com o mesmo nome do Phing, e mudei o PATH para que meu arquivo venha antes. Para poder usar isso basta uma pequena modificação no PATH, sem precisar tocar nada no PATH.