Basic Intro

To start, lets define the tools we will required

For this tutorial, you required the following awesome projects:

• Apache Webserver with the XDebug module installed
  • XDebug is a PHP extension which provides debugging and profiling capabilities. It uses the DBGp debugging protocol.
  • http://xdebug.org
• Eclipse with PHP Development Tools
  • The Eclipse PHP Development Tools project (PDT) is a PHP Integrated Development Environment (IDE). PDT provides all the core capabilities needed in a PHP IDE. Powerful IDE with all the PHP required tools installed. I normally use the All-In-One package, which is the one I used for doing this tutorial
  • http://www.eclipse.org/pdt/downloads/
  • All-In-One download
• Apache JMeter
  • JMeter is a desktop application designed to load test functional behavior and measure performance. It was originally designed for testing Web Applications but has since expanded to other test functions.
  • JMeter Project

Issue

As explained previously, using the browser for API debugging can be pretty hard or nearly impossible unless you build some sort of UI, which normally I do not have time to do, so JMeter is perfect for the job!

Now, the hard part is to be able to do real debugging using JMeter, which means hook JMeter to start the debugging session and catch the XDebug call with Eclipse, which sounds quite hard but on the contrary, it’s very simple.

Apache Configuration

XDebug requires some small configurations in the php.ini file in order to work, lets look at them:

Open the php.ini file add the following configurations (if you don’t have it already)

[XDebug]

; Load the XDebug module
zend_extension="{FULL_PATH_FOR_XDEBUG_EXTENSION}/xdebug.so"

; This switch controls whether Xdebug should try to contact a debug client, defaults to 0
; http://xdebug.org/docs/all_settings#remote_enable
xdebug.remote_enable=1


; Selects the host where the debug client is running, you can either use a host name or an
; IP address
; http://xdebug.org/docs/all_settings#remote_host
xdebug.remote_host=127.0.0.1


; If enabled, the xdebug.remote_host setting is ignored and Xdebug will try to connect
; to the client that made the HTTP request. It checks the $_SERVER['REMOTE_ADDR']
; variable to find out which IP address to use. Please note that there is no filter
; available, and anybody who can connect to the webserver will then be able to start a
; debugging session, even if their address does not match
; xdebug.remote_host.
; http://xdebug.org/docs/all_settings#remote_connect_back
; xdebug.remote_connect_back=1

; The port to which Xdebug tries to connect on the remote host. Port 9000 is the
; default for both the client and the bundled debugclient.
; http://xdebug.org/docs/all_settings#remote_port
; xdebug.remote_port=9000


; Can be: php3, gdb or dbgp. The DBGp protocol is more widely supported by clients.
; Default value: dbgp
; http://xdebug.org/docs/all_settings#remote_handler
xdebug.remote_handler=dbgp


; If set to a value, it is used as filename to a file to which all remote debugger
; communications are logged. 
; http://xdebug.org/docs/all_settings#remote_log
xdebug.remote_log="/tmp/xdebug/xdebug.log"


; Controls which IDE Key Xdebug should pass on to the DBGp debugger handler.
; http://xdebug.org/docs/all_settings#idekey
xdebug.idekey=ECLIPSE_DBGP

Remote Debugging Gotchas

1. XDebug requires a local copy of the source code, if you are doing remote debugging, you need to have the project configured locally
2. You can follow the same steps and do remote debugging, as long as you have the code locally. You don’t require a working instance running, just the code.
3. Important: For remote debugging make sure your local port 9000 is open and can receive connections from the remote host.

Eclipse PDT Setup

In Eclipse, we need to create a new project, in my case I’ll use the same Apache instance and domain as the one used here

1. Create the project

Right click in the PHP Explorer area and select New > PHP Project

In my case, the project source files were already created, so I selected Created project at existing location

2. Set XDebug as your debugger

Now we need to tell the project to use XDebug. To do this, right click the project name and select Properties

In the properties window, select the PHP Debug option and select as the PHP Debugger XDebug. Once you do that, click Configure…

Select XDebug and click Configure

Now select any for the Accept remote session (JIT) option.

With the previous steps, you should be set and ready for serious debugging!. NOTE: I had to restart Eclipse for it to work, I guess because of the port binding but this is just a guess. So after doing these steps it does not work, just restart Eclipse.

JMeter Plan

I will be using the exact same plan as my previous post with the small difference of the Cookie Manager. So I won’t be covering the JMeter setup, just the Cookie Manager part.

Download the JMeter plan

Click here to download the JMeter plan (JMeterXdebug.zip)

XDebug is much more simple than Zend Debugger, it just require one cookie called XDEBUG_SESSION as follow:

Execute the JMeter plan

Now let’s test the plan, on the top menu select Run > Start

Now Eclipse should start and ask you to switch to the debug perspective, if you click yes, this is the Eclipse view you will have

Now Eclipse should start and ask you to switch to the debug perspective, if you click yes, this is the Eclipse view you will have

Note that the parameters sent to the request are available in the Variables view

You’re done!

Congrats you now have a JMeter plan that triggers an XDebug debugging session!

If you’re working on an API or consuming content from any HTTP service you could easily create a JMeter plan in order to test it.

Problem

Now, I think JMeter is awesome, no doubt about it, however what if I want to test something while developing a new API Endpoint? well I used to be accustom to the nasty var_dump(); exit; combination or if the API was already completed I used to do error_log() everywhere and figure out the results.

Now, I’ve been using Zend Studio for quite a while and installed Zend Server on my local machine to test and develop and I love the easy integration that Zend Server has with Zend Studio for debugging and I though to myself, why not just change the client that triggers the debugging console so instead of the browser use JMeter, at the end both uses HTTP so it should work, well guess what, IT DOES, and It’s awesome. No more print_r, error_log, var_dump in the API, lets do the Step by Step debugging with JMeter!

Solution

If you can do it using a browser you can do it using JMeter. So lets start.

Note: Even though I’m writting about Zend Debugger and Zend Studio, I would like to point out that the same can be acomplished using XDebug (I’ll write later on about it). If you don’t like Zend Server/Zend Studio, don’t worry, XDebug is an awesome project, it’s open, free and there are plugins for the most popular browsers and IDEs, 100% recommended!

Download the JMeter Plan

JMeter Plan: JMeterZend.jmx

1. Create a new project in Zend Studio.

I created a new virtual host on my machine just for the sake of the example. In my case I’ll use fakesite.pabloviquez.com.

Once that was completed, I added a new page (index.php) with some simple code for the sake of the example.

index.php

<?php
/**
 * This site is a fake site, however I want to make request to
 * it and do step by step debugging with JMeter and
 * Zend Debugger
 *
 * @see http://www.pabloviquez.com
 * @author Pablo Viquez <pviquez@pabloviquez.com>
 */
$startVariable = 1;
$anotherVariable = 'x';

for ($i = 0; $i <= 10; $i++) {
    echo "For loop, i: {$i}\n<br />\n";
}

2. Configure Zend Studio

Open Zend Studio preferences, and open the Installed Debuggers section: PHP > Debug > Installed Debuggers, now write the port used for the Zend Debugger somewhere, we’re going to need it later on.

3. Create a new JMeter Plan

Open JMeter and create a new plan, should look like this:

Now lets add the following sections using the same structure:

• Thread Group
  • HTTP Request
  • HTTP Cookie Manager
• User Defined Variables
• View Results Tree

4. Configure JMeter

Now, lets add the required configurations to JMeter in order to make a simple GET request to the index.php page we created in the step 1.

4.1 User Defined Variables

Create a new variable with the name HOST, the value must be the host name you’re going to use without the protocol.

4.2 HTTP Request

Click on the HTTP Request, and put the HOST variable we created in the previous step inside the Server Name or IP field.

For the sake of testing, add a parameter in the “Send Parameters With the Request:” section. Add whatever you want, this is because I want to be able to see them in the debugger later on.

4.3 HTTP Cookie Manager

This is where the magic happens! Zend Debugger requires a set of cookies in the request in order to launch the debugger. Basically, PHP reads these cookies and the Zend Debugger module recognize them, if they are good, the debugger makes a broadcast to the debug port configured launching the debugging session.

The set of key/values are:

(Values taken from: http://kb.zend.com/index.php?View=entry&EntryID=434)

Using those values, now add them to the HTTP Cookie manager:

5. Run the test plan!

Click Run > Run

The IDE should start! with the step by step debugging

Once completed you can check the results like you normally will do.

The response is yes you can. Now the best part is that you can take advantage of the tools MySQL give you, if you want to take the profiler to a new level.

ZF built-in profiler.

If you just care about the time that takes a certain query to execute and retrieve the data on your PHP application, then this might be the best choice for you.

Zend Framework provides a built in profiler for MySQL that keep tracks of the time that took a query to execute on your page and as a plus you can get the results displayed using Firebug (see: how to enable Firebug on ZF), the setup is quite simple and does not require rocket science to get it up and running.

To enable the MySQL profiling built in on ZF + FirePHP just modified the config file (assuming you’re using a ZF with Zend_Application):

config.ini

database.params.profiler.enabled = true
database.params.profiler.class = Zend_Db_Profiler_Firebug

That’s it! easy enough huh?

ZF built-in profiler preview

MySQL Profiler Advanced

If you care about deep performance and want to see “real” MySQL profiling, which tells you what did MySQL engine actually did, and the time it took to performed each particular step, then this is your best choice.

You can enable profiling on MySQL itself, which you can later query and see what did the database actually did in order to get your data.

Applying the same plugin architecture, you need to write a new plugin and register it. In this case I’ll assume the following directory structure:

lib/
   MyApp/
      Controller/
         Plugin/
            MySQLProfiling.php
   zend/
    *

The MySQLProfiling.php will contain the necessary code to communicate with the MySQL DB server and get the data I want:

MySQLProfiling.php

<?php
/**
 * MySQL Profiling plugin
 *
 * Enables the profiling feature on MySQL server, queries it and
 * retrieves the nescesary data for each individual query.
 *
 * @category MyApp
 * @package MyApp_Controller
 * @subpackage MyApp_Controller_Plugin
 * @author Pablo Viquez <pviquez@pabloviquez.com>
 */
class MyApp_Controller_Plugin_MySQLProfiling
    extends Zend_Controller_Plugin_Abstract
{
    /**
     * Constant to use to diferentiate the queries that dont require
     * profiling
     *
     * @var string
     */
    const DONT_PROFILE = '/*DN_PROFILE*/ ';

    /**
     * Predispatch loop.
     *
     * Is called before an action is dispatched by the dispatcher. This
     * callback allows for proxy or filter behavior. By altering the
     * request and resetting its dispatched flag (via
     * Zend_Controller_Request_Abstract::setDispatched(false)), the
     * current action may be skipped and/or replaced.
     *
     * @return null
     */
    public function preDispatch(Zend_Controller_Request_Abstract $request)
    {
        // Init the profiler
        $db = GET_DB_CONNECTION_INSTANCE
        $db->query(self::DONT_PROFILE . 'set profiling=1');
        $db->query(self::DONT_PROFILE . 'set profiling_history_size=100');
    }

    /**
     * Postdispatch Loop.
     *
     * Is called after an action is dispatched by the dispatcher. This
     * callback allows for proxy or filter behavior.
     */
    public function postDispatch(
        Zend_Controller_Request_Abstract $request)
    {
        $columns =
            array(
                'Query ID',
                'Duration',
                'Executed Query');

        $profiles =
            $this->_constructFirePhp(
                $columns,
                'MySQL Profiling - Profiles');

        $columns =
            array(
                'Query ID',
                'SEQ',
                'State',
                'numb ops',
                'Total duration',
                'Avg duration',
                'Total CPU',
                'Avg CPU',
                'Avg CPU Sys',
                'Block Ops In',
                'Block Ops Out');

        // Do the MySQL profiling
        $queryIds = $this->_setProfiles($profiles);

        // Get the profiling for each individual query
        foreach ($queryIds as $id) {
            $queriesProfile =
                $this->_constructFirePhp(
                    $columns,
                    "MySQL Profiling - Query ID: {$id}");
            $this->_getProfileForQueryId($queriesProfile, $id);
        }
    }

    /**
     * Retrieves the query profile for each indidividual query
     *
     * @param Zend_Wildfire_Plugin_FirePhp_TableMessage $profiles
     * @param int $queryId
     * @return void
     */
    private function _getProfileForQueryId(
        Zend_Wildfire_Plugin_FirePhp_TableMessage $profiles,
        $queryId)
    {
        if (!ctype_digit((string)$queryId)) {
            return;
        }

        $query = self::DONT_PROFILE .
            "SELECT {$queryId},
                    MIN(seq),
                    state,
                    COUNT(*),
                    ROUND(SUM(duration),5),
                    ROUND(AVG(duration),5),
                    ROUND(SUM(cpu_user),5),
                    ROUND(AVG(cpu_user),5),
                    ROUND(AVG(cpu_system),5) ,
                    ROUND(AVG(block_ops_in),5),
                    ROUND(AVG(block_ops_out),5)
               FROM information_schema.profiling
              WHERE query_id = {$queryId}
           GROUP BY state
           ORDER BY seq";

        $db = GET_DB_CONNECTION_INSTANCE
        $sth = $db->query($query);
        $rows = $sth->fetchAll();

        foreach($rows as $row) {
            $values = array_values($row);
            $profiles->addRow($values);
        }
    }

    /**
     * Constructs and send the profiles table.
     *
     * @param Zend_Wildfire_Plugin_FirePhp_TableMessage $profiles
     * @return array Retrieves an array with the queries profiles
     */
    private function _setProfiles(
        Zend_Wildfire_Plugin_FirePhp_TableMessage $profiles)
    {
        // Get the profiles
        $db = GET_DB_CONNECTION_INSTANCE
        $sth = $db->query(self::DONT_PROFILE . 'show profiles');
        $rows = $sth->fetchAll();

        $queryIds = array();
        foreach($rows as $row) {
            // Profile only queries marked as profile
            if (!(strpos($row['Query'], self::DONT_PROFILE) === false)) {
                continue;
            }

            $queryIds[] = $row['Query_ID'];
            $values = array_values($row);
            $profiles->addRow($values);
        }

        return $queryIds;
    }

    /**
     * Constructs the FirePHP messages.
     *
     * @param array $profiles
     * @param string $label
     * @return Zend_Wildfire_Plugin_FirePhp_TableMessage
     */
    private function _constructFirePhp(
        array $columns,
        $label,
        $setBuffer = true)
    {
        $msg = new Zend_Wildfire_Plugin_FirePhp_TableMessage($label);

        // If a message is buffered it can be updated for the duration
        // of the request and is only flushed at the end of the request.
        $msg->setBuffered($setBuffer);
        $msg->setHeader($columns);

        // Destroy the message to prevent delivery
        $msg->setOption('includeLineNumbers', false);
        Zend_Wildfire_Plugin_FirePhp::getInstance()->send($msg);
        return $msg;
    }
}

Now, you need to modify 3 lines of code, in the same file “MySQLProfiling.php” look in the lines 38, 122 and 142.

$db = GET_DB_CONNECTION_INSTANCE

Modify those lines and instead of “GET_DB_CONNECTION_INSTANCE” replace it with a call to your DB handler that you created with “Zend_Db::factory”.

Once that’s done, you can enable the plugin by either registering it on your bootstrap, or enabling it on your config file:

config.ini

resources.frontController.plugins.MySQLProfiling = MyApp_Controller_Plugin_MySQLProfiling

Done! you should have your MySQL profiler running!

MySQL profiling plugin preview

Keep in mind…

Always keep in mind…

• DB profile tools SHOULD BE USE on development environments only.
• The plugin is set to profile 100 queries (line 40), I HOPE your page contains much less than 100 queries, however be aware that for every query performed on your page, the plugin will generate one table with all the data plus the profiles table.

As you might now, you can view and download the Zend Framework reference manual from the Zend Framework site and download it from the download section, however what I wanted was the Windows compiled version of it (CHM file). In order to get this version you need to compile the documentation, after running into some small issues, I manage to do it, and to save you some work here it’s

By the way, the problem I had was parsing one XML file. Zend Framework issue tracker reports that the issue was fixed but the SVN tag have the error, anyway if you try to create the documentation from the SVN repository for the version 1.10.2, you will encounter some parsing errors, in order to fix those, you can do this:

Line 161
From:

<title type="html"><![CDATA[All Your Base Are Belong To Us]]></title>

To:

<title type="html"><![CDATA[All Your Base Are Belong To Us]]&gt;</title>

Line 163
From:

<![CDATA[Exposing the difficultly of porting games to English.]]>

To:

<![CDATA[Exposing the difficultly of porting games to English.]]&gt;

Line 177
From:

The example is long enough as is ;;).]]>

To:

The example is long enough as is ;;).]]>

IMPORTANT, since you escaped the XML file, you also need to revert it in the generated HTML file.

Anyway, if you want you can just download both files here: Zend_Feed_Writer.xml and zend.feed.writer.html

Zend Framework Documentation – CHM Format

I compile the CHM format for English and Spanish, the spanish version is incomplete so you might find some parts in english.

Información para el archivo en español

La documentación en español está incompleta y debido a esto, se econtrará muchas secciones de la guía en inglés.

On a standard setup of Zend Framework, the Zend error handler plugin (Zend_Controller_Plugin_ErrorHandler) enable by default and it was designed for:

• Errors due to missing controllers or actions
• Errors occurring within action controllers

I wanted to keep using the error handler plugin and didn’t want to log the exceptions by using: Zend_Controller_Front::throwExceptions() or Zend_Controller_Response_Abstract::renderExceptions() or any other way since eventually might get complicated, besides, I think that the error handler plugin works fine and if it gets updated in the future, I won’t have to do a major refactor.

So this is how I did it:

Create the Zend Log Object

Using Zend_Application can be very helpful here, because you can init the logger and automatically store the object in the registry, making available to the controllers later on.

Summary, if you want an object created on the boostrap class, to be available on the controllers later, you need to return it from the init method, in this case, we’re initializing the Zend_Log, so we need to return the object.

<?php
class App_Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{

    /**
     * Initializes the logging on the application
     * 
     * We're using 2 ways for logging exceptions:
     * 1. PHP Error log file.
     * 2. Firebug for Development environments only.
     *
     * @return Zend_Log
     */
    protected function _initLogger()
    {
        // Create the Zend_Log object
        $logger = new Zend_Log();

        // Create the resource for the error log file
        // if you dont want to use the error suppressor "@"
        // you can always use: is_writable
        // http://php.net/manual/function.is-writable.php
        $stream = @fopen(ini_get('error_log'), 'a');
        if ($stream) {
            $stdWritter = new Zend_Log_Writer_Stream($stream);
            $stdWritter->addFilter(Zend_Log::DEBUG);
            $stdWritter->addFilter(Zend_Log::INFO);
            $logger->addWriter($stdWritter);
        }

        // Create the Firebug writter - Development only
        if ($this->_application->getEnvironment() != 'production') {
            // Init firebug logging
            $fbWriter = new Zend_Log_Writer_Firebug();
            $logger->addWriter($fbWriter);
        }

        return $logger;
    }

I have now the log object but I’m not logging anything yet, so I need to implement the logging part.

Log the Exception

For this part, I thought in 2 ways to do it:

1. Extend the error handler plugin and log errors there.
2. Log the errors on the error controller.

I choose the second one for several reasons:

1. Easier.
2. If the error handler changes somehow, you dont have to change your code.
3. Extending the error plugin, might lead to repeated code and eventually deprecated code.

By default, Zend_Controller_Plugin_ErrorHandler will forward to ErrorController::errorAction() in the default module.

Now in order to retrieve a resource created in the bootstrap we need to access the bootstrap registered in the front controller, and from there we can get our logger:

// The method _initLogger on the class App_Bootstrap
// returns a Zend_Log object that is available
// on the Zend_Registry. To retrieve it we need to request the
// bootstrap from the Front controller and then get the logger.
$boot = $this->getInvokeArg('bootstrap');
if ($boot->hasResource('logger')) {
    $log_object = $boot->getResource('logger');
}

So using the Zend Framework default error controller (the one provided on the reference), with the logging will be something like this:

class ErrorController extends Zend_Controller_Action
{
    /**
     * Error action. This method is called by
     * Zend_Controller_Plugin_ErrorHandler
     *
     * @see Zend_Controller_Plugin_ErrorHandler
     * @return void
     */
    public function errorAction()
    {
        $errors = $this->_getParam('error_handler');

        // Log the Error.
        $boot = $this->getInvokeArg('bootstrap');
        if ($boot->hasResource('logger')) {
            $boot->getResource('logger')->err($errors->exception);
        }

        // Default error handling...
        switch ($errors->type) {
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_CONTROLLER:
            case Zend_Controller_Plugin_ErrorHandler::EXCEPTION_NO_ACTION:

                // 404 error -- controller or action not found
                $this->getResponse()->setHttpResponseCode(404);
                $this->view->message = 'Page not found';
                break;
            default:
                // application error
                $this->getResponse()->setHttpResponseCode(500);
                $this->view->message = 'Application error';
                break;
        }

        $this->view->exception = $errors->exception;
        $this->view->request   = $errors->request;
    }
}

Result

The final result looks like this:

Firefox with Firebug enabled:

PHP error log file:

[pviquez /usr/home/pviquez]$ cat php_error.log
2009-11-25T15:23:19-06:00 ERR (3): exception 'Zend_Exception' with message 'The logging is working!' in /usr/home/pviquez/app/deploy/application/modules/admin/controllers/IndexController.php:33
Stack trace:
#0 /usr/home/pviquez/app/deploy/library/Zend/Controller/Action.php(513): Admin_IndexController->indexAction()
#1 /usr/home/pviquez/app/deploy/library/Zend/Controller/Dispatcher/Standard.php(289): Zend_Controller_Action->dispatch('indexAction')
#2 /usr/home/pviquez/app/deploy/library/Zend/Controller/Front.php(946): Zend_Controller_Dispatcher_Standard->dispatch(Object(Zend_Controller_Request_Http), Object(Zend_Controller_Response_Http))
#3 /usr/home/pviquez/app/deploy/library/Zend/Application/Bootstrap/Bootstrap.php(77): Zend_Controller_Front->dispatch()
#4 /usr/home/pviquez/app/deploy/library/Zend/Application.php(346): Zend_Application_Bootstrap_Bootstrap->run()
#5 /usr/home/pviquez/app/deploy/public/index.php(23): Zend_Application->run()
#6 {main}

References

• Install Firebug on Firefox Firebug Add-on
• Error Handler Plugin: http://framework.zend.com/manual/en/zend.controller.plugins.html#zend.controller.plugins.standard.errorhandler
• MVC Exceptions: http://framework.zend.com/manual/en/zend.controller.exceptions.html

The application uses Zend Framework 1.9.1 and so far ZF does not support for “Office” formats, so after searching for a nice implementation, I found a PEAR module called Spreadsheet Excel Writter, which looked pretty good, it had very good documentation and the code was clean and well structured so I wanted to give it a shot.

1. PEAR Setup

I used the web interface for the PEAR setup which worked pretty good! (Not covering PEAR installation here).

If you want more info on how to install PEAR, go here: http://pear.php.net/manual/en/installation.getting.php and for the web setup: http://pear.php.net/go-pear

ONCE INSTALLED, REMEMBER TO ADD THE PEAR PATH TO YOUR INCLUDE PATH

2. Following the MVC pattern.

Model View Controller Diagram

I love the architecture following MVC (Model View Controller) and if I follow the MVC pattern, excel file will go as VIEW, this because the data is being presented an excel file.

Also, the controller does not care which format does the info gets display, the controller should care about manipulating modules, getting the data, controlling the flow of the application not about the presentation layer.

So what did I do?

Zend Framework offers a nice feature called “Context Switch”. This is an action helper that detects requested output and calls the specific view for the required format.

In my case, I wanted to enable this feature to the user controller, which had 3 actions:

• user/index
• user/new
• user/report

Now, I wanted to give the option to export the data as excel only for the “report” action, so I did this on the controller init method:

class UserController extends Zend_Controller_Action
{
    /**
     * Initializes the controller
     *
     * @return void
     */
    public function init()
    {
        // Optional added for consistency
        parent::init();

        // Excel format context
        $excelConfig =
            array(
                'excel' => array(
                    'suffix'  => 'excel',
                    'headers' => array(
                        'Content-type' => 'application/vnd.ms-excel')),
            );

        // Init the Context Switch Action helper
        $contextSwitch = $this->_helper->contextSwitch();

        // Add the new context
        $contextSwitch->setContexts($excelConfig)

        // Set the new context to the reports action
        $contextSwitch->addActionContext('report', 'excel')

        // Initializes the action helper
        $contextSwitch->initContext();
    }

    public function indexAction() { /* ... */ }
    public function newAction() { /* ... */ }
    public function reportAction() { /* ... */ }
}

What this code does is that it tells the controller to search on the parameters (GET/POST) for token “format” and the value “excel”. In other words, If the report action get requested like this:

/user/report?format=excel or /user/report/format/excel instead of loading the view: report.phtml will load the view report.excel.phtml and here is where the magic happens!

In the setup of the Context Switch, the “suffix” is what will be appended to the view file.

The report action, just gets the report and sets a variable on the view so it’s accesible as follow:

class UserController extends Zend_Controller_Action
{
    public function init() { /* ... */ }
    public function indexAction() { /* ... */ }
    public function newAction() { /* ... */ }

    /**
     * Report action
     *
     * @return void
     */
    public function reportAction()
    {
        // Proof of concept
        // Lets say that the result have the following structure
        // 
        // array(
        //     [USER ID] => array(
        //                      'name'  => 'Pablo Víquez',
        //                      'email' => 'email@domain.com',
        //                  ),
        //     [USER_ID] => array(...),
        //     ...
        // )
        $this->view->users = User_Model_Name::getReport();
    }
}

Now the view…

I need to have 2 files for this action:

• report.phtml – Output will be regular HTML
• report.excel.phtml – Output will be an MS Excel spreadsheet

report.phtml

This is the HTML format.

<h1>Users report</h1>

<table>
    <thead>
        <tr>
            <th>User Id</th>
            <th>Name</th>
            <th>Email</th>
        </tr>
    </thead>
<!--
    Variable set on the controller, if there's no data to display
    the count will be 0.
-->
<?php if(count($this->users) > 0) : ?>
<?php foreach ($this->users as $userId => $user) : ?>
    <tr>
        <td><?php echo $userId; ?></td>
        <td><?php echo $user['name']; ?></td>
        <td><?php echo $user['email']; ?></td>
    </tr>
<?php endforeach; ?>
<?php endif; ?>
</table>

report.excel.phtml

// Change error reporting for compatibility
// Spreadsheet Excel Writter was built using PHP4,
// so there's a lot of DEPRECATED notices
error_reporting(E_ERROR | E_WARNING | E_PARSE);


/**
 * PEAR package
 *
 * @link http://pear.php.net/package/Spreadsheet_Excel_Writer
 * @see PEAR/Spreadsheet/Excel/Writer.php
 */
require_once 'Spreadsheet/Excel/Writer.php';


// Lets define some custom colors codes
define('CUSTOM_DARK_BLUE', 20);
define('CUSTOM_BLUE', 21);
define('CUSTOM_LIGHT_BLUE', 22);
define('CUSTOM_YELLOW', 23);
define('CUSTOM_GREEN', 24);


// First, we create a Workbook
$workbook = new Spreadsheet_Excel_Writer();


// Add one sheet, called: Users Report
$worksheet = &$workbook->addWorksheet('Users Report');


// Create the custom colors on our new workbook
// This function takes 4 params:
//    - Code index [1 to 64]
//    - RGB colors (0-255)
$workbook->setCustomColor(CUSTOM_DARK_BLUE, 31, 73, 125);
$workbook->setCustomColor(CUSTOM_BLUE, 0, 112, 192);
$workbook->setCustomColor(CUSTOM_LIGHT_BLUE, 184, 204, 228);
$workbook->setCustomColor(CUSTOM_YELLOW, 255, 192, 0);
$workbook->setCustomColor(CUSTOM_GREEN, 0, 176, 80);


// Lets hide gridlines
$worksheet->hideScreenGridlines();


// Lets create some custom styles
$formatHeader = &$workbook->addFormat();
$formatHeader =
    &$workbook->addFormat(
        array('Size'    => 16,
              'VAlign'  => 'vcenter',
              'HAlign'  => 'center',
              'Bold'    => 1,
              'Color'   => 'white',
              'FgColor' => CUSTOM_DARK_BLUE));


$formatReportHeader =
    &$workbook->addFormat(
        array('Size'     => 9,
              'VAlign'   => 'bottom',
              'HAlign'   => 'center',
              'Bold'     => 1,
              'FgColor'  => CUSTOM_LIGHT_BLUE,
              'TextWrap' => true));

$formatData =
    &$workbook->addFormat(
        array(
            'Size'   => 8,
            'HAlign' => 'center',
            'VAlign' => 'vcenter'));

/**
 * First, format the worksheet, adding the headers
 * and row/columns custom sizes
 */

// Create a nice header with a dark blue background
// The function setRow takes 3 parameters:
//    - row index
//    - row height
//    - Format to apply to row [Optional]
$worksheet->setRow(0, 11, $formatHeader);
$worksheet->setRow(1, 46, $formatHeader);
$worksheet->setRow(2, 11, $formatHeader);


// Set the size of the columns
// The function setColumn takes 5 params:
//     - First column
//     - Last column
//     - Column Width
//     - Format [Optional, default = 0]
//     - Hidden [Optional, default = 0]
$worksheet->setColumn(0, 0, 7); // User Id, shrink it to 7
$worksheet->setColumn(1, 1, 12); // Name, set the width to 12
$worksheet->setColumn(1, 1, 15); // Email, set the width to 15


/**
 * 
 * Once we have the format ready, add the text to the spreadsheet
 * 
 */
// Write a text header
$worksheet->write(1, 1, 'Users report', $formatHeader);


// Create the header for the data starting @ row 4
$indexCol = 0;
$indexRow = 4;
$worksheet->write($indexRow, $indexCol++, 'User Id', $formatReportHeader);
$worksheet->write($indexRow, $indexCol++, 'Name', $formatReportHeader);
$worksheet->write($indexRow, $indexCol++, 'Email', $formatReportHeader);


$indexRow++;   // Advance to the next row
$indexCol = 0; // Start @ column 0

// Print the report data
if(count($this->users) == 0) {
    // No data
    $worksheet->write(
        $indexRow,
        $indexCol, 
        'No data to display',
        $formatData);

} else {
    // Write the data
    foreach ($this->users as $userId => $user) {
        $worksheet->writeNumber(
            $indexRow,
            $indexCol++,
            $userId,
            $formatData);

        $worksheet->write(
            $indexRow, 
            $indexCol++, 
            $user['name'], 
            $formatData);

        $worksheet->write(
            $indexRow, 
            $indexCol++, 
            $user['email'], 
            $formatData);

        // Advance to the next row
        $indexRow++;
    }
}


/**
 *
 * Response with the excel file
 *
 */

// Sends HTTP headers for the Excel file.
$workbook->send('report.xls');

// Calls finalization methods.
// This method should always be the last one to be called on every workbook
$workbook->close();

Esta es la información del evento:

Donde: Auditorio Universidad Latina de Costa Rica

Cuando: Martes 11 de Agosto, 7:00pm

El tema de Unit Testing e Integración Continua la verdad está muy bueno, recomendado.

Problem: Function json_encode does not support ISO-8859-1 encoded data.

One solution that I did, in order to preserve the character set was to encode the
data before using the json_encode function to use just A-Z, a-z and 0-9 characters,
instead of sending text with accents or symbols.

One encoding that fits perfectly in this schema, is Base64 Content-Transfer-Encoding. (see base 64 explanation below)

This leads me to the solution: Encode the ISO-8859-1 using base64 and decoded in the client using JavaScript.

Now, this lead me to another issue, what’s the algorithim to implement the base64_decode function in JavaScript?

Luckly enough, I was looking at the site: http://phpjs.org/ which ported most of the PHP functions to JavaScript and problem solved!

Download the demo files here

Solution

So my solution will look like this (using the demo files from my previous post):

prueba_ansi.php

<?php
$id =
    base64_encode(
        utf8_encode('iso-8859-1'));
$name =
    base64_encode(
        utf8_encode('Pablo Víquez - This is an ISO-8859-1 encoded text'));
$notes =
    base64_encode(
        utf8_encode('Test with JSON encoding. á é í ó ú, ñ, Ñ.'));

$customer =
    array(
        'id'    => $id,
        'name'  => $name,
        'notes' => $notes
);

echo json_encode($customer);

As you can see, I used 2 functions to encode the data: base64_encode and utf8_encode.

I used these 2, mostly because the JavaScript implementation of base64_decode asumes
that the data is UTF-8 encoded, by doing base64_encode(utf8_encode(‘iso-8859-1′))
I’m acctually first encoding the data to be UTF-8 first and then encoding it using Base64.

base64_encode
Encodes data with MIME base64, and has the following description:

string base64_encode ( string $data )

utf8_encode
Encodes an ISO-8859-1 string to UTF-8, and has the following description:

string utf8_encode  ( string $data  )

Client Side

I used JQuery to retrieve the JSON data, and the phpjs.org implementation for the
base64_decode and utf8_decode functions.

index.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>JSON Consumer</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<script type="text/javascript" src="http://jqueryjs.googlecode.com/files/jquery-1.3.2.min.js"></script>
<script type="text/javascript">
$(document).ready(function(){
    $("#query_data_iso").click(
        function(){
            getIsoData();
        }
    );

    $("#query_data_utf8").click(
        function(){
            getUtfData();
        }
    );
});

function getUtfData() {
    $.ajax({
        type:       "GET",
        dataType:   "json",
        url:        "prueba_utf8.php",
        success:    function(response){
            $("#customer_data_id").html(response.id);
            $("#customer_data_name").html(response.name);
            $("#customer_data_notes").html(response.notes);
        },
    });
}

/**
 * Gets a JSON response from the server.
 * Expectes a base64 encoded response with: id, name and notes all base64 encoded.
 */
function getIsoData() {
    $.ajax({
        type:       "GET",
        dataType:   "json",
        url:        "prueba_ansi.php",
        success:    function(response){
            $("#customer_data_id").html(base64_decode(response.id));
            $("#customer_data_name").html(base64_decode(response.name));
            $("#customer_data_notes").html(base64_decode(response.notes));
        },
    });
}

/**
 * Decodes string using MIME base64 algorithm
 * @see http://phpjs.org/functions/base64_decode
 */
function base64_decode( data ) {
    var b64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=";
    var o1, o2, o3, h1, h2, h3, h4, bits, i = 0, ac = 0, dec = "", tmp_arr = [];

    if (!data) {
        return data;
    }

    data += '';

    do {  // unpack four hexets into three octets using index points in b64
        h1 = b64.indexOf(data.charAt(i++));
        h2 = b64.indexOf(data.charAt(i++));
        h3 = b64.indexOf(data.charAt(i++));
        h4 = b64.indexOf(data.charAt(i++));

        bits = h1<<18 | h2<<12 | h3<<6 | h4;

        o1 = bits>>16 & 0xff;
        o2 = bits>>8 & 0xff;
        o3 = bits & 0xff;

        if (h3 == 64) {
            tmp_arr[ac++] = String.fromCharCode(o1);
        } else if (h4 == 64) {
            tmp_arr[ac++] = String.fromCharCode(o1, o2);
        } else {
            tmp_arr[ac++] = String.fromCharCode(o1, o2, o3);
        }
    } while (i < data.length);

    dec = tmp_arr.join('');
    dec = this.utf8_decode(dec);
    return dec;
}

/**
 * Converts a UTF-8 encoded string to ISO-8859-1
 * @see http://phpjs.org/functions/utf8_decode
 */
function utf8_decode ( str_data ) {
    var tmp_arr = [], i = 0, ac = 0, c1 = 0, c2 = 0, c3 = 0;

    str_data += '';

    while ( i < str_data.length ) {
        c1 = str_data.charCodeAt(i);
        if (c1 < 128) {
            tmp_arr[ac++] = String.fromCharCode(c1);
            i++;
        } else if ((c1 > 191) && (c1 < 224)) {
            c2 = str_data.charCodeAt(i+1);
            tmp_arr[ac++] = String.fromCharCode(((c1 & 31) << 6) | (c2 & 63));
            i += 2;
        } else {
            c2 = str_data.charCodeAt(i+1);
            c3 = str_data.charCodeAt(i+2);
            tmp_arr[ac++] = String.fromCharCode(((c1 & 15) << 12) | ((c2 & 63) << 6) | (c3 & 63));
            i += 3;
        }
    }

    return tmp_arr.join('');
}
</script>

</head>

<body>
    <h1>ISO 8859-1, JSON consumer</h1>

    <p>
        <a href="#" id="query_data_iso">Query for ISO-8859-1 data</a> |
        <a href="#" id="query_data_utf8">Query for UTF-8</a>
    </p>
    <table border="1">
        <tr>
            <td>Id</td>
            <td>Name</td>
            <td>Notes</td>
        </tr>
        <tr>
            <td><div id="customer_data_id"></div></td>
            <td><div id="customer_data_name"></div></td>
            <td><div id="customer_data_notes"></div></td>
        </tr>
    </table>
</body>
</html>

Downsize

The downsize to this solution will be the size of the encoded transfer, this because Base64-encoded data takes about 33% more space than the original data.

References

Base64 Content-Transfer-Encoding

http://tools.ietf.org/html/rfc2045

Normally, many media types which could be usefully transported via email are
represented, in their “natural” format, as 8bit character or binary data.
Such data cannot be transmitted over some transfer protocols.

For example, email. The SMTP (simple mail transfer protocol) restricts mail
messages to 7bit US-ASCII data with lines no longer than 1000 characters
including any trailing CRLF line separator.

PHP JS

• base64_decode – http://phpjs.org/functions/base64_decode
• utf8_decode – http://phpjs.org/functions/utf8_decode

While I was looking at some AJAX calls, I started to have a problem, for some reason, when I tried to query a JSON service I did using JQuery, the result was null for some fields.

Going a little deeper, I notice that the records from the DB were OK, and the JavaScript was OK to, so what was the problem? The JSON Encode!

So take for instance this code:

$customer =
    array(
        'id'    => 1,
        'name'  => 'Pablo Víquez',
        'notes' => 'Pruebas de encoding con JSON. á é í ó ú, ñ, Ñ'
);

echo json_encode();

If I save it as a ISO-8859-1, the result is the following:

{"id":1,"name":null,"notes":null}

Now, using the same code, but saving the PHP file as UTF-8 I got this result:

{"id":1,"name":"Pablo V\u00edquez","notes":"Pruebas de encoding con JSON. \u00e1 \u00e9 \u00ed \u00f3 \u00fa, \u00f1, \u00d1"}

The problem that I had was that the site was built using ISO 8859-1 not UTF-8, and changing it to UTF-8 is not an option, andn the AJAX call must return a JSON response.

json_encode documentation

string json_encode ( mixed $value [, int $options= 0 ] )

• $value: The value being encoded. Can be any type except a resource.
  This function only works with UTF-8 encoded data.
• $options (PHP 5.3 ONLY): Bitmask consisting of JSON_HEX_QUOT, JSON_HEX_TAG, JSON_HEX_AMP, JSON_HEX_APOS, JSON_FORCE_OBJECT. Defaults to 0.

There has been a lot of comments both on this blog and the internals list. There seems to be a fairly large group of core developers who like the idea as well as surpassingly large support base on the user level too (wow, didn’t think that this many people want type hinting). Unfortunately, there have also been, as is typically on the internals list a few people complaining for the sake of complaining. Their arguments have ranged from type hinting is against PHP’s loosely typed nature and people will mis-use it and make PHP into something that it is not, to I don’t need or will use it, so no one should get it.

…Here is the quick changelog.

1. Added support for “object” type hint
2. Modified the patch not to break binary compatibility so you can now use patched PHP without having to re-compile your extensions or having issues with binary ones.
3. Added full reflection support, which I appropriated from Felipe’s earlier work on type hinting
4. Added support for type casting, where by you can do things like this function a((int)$foo), which will force PHP to cast the value of $foo to an integer
5. Added tests, which again I partially appropriated from Felipe’s earlier work.

The types that could be used (according to the proposed patch) are:

So, how do that will look like? Here some examples of how this will look like:

Type Casting on function definition:

function printMe((int) $value) {
    var_dump($value);
}

// Output:
// int(50)
printMe(50);

// Output:
// int(123)
printMe('123');

// Output:
// int(0)
printMe('Testing');

// Output:
// int(0)
printMe(null);

Or using String as type casting

function printMeAgain((string) $value) {
    var_dump($value);
}

// Output:
// string(2) "50"
printMeAgain(50);

// Output:
// string(3) "123"
printMeAgain('123');

// Output:
// string(7) "Testing"
printMeAgain('Testing');

// Output:
// string(0) ""
printMeAgain(null);

Type Hinting

function test_int(int $a = 1) {
    var_dump($a);
}

// Output:
// int(1)
test_int();

// Output:
// int(123)
test_int(123);

// Output:
// Catchable fatal error: Argument 2 passed to test_int()
// must be of the type integer, string given
test_int("123");

With doubles:

function test_double(real $a) {
    var_dump($a);
}

// Output:
// float(1)
test_double(1);

// Output:
// float(1.123)
test_double(1.123);

// Output:
// Catchable fatal error: Argument 1 passed to
// test_double() must be of the type double,
// string given.
test_double("123");

With Strings:

function test_string(string $a) {
    var_dump($a);
}

// Output:
// string(10) "Hola Mundo"
test_double("Hola Mundo");

// Output:
// Catchable fatal error: Argument 1 passed to
// test_string() must be of the type string,
// int given
test_double(123);


// Output:
// Catchable fatal error: Argument 1 passed to
// test_string() must be of the type string,
// null given
test_str(null);