So, lyrics aside – today I had to learn new Subversion trick (the hard way), so I am writing it down here, in hope that it saves some other hacker time to play PacMan.

Problem:
I needed to checkout into single working copy all relevant (to me) parts of ZF repository. Not doing separate checkouts for the trunk, then branches, then incubator, but having single checkout of repo which I can keep up to date by simple

svn up

directly from the root of working copy.

Now the problematic part: you never ever want to checkout whole ZF repository – need I mention that it is HUGE? So, what I actually wanted is to checkout the whole repo excluding some paths – such as lots of previous releases in tags/branches folders.

Solution:
That’s where Sparse Directories chapter from svn book comes handy.

I will not repeat what’s written there, as I doubt I can explain it better. Yet I would add couple of notes, that might be a time savers I was talking about:

First, as of Subversion 1.6 you can actually exclude directories explicitly (go on and actually read that chapter, to find out that 1.5 supports what they call implicit exclusion).

And second, if you are tempted to run

$ svn co http://framework.zend.com/svn/framework/standard zf-standard --depth immediates

it is probably a bad idea.

In theory it should work like a charm, in practice on my Ubuntu box it takes for ever to bring those 4 immediate directories located in “standard” repo. I checked those directories with svn info and they have Depth attribute set (quite correctly) to “empty” – yet it takes a lot of network traffic and time to checkout them (once that’s done – svn up takes no time at all though). It takes so much time, as to make all this sparse directory magic not worth using.

Fortunately, there’s a work around: proceed one directory at a time, using “empty” as depth:

$ svn co http://framework.zend.com/svn/framework/standard zf-standard --depth empty
$ cd zf-standard
$ svn co http://framework.zend.com/svn/framework/standard/branches --depth empty
$ svn co http://framework.zend.com/svn/framework/standard/tags --depth empty
$ svn co http://framework.zend.com/svn/framework/standard/trunk --depth infinity

As you see, I made sure that trunk directory is fetched recursively. That’s because I work on trunk and need it in full.

Now let’s fetch some branch that we are interested in, while ignoring (and as such implicitly excluding) those that are too outdated to waste time and traffic on them.

Descend to zf-standard/branches directory of your newly created working copy and issue following command:

$ svn up release-1.10

As you don’t provide any depth specifiers “infinity” is assumed, and whole branch is fetched. Once that done, you can use your regular svn up/ci workflow – directory depth parameter is sticky, so you don’t have to worry about any directory that you didn’t fetch. Everything works as in normal checkouts, you just don’t have some of files (and in our case number of files tends to be 6-7 digit number) from your central repo.

Although I tend to git more and more lately, subversion can still amaze me (after all these years!)

$client = new Zend_Http_Client($uri);
$client->request(Zend_Http_Client::HEAD); // HTTP HEAD request

However, today, on my Ubuntu box I had real problems as HTTP client constantly ended in segmentation fault (SIGTERM in apache logs). When debugging, I noticed that it does so only if $uri contains so called “unwise” characters, such as spaces, “{“, “}”, “^” etc.

Going deeper, I reviewed the source code of Zend_Http_Client::setUri($uri) method, only to discover that it relies on Zend_Uri::factory($uri), to initialize the URLs. From there it was pretty simple. Zend_Uri is aware of “unwise” chars problem and disallows them by default (why exception thrown by Zend_Uri ended in SIGTERM is yet to discover, however). In order to allow such a characters:

Zend_Uri::setConfig(array('allow_unwise' => true));
$client = new Zend_Http_Client($uri); // $uri may contain unwise chars now

After issuing above instruction Zend_Uri accepts those unwisely formed URIs. Plus, you have to URL-encode white-spaces (i.e. make sure that white-spaces in query string, or actually in URI part after the host name are replaced with “%20″ char) to make them acceptable.

Further info available in offical documentation.

Please note, that I still think that having unreliable chars in URI is really bad practice. If you work with some system that already gone far on this path, it’s nice to have a method to actually consume such a wildly formed URIs. Kudos to Zend_Uri maintainers!

So, go into folder which stores ZF, and safely remove the library. Then just add ZF as external dependency (which would be updated every time you update the working copy):

svn pe svn:externals .

in and editor opened, enter the dependencies:

Zend http://framework.zend.com/svn/framework/standard/trunk/library/Zend
ZendX http://framework.zend.com/svn/framework/extras/trunk/library/ZendX

finally commit everything and obtain.

svn ci -m 'ZF set as external dep'
svn up

The beauty of this approach – you always have up to date version of ZF.
The danger of this approach – you always have up to date version of ZF!

Word of caution:
Sometimes this may break things (when backward-compatibility is broken in ZF trunk), but actually if you have unit tests which check your build before deploying, you are pretty safe – you spot the problem, you resolve it.

NB: This approach supposes that you tag your releases, so that when new release is coming out, you create a tag, export everything into newly created tag (thus freezing the code), and checkout from tag on production server.

Let me know your suggestions on how the component can be improved.

However, sometimes it’s not what you want, instead you need to render some other view depending on some internal criteria. For example, you may want to render some custom error displaying view. So, if we are positive on what we want, let me show you how to do it:

class TestController extends Zend_Controller_Action
{
    /**
     * test/index.phtml would be rendered by default
     * @return void
     */
    public function indexAction()
    {
        // render test/foo.phtml
        $this->_helper->viewRenderer('foo');

        // render bar/foo.phtml to the default response segment, without using a
        // controller view script subdirectory ("test" in this case):
        // so you may use scripts from other controllers
        $this->_helper->viewRenderer('bar/foo', null, true);

        // now render the script, as previous calls do not render anything,
        // they are just used so that default script is swapped and not rendered:
        $this->render('foo');
        // OR
        $this->render('bar/foo', null, true);
    }
}

Please, note that you do not need to provide view extension (foo but not foo.phtml or any extension you happen to use for your views) – what renderer expects is action name, and we simply swapping the current action. Internally, direct() method is called when you update view renderer, which in turn is proxy for setRender():

// allows you to set any of scriptAction, responseSegment,
// and noController in one pass.
setRender($action = null, $name = null, $noController = false)

So, you may use

$this->_helper->viewRenderer->setRender('foo');

to change current view, but this form is less common, as it requires more typing
NB: If you need more info on ViewRenderer there’s no better place but ZF Manual.

Frameworks make our coding life easier, and ZF is not an exception – you need very little code to get your application skeleton working. And when it comes to MVC, ZF handles almost everything – your action controllers are triggered, your views are loaded, w/o you having to worry about them. Not the same with models. If you comply to directory layout advised by ZF, you have “models” folder, but framework doesn’t interact with it in any way.

Models are simply classes, containing application logic, and to initialize one of them you have to make sure that:
a) containing directory is withing include_path
b) you require_once the class file before using it

I wanted my models to be available without any additional hassle, so I decided to find a way to auto-load models from within my controller actions.

What I did is the following:

1. Extend Zend_Controller_Action

I extended abstract controller action class, and let it remain abstract:

abstract class Afc_Controller_Action extends Zend_Controller_Action
{}

Every controller action now should be a subclass of Afc_Controller_Action, instead of Zend_Controller_Action. That way, if I need to put some method common for all my controllers, I could put it into Afc_Controller_Action, and all of them would inherit the functionality. One good example of such functionality might be auto-loading the model

2. Add loadModel() method into abstract controller action

Here is the full code of my base controller action (there are quite a few other methods, but they are not necessary for this discussion):

abstract class Afc_Controller_Action extends Zend_Controller_Action
{
    /**
     * Loads specified model from module's "models" directory
     * 
     * @param   string  $class  Model classname
     * @param   string  $module Module name. By default, current module is assumed
     * @throws  Zend_Exception  In case model class not found exception would be thrown
     * @return  string Class name loaded
     */
    public function loadModel($class, $module = null)
    {
        $modelDir = $this->getFrontController()->getModuleDirectory($module)
                       . DIRECTORY_SEPARATOR . 'models';
        Zend_Loader::loadClass($class, $modelDir);
 
        // if we got here - then file is included
        return $class;
    }
}

I doubt it could be easier! getModuleDirectory() returns me the full directory path to my modules folder, within which (according to ZF directory recommendations) I have my models:

application
  modules
    default               <---- module name
      controller
      models              <----- models directory
        Account             <----- I separate models by controllers
          Profile.php         <----- model
      views

Please note that I set modules directory in my bootstrap with:

$frontController = Zend_Controller_Front::getInstance();
$frontController->addModuleDirectory(FULL_PATH_TO_MODULES);

Here is sample action which uses model auto-loading:

class AccountController extends Afc_Controller_Action  
{
    /**
     * /default/account/profile/
     *
     * @return void
     */
    public function profileAction() 
    {
        try {
            // application/modules/default/models/Account/Profile.php is loaded
            $model = $this->loadModel('Account_Profile'); 
        } catch (Zend_Exception $e) {
            // module is not found
        }
    }
}

That's it, we auto-loading our models w/o any additional efforts to locate the models directory.

3. (Optional) Enable class auto-loading

This one is not strictly necessary, it just goes in line with model auto-loading, as it allows to auto-load any other classes within your include_path. At the beginning of bootstrap process:

require_once 'Zend/Loader.php';
Zend_Loader::registerAutoload();

Now if class is not found, Zend_Loader would try to locate it. According to ZF naming convention underscores would be considered directory separators. So, if I try to initialize My_Cool_Class() Zend_Loader would look for My/Cool/Class.php within include_path directories (well it would actually include that file, and if it is within include_path, then, obviously, it would be included).

On UMapper, I added our library path into include_path within bootstrap file, so I have no require_once() left in my code, and classes are loaded when they are necessary, not when the file with tons of require_once() is loaded.

Alternatives:

Are there any alternative approaches? Plenty! Here what I have considered (and ruled out due to various reasons) when looking for a solution:

a) Zend_Load_PluginLoader - plugin loader is used extensively in Zend_Form_* as it helps loading filters, validators, and decorators. I considered the idea to just register prefix path for all my model folders, but plugin loader is not a good option performance-wise. If you looking for such a solution reading respective section of the original documentation should be enough to get you going.

b) Zend_Load subclassing - based on class name analysis (say MyModelNameModel) decide that what needs to be loaded is the model, and look within "models" folder. The detailed solution could be found here. I did like the idea, but solution seemed to be patchy to me. Granted, Zend_Loader is the way to load classes adhering to certain convention, but if "underscores are directory separators" assumption is logical enough "all models should have keyword Model in class name" is not that intuitive. What is worse - it is not a universal convention.

c) Use controller plugin. Just extend Zend_Controller_Plugin_Abstract and put include_path changing logic into preDispatch(). Not a bad solution, but I didn't want to update include_path with "models" folders from my modules. Ideally, my include_path should contain reference to ZF, my own library, and current folder! And right now it is exactly like this.