I work in plain text a lot, from using Markdown or more specifically PHP Markdown on this WordPress setup and elsewhere, as well as doing HTML markup and programming PHP. It is therefore not surprising that this article on Collaboration Made Simple with Bracket Notation caught my eye (linked via Lifehacker).

It’s a simple but clever idea that eschews a specific software solution for collaborative content editing in favour of notations in plain text. I don’t want to steal anyone away from reading the article but I did want to note a simple way of remembering their idea…

[delete][replace with][comment]

…so if we take the text…

The Bat in the Hat

…and apply some collaborative revision markup…

The [Bat][Cat][less sinister?!] in the Hat

…it would be revised to…

The Cat in the Hat

It’s a useful trick to to remember e.g., for passing edits around in text format via IM or Email. Whether I use it or not is another thing but I certainly like the inventive use of simple tools.

Now that the host for underwater.com.au has upgraded to PHP5 I’m working on migrating it to use the Zend Framework. I thought it may be interesting to run through a few of the reasons I’ve chosen to do so especially while the framework is in such an early stage of development.

“Underware”

The engine, code-named “Underware”, that underwater.com.au currently runs on is built almost entirely (excluding a few additional class files) from my own code. Developed, via several projects, over the course of about five years from a modified version of the PHP e-Commerce application Freetrade and the FreeEnergy structure (Actually, it’s interesting to look back over that FreeEnergy article to see how it’s almost a Model-View-Controller structure), Underware is now more object-oriented, more MVC’ed and more woven with design patterns than its early incarnations, however it still has loose threads.

Why grow your own?

Considering the amount of freely-available, open-source, PHP code it seems idiotic to be doing it all yourself. Sadly, the number of applications available is no indication of their quality, nor whether they will play nicely together, a point taken up by Clay Loveless in his Stop Writing Loner Applications post.

At every stage of Underware’s development I looked at pre-existing solutions, hoping to find one that wouldn’t force me to duplicate components I already had, such as user management. It wasn’t necessarily that I had better code, more that what I did have was only what I needed. Besides, I knew as I worked on it the code quality would also improve. Inevitably, after spending many unbillable hours pouring through different solutions I’d look at the clock and think “I could have spent those hours moving forward and coding a solution”!

Pros of doing it all yourself

• You only build, debug and support what you need.
• You know all the code.
• You learn a lot.

Cons of doing it all yourself

• You have to build and support every bit of code and unless you build it it’s not just going to appear from somewhere.
• You have to document it all.
• You have to spend time researching solutions to every issue, including system level ones that are not directly providing solutions for your clients.

Thankfully the increasing amount of frameworks available (i.e. rather than finished applications) combined with the growing object-oriented’ness of PHP mean it’s less of an either or situation.

So why Zend Framework?

Honestly, I think because it feels right and I say that not to be facetious, but partly because I see so many lengthy arguments for and against such and such framework as if one or the other holds the golden key. Part of the reason I went back to my roots was to show the influences on my way of structuring web applications and if you’re interested enough to look into them you may see some similarities. For me the Zend Framework not only fits the way I’m currently working but moves it forward, tying up some of the aforementioned loose threads for example.

More pragmatically there are factors like the fact that my clients can worry less about being so totally dependant on me for every facet of their applications; I can benefit from all the external input to the framework itself; I can focus on solving client needs more and system level needs less and not to be ignored is the Zend part of the framework which for me puts at least some stamp of longevity and consistency on the code base.

Some further Underware influences

• Philip Greenspun’s Software Engineering for Internet Applications, in particular the section on content management.

• Design patterns picked up from various sources, but really understood in Head First Design Patterns and phpPatterns. The Head First Java is also a good read, particularly if like me you’re really only after a better understanding of OOP rather than wanting to specifically program Java applications.

• Marcus Baker’s articles on unit testing. I plan to read more about PHPUnit too but Marcus’ writing was really a good intro to a practice I must practice more of!

Some current Zend Framework reading

• Using Layouts with the Zend Framework
• Zend Framework Tutorial
• Blueprint for PHP Applications

There are plenty of articles on setting up virtual hosts on Mac OS X but I’d not found a simple one that showed you how to set up named virtual hosting that could be read across your LAN. The aim for me is to be able to type in e.g., http://myparty/, in any browser on our small local network and get to the locally hosted site.

My requirements are pretty minimal, needing only to have one or two other Macs running OS X (Tiger) access the development server. I’m not going to go into too much detail, partly as I’m too lazy, but also as your setup and needs will be different to mine anyhow. Instead I’ll just give a general run through and point to further reading.

Decide where we’re going to host the party

The first thing we need to establish is the main server which requires that that server have a static IP address. In my case this involved going to System Preferences > Network > TCP/IP and setting Configure IPv4 to “Using DHCP with manual address”. In that same dialog I then set an IP address of 192.168.1.100 and clicked “Apply Now”. That now means that this machine has a consistent address that others on the network will refer to.

Tell everyone where the party is

When the other OS X machines on the network type http://myparty/ in their browsers the first thing their machines do is check in the file /etc/hosts to see if there’s an IP address that matches “myparty”. If there isn’t things won’t go very far. So if you take a look at my one…

127.0.0.1   localhost
127.0.0.1   myparty
255.255.255.255 broadcasthost
::1             localhost

…you’ll see that http://myparty/ maps to my localhost IP address 127.0.0.1 which is fine as my machine is the host. In order that the other machines know where to go for “myparty” we have to edit their /etc/host files to send requests to the static IP address I set earlier:

127.0.0.1   localhost
192.168.1.100   myparty
255.255.255.255 broadcasthost
::1             localhost

Set up the virtual hosts

Now that everyone knows where myparty is being hosted we need to prepare. First you need to edit the Apache web server configuration file httpd.conf which by default lives here /private/etc/httpd/httpd.conf. I’ve installed Apache2 in /usr/local/ which is the more generally expected place for it to be and since this is my notepad I’m going to go with that. So first I need to open httpd.conf as the all powerful root user so I need to type…

$ sudo vim /usr/local/apache2/conf/httpd.conf

…whereas you could go…

$ open -a TextWrangler.app /private/etc/httpd/httpd.conf

…or whatever your personal setup/preference is. Once open you might like to use this little tip I picked up of having your specific settings in a separate file so e.g. at the end of my httpd.conf I have the following…

include /Users/nicklo/Sites/apacheconf/users

…that points to a directory which contains the file nicklo.conf. Inside that file are my virtual host settings. Having those settings separate from the main httpd.conf makes them more easy to backup along with all my other projects. It also potentially keeps them out of harms way in case a Software Update decides it’s time to fiddle with your httpd.conf file.

In keeping with the example my nicklo.conf could then have the following…

NameVirtualHost *:80

<Directory "/Users/nicklo/Sites">
    Options Indexes MultiViews
    AllowOverride All
    Order allow,deny
    Allow from all
</Directory>

<VirtualHost *:80>
    ServerName 127.0.0.1
    DocumentRoot /Users/nicklo/Sites
</VirtualHost>

<VirtualHost *:80>
    ServerName myparty 
    DocumentRoot /Users/nicklo/Sites/myparty
</VirtualHost>

You’ll notice the settings specific to “myparty” are the last ones. These basically say if you get any requests for “myparty” on any IP address (* wildcard) via port 80 then send them through to /Users/nicklo/Sites/myparty.

Party on!

All that’s left now is restart Apache via System Preferences > Sharing > Services > Personal Web Sharing or…

$ sudo apachectl graceful

…which is actually better as it will at least tell you if there are any issues rather than just sit there.

Actually, we we still have to build the myparty website/web application in /Users/nicklo/Sites/myparty/public_html but hey, that’s the easy part right?!

Now in an even more perfect world I would be able to tell you how to set up a proper DNS Server on the host machine, that would replace the somewhat hacky need for individually configured /etc/host files. However, right now I’m just too stupid and honestly, a bit scared, to even attempt that. If anyone can give me a simple and if possible metaphorical run through I’d be very interested.

Further Reading

Virtual Hosting on Mac OS X I need to give credit to the comments by “Mats” on that page for much of my setup above.

Staging websites on Mac OS X

Virtual Hosts for Dummies

Location, Location, Location: Tips for Storing Web Site Files

Apache Virtual Host documentation

VirtualHost Examples

The Zend Framework Manual describes View Helpers like so:

“In your view scripts, often it is necessary to perform certain complex functions over and over; e.g., formatting a date, generating form elements, or displaying action links. You can use helper classes to perform these behaviors for you.”

Currently the framework (version 0.1.3) includes a small selection of form helpers which will no doubt expand as it matures. For now I’m more interested in the ability to add custom helpers for specific project use. The first thing I did was to set up the same directory structure as Zend_View_Helper as is suggested when subclassing controllers:

library/
    Zend/
        View/
            Helper/
    MyProject/
        View/
            Helper/

Having my project specific helper files in library/MyProject/View/Helper/ will make it easy to keep them separate from Zend core updates.

The next step is to tell Zend_View to look in the custom helper directory as well as the default Zend helper directory. This just requires adding the new helper path to the Zend_View object I created in the public_html/index.php file:

$view = new Zend_View;
$view->addHelperPath('MyProject/View/Helper');

Cautionary Note (* see update below)

The above is actually a bit of a fiddle to get working if you decide like I did to use a relative path to your helper files. I had set…

set_include_path( /home/exciting_zfw_site/library/ );

…pointing to the main Zend library directory, however, Zend_View_Abstract:: _loadClass() uses is_readable() as a check before loading any helper or filter files like so…

if (is_readable($dir . $file)) {
    include $dir . $file;

    if (! class_exists($class, false)) {
        $msg = "$type '$name' loaded 
                        but class '$class' not found within";
        throw new Zend_View_Exception($msg);
    }

    return $class;
}

…and since is_readable just ignores include paths, your new helper files won’t be found. This is currently listed as a bug but for the moment I simply changed…

if (is_readable($dir . $file)) {
    include $dir . $file;

…to…

if (include $dir . $file) {

…and it worked fine. Portability was the reason I wanted to keep the paths relative as I move files from a development server to the live server. It’s much easier to keep as few path configuration settings as possible.

The next step is pretty well documented in the manual but for the sake of completeness I’ll keep going. Create a new helper file:

class Zend_View_Helper_DoStuff {

    public function doStuff()
    {
        return 'Hello to you all';
    }
}

Another Cautionary Note

Something that caught me out was that the new helper class must be called Zend_View_Helper_YourNameHere rather than MyProject_View_Helper_YourNameHere which seems a little odd considering it’s position in the directory structure I mentioned before. While logically it is a Zend_View helper class, it will be kept with other subclassed files with your own “namespaced” class names under the MyProject directory so it seems to break a convention.

Ready to use

After saving the new helper file in MyProject/View/Helper/DoStuff.php it should be available to use in your view scripts like so:

<?php echo $this->doStuff(); ?>

When writing helper classes the key points to initially getting them to work are the naming conventions as illustrated by my doStuff example:

1. Class name must be Zend_View_Helper_DoStuff
2. The class must contain a public function doStuff()
3. The file must be save as DoStuff.php

As mentioned in my post on getting to know Zend_View elements of the above may well change as development continues.

Further Reading

View Helpers in the Zend Framework Manual

* Update

Forget the above hack…

if (include $dir . $file) {

…as it will produce warnings as Zend_View_Abstract::_LoadClass() attempts to include the doStuff file from any other path in the _path stack. Instead the only solution I’ve found to currently work is to specify a relative path like so:

$view->addHelperPath('../MyProject/UW/View/Helper');

Well-heeled Vim users will no doubt see the following as being pretty obvious. For anyone else like me fumbling around with Vim to the point of giving up, I hope this at least saves you the time I spent until the small hours of the morning!

The way I used to think

Coming from working with text editors like jEdit which, like others, has a file browser in a split pane, I had been trying to reproduce this in Vim.

However, since upgrading to Vim 7, this had been causing irritations, like this routine to open a file:

• Select a file in the left pane.
• Click in a window in the right pane to indicate that was the one to open it in.
• Go back to the file in the left pane and Shift-p to open it.

Forgetting to select the window to open it in meant it would open in the left pane instead, which was supposed to be my file browsing pane.

Not only that but for whatever reason I was getting an odd refresh when I moved to another application and back to Vim. This refresh was annoying enough to have me spend time reinstalling netrw, attempting to compile Vim for myself (which failed) and even taking time to try out Textmate.

All in all I was getting pretty fed up and was even converting the Euro to Aussie Dollar to see if I had enough pocket money to buy Textmate. Luckily, the stubbornness of anyone who has put the time into learning Vim wouldn’t go away and I stopped to have a look at the new tabs in Vim 7. It was then that I realised I’d been thinking about this all wrong…

Vim is about modes

My mistake was to think of any window in Vim as having a specific role and ignoring vim’s modal nature. I realised that file browsing was always there in the background as I edited a file and I didn’t need to have windows specifically assigned to file browsing.

The joy of :Ex (very poor, I know!)

The magic lies in the fact that the file browsing functionality of netrw is following you around as you go. For example, if I open …/Sites/zend_framework/library/Zend.php in a window…

…and then hit :Ex I will be in that files directory…

However, if I open a file from another directory in another window hitting :Ex for that window will bring up it’s directory. This then allows me to have a contextual file browser available at any time without having to move my hands from the keyboard.

Admittedly this is not exactly a nirvana attaining moment of enlightenment, but it’s certainly one of those “Aha!” moments that reinforces your faith in your tools and the time spent learning them.

Further Reading

Beginner’s guide to Vi Improved (vim)

I like the fact that Jon Hicks, who is well known for designing, amongst other things, the logo for the Firefox web browser, talks about using a cheap rounded corner punch on his business cards in his New Business Cards are here! journal entry.

I’d ruled out rounded corners as being cost prohibitive but this is an obvious and simple workaround. Searching locally (in a brief Google Australia search) I’ve so far come up with ones like Fiskars’ photo corner punch which is not quite what I’m after. I’ll keep looking…