Configurando o Zend Debugger

Conforme prometido no Review do Zend Studio 7 , estarei tentando facilitar a configuração do Zend Debugger e também do Zend Studio na máquina.

É um processo teoricamente simples e sem mistérios, porém, o que muito vejo são pessoas com dificuldades em utilizá-lo da maneira correta. Acho que falta as vulgas tips para reduzir tais incidentes.

Vou dividir a configuração básica em duas partes. São elas:

1. Configurando o Zend Debugger no Windows
2. Configurando o Zend Debugger no Linux

Após a configuração particular em cada ambiente, teremos:

• Configurações no Zend Studio (comum para ambos ambientes)
• Configurações na Zend Toolbar
• Exemplos de uso
• Troubleshoot

Note que após baixar o Zend Studio, você não precisará de mais nada pois o pacote de mais de 300MB trás consigo além do Zend Studio os itens:

• Manual do PHP
• Manual do Zend Studio
• Zend Debugger (vamos precisar)
• Zend Toolbar for Mozilla Firefox, Internet Explorer e Google Chrome (vamos precisar)
• PHP 5.2 e PHP 5.3
• PHPUnit plugin
• Ambiente JRE (Java Runtime Environment - para rodar o Zend Studio)
• Todos plugins que o Zend Studio tem por default

Nota: desative quaisquer outros debuggers. Isto inclui o famoso Xdebug. Ao final explico como deixar ambos ativados – e falo o porque de ambos ativos antes que alguém me xingue =P

1. Configurando o Zend Debugger no Windows

Vou usar aqui a variável $ZEND_DIR para designar o caminho até a instalação do Zend Studio. No meu caso é: C:\Program Files\Zend\

Misteriosamente no Windows a biblioteca ZendDebugger.dll que acompanha o Zend Studio não funciona. Também não é para menos: a disponível no site tem 893kb, contra 132kb da que acompanha o Studio. No Linux isto não ocorre, tornando tudo mais estranho ainda. De qualquer modo, perguntei para eles o motivo.

Então, nosso primeiro passo é baixar o ZendDebugger do site . Após baixar, descompacte o conteúdo em um diretório temporário e copie apenas a biblioteca ZendDebugger.dll para o diretório que você vai criar: $ZEND_DIR\debug. Deverá estar assim:

Procure seu arquivo php.ini – caso não saiba onde esteja um php -i ou rodar o phpinfo() no servidor pode ajudar

Ao final dele você deve colocar:

; The section name is optional, but it's always a good idea to add it,
; especially if you are not using a separate file
[Zend]

; This directive needs the full path to the Zend Debugger DLL.
zend_extension_ts="C:\Program Files\Zend\debug\ZendDebugger.dll"

; This directive allows Zend Debugger to start a debug session with:
; 127.0.0.1/32 - Zend Studio on the same computer
; 192.168.0.1/32 - Zend Studio on a computer with IP address 192.168.0.1
; 10.0.0.0/8 - Zend Studio on any computer with IP starting with 10.
zend_debugger.allow_hosts=127.0.0.1/32

; This directive allows Zend Debugger to expose itself
; upon request (this is used in some service functionality).
; The possible options are:
; never - do not expose (default)
; always - expose to whoever wants to know
; allowed_hosts - expose only if the request comes from an IP listed above
zend_debugger.expose_remotely=always

Certifique-se do caminho correto em zend_extension_ts e em allow_hosts, caso queira adicionar mais IPs, apenas coloque uma virgula separando-os.

Agora procure por:

; Implicit flush tells PHP to tell the output layer to flush itself
; automatically after every output block.  This is equivalent to calling the
; PHP function flush() after each and every call to print() or echo() and each
; and every HTML block.  Turning this option on has serious performance
; implications and is generally recommended for debugging purposes only.
implicit_flush = On

Certifique-se que esteja On. Reinicie seu Apache, Lighttpd, IIS,…

Acessando seu phpinfo() novamente, você deverá ver a entrada do Zend Debugger:

Com isto a instalação do Zend Debugger está concluída. Em caso de problemas, certifique-se do caminho até a DLL do ZendDebugger ou ainda tente desativar os debuggers que você possa ter instalado ou ainda extensions adicionais para cache, performance e etc.

2. Configurando o Zend Debugger no Linux

Diferentemente do Windows, a instalação no Linux não requer baixar o ZendDebugger do site, pois a versão que acompanha o Zend Studio funciona perfeitamente igual

Assumindo $ZEND_DIR como diretório base do Zend Studio. No meu caso é: /usr/local/Zend/

Localize seu php.ini . Como eu instalo tudo separado, o meu encontra-se em /etc/php/php.ini. Você pode usar o comando # find / -name php.ini para localizá-lo ou ainda, rodar o phpinfo() que também serve.

Ao final do arquivo, coloque:

[Zend]
zend_extension="$ZEND_DIR/ZendStudio-7.1.1/plugins/org.zend.php.debug.debugger.linux.x86_64_5.3.7.v20091116/resources/php5/ZendDebugger.so"
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always
[Debugger]
zend_extension_manager.debug_server_ts="$ZEND_DIR/ZendStudio-7.1.1/plugins/org.zend.php.debug.debugger.linux.x86_64_5.3.7.v20091116/resources/php5/"
zend_debugger.expose_remotely=allowed_hosts

O caminho não há quebra de linha

Note a versão do meu Zend Studio. Isto pode acabar mudando a versão do plugin também.

 org.zend.php.debug.debugger.linux.x86_64_5.3.7.v20091116

O seu pode ser bem diferente disto. até o .linux deverá ser semelhante. Depois disto, vem a arquitetura do sistema operacional (aqui é 64bits) a versão do Debugger e por fim a versão de atualização. Com um ls no diretório de plugins você acha a versão correta ao seu caso.

Procure ainda no php.ini por:

; Implicit flush tells PHP to tell the output layer to flush itself
; automatically after every output block.  This is equivalent to calling the
; PHP function flush() after each and every call to print() or echo() and each
; and every HTML block.  Turning this option on has serious performance
; implications and is generally recommended for debugging purposes only.
implicit_flush = On

Certifique-se de que esteja On. O comentário acima do comando já diz o porque temos que deixá-lo ativado =P
Salve e reinicie o Apache ou Lighttpd.

Acesse seu phpinfo e você deverá encontrar as seguintes entradas:

Com isto sua configuração no Linux está concluída

3. Configurações no Zend Studio

Assumindo que seu Zend Debugger está devidamente instalado, vamos as configurações no Zend Studio:

Certifique-se de possuir uma configuração semelhante.

Na linha PHP Debugger, clique em Configure…
Selecione o Zend Debugger na listagem e  clique em Configure

Mantenha essa configuração. Muito provavelmente você não precisará editar nada. Atenção apenas para o Client Host/IP:

Retornando à primeira tela, agora na linha Server: clique em PHP Servers…
Selecione Default PHP Web Server e clique em Edit

Muita atenção nesta parte: tudo que estiver listado ali será reconhecido pelo Zend Debugger como parte do projeto e portanto passível de debugar. O que não constar ali ele simplemente terá como “ok” e mesmo que você venha a colocar um breakpoint no código que não está contido no Path Mapping, ele irá ignorá-lo.

Por padrão, todo projeto que você cria no Zend Studio, ele automaticamente seta o próprio projeto na lista, e cada projeto tem o seu próprio Path Mapping. Por isso mesmo eu com 6 projetos setados na minha Workspace ele apenas está listando o projeto que está atualmente aberto. Caso eu abra e peça para ele debugar outro projeto, ele adiciona a lista esse meu outro projeto automaticamente.

Certo. Se ele adiciona automaticamente porque tenho que saber disto ?
Simples ! Você pode estar usando bibliotecas de terceiros ou usando sua própria biblioteca e não tê-la incluida ali significa que o Zend Studio não irá debugá-la.

Para finalizar, copie o conteúdo que coloquei online e salve-o como dummy.php na raiz de seu Servidor HTTP. Ele deverá estar acessível através do http://seuip/dummy.php e não é necessário colocar um em cada projeto, porém se você usa virtualhosts deverá ser um por virtualhost. Sem isto, o Debugger não funciona. A Zend disponibiliza este arquivo porém eu não me recordo se vem com o ZendDebugger ou se eu o peguei de outra fonte no site deles.

Neste ponto você já pode debugar um Script PHP ou uma URL que você forneça. Explicarei isto mais abaixo na parte Exemplos de uso.

4. Configurando o Zend Toolbar

Durante a instalação ele configura a Zend Toolbar para o Internet Explorer. Para configurá-la no Firefox é simples:

Com o browser aberto acesse o caminho: $ZEND_DIR/ZendStudio-(sua_versao)/toolbars e clique em ZendFirefoxToolbar-2.2.xpi.
Instale e reinicie o Mozilla Fx.

Após reiniciar o Firefox e com o Zend Studio aberto, vá na ZendToolbar em Extra Stuff -> Settings

Certifique-se do caminho setado em Zend Studio Executable que geralmente vem errado e o Zend Studio Broadcasting Port que deverá ser igual ao meu.
Após isto, clique em Test e o resultado deverá ser:

Com isto a configuração do Zend Studio, Zend Debugger e Zend Toolbar estão concluídas.

5. Exemplos de uso

Para exemplificar melhor, vamos criar um pequeno projeto no Zend Studio.
New -> PHP Project

Coloque o nome Zend ou qualquer outro e finalize.

Ele terá três arquivos: São eles: Foobar.php Finaliza.php e index.php . Salve-os em seu projeto.

Acesse http://seuip/projeto/index.php com o Mozilla Firefox. Deverá aparecer na tela o conteúdo:

Uma string qualquerFinalizando

Agora, clique em Debug na Zend Toolbar. Talvez ele pergunte sobre abrir a perspectiva de Debugging. Marque para sempre tomar esta ação e dê ok.

Note que ele está parado na primeira linha do arquivo:

Suas opções são:

• F5: entra no método/classe que esteja dentro do seu Path Mapping. Caso não esteja, ele executa a ação normalmente e vai para a próxima instrução.
• F6: executa a linha corrente e segue para a próxima instrução
• F7: executa a linha corrente e sobe um nível (usando quando você aperta F5 sem querer :p)
• F8: executa todo até encontrar um breakpoint
• Ctrl + F2: mata a sessão de debugging sem finalizar o script.

Estas opções que listei, você encontrará na barra que está na aba Debug.

Aperte F6 até ele ficar sobre a linha 6, $objFoo = new Foobar(); e então, aperte F5.Note que ele abriu a classe Foobar e parou sobre a primeira linha dentro do construtor da classe. Repare na aba Variables que até aquele ponto, a variável membro baz está nula.

Pressionando novamente F5 ou F6, você será enviado para a linha que contém a chave que fecha o método construtor. Neste ponto, baz possui o valor bar que contém três caracteres.

Apertando F6 ou F5 novamente, ele retornará a index.php sob a linha $objFoo->finaliza(). Caso decida pelo F5, ele entrará no método. Caso F6, ele executará a ação do método (e seus subníveis) e passará para a próxima instrução – que em nosso caso seria a próxima linha.

Siga com F5 ou F6 até o término do script para acompanhar a evolução e modificação das variáveis.

Breakpoints

Quem nunca usou um debug, talvez não conheça o que venha a ser um breakpoint. Ele na forma literal é um ponto de parada do debug

Vamos como exemplo, setar um na classe Foobar na linha 20. Para tal, você pode clicar duas vezes ao lado do número que identifica a linha ou então, com o cursor sobre a linha usar Ctrl + Shift + B

Um ponto ficará ao lado da linha identificando que há um breakpoint ativo. Novamente clique em Debug na toolbar. Ao abrir o Debug na primeira linha, pressione F8. Ele deverá parar sob nosso breakpoint.

Na aba Breakpoints você pode desativar ou remover os breakpoints setados sem necessitar abrir arquivo por arquivo para removê-los.
É possível definir condição para que o Debugger pare sobre determinado breakpoint. Para definir a condicional, clique com o botão direito sobre o breakpoint e vá em breakpoint properties.

Ao lado do botão Debug na Zend Toolbar, há o Debug Menu . Nele há quatro opções: Current Page; Next Page; All forms (POST) in this site; All pages in this site. Recomendo que crie formulários, teste em chamadas Ajax, iframes (argh!), redirecionamentos HTTP e tudo mais que use no seu dia-a-dia. O Debugger pega qualquer ação no browser

E como brinde por ter configurado o Zend Debugger, você tem o Profile da página atual. Bastando para tal clicar em Profile.

Enjoy

6. Troubleshoot

Habilitando o Xdebug junto com o Zend Debugger

A utilidade disto é que o Xdebug fornece recursos como: highlight de variáveis var_dump() – que não vamos mais usá-la como debugger – controle contra loopings infinitos, o trace completo quando encontramos Warning ou Fatal Errors e alguns outros mimos que o Zend Debugger não trás – ou eu os desconheço

Para habilitar ambos, abra seu php.ini. E mude a entrada do Xdebug de:

;zend_extension=php_xdebug.dll

para

extension=php_xdebug.dll

O mesmo vale para a versão Linux, mudando apenas para .so

Ele não para sob os breakpoints que setei

Verifique o Path Mapping se o mesmo contém seu projeto listado. Caso não, adicione manualmente o projeto ao Path Mapping e tente novamente.

Uso biblioteca externa – Propel, Symfony, Zend.. e toda vez que chamo o debugger recebo a tela:O problema é novamente o Path Mapping. Adicione o caminho da sua lib externa ao Path Mapping (veja como na sessão de configuração do Zend acima) e tente novamente.

Para finalizar…

Há um excelente artigo em inglês que explica como configurar o ZendDebugger no Linux e Windows e ainda explica o funcionamento do Debugger sobre a aplicação web. Vale a pena a leitura.