Setup apigen to generate documentation

Lately I'm working on some extensions to improve my productivity and also add value to my project.
In the process I tried to implement unit test cases for my project and test them using PHPUnit.
One can find information on that on my post here

Now I'm trying to get some automation to make documentation for my project.
Well in general cases it will be mundane task for each successful build.
People who have seen my last post might think that I'm going to blog about phpDocumentor2 but things are different this time.
I have tried more than couple of tools to generate documentation for my project like

1. yiidocsgenerator
2. phpDocumentor
3. phpDocumentor2 (works for basic implementations)
4. apigen (working for me)

You might want to know why I didn't used above tools to get my documentation done
Before that I need to tell you that our project was a mess in terms of standards so no documenting tool is ready to give perfect output. Our mess includes not managing namespaces correctly for user, admin, vendors end.

1. yiidocsgenerator - Gives errors related to multiple declarations of same class in different places. Gives problem if there is a class which extends a base class and it couldn't get it at parsing time.
2. phpDocumentor - Old UI. More info is thrown out at random places. Not intuitive to read documentation. It gives a feeling that we are reading code and not documentation.
3. phpDocumentor2 - Good UI. For basic documenting it works but when we use configuration file then we might land into problems regarding parser, transformer, target directory.
4. apigen - Works flawlessly and has decent UI to get going.

Leaving apart my failures with other documenting tools I will post my success story with apigen here

One can always look at official documentation

Steps to get documentation done

1. Setup/Installation
2. Basic testing of command
3. Generalizing using config file
4. Testing command using config file

Setup/Installation

This command tells that it needs to resolve any dependencies it faces while installing below package
So we don't have the work of setting up all dependeny packages and their channels.

pear config-set auto_discover 1

Install apigen package for documentation

pear install pear.apigen.org/apigen

Basic testing of command

This is a simple execution to prove that this can document our project

apigen.bat --source C:\Users\sampathv.IE\Documents\Projects\<your project>\protected\components --destination C:\Docs\<your project>\apigen\Doc

Check the destination for index.html. See if the documentation is fine. 

Note: Here I'm documenting only components of my project because it is test and it has less files to parse.

Issue: When I executed only for components, documentation was successful but when I tried whole protected folder then there is an issue related to insufficient memory.
The error was asking me to increase my memory allocated to PHP for processing large amount of files.
Solution: So while researching I came to know that I need to change memory related values in php.ini config file. Initially it was 128M for my installation for which I changed to 512M.
For more information regarding how and where to edit please see these links
http://www.hostucan.com/webmaster-tutorials/increase-php-memory-limit
https://groups.google.com/forum/#!forum/apigen

 

 Generalizing process with config file

We can setup our config file using this official documentation and sample config file

When I used information from both links I faced certain problems like

Issue : I faced certain problems regarding skipDocPath parameter too long (more than 260 characters) because I added more than 15 directories to omit while generating documentation.
Well I could able to solve the issue by reducing the overall directories but there is another problem.
The documentor doesn't understand the skipDocPath parameter and it does document all files in specified project path which is not what you want at times.
Solution : Well I'm still looking into this issue. I think the problem is with relative paths and I don't understand how to give those things in windows environment. Everywhere the documentation is given for only linux paths and no documentation for windows.

After a lot of trials and tinkering with NEON Parser I could able to build some config file for my own project and you can find it here

Note : This is the first time I'm dealing with Git so if any users not able to view the file please comment and I will try to provide it by other means. Please change necessary locations in config.neon to your environment.

Testing command using config file

apigen.bat --config .\config.neon

After the command completes open up index.html page and check if that is what you intended.

Note : I executed the command from the directory where config.neon exists. Make sure you too do that.

Useful PEAR commands to get things done

Today I'm going to outline some important commands related to PEAR.
These commands are nothing new which you can't find online or in PEAR site but these are something which I need every time to get things done on my workstation for any new extension.

For more information about PEAR follow this link
Here are some important commands

Check which channels are setup on your PEAR installation

pear list-channels

Consider a channel to look for packages in current session.(add or use this channel)

pear channel-discover pear.phpdoc.org

Check available packages in a channel.

pear remote-list -c pear.phpdoc.org

Install phpDocumentor2 package

pear install phpdoc/phpDocumentor-alpha

List all installed packages in a channel

pear list -c pear.phpdoc.org

List all available packages in a channel

pear list-all

Get information of files which are installed through a package

pear list-files phpDocumentor-2.0.0b4

Clear cache (I often use it when I get errors during installations)

pear clear-cache

Uninstall a package (mention complete package name otherwise it throws errors regarding package not available)

pear uninstall phpDocumentor-2.0.0b4

Setup and Write Yii Test Cases

First you need to know below things to start running a test case.

Business Problem:
Generally developers develop a web application or standalone application then they give the build to testers to test it. So testers understand all features of the build and plan to test it but when the build is so big then testers feel uncomfortable to test large builds. These scenarios come more than once before the build is live. So eventually a developer or tester come to a point of automating the whole thing which brings us to the point of writing a test suite.
One can start a test suite by using third party components or write individual test cases specifically for their business.

Here we are interested only in specific test cases which are related to business so we talk about only those in further discussions.

Solution:
Yii framework provides a base platform where in developers can test their features by writing separate code which tests the real code.
While creating a new project yiic tool will also generate necessary folder structure where in we can put test related files. (I guess you people used that tool)
For more information Yii Testing

Steps involved

1. Installation/prerequisites
2. Setup project for testing
3. Write Test Cases
4. Run Test Cases

Setting up the environment:

My environment is something different when compared to others.

• We have code in windows and work on code development in eclipse
• We share the folder and then map the folder to a Linux share.
• We then symlink the code folder so sites
• Use Apache as web server to serve the requests.

On whole we develop code in windows using eclipse and use Linux to host the code. We use share folders to sync the changes from windows to Linux.

Installation

 For testing we don't require that complex setup

• PHP environment
• PEAR package manager
• Apache Server (I don't cover this step here)
• Selenium RC Server to test the code
• PHPUnit to test PHP test cases
• PHPUnit_Selenium

Get PHP runtime
Goto below url
http://php.net/downloads.php
Download 5.3.x version for compatibility reasons (I have that version)
My file looks something like this 'php-5.3.26-Win32-VC9-x86.zip'
Extract the archive.

Get PEAR package manager
http://pear.php.net/go-pear.phar
Download the phar file.
Copy the go-pear.phar file to 'C:\Users\<user>\Downloads\php-5.3.26-Win32-VC9-x86' directory
Now open command prompt (I'm using power shell for all operations) and execute go-pear.phar using php runtime
Note: From this point I consider shell as your command shell whether it is command prompt or power shell

.\php.exe .\go-pear.phar

 If it asks for 'local' or 'system' then go for system

To select all options press enter

To install registry keys execute

.\PEAR_ENV.reg

Install Selenium RC Server as documented in Yii
http://selenium.googlecode.com/files/selenium-server-standalone-2.33.0.jar

Well if version changes we can always look at here http://docs.seleniumhq.org/download/ to get latest ones

Note: A working java environment should be there for Selenium Server to run because its a jar file.

Now install PHPUnit

.\pear.bat channel-discover pear.phpunit.de
.\pear.bat install PHPUnit

Install SeleniumTest

.\pear.bat install phpunit/PHPUnit_Selenium

If you run into any errors like "No releases available for package "pear.phpunit.de/PHPUnit_Selenium"" then run below command

.\pear.bat clear-cache

Setup project for testing

Goto directory <your web application folder>/protected/tests
Open WebTestCase.php and change the TEST_BASE_URL in eclipse or text editor

define('TEST_BASE_URL','http://192.168.0.32/<my web application>/index-test.php/');

Note: I have already mentioned that my environment is different. In your cases it my be localhost or 127.0.0.1

After that open the url and see if there are any other errors with main config with index-text.php
(I have to do some other config because we have more things in index.php which aren't copied to index-test.php)

Write Test Cases

Yii made this easy by providing some basic test cases where we can understand them and implement the logic to our scenarios.

For sample test cases open below file

protected/tests/functional/SiteTest.php

One can start editing those test cases or write their own.
I have written my own for my specific requirement. Here is the code snippet for your reference

public function testContact()
{
    $this->open('?r=site/contact');
    $this->assertTextPresent('Contact Us');
    $this->assertElementPresent('name=ContactForm[firstName]');
    $this->type('name=ContactForm[firstName]','tester');
    $this->assertElementPresent('name=ContactForm[lastName]');
    $this->type('name=ContactForm[lastName]','beta');
    $this->type('name=ContactForm[email]','demo.123@gmail.com');
    $this->type('name=ContactForm[purpose]','other');
    $this->type('name=ContactForm[body]','PHPUnit test cases sample');
    $this->click("//input[@value='Submit']");
    $this->waitForTextPresent('Thank you for contacting us.');
}

To change test case preferences open phpunit.xml file and change as per your requirements.
If you feel you don't want to test in Internet Explorer then you can remove Internet Explorer browser node or you can add another browser to your configuration

Running Test Cases

Now start running test cases against PHPUnit using Selenium Remote Control Server

Before that make sure that we are running an instance of Selenium RC Server
For this case open another shell and type this command to run it

java -jar .\selenium-server-standalone-2.33.0.jar

 Leave that window because it will throw log information which may be useful.

Open another shell window for running test cases

Change directory to your project folder

phpunit.bat .\functional\SiteTest.php

Note: Add phpunit.bat location to PATH in environment variables to access it anywhere. It it suggested to add

Note: This is how I made PHPUnit to work on my workstation and run test cases of my project. Your experiences may vary. This post is purely meant for informational purposes and I don't guarantee that everything mentioned here works as expected.

For more information browse below links
Yii Testing
PHPUnit Documentation
PHPUnit Manual

Recover eclipse code templates using workspace metadata.

Have you ever lost your eclipse installation and feeling bad that you didn't backup code templates? 

Since code templates are integral part of rapid development a developer should keep his code templates under check. 
In any case if he loses his code templates and have his workspace handy then one can follow below steps to get it back. 

One may wonder where eclipse stores its code templates. Well here is the location. 

C:\Users\<user>\workspace\.metadata\.plugins\org.eclipse.core.runtime\.settings\org.eclipse.php.ui.prefs

Note: The location can change for java and other perspectives. It may be like org.eclipse.java.ui.prefs. I leave the rest to your search within that above folder.

Open that file in your favourite text editor (mine is Notepad++. So screenshots will be in that)
Consider the line(9) where it starts with 

org.eclipse.php.ui.editor.templates

Start copying the part where it looks like above snippet and ends with  

</templates>

Copy the data into another file. 
Personally I don't prefer importing that data directly into eclipse because 

1. Its eclipse settings file and our required format of xml may differ from raw data of eclipse 
2. We need to take care of xml safe characters while creating a new xml for code templates 
3. Eclipse may add other node elements, attributes etc., while generating code templates xml file so please don't try to mimic the functionality of eclipse

Since the raw data we got is not exactly we want so we plan on improving the raw data we got. So lets get started with some simple text manipulations using Regex Expressions. 
First we reorder the data which is earlier in single line.
Note: Don't forget to select Regular expression as your search mode

Match : >< 
Replace : >\r\n< 

After the above operation we can see all templates ordered nicely. (sorry for the dull image)
But there is still a problem with extra backslashes. 
So we remove them

Match : \\=
Replace : =

Add below line at the top of file to make it  as xml with specific encoding

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>

Now save the file as your code templates file and try to import it into eclipse. 

I personally never tried it because I have my eclipse set and I will try it when situation demands.

Please do reply me with your experiences.