Integrating offline documentation into my workflow with Dash

People like to compare programming languages, or their favourite framework. Everyone tends to have a favourite and the subsequent discussions (arguments/flame wars) very rarely add any value. Lots of non-PHP programmers delight in the various “php sucks!” articles, sometimes they’re right but often they miss the point. PHP can suck but so can any programming language when used incorrectly. That said, i’m pretty fond of PHP. Its been my programming language of choice for the last 10 years give or take. I happen to like it and I tend to think there’s a lot to like about it. If I was to distill this down to a killer feature though (as people tend to do) then i’d suggest its nothing in the language itself. For me the killer feature in PHP has always been the documentation. The PHP docs rock, they look awful (hopefully not for much longer) but they add so much value to the language its untrue. The comments too are usually excellent. I’ve lost count of the amount of times where the answer I was looking for (whatever the question) was either answered by the documentation itself or the user contributed notes beneath. If you’re a PHP dev then you will have found this too – 100%. The only problem with the PHP docs is how much I can rely on them at times, and that they rely on an active internet connection. Now, admittedly this is few and far between but there are times when internet is flaky or non-existent – travelling on trains, planes (or automobiles) for example. Recently though I’ve found a solution to this issue – a great Mac App called Dash

Screen Shot 2013-02-23 at 21.12.45
launching dash from Alfred

Dash. Dash describes itself as “… an API Documentation Browser and Code Snippet Manager. Dash stores snippets of code and searches offline documentation”. You want a searchable copy of the PHP docs available offline then Dash is for you. Of course, Dash is not limited to PHP. There are docsets for most languages and libraries you can think of. This is already powerful. Recently though i’ve picked up on a couple more features in Dash that make it really killer for me and now, whether I have internet or not, I tend to use Dash for all documentation reading. One of these things is the hookup it has with Alfred, another excellent Mac app. I can launch Alfred with the shortcut ⌥+SPACE, and by typing “dash SOMETHING” the docs are immediately searched for that item – for example “dash array_intersect“.

Screen Shot 2013-02-23 at 21.27.48
A function definition file within Netbeans

This is pretty sweet. Its quick, its offline, and somehow it feels distraction free as its outside of the browser. This definitely scratched an itch for me, I wondered if Dash could do anything more that I would fine useful. It turns out it could. I’m a big fan of the Netbeans IDE for all my PHP development. Yeah, I know all the cool-kids are using Sublime Text with its infinite customisation but I like Netbeans. I’ve been using it for years, i’m happy with it. One thing i’ve never liked so much though is the way it handles documenting core php functions and libraries. Hovering over a function will display the Phpdoc for that code, where as ⌘+Click will take you to the function. This works great for custom code but not so great for the core  language code.  I want to see this documentation on the PHP site, the Netbeans method of displaying it within a function definition file just doesn’t cut it. Fortunately i’ve found a method of integrating Dash here too – using the “Look up in Dash” System Service. I’ve been a Mac user for about 3 years though and i’ve always been a little confused by services, this is the first time i’ve made any use of them. Through a System Service within Netbeans i’ve been able to connect a shortcut in Netbeans to the Dash service. I’ve chosen ⌘+⇧+D. By highlighting a piece of code, and using that shortcut Dash is launched and searches immediately for that code. Of course you can use any shortcut you like but this works for me. Pretty simple in the end, and now I have Dash linked into my workflow quite effectively.

Working with Zend Tool in multiple dev environments

On any given Zend Framework project I can be working in 2 or 3 locations – my work PC, home PC or my MacBook. My source code will always be in Subversion and I usually work on a development server before pushing completed work to the production server. In this kind of environment I’ve never been too sure where exactly I should work with Zend_Tool.

How i see it, there’s 2 options:

  • Set up to work locally with Zend_Tool on each dev environment and then push to the dev server from there, checking in the Zend_Tool manifest etc with each Zend_Tool usage.
  • Use Zend_Tool directly on the dev server and then download each addition/alteration to then push into SVN.

I would be inclined to say the most reliable way would be the multiple Zend_Tool setup but i’d be interested to hear if people can think of any potential issues with this or reasons why i should make a different choice.

n.b. I originally posted this as a question on Stack Overflow – feel free to drop in over there and answer the question.

Simple introduction to using Oauth with Zend_Service_Twitter

The Zend Framework is slowly changing the way i develop websites. I say slowly as the documentation for much of the framework is sadly lacking. It is overly complex at times and at other times it is lacking in required detail or is just out-of-date. In putting together  a twitter based application recently i came across such an occasion with regards to the recent changes made by twitter in turning off basic authentication. Hopefully, this might help someone else too.

If you’re looking to build a Twitter application using the Zend Framework then there is some half decent information on the Zend Framework site in the section dealing with Oauth. However it was lacking in some detail, looking at the documentation for Zend_Service_Twitter was also not particularly useful as it has not been updated with examples of how to use Oauth. What i’ve put together is a really simple example of the process you could follow to make this work. The beauty of the Zend Framework is that there is always a number of ways to achiveve the same task so this is by no means the “right” way to do it, that being said it works for me.

First of all i added the configs i would need to my config file, application.ini

oauth_consumer.callbackUrl = "";
oauth_consumer.siteUrl = "";
oauth_consumer.consumerKey = "MY_CONSUMER_KEY";
oauth_consumer.consumerSecret = "MY_CONSUMER_SECRET";

Its probably worth noting that i use sessions to persist a few values in this example, they are setup like this within my TwitterController.php file:

class TwitterController extends Zend_Controller_Action
protected $session;
public function init()
$this->session = new Zend_Session_Namespace(‘Default’);
// etc..

Given the multitude of options with regards to how your Zend application might be put together I will not tell you where the rest of the code should be placed as thats completely dependent on your application.

First of all get your request token and then redirect the user to Twitter for them to grant access to your application

// within TwitterController::authAction
$config = $this->getInvokeArg(‘bootstrap’)->getOption(‘oauth_consumer’);
$consumer = new Zend_Oauth_Consumer($config);
$token = $consumer->getRequestToken();
$this->session->request_token = serialize($token);

Following the authorisation at Twitter the user will be returned to your callback URL, identified in your config file as oauth_consumer.callbackUrl. Using a combination of your request token and the response from Twitter the unique user access token is generated using the getAccessToken method of Zend_Oauth_Consumer.

// within TwitterController::callbackAction
$config = $this->getInvokeArg(‘bootstrap’)->getOption(‘oauth_consumer’);
$consumer = new Zend_Oauth_Consumer($config);
$access_token = $consumer->getAccessToken($this->_request->getQuery(), unserialize($this->session->request_token));

This was all pretty simple, you now have an access token that you can store for all later usage. It was unclear from the documentation though what the next step should be, all examples of Zend_Service_Twitter used basic authentication. Looking at the source code i noticed that for a valid signature you have to pass to the Zend_Service_Twitter constructor an array of options that included the config variables from your original request to Zend_Oauth_Consumer as well as your access token and twitter screen name:

$token = unserialize($user->getUserToken()); // retrieve token from storage
$configs = $this->getInvokeArg(‘bootstrap’)->getOption(‘oauth_consumer’);
$twitter = new Zend_Service_Twitter(array(
‘username’ => $token->screen_name,
‘accessToken’ => $token,
‘consumerKey’ => $configs[‘consumerKey’],
‘consumerSecret’ => $configs[‘consumerSecret’],
‘callbackUrl’ => $configs[‘callbackUrl’]
$response = $twitter->account->verifyCredentials();

Thats it, you are now able to make use of all methods within Zend_Service_Twitter. Happy tweeting!