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.

One (not quite pretty) way to still provide some feedback from __toString() is using trigger_error:

public function  __toString()
{
    try {
        $output = $this->generateXml();
        return $output;
    } catch(Exception $e) {
        trigger_error($e->getMessage(), E_USER_ERROR);
        return '';
    }
}

If you know of a better option, let me know!

In an attempt to shed some light on and to draw attention to SPL, I plan to post several articles discussing various parts of this extension. I will start with SPL Interfaces so that you can grasp immediately the usefulness of the SPL.

Comprehending SPL interfaces presupposes that you know standard interfaces that come build-in with PHP5. So, I wrote preliminary article discussing them – I consider it to be a prerequisite for good understanding of the current material.

Covered in this article:

• The Countable Interface
• The OuterIterator Interface
• The SeekableIterator Interface
• The RecursiveIterator Interface
• The SplObserver and SplSubject Interfaces

 
The Countable Interface

Countable interface is quite simple: classes implementing it can be used with the count() function.

Countable   {
    /* Methods */
    abstract public int count ( void )
}

As you see, all it takes to comply to interface’s contract is implementation of single method, namely count():

/**
 * Dummy "contained" class
 */
class Item {}

/**
 * Dummy "container" class implementing Countable
 */
class Items implements Countable
{
    protected $items = array();

    public function add(Item $item)
    {
        $this->items[] = $item;
        return $this;
    }

    public function count()
    {
        return count($this->items);
    }
}

$items = new Items();
$items->add(new Item())
      ->add(new Item())
      ->add(new Item());
echo count($items);     // outputs 3
// you can use sizeof() as well - since it's an alias for count()
echo sizeof($items);

 
The OuterIterator Interface

I am not sure why php manual’s respective section doesn’t contain explanation of this interface, my wild guess – doc.team hasn’t time to fill it (hopefully, yet). Anyway, here is what OuterIterator is all about: OuterIterator serves as wrapper for another inner iterator (which is generally passed into constructor of implementing class). It is similar to IteratorAggregate, but while the former is extending Traversable, OuterIterator extends Iterator – so implementing class not only contains accessor method for contained iterator, but could be iterated itself as well I know, how it sounds, no need to panic though – everything would be clear in a moment. Let’s first look into synopsis:

OuterIterator extends Iterator {
    /* Methods */
    abstract public Iterator getInnerIterator();

    /* Inherited methods */
    abstract public mixed current( void  )
    abstract public scalar key( void )
    abstract public void next( void )
    abstract public void rewind( void )
    abstract public boolean valid( void )
}

So, implementing object must be traversable and contain reference to some inner iterator. There’s great pre-build FilterIterator, which is an abstract class, allowing to create filter iterators (iterators that filter out some unwanted values). FilterIterator implements OuterIterator – you pass the iterator to be filtered, and then you can traverse the FilterIterator for filtered values. Let’s build our own version of FilterIterator:

class OddsFilter implements OuterIterator
{
    protected $innerIterator;

    public function __construct($it)
    {
        $this->innerIterator = $it;
    }

    /**
     * whether the current element of the iterator is acceptable
     */
    public function accept()
    {
        return (bool)($this->current() % 2); // false on evens, true on odds
    }

    /**
     * OuterIterator Methods
     */
    public function getInnerIterator()
    {
        return $this->innerIterator;
    }

    /**
     * Inherited Methods
     */
    public function current()
    {
        return $this->innerIterator->current();
    }

    public function key()
    {
        return $this->innerIterator->key();
    }

    public function next()
    {
        $this->innerIterator->next();
        $this->fetch();
    }

    public function rewind()
    {
        $this->innerIterator->rewind();
        $this->fetch();
    }

    public function valid()
    {
        return $this->innerIterator->valid();
    }

    /**
     * Move forward until the condition defined in accept() is met
     */
    protected function fetch()
    {
        while($this->innerIterator->valid()) {
            if($this->accept()) {
                return;
            }
            $this->innerIterator->next();
        }
    }
}

$iterator = new ArrayIterator(array(1, 2, 3, 4, 5));
$filteredIterator = new OddsFilter($iterator);
print_r(iterator_to_array($filteredIterator));

Time to take a closer look at code. OddsFilter is an iterator that filters out even numbers and returns odd numbers only. It accepts instance of Iterator in its constructor, here we used ArrayIterator (very simple iterator, allowing us to traverse arrays and objects). So, on line 70, we created $iterator variable from sample array, and passed this iterator into OddsFilter. OddsFilter mainly delegates calls to contained/inner iterator with a prominent exception of next() and rewind() methods, they call additional method fetch():

protected function fetch()
{
    while($this->innerIterator->valid()) {
        if($this->accept()) {
            return;
        }
        $this->innerIterator->next();
    }
}

Here, again, we eventually call inner iterator’s next() method, but we might call it several times, untill acceptable value is found.

You might wonder what iterator_to_array() function does, simple – it copies iterator into array, so that resultant output of our code would be:

Array
(
    [0] => 1
    [2] => 3
    [4] => 5
)

Of course, instead of using iterator_to_array(), I could have also traversed $filteredIterator with foreach loop – after all OddsFilter is an iterator itself.

To sum up, OuterIterator is helpful when we have some input iterator (which serves as inner iterator), that should be somehow manipulated (filtered in our case), and results should also be traversable (which is true, as OuterIterator implements Iterator interface itself).

Please note that extending FilterIterator class is far superior way of building filters – all you need is to implement abstract accept() method to get very same results (all traversal logic is done within FilterIterator itself).

Note: Thanks to P18X for spotting the bug in original code – fixed now.

 
The SeekableIterator Interface

This interface is build on Iterator and adds support for quick navigating (seeking) of a certain positions. Everything is done via seek() method added with this interface:

SeekableIterator extends Iterator {
    /* Methods */
    abstract public void seek( int $position )
    /* Inherited methods */
    abstract public mixed Iterator::current( void )
    abstract public scalar Iterator::key( void )
    abstract public void Iterator::next( void )
    abstract public void Iterator::rewind( void )
    abstract public boolean Iterator::valid( void )
}

Within seek() method internal iterator position should be set to requested value, if position not found or applicable OutOfBoundsException should be thrown.

Here is sample iterator implementing the SeekableIterator:

class Item
{
    protected $title = null;

    public function __construct($title)
    {
        $this->title = $title;
    }

    public function __toString()
    {
        return $this->title;
    }
}

class Items implements SeekableIterator
{
    /**
     * List of contained items
     * @var array
     */
    protected $items = array();

    /**
     * Current iterator position
     * @var int
     */
    protected $pos = 0;

    public function add(Item $item)
    {
        $this->items[] = $item;
        return $this;
    }

    /**
     * SeekableIterator methods
     */
    public function seek($pos)
    {
        $this->pos = $pos;
        if(!$this->valid()) { // position is not seekable!
            throw new OutOfBoundsException('Item at position ' . $pos . ' not found..');
        }
    }

    /**
     * Iterator methods
     */
    public function current()
    {
        return $this->items[$this->pos];
    }

    public function key()
    {
        return $this->pos;
    }

    public function next()
    {
        $this->pos++;
    }

    public function rewind()
    {
        $this->pos = 0;
    }

    public function valid()
    {
        return isset($this->items[$this->pos]);
    }
}

$items = new Items();
$items->add(new Item('milk'))
      ->add(new Item('butter'))
      ->add(new Item('bread'));

try {
    $items->seek(2);
    printf('%d - %s ', $items->key(), $items->current()); // 2 - bread

    $items->seek(3); // OutOfBoundsException should be thrown
                     // Item at position 3 not found..
} catch (OutOfBoundsException $e) {
    die($e->getMessage());
}

As you can see, I based this example on Iterator’s example from preliminary article. Indeed, in order to make our iterator more flexible (next() method is cool but locating items in any order other than sequential is impossible), all we have to do is to add seek() method that does the job.

 
The RecursiveIterator Interface

Before we get into details, let’s give somewhat formal definition of interface.

RecursiveIterator extends Iterator interface, so it is an iterator itself. What is special about this iterator is the fact that items it contains can be also traversed i.e. we can create iterators for them. Consider multi-dimensional array:

$numbers = array(
    array(1, 2),
    array(3, 4, 5, array(6, 7)),
    8, 9
);

This array has 4 elements in total. Whilst first two are arrays, last two (8, 9) are scalars. Imagine that we wanted to print all numbers in that $numbers array – obviously the recursive function is the most elegant solution (which allows us to have as much depth as necessary). Here, we can traverse first two elements of the array, as they are arrays themselves, even more – the second element has not only scalars in it but yet another array to be traversed:

    array(3, 4, 5, array(6, 7))

RecursiveIterator interface was designed to solve exactly this kinds of problems. If you have a complex structure with multiple levels of data, this interface helps you to recursively traverse all contained elements. Thus in PHP manual definition of this interface goes as following:

Classes implementing RecursiveIterator can be used to iterate over iterators.

Indeed, if any contained entry can be traversed (i.e. we can attach iterator to it), RecursiveIterator provides an interface to do so.

Here is the synopsis:

RecursiveIterator extends Iterator {
    // Returns an iterator for the current entry
    public RecursiveIterator getChildren( void )

    // whether an iterator could be created for the current entry
    public bool hasChildren( void ) 

    /* Inherited methods */
    abstract public mixed Iterator::current ( void )
    abstract public scalar Iterator::key ( void )
    abstract public void Iterator::next ( void )
    abstract public void Iterator::rewind ( void )
    abstract public boolean Iterator::valid ( void )
}

As you see two new methods has been added.

Please note, these methods apply to the current entry, not the base iterator itself. So, hasChildren() should check whether current entry is an array or object, and as such is traversable, thus allowing to create iterator for it. By the same token, getChildren() returns iterator for the current entry’s contained items. Somewhat obvious, but when I first read the documentation, it took me some time to figure this out.

In order to iterate over children items, we have to be sure that entry is traversable – hasChildren() method is exactly for this. Once we know, that current entry is traversable, we should be able to obtain iterator to do so – getChildren() returns such an iterator (its type must be RecursiveIterator – what we are dealing with, on all levels of recursion, is always one type of interface).

It’s time to show you some code! First of all NumberIterator I have written to “flatten” arrays, so that despite the dimensions, I can have a list of all elements:

class NumbersIterator implements RecursiveIterator
{
    /**
     * List of numbers. Array may be multi-dimensional.
     * @var array
     */
    public $numbers = array();

    /**
     * Current iterator's position
     * @var int
     */
    protected $pos = 0;

    /**
     * Initiates iterator
     * @param array $numbers
     */
    public function __construct($numbers = array())
    {
        $this->numbers = $numbers;
    }

    /**
     * RecursiveIterator methods
     */

    /**
     * Returns current entry's iterator
     * @return NumbersIterator
     */
    public function getChildren()
    {
        return new NumbersIterator($this->current());
    }

    /**
     * Returns true if iterator could be obtained for the current entry.
     * @return boolean
     */
    public function hasChildren()
    {
        return is_array($this->current());
    }

    /**
     * Iterator methods
     */
    public function current()
    {
        return $this->numbers[$this->pos];
    }

    public function key()
    {
        return $this->pos;
    }

    public function next()
    {
        $this->pos++;
    }

    public function rewind()
    {
        $this->pos = 0;
    }

    public function valid()
    {
        return isset($this->numbers[$this->pos]);
    }
}

Now we need a recursive function, which would help us traversing:

function displayNumbers(NumbersIterator $iterator) {
    while($iterator->valid()) {
        if($iterator->hasChildren()) {
            displayNumbers($iterator->getChildren());
        } else {
            echo $iterator->current() . '';
        }
        $iterator->next();
    }
}

Finally, let’s traverse the array I have shown you at the beginning of this section:

$numbers = array(
    array(1, 2),
    array(3, 4, 5, array(6, 7)),
    8, 9
);

$iterator = new NumbersIterator($numbers);
displayNumbers($iterator);

Everything should be pretty self-explanatory – scalars get printed “as is”, if current iteratable entry is an array (i.e. hasChildren() returns true), I traverse all its children, by recursively calling displayNumbers().

This section was one of the hardest to explain, so sorry for lengthy code and explanations. If you still feel lost, please, let me know via comments – I would try to clarify and improve current section.

 
The SplObserver and SplSubject Interfaces

I would discuss both interfaces in a single section, as they describe well known Observer design pattern.

Again, I am not sure why PHP Manual’s respective section does not provide any info regarding this interfaces, I believe they are quite important, so here is what they all about:

I would not go into any details regarding observer pattern – as there better places (here for eg) that provide explanation and PHP implementations of the pattern. In a nutshell, the pattern allows you to define one-to-many relationship between so called Subject and Observer(s), and once the state of the Subject changes, all bind Observer(s) get notified. If you know Java (read-only is enough), Head First Design Patterns is really mind-friendly intro (I don’t suggest GoF’s book, because if you are able to get through it, there’s 0 possibility you haven’t tried it yet )

Now, back to interfaces.

SplSubject

SplSubject {
    public void attach(SplObserver $observer);
    public void detach(SplObserver $observer);
    public void notify();
}

Interface is pretty simple: you should be able to attach observing objects, detach them, and, once state of the subject is changed, notify observers. Here is sample implementation:

class Subject implements SplSubject
{
    /**
     * List of attached observers
     * @var array
     */
    protected $observers = array();

    protected $title = null;

    /**
     * Update subject's title - observers notified!
     * @param string $title
     */
    public function setTitle($title)
    {
        $this->title = $title;
        $this->notify(); // all observers get notified of change
    }

    public function getTitle()
    {
        return $this->title;
    }

    /**
     * SplSubject methods
     */

    public function attach(SplObserver $observer)
    {
        $this->observers[] = $observer;
    }

    public function detach(SplObserver $observer)
    {
        // I cannot use array_search output in IF block directly,
        // as 0 might be returned (if what I am detaching is the first observer)
        // so I must make sure that $key is not false (taking type into account)
        $key = array_search($observer, $this->observers, true);
        if( !($key === false) ) {
            unset($this->observers[$key]);
        }
    }

    public function notify()
    {
        foreach($this->observers as $observer) {
            $observer->update($this);
        }
    }
}

SplObserver is even more simple, all you have to do is to provide update() method:

SplObserver {
    public void update(SplSubject $subject);
}

Implementation of simple observer class:

class Observer implements SplObserver
{
    public function update(SplSubject $subject)
    {
        echo 'Subject updated! New title: ' . $subject->getTitle();
    }
}

Now, let’s use our Subject and Observer together:

$subject = new Subject();       // create subject
$observer = new Observer();     // create observer
$subject->attach($observer);    // attach observer
$subject->setTitle('Hi, there!'); // Subject updated! New title: Hi, there!

Well, SPL implementation of the observer pattern is not the best I’ve seen – since it tightly couples the subject and observer (for example, our observer is aware that subject has getTitle() method). However, for most needs it is good enough.

Conclusion

I hope you enjoyed at least some parts of this article, and hopefully it gives you better understanding of the SPL’s interfaces.

I wanted to provide good overview of (highly under-used) Standard PHP Library (SPL) starting with interfaces. However, without firstly discussing predefined interfaces, which come bundled with each and every PHP distribution, discussion of SPL-provided ones seemed to be incomplete.

To be covered in this article:

• The Traversable Interface
• The Iterator Interface
• The IteratorAggregate Interface
• The ArrayAccess Interface
• The Serializable Interface

 
The Traversable Interface

Basically this interface is used to mark that object of the class can be used in foreach i.e. it could be traversed. This interface is internal in a sense that you cannot use it directly in your scripts, instead you have to implement either Iterator or IteratorAggregate interfaces (which extend the Traversable). Since the interface is not implementable within your PHP classes, it’s synopsis does not enforce any methods:

Traversable
{}

 
The Iterator Interface

Extends the Traversable, this interface can be used to produce objects that can iterate themselves. As a rule of thumb: if your object holds number of some items, and you need to access them individually in foreach, Iterator (or IteratorAggregate for that matter) is the good bid. Here is the synopsis:

Iterator extends Traversable {
    /* Methods */
    abstract public mixed current ( void )  // return current element's value
    abstract public scalar key ( void )     // return current element's key
    abstract public void next ( void )      // move internal pointer forward
    abstract public void rewind ( void )    // move to the beginning
    abstract public boolean valid ( void )  // check if current position is valid
}

To illustrate, here is sample Iterator implementation and usage:

class Item
{
    protected $title = null;

    public function __construct($title)
    {
        $this->title = $title;
    }

    public function __toString()
    {
        return $this->title;
    }
}

class Items implements Iterator
{
    /**
     * List of contained items
     * @var array
     */
    protected $items = array();

    /**
     * Current iterator position
     * @var int
     */
    protected $pos = 0;

    public function add(Item $item)
    {
        $this->items[] = $item;
        return $this;
    }

    /**
     * Iterator methods
     */
    public function current()
    {
        return $this->items[$this->pos];
    }

    public function key()
    {
        return $this->pos;
    }

    public function next()
    {
        $this->pos++;
    }

    public function rewind()
    {
        $this->pos = 0;
    }

    public function valid()
    {
        return isset($this->items[$this->pos]);
    }
}

$items = new Items();
$items->add(new Item('milk'))
      ->add(new Item('butter'))
      ->add(new Item('bread'));

foreach($items as $key => $item) {
    printf('%d - %s ', $key, $item);
}
// Output:
// 0 - milk
// 1 - butter
// 2 - bread

Pretty simple, isn’t it? Granted, it takes time to get used to, but once you do, you would never look back.

 
The IteratorAggregate Interface

PHP5 comes with a lot of predefined iterators (and SPL adds to the list), so you rarely need to write your own. For situations when there’s already suitable iterator for your object (either pre-build or written by you), there’s little sense to implement Iterator interface, instead it’s just enough to implement the IteratorAggregate, which allows you to use external iterators. Here is interface synopsis:

IteratorAggregate extends Traversable {
    /* Methods */
    abstract public Traversable getIterator( void )
}

As you see, all you have to do is to provide getIterator() method, which would return suitable instance of iterator to be used for traversal:

class Numbers implements IteratorAggregate
{
    protected $numbers = array(1, 2, 3);

    public function getIterator()
    {
        return new ArrayIterator($this->numbers);
    }
}

$nums = new Numbers();
foreach($nums as $k=>$v) {
    printf('%d - %d ', $k, $v);
}

// Output:
//0 - 1
//1 - 2
//2 - 3

I used predefined ArrayIterator iterator, which allows to traverse arrays and objects. You can use your own iterator as well (the only requirement is that it implements on Traversable).

 
The ArrayAccess Interface

One of the coolest interfaces that come with PHP5, ArrayAccess allows you to interact with your objects as if they were arrays. If you are familiar with C++, it’s like overloading [] operator (well, almost). Anyway, here is interface synopsis:

ArrayAccess {
    // whether an offset exists
    abstract public boolean offsetExists( mixed $offset )
    // returns the value at specified offset
    abstract public mixed offsetGet( mixed $offset )
    // assigns a value to the specified offset
    abstract public void offsetSet( mixed $offset , mixed $value )
    // unsets an offset
    abstract public void offsetUnset( mixed $offset )
}

Don’t worry if interface doesn’t seem simple at first, everything would clear up once you review the example:

class Config implements ArrayAccess
{
    protected $options = array(
        'username' => 'torio',
        'uri'      => 'http://www.phpmag.ru/'
    );

    /**
     * ArrayAccess implementation
     */
    public function offsetExists($offset)
    {
        return isset($this->options[$offset]);
    }

    public function offsetGet($offset )
    {
        return $this->options[$offset];
    }

    public function offsetSet($offset, $value )
    {
        $this->options[$offset] = $value;
    }

    public function offsetUnset($offset )
    {
        unset($this->options[$offset]);
    }
}

$config = new Config();
if(isset($config['uri'])) { // offsetExists() is called internally
    printf('URI: %s ', $config['uri']);   // offsetGet()
}
$config['username'] = 'vic';                    // offsetSet()
printf('Username: %s', $config['username']);

unset($config['uri']);                          // offsetUnset()
if(!isset($config['uri'])) {
    echo 'Offset deleted..';
}

// Output:
// URI: http://www.phpmag.ru/
// Username: vic
// Offset deleted..

Note: As of PHP 5.3 it is possible to return the value at a given offset by reference.

 
The Serializable Interface

This is the last of predefined interfaces, and is actually quite a simple one (if you are familiar with data serialization). If you want your object to control its serialization/unserialization process you can either use magic methods __sleep()/__wakeup() or, more explicitly, just to implement the Serializable interface:

Serializable {
    /* Methods */
    abstract public string serialize( void )
    abstract public mixed unserialize( string $serialized )
}

Here is trivial example:

class Item implements Serializable
{
    protected $title = null;

    public function __construct($title)
    {
        $this->title = $title;
    }

    public function getTitle()
    {
        return $this->title;
    }

    /**
     * Serializable implementation
     */
    public function serialize()
    {
        return serialize(array($this->title));
    }

    public function unserialize($serialized )
    {
        list($title) = unserialize($serialized);
        // this method is invoked as constructor, if you need to use
        // default constructor, invoke it manually:
        $this->__construct($title);
    }

}

$serialized = serialize(new Item('milk'));
$obj = unserialize($serialized);
printf('Title: %s ', $obj->getTitle()); // Title: milk

That’s about it! If you liked the article, consider subscribing to RSS, so that you can follow up the incoming SPL tutorials.

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.

/**
 * @return Some_Base_Abstract_Class_Name
 */
public function factory($adapter)

but that doesn’t work if returned objects are specifications of more general abstract class (exactly the case with factory).

As it turned out, you can easily resolve this issue – just document your variable with @var, before calling factory() method:

/**
 * @var Some_Specific_Class $foo
 */
$foo = Magic::factory('adapterName');
$foo-> // and NetBeans opens pop-up list with available attributes and methods

The good news, you can use this method in any scope – it just works I love NetBeans!!

UPD: Well, actually NetBeans seems to be picky of scope – as reported by others (and confirmed by myself).

UPD1: Actually NetBeans handles this quite well, just use vdoc (review this and this for details)

jQuery(document).ready(function($){
    // inside this block you can use $ shortcut !!
});

Just a small note to myself