• We would create a marker ExceptionInterface for each package.
• We would extend SPL exceptions and implement the package marker interface when doing so.

What this gave users was the ability to catch in three ways:

• They could catch the most specific exception type by class name.
• They could catch all package-level exceptions using the marker interface.
• The could catch general exceptions using the associated SPL type.

So, as an example:

try {
    $do->something();
} catch (MostSpecificException $e) {
} catch (PackageLevelExceptionInterface $e) {
} catch (\RuntimeException $e) {
}

This kind of granularity is really nice to work with. So nice that some standards produced by PHP-FIG now ship them, such as PSR-11, which ships a ContainerExceptionInterface and a NotFoundExceptionInterface.

One thing we've started doing recently as we make packages support only PHP 7 versions is to have the marker ExceptionInterface extend the Throwable interface; this ensures that implementations must be able to be thrown!

So, what happens when you're writing a one-off implementation of something that is expected to throw an exception matching one of these interfaces?

Why, use an anonymous class, of course!

As an example, I was writing up some documentation that illustrated a custom ContainerInterface implementation today, and realized I needed to throw an exception at one point, specifically a Psr\Container\NotFoundExceptionInterface. I wrote up the following snippet:

$message = sprintf(/* ... */);
throw new class($message) extends RuntimeException implements
    NotFoundExceptionInterface {
};

Done!

This works because RuntimeException takes a message as the first constructor argument; by extending that class, I gain that behavior. Since NotFoundExceptionInterface is a marker interface, I did not need to add any additional behavior, so this inline example works out-of-the-box.

What else are you using anonymous classes for?

Creating Exception types on-the-fly in modern PHP was originally published 5 December 2018 on https://mwop.net by Matthew Weier O'Phinney.

In the process, I ran into a number of interesting issues, some of which took quite some time to resolve; this post is both to help inform other potential users of the service, as well as act as a reminder to myself.

Cron

OpenShift offers a Cron cartridge, which I was excited to try out.¹

The basics are quite easy. In your repository's .openshift directory is a cron subdirectory, further divided into minutely, hourly, daily, weekly, and monthly subdirectories. You drop a script you want to run into one of these directories, and push your changes upstream.

The problem is: what if I want a job to run at a specific time daily? or on the quarter hour? or on a specific day of the week?

As it turns out, you can manage all of the above, just not quite as succinctly as you would in a normal crontab. Here, for example, is a script that I run at 5AM daily; I placed it in the hourly directory so that it can test more frequently:

#!/bin/bash
if [ `date +%H` == "05" ]
then
    (
        export PHP=/usr/local/zend/bin/php ;
        cd $OPENSHIFT_REPO_DIR ; 
        $PHP public/index.php phlycomic fetch all ; 
        $PHP public/index.php phlysimplepage cache clear --page=pages/comics 
    )
fi

And here's one that runs on the quarter-hour, placed in the minutely directory:

#!/bin/bash
MINUTES=`date +%M`

for i in "00" "15" "30" "45";do
    if [ "$MINUTES" == "$i" ];then
        (
            export PHP=/usr/local/zend/bin/php ;
            cd $OPENSHIFT_REPO_DIR ;
            $PHP public/index.php githubfeed fetch 
        )
    fi
done

The point is that if you need more specificity, push the script into the next more specific directory, and test against the time of execution.

Naked Domains

Naked domains are domains without a preceding subdomain. In my case, this means "mwop.net", vs. "www.mwop.net".

The problem that cloud hosting presents is that the IP address on which you are hosted can change at any time, for a variety of reasons. As such, you typically cannot use DNS A records to point to your domain; the recommendation is to use a CNAME record that points the domain to a "virtual" domain registered with your cloud hosting provider.

However, most domain registrars and DNS providers do not let you do this for a naked domain, particularly if you also have MX or other records associated with that naked domain.

Some registrars will allow you to forward the A record to a subdomain. I tried this, but had limited success; I personally found that I ended up in an infinite loop situation when doing the DNS lookup.

Another solution is to have a redirect in place for your naked domain to the subdomain, which can then be a CNAME record. Typically, this would require you have a web server under your control with a fixed IP that then simply redirects to the subdomain. Fortunately, there's an easier solution: wwwizer. You simply point your naked domain A record to the wwwizer IP address, and they will do a redirect to your www subdomain.

I implemented wwwizer on my domain (which is why you'll see "www.mwop.net" in your location bar), and it's been working flawlessly since doing so.

Private repositories

I keep my critical site settings in a private repository, which allows me to version them while keeping the credentials they hold out of the public eye. This means, however, that I need to use GitHub deploy keys on my server in order to retrieve changes.

This was simple enough: I created an ssh subdirectory in my $OPENSHIFT_DATA_DIR directory, and generated a new SSH keypair.

The problem was telling SSH to use this key when fetching changes.

The solution is to use a combination of ssh-agent and ssh-add, and it looks something like this:

#!/bin/bash
ssh-agent `ssh-add $OPENSHIFT_DATA_DIR/ssh/github-key && (
    cd $OPENSHIFT_DATA_DIR/config ; 
    git fetch origin ; 
    git rebase origin/mwop.net.config
)`

After testing the above, I put this in a pre_build script in my OpenShift configuration so that I can autoupdate my private configuration on each build. However, I discovered a new problem: when a build is being done, the ssh-agent is not available, which means the above cannot be executed. I'm still trying to find a solution.

Fin

I'm pretty happy with the move. I don't have to do anything special to automate deployment, and all my cronjobs and deployment scripts are now self-contained in the repository, which makes my site more portable. While a few things could use more documentation, all the pieces are there and discoverable with a small amount of work.

I'll likely give some other PaaS providers a try in the future, but for the moment, I'm quite happy with the functionality and flexibility of OpenShift.

Footnotes

• ¹ Zend Server's JobQueue can also be used as a cron replacement, but I was not keen on exposing the job functionality via HTTP.

OpenShift, Cron, and Naked Domains was originally published 30 December 2012 on https://mwop.net by Matthew Weier O'Phinney.

I was a founding member of the Framework Interoperability Group, now called "php-fig". I was one of around a dozen folks who sat around a table in 2009 in Chicago during php|tek and started discussions about what we could all do to make it possible to work better together between our projects, and make it simpler for users to pick and choose from our projects in order to build the solutions to their own problems.

The first "standard" that came from this was PSR-0, which promoted a standard class naming convention that uses a 1:1 relationship between the namespace and/or vendor prefix and the directory hierarchy, and the class name and the filename in which it lives. To this day, there are both those who hail this as a great step forward for cooperation, and simultaneously others who feel it's a terrible practice.

And then nothing, for years. But a little over a year ago, there was a new push by a number of folks wanting to do more. Paul Jones did a remarkable job of spearheading the next two standards, which centered around coding style. Again, just like with PSR-0, we had both those feeling it was a huge step forward, and those who loathe the direction.

What was interesting, though, was that once we started seeing some new energy and momentum, it seemed that everyone wanted a say. And we started getting dozens of folks a week asking to be voting members, and new proposal after new proposal. Whether or not somebody likes an existing standard, they want to have backing for a standard they propose.

And this is when we started seeing proposals surface for shared interfaces, first around caching, and now around logging (though the latter is the first up for vote).

Shared Interfaces

The idea around shared interfaces is simple: if we can come to a consensus on the basic interface for a common application task, libraries and frameworks can typehint on that shared interface, allowing developers to drop in the implementation of their choosing — or even a standard, reference implementation. The goal is to prevent Not Invented Here (NIH) syndrome, as well as to make it simpler to re-use components between one library and another. As an example, if you're using Framework A, and it has a caching library, and you're consuming ORM B, you'd be able to pass the same cache object to the ORM as you use in the framework.

Great goals, really.

But I'm not sure I buy into them.

Problems

First, I agree that NIH is a problem.

Second, I also think there's space for multiple implementations of any given component. Often there are different approaches that different authors will take: one might focus on performance, another on having multiple adapters for providing different capabilities, etc. Sometimes having a different background will present different problem areas you want to resolve. As such, having multiple implementations can be a very good thing; developers can look at what each provides, and determine which solves the particular issues presented in the current project.

Because of this latter point, I have my reservations about shared interfaces.

What if a particular approach requires deviating from the shared interface in order to accomplish its goals? Additionally, in order to keep the greatest amount of compatibility between projects, shared interfaces tend to be so generic that specific implementations require developers to do a ton of manual type checking and munging of parameters, leading to more overhead, more difficulty testing and maintaining, and more difficulty documenting and understanding.

As an example, consider the following (made up) signature for a log method:

public function log($message, array $context = null);

What if your library supports an idea of priorities? Where would that information go in the above signature — and would that differ between libraries — would one library use the key for a completely different purpose? What about logging objects — the signature doesn't say you can't, but how would I know if a specific implementation supports it, and won't blow up if I do pass one? Why must the $context be an array — why won't any Traversable or ArrayAccess object work?

Basically, by being overly generic, the signature becomes a liability for those implementing the interface; it prevents meaningful interoperability and leads to splintering implementations.

(Please note: the above is completely fictional and has no bearing on current proposed or accepted standards. It is a thought exercise only.)

Furthermore, if a given project writes their own implementation of a component, and it has specialized features, why would they want to typehint on a generic, shared interface that doesn't implement those features? This would be counter-intuitive, as the project would then need to either check on additional interfaces for the specialized capabilities, duck-type, etc. — all of which make for more maintenance and code.

In summary, my primary problem with the idea of shared interfaces is that I feel there is always room for new thinking and ideas in any given problem space, and that this thinking should not be restricted by what already exists. Secondarily, I feel that it's okay for a given project to be selective about what capabilities it requires for its internal consumption and consistency, and should not limit itself to a standardized interface.

But, but, SHARING

Remember, the first point I made was that I think NIH is a problem. How do I reconcile that with a firm stance against shared interfaces?

Easy: bridges and/or adapters.

Let's go back to that example of Framework A, its caching library, and working with ORM B.

Let's assume that ORM B defines an interface for caching, and let's say it looks like this:

interface CacheInterface
{
    public function set($key, $data);
    public function has($key);
    public function get($key);
}

Furthermore, we'll assume that the expected parameter values and return types are documented.

What we as a consumer of both Framework A and ORM B can do is build an implementation of CacheInterface that accepts a cache instance from Framework A, and proxies the various interface methods to that instance.

class FrameworkACache implements CacheInterface
{
    protected $cache;

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

    public function set($key, $data)
    {
        $item = new CacheItem($key, $data);
        $this->cache->setItem($item);
    }

    public function has($key)
    {
        return $this->cache->exists($key);
    }

    public function get($key)
    {
        $item = $this->cache->getItem($key);
        return $item->getData();
    }
}

Assuming your code is well-decoupled, and you're using some sort of Inversion of Control container, you can likely create a factory for your ORM that will grab the above class, with the cache injected, and inject it into the ORM instance. Yes, it's a bit more work, but it's difficult to question the end result: shared caching between the framework and the ORM — and no need for shared interfaces, nor any need to sacrifice features within the framework or the ORM.

Sharing is good, developing solutions is better

I think the core idea of the php-fig group is sound: let's all start thinking about how we can make it easier to operate with each other. That said, my thoughts on how to accomplish that goal have changed significantly, and boil down to:

• Use naming conventions that will reduce collisions (i.e., use per-project vendor prefixes/namespaces)
• Use semantic versioning
• Keep your installation packages segregated
• Have a simple, discoverable way to autoload
• Provide interfaces for anything that could benefit from alternate implementations Don't write code that has side-effects in the global namespace (including altering PHP settings or superglobals)

Following these principals, you can play nice with each other, while still fostering innovative and differentiating solutions to shared problems.

On php-fig and Shared Interfaces was originally published 20 December 2012 on https://mwop.net by Matthew Weier O'Phinney.

Why would you want to participate? Well, for one, because you can interact directly with the various speakers during the presentations. Sure, you can likely find the slide decks elsewhere, or possibly even recordings. But if we all do our jobs right, we'll likely raise more questions than answers; if you attend, you'll get a chance to ask some of your questions immediately, and we may even answer them!

On top of that, this is a fantastic lineup of speakers, and, frankly, not a lineup I've ever participated in. In a typical conference, you'd likely see one or two of us, and be lucky if we weren't scheduled against each other; if you attend this week, you'll get to see us all, back-to-back.

What else will you be doing this Friday, anyways, while you wait for the end of the world?

So, do yourself a favor, and register today!

PHP Master Series on Day Camp For Developers was originally published 18 December 2012 on https://mwop.net by Matthew Weier O'Phinney.

Unusually for me, I did not speak on a Zend Framework topic, and had only one regular slot (I also co-presented a Design Patterns tutorial with my team). That slot, however, became one of my favorite talks I've delivered: "Designing Beautiful Software". I've given this talk a couple times before, but I completely rewrote it for this conference in order to better convey my core message: beautiful software is maintainable and extensible; writing software is a craft.

I discovered today that not only was it recorded, but it's been posted on YouTube:

I've also posted the slides.

My ZendCon Beautiful Software Talk was originally published 17 November 2012 on https://mwop.net by Matthew Weier O'Phinney.

Starting in PHP, OOP enthusiasts got a whole bunch of new tools, and new tools keep coming into the language for us with each minor release. One feature that has had a huge impact on frameworks and libraries has been available since the earliest PHP 5 versions: visibility.

Theory

The visibility keywords include private, protected, and public, often referred to as PPP. There's an additional keyword I often lump in with them, final.

Public visibility is the default, and equivalent to the only visibility available to PHP prior to version 5: any member declared public is accessible from any scope. This means the following:

class Foo
{
    public $bar = 'bar';

    public function baz() 
    {
        // I can access within my own scope
        return $this->bar;
    }
}

class FooBar extends Foo
{
    public function doThat()
    {
        // I have access to members in my parent
        return $this->bar . $this->baz();
    }
}

$foo = new Foo();

// I can access public members from an instance
echo $foo->bar . $foo->baz();

Basically, public visibility means that I can access the member from within the object, within an extending class, or from simply an instance.

Protected visibility starts to tighten things down a little. With protected visibility, only the class itself, or an extending class, can access the member:

class Foo
{
    protected $bar = 'bar';

    protected function baz() 
    {
        // I can access within my own scope
        return $this->bar;
    }
}

class FooBar extends Foo
{
    public function doThat()
    {
        // I can access protected members in my parent
        return $this->bar . $this->baz();
    }
}

$foo = new FooBar();

// This works, as I'm calling a public member of an extending class:
$foo->doThat();

// But these are both illegal:
echo $foo->bar . $foo->baz();

Protected visibility is nice for hiding things from those consuming your class. It can be used to hide implementation details, and to prevent direct modification of public properties — something important to consider, if a property may be the product of calculation, or if a particular type is required.

Private visibility locks things down further. With private visibility, the object member is only directly modifiable or callable within the declaring class.

class Foo
{
    private $bar = 'bar';

    private function baz() 
    {
        // I can access within my own scope
        return $this->bar;
    }
}

class FooBar extends Foo
{
    public function doThat()
    {
        // These are both illegal
        return $this->bar . $this->baz();
    }
}

$foo = new FooBar();

// These are also both illegal:
echo $foo->bar . $foo->baz();

Private visibility is generally of interest for locking down algorithms. For instance, if you know that a particular value or operation must not change, even in extending classes, declaring the member private ensures that extending classes cannot directly call it.

At any point, you can redeclare a property in an extending class using equal or more public visibility. The effect of doing so depends on what the visibility of the member was in the parent class.

• In the case of a public property, if an extending class re-declares with public visibility, any access to the member within the extending class or an instance of the extending class will see only the new declaration.

  class Foo
  {
      public $bar = 'bar';
  
      public function baz() 
      {
          return $this->bar;
      }
  }
  
  class FooBar extends Foo
  {
      public $bar = 'foobar';
  }
  
  $foo = new FooBar();
  echo $foo->bar;   // "foobar"
  echo $foo->baz(); // "foobar"
  

• In the instance of a protected property, if the extending class re-declares with either public or protected visibility, you get the same behavior as public -> public.

  class Foo
  {
      protected $bar = 'bar';
  
      public function baz() 
      {
          return $this->bar;
      }
  }
  
  class FooBar extends Foo
  {
      public $bar = 'foobar';
  }
  
  $foo = new FooBar();
  echo $foo->bar;   // "foobar"
  echo $foo->baz(); // "foobar"
  

• In the instance of a private property, things get interesting. The private value or method will be used for any access made within code declared in the parent class, but not overridden in the child. However, if the child class overrides any code, the value of the re-declared instance will be used. This is far easier to understand via an example.

  class Foo
  {
      private $bar = 'bar';
      private $baz = 'baz';
  
      public function baz() 
      {
          return $this->bar;
      }
  }
  
  class FooBar extends Foo
  {
      protected $bar = 'foobar';
      private $baz = 'foobaz';
  
      public function myBaz() 
      {
          return $this->bar;
      }
  
      public function myBaz2()
      {
          return $this->baz;
      }
  }
  
  $foo = new FooBar();
  echo $foo->baz();    // "bar"
  echo $foo->myBaz();  // "foobar"
  echo $foo->myBaz2(); // "foobaz"
  

My personal takeaway from this is:

• Use public for members that are safe for anything to call.
• Use protected for anything you don't want called from instance methods, not important to the public API (implementation details), and anything you feel is safe for extending classes to muck about with.
• Use private for any important implementation details that could adversely affect execution if overridden by an extending class.

Those paying attention will note that I skipped final. Actually, I saved that for last. Marking a class or method final tells PHP that the class or method may not be extended or re-declared/overridden. At all. I lump this with visibility, because it's another way of locking down access to an API; marking something final is saying, "you cannot extend this", similar to using private, but without even the possibility of redeclaring.

Applied

What got me to thinking about all this was a turn of events with Zend Framework 2. We've had an annotation parser since last summer. Ralph Schindler developed it in order to facilitate automatic discovery of injection points for our Dependency Injection container. Classes could mark a method with the @Inject annotation, and the various DI compilers would know that that method needed to be injected.

use Zend\Di\Definition\Annotation\Inject;

class Foo
{
    protected $bar;

    /**
     * @Inject()
     * @param  Bar $bar
     * @return void
     */
    public function setBar(Bar $bar)
    {
        $this->bar = $bar;
    }
}

class Bar {}

Recently, part of our Forms RFC included a feature to allow creating forms and their related input filters by using annotations. Basically, this allows developers to hint on their domain entities how specific properties should be filtered, validated, and potentially represented at the form level.

use Zend\Form\Annotation;

class Foo
{
    /**
     * @Annotation\Filter({"name":"StringTrim"})
     * @Annotation\Validator({"name":"Between","options":{"min":5,"max":20}})
     * @Annotation\Attributes({"type":"range"})
     */
    protected $bar;
}

One developer testing the support wanted to use a combination of Doctrine annotations and ZF2 form annotations — that way his entities could also describe validation and representation.

I did some work to make this happen, and everybody was happy. Except then that same developer went to use that entity with Doctrine, and Doctrine's annotation parser started raising exceptions on all the ZF2 annotations.

After some debate, I realized: (a) we were basically just making up syntax for our annotations; it'd be better to use an established syntax; but (b) we should still retain the ability to use arbitrary syntax, as we can't really know what sorts of annotations developers may already be using.

So, we decided to make our annotation component depend on the annotations support in Doctrine\Common, and to use the annotation syntax they utilize. ZF2 would provide some code to make it possible to plug in arbitrary parsers, and use the Doctrine\Common annotation parser to parse annotations officially supported by ZF2.

However, when I went to start making this happen, I ran into immediate issues.

Remember how this post is about visibility? Well, the class I was directly interested in, Doctrine\Common\Annotations\DocParser, not only contains private members, but is marked final.

My immediate response was to start dissecting the class, cutting and pasting the bits interesting to my solution into a new class in ZF2. I went down this route for several hours, gradually pulling in more and more methods as I discovered how far down the rabbit hole I needed to go to accomplish my task.

But at the back of my head, I kept thinking this was a bad idea. If any patches ever came in for the original class, I'd need to port them into our ZF2 solution. And I couldn't help but think that I'd miss a crucial piece.

So I started playing with its public API, to see if there were any shortcuts I might be able to take. And there were.

The class has a public parse() method. Based on how Doctrine uses the code, I assumed I needed to pass a full PHP docblock in — which ran counter to how I wanted to use the code. I wanted to pass in an annotation at a time. But when I looked closer, I realized that the parser didn't require a full docblock; any fragment would do.

To make a long story short: I was able to feed the parser a single annotation at a time from ZF2's AnnotationScanner. This allowed me to build a very simple class that allows registering a set of annotations it can handle, and feeding it a single annotation string at a time to decide (a) if it supports it, and (b) to parse it and return the associated annotation object.

In sum: because the class in question was marked final and had private members, I found myself forced to think critically about what I wanted to accomplish, and then thoroughly understand the public API to see how I might accomplish that task without the ability to extend.

Conclusions

Doctrine has a policy that encourages poka-yoke solutions: code should be executable in a specific way. The policy was developed to both aid users (having multiple ways of doing something is often confusing), as well as to ease maintenance (fewer extension points means less liklihood of developers doing hard-to-debug things in extending code and reporting it back to the project). These have led them to heavily use private and final visibility.

I've said it before, and I'll say it again: I feel that frameworks and libraries should use private and final sparingly. Over the years, I've seen code repurposed in simply wondrous ways — largely due to keeping the code as open as possible to extension. I like to enable my users as much as possible.

That said, I can also see Doctrine's argument — and can see where, while it can often be frustrating, it can also lead to potentially more sound and elegant solutions.

I'll probably continue shying away from private and final visibility, but I do plan to experiment with it more in the future. What about you?

On Visibility in OOP was originally published 28 June 2012 on https://mwop.net by Matthew Weier O'Phinney.

So, at times, you find yourself writing code like this:

if (false === ($fh = @fopen($filename, 'r'))) {
    throw new RuntimeException(sprintf(
        'Could not open file "%s" to read', $filename
    ));
}

Seems straight-forward enough, right? But it's wrong on so many levels.

• The error doesn't magically go away. If you've got PHP's log setup, you're going to be getting a log entry each time the suppressed statement errors.
• Error suppression is expensive. Like, really, really expensive. A special error handler is registered to prevent the error propagating to the display (if display_errors is enabled), but errors are still sent to the log (as noted above). When done, the original error handler has to be restored.
• If you use things like error_get_last(), you may find that if you have many error suppressions, it returns something unrelated to the error that just occurred.
• PHPUnit, anyone? Error suppression and PHPUnit do not play well together. And there's a reason for that: often suppressed errors are indicative of bigger issues.

So, how do you address it?

PHP has two functions to assist with this: set_error_handler() and restore_error_handler(). The first takes a callable argument, and optionally a mask of error levels to which it will respond; the second is used to return error handling to the previously set handler.

function handleError($errno, $errmsg = '', $errfile = '', $errline = 0)
{
    throw new RuntimeException(sprintf(
        'Error reading file (in %s@%d): %s',
        $errfile, $errline, $errmsg
    ), $errno);
}

set_error_handler('handleError', E_WARNING);
$fh = fopen($filename, 'r');
restore_error_handler();

Traditionally, these have been a pain to use, as you have to create individual functions or methods for handlers, and methods must have public visibility, even if the functionality is internal to the class.

With PHP 5.3, we get a new option, however: closures.

With closures, error handlers are still a pain to use, but you now get to scope the handlers directly in the context of the application flow. Let's look at an example:

set_error_handler(
    function($error, $message = '', $file = '', $line = 0) use ($filename) {
        throw new RuntimeException(sprintf(
            'Error reading file "%s" (in %s@%d): %s',
            $filename, $file, $line, $message
        ), $error);
    },
    E_WARNING
);
$fh = fopen($filename, 'r');
restore_error_handler();

If you just want to ignore the error, it's even simpler:

set_error_handler(function() { return true; }, E_NOTICE);
$contents = file_get_contents($filename);
restore_error_handler();

The code isn't necessarily succinct, which is one reason many gravitate towards using error suppression instead. However, it has the benefit of being context-sensitive and robust, which is always a good goal.

On Error Handling and Closures was originally published 16 December 2011 on https://mwop.net by Matthew Weier O'Phinney.

In talking with my wife about it a week or two ago, I realized that I needed an analogy she could understand; I was basically using her as my rubber duck. And it turned out to be a great idea, as it gave me some good analogies.

Dining Out

The analogies go like this: you walk into a burger join, and you're hungry.

• Dependency Injection is like ordering off the menu — but specifying things like, "I'd like to substitute portabella mushrooms for the patties, please." The waiter then goes and brings your dish, which has portabella mushrooms instead of the hamburger patties listed on the menu.
• Service Location is like ordering with substitutions, and having the waiter completely ignore the substitutions; you get what's on the menu, nothing more, nothing less.

Now, when it comes to Zend Framework's version 1 releases, we've really got neither. Our situation is more like a buffet or a kitchen — you grab a little of this, a little of that, and assemble your own burger. It's a lot more work.

Frankly, I'm lazy, and like my dinner brought to me… and if I want any substitutions, I'd like those, too.

Getting the Ingredients

A number of developers I've talked to seem to think DI is a bit too much "magic" — they're worried they'll lose control over their application: they won't know where dependencies are being set.

There are two things to keep in mind:

1. you, the developer, define the dependencies up front
2. if you don't pull the object from the container, you're in charge

Regarding the second point, it appears some developers think that with a DI container in place, dependencies magically get injected in every object. But that's simply not the case. If you use normal PHP:

$o = new SomeClass();

you'll get a new instance, just like always, configured only with any parameters you pass in to the constructor or methods you call on it. It's only when you retrieve the object from the DI container that you dependency injection takes place; if you do that, you can always examine the DI configuration (which can either be programmatic or via a configuration file) to determine what dependencies were configured.

Basically, it's like the difference between making your own hamburger patty out of fresh ground sirloin, and ordering Animal Style from In-N-Out.

I'm done now

What's your favorite way of thinking of these concepts?

Dependency Injection: An analogy was originally published 21 March 2011 on https://mwop.net by Matthew Weier O'Phinney.

But first, some background is probably in order, as this is a jargon-heavy post.

Aspect Oriented Programming

I was first introduced to AOP in 2006 via an April 2006 php|architect article by Dmitry Sheiko. That article detailed adding calls at various places in a method where you might want to hook into functionality — for instance, to log, cache, etc. Expanding on this, I considered other possibilities: manipulating incoming arguments, validation, ACL checks, implementing write-through caching strategies, and more. The approach is daunting, however; typical, naive implementations lead to a lot of boiler-plate code:

interface Listener
{
    public function notify($signal, $argv = null);
}

class Foo
{
    protected $listeners;

    public function attach($signal, Listener $listener)
    {
        $this->listeners[$signal][] = $listener;
    }

    public function doSomething($arg1, $arg2)
    {
        foreach ($this->listeners as $listener) {
            $listener->notify('preDoSomething', func_get_args());
        }
        
        // do some work
        
        foreach ($this->listeners as $listener) {
            $listener->notify('postDoSomething', $result);
        }
    }
}

The article didn't go into any real details on how you might short-circuit the filters or handle return values from them, and aspect handling itself was not detailed completely. As such, the code begins to add up, particularly if many classes and/or methods implement the functionality.

Intercepting Filters

A similar concept to AOP is the idea of Intercepting Filters. Like AOP, the idea is to separate cross-cutting concerns such as logging, debugging, and more from the actual logic the component exposes. The difference is that typically Intercepting Filters are language independent, have a standard implementation in a given framework, and can be re-used. The approach gwoo used in his post falls more under this category.

Lithium, a PHP 5.3 framework and the reference for gwoo's article, has a very intriguing approach. Instead of calling the filters explicitly within the body of the code, they suggest that the body of the code simply becomes one of the filters, via a closure:

Dispatcher::applyFilter('run', function ($self, $params, $chain) {
    // do something...
    return $chain->next($self, $params, $chain);
});

In Lithium, each filter is responsible for calling the next (each filter receives the chain as its third and final argument); as soon as one doesn't call next(), execution is stopped, and the result returned (or at least that's how I read the source). You can call the chain either before or after the code you want to execute in each filter; placement will determine whether it's a pre- or a post-filter. The approach answers a number of the concerns I outlined previously — namely, standardization of approach, and the ability to short-circuit execution.

The above example defines a filter that will run when the run() method of the Dispatcher class is executed. $self will typically be the object instance, $params an array of the parameters passed to the method, and $chain as described above. The method itself will execute any filters — typically with something like this:

use lithium/core/Object as BaseObject;

class Foo extends BaseObject
{
    public function doSomething($with, $these, $args)
    {
        $params = compact('with', 'these', 'args');
        
        return $this->_filter(__METHOD__, $params, function ($self, $params) {
            // do the actual work here
            return $result;
        });
    }
}

(The _filter() method is defined in lithium\core\Object, and basically passes a local, static chain of filters to Lithium's Filter class for execution. applyFilter() from the previous example statically adds a callback under the named method to the chain.)

This solution is elegant — but I see some limitations:

• First and foremost, I'm not particularly fond of the filtering functionality being via static methods on a single class; it introduces a hard-coded, hidden dependency. This means you cannot provide alternate filtering functionality without extending the class consuming the filters, nor without either extending the base filters implementation should you wish to provide a compatible API (for instance, to introduce an implementation that understands priorities).

  Additionally, the easiest way to implement filtering in Lithium is by extending the lithium\core\Object class — I could find no examples elsewhere in the documentation that showed how you would compose the Filters implementation in your own objects. As such, the easiest way to compose filters is now via inheritance, which seems to be counter-productive to the whole rationale behind filtering, to my thinking.

• Second, the approach of making the body of the calling method a closure makes it difficult to create non-public helper methods. Inside the filter, you're no longer in the scope of the object, losing the semantics that tie the various metadata and functionality of the object together. (The Lithium docs provide illustrations of how to accomplish this, but they require extra work, and a keen understanding of how references work in PHP.)

• Third, it's sometimes useful to have access to the return results of all the filters (not just the last executed); you may want to aggregate them in some way, or branch logic based on the various returns.

• Fourth, it's sometimes useful to have multiple call points within the main code. As an example, for many caching strategies, you'd check first to see if you have a cache hit, and return immediatly if found; otherwise, you'd execute the code, and cache the result prior to returning it. This might be possible in Lithium with constructs like this:

  Filters::add('SomeClass::doSomething', function ($method, $self, $params) {
      if (null !== ($content = cache_hit($params))) {
          return $content;
      }
      $content = Filters::next($method, $self, $params);
      return $content;
  });
  

  However, if you have several filters such as this, the order then becomes paramount, and that introduces new complexities.

  Another example would be with façade methods, where you may wish to introduce filters before and after each method call:

  public function doSomeWorkflow($message)
  {
      $this->somePrivateMethod($message);
      $this->nextPrivateMethod($message);
      $this->lastPrivateMethod($message);
  }
  

  (I can already hear Nate saying "make those all filters!" or "filter each method!" — but that's the problem with simple examples - they can't always express the nuances of a use case.)

• Fifth, it's useful to be able to attach callbacks that are not aware of the chain. For instance, you may have code you've already written that works perfectly fine in a standalone situation — e.g., a logger — and you simply want to add it to the chain. In the Lithium paradigm, you'd need to curry the calls in, instead of simply using the existing method:

  // This:
  SomeClass::applyFilter('doSomething', function ($self, $params, $chain) use ($log) {
      $log->info($params['message'];
      $chain->next($self, $params, $chain);
  });
  // VS:
  SomeClass::signals()->connect('doSomething', $log, 'info');
  

  Related to this, I personally dislike aggregating the filter parameters into a single associative array. I don't like having to test for the existence of parameters, and would much rather PHP tell me if I'm missing required parameters or if any fail typehints. That said, doing so provides a consistent API when filtering.

All in all, however, the approach Lithium provides is very good; it just doesn't completely suit my tastes or use cases.

Signal Slots

Interestingly, the capabilities I need are not far from what Lithium provides — in fact, I'd argue that the Intercepting Filters of Lithium are actually probably more akin to another pattern, Signal Slots.

With Signal Slots, your code emits signals (Lithium does this — it emits the name of the method being called); any handler, or slot (filters in Lithium), connected to the signal is then executed.

As such, you typically have some sort of signal "manager" object (the Filters class in Lithium) that aggregates signals and attached slots; this manager is then composed into the object emitting signals. For those of you familiar with events in JavaScript or other event-driven languages, this should sound quite familiar.

Such an approach looks like this:

class Foo
{
    protected $signals;

    public function signals(SignalSlot $signals = null)
    {
        if (null === $signals) {
            // No argument? make sure we have a signal manager
            if (null === $this->signals) {
                $this->signals = new Signals(); // SignalSlot implementation
            }
        } else {
            // Compose in an instance of a signal manager
            $this->signals = $signals;
        }
        return $this->signals;
    }

    public function doSomething($with, $these, $args)
    {
        $this->signals()->emit('doSomething.pre', $this, $with, $these, $args);
        
        // do some work
        $this->signals()->emit('doSomething.during', $this, $with, $these, $args);

        // do some more work
        // This time, pass the result
        $this->signals()->emit('doSomething.post', $this, $result, $with, $these, $args);
        return $result;
    }
}

$f = new Foo();
$f->signals()->connect('doSomething.pre', $log, 'info');
$f->signals()->connect('doSomething.during', $validator, 'isValid');
$f->signals()->connect('doSomething.post', $indexer, 'index');

Basically, a SignalSlot provides an object in which signals and their attached slots are aggregated. This allows having a single manager for multiple signals (which is similar to how Lithium's Filters class works), while also providing a way to emit multiple signals from a single procedure. Additionally, since it is simply an object, you can compose it in to classes that may emit signals — without requiring inheritance.

This is the basic approach of the ZF2 SignalSlot implementation, as well as that found in Symfony 2's Event Dispatcher and Zeta Components' SignalSlot component.

Both Symfony 2's Event Dispatcher and ZF2's SignalSlot component build in the ability to short-circuit, Symfony via a notifyUntil() method, and ZF2 via an emitUntil method. With ZF2, each time a signal is emitted, a ResponseCollection is returned by the manager, containing an aggregate of all slot responses. Calling emitUntil() will short-circuit execution of remaining slots if a given slot returns a response that validates against given criteria; at this point, the collection is marked as "stopped", and you can pull the "last" response and return it:

$responses = $this->signals()->emitUntil(function($response) {
    return ($response instanceof SpecificResultType);
}, 'doSomething.pre', $this, $with, $these, $args);
if ($responses->stopped()) {
    return $responses->last();
}

This introduces extra code in the method emitting the signals — but meets the criteria that no given slot need be aware of the chain.

The Signal Slot approach actually supports paradigms similar to those illustrated in Lithium. For instance, I can make my method body a slot:

class Foo
{
    protected $handlers = array();

    // ... skip signals composition ...
    
    public function doSomething($with, $these, $args)
    {
        $params = compact('with', 'these', 'args');
        
        // connect() returns a signal handler (slot); store it so that we only
        // ever attach it once...
        if (isset($this->handlers[__FUNCTION__])) {
            $this->handlers[__FUNCTION__] = $this->signals()->connect(__FUNCTION__, function($self, $params) {
                // do the work here!
            });
        }
        
        // Emit the signal, and return the last result
        return $this->signals()->emit(__FUNCTION__, $this, $params)->last();
    }
}

Concerns

Using Signal Slots and Intercepting Filters is not without its concerns, nor is any given implementation perfect.

• Zeta Components does a fantastic job of handling signal slots. However, you cannot short-circuit execution, nor introspect return values. It does offer two features neither ZF2 nor Symfony 2 offer (at this time): the ability to statically connect slots to signals, allowing you to wire without having an existing instance, nor even caring what object might emit the signal; and the ability to add a priority to slots, which allows you to alter the execution order.
• Lithium does a nice job of providing good standards (signals are method names; parameters are predictable for all handlers), but at the price of some flexibility (static implementation with no interface for alternate implementations; no ability to re-use existing methods and functions with differing signatures without currying).
• Symfony 2 offers short-ciruiting and flexibility in callbacks, but requires that you create an event object to pass to the Event Dispatcher, making the usage slightly more verbose, and offers no standardization of signal naming.
• ZF2's SignalSlots offer similar benefits (and drawbacks) to Symfony 2's implementation, provides standardization of the signal manager response, allows registering classes that self-register with the signal handler, but lacks static wiring capabilities or prioritization.

On a more abstract level, signal slots and intercepting filters can lead to difficulties in learning and mastering code that use them:

How are signals named?

How do you document the parameters available to slots/filters?

• How can those using IDEs discover available signals? and the arguments expected?

Where does the wiring occur?

• For instance, if any wiring is automated, this can potentially lead to more difficulty in debugging.
• If done manually, when, and where?

What happens if a slot doesn't receive arguments it needs, or cannot handle the arguments it receives?

In short, while they solve many problems, the implementations also introduce new concerns — though this will be true of any extension system, in my experience.

Conclusions

I personally am a huge fan of Intercepting Filters and Signal Slots. I think they can make code easier to extend, by providing a standard methodology for introducing cross-cutting concerns without requiring class extension. They can also make code quite expressive — sometimes at the cost of readability — by introducing functional programming paradigms.

If you have not investigated these concepts or components before, I highly recommend doing so; I think they play a fundamental role in the next generation of PHP frameworks.

Caveats

I am not an expert, nor well-versed, in all the frameworks listed here, and as such, some of the information may be incorrect or incomplete. I am the author of ZF2's current Signal Slot implementation, and am still working on improvements to it.

Updates

• 2011-01-10 11:35Z-05:00 Cal Evans found the original php|architect article I referenced, and I've revised some of the assessments based on re-reading it, as well as linked to the issue.

Aspects, Filters, and Signals, Oh, My! was originally published 10 January 2011 on https://mwop.net by Matthew Weier O'Phinney.

PHPUnit offers a variety of methods for setting up test suites, some trivial and some complex. The Zend Framework test suite, for instance, goes for a more complex route, adding component-level suites that require a fair amount of initial setup, but which allow us fairly fine-grained control.

However, testing and test automation should be easy and the complex approach is overkill for most of our applications. Fortunately, PHPUnit offers some other methods that make doing so relatively simple. The easiest method is to use an XML configuration file.

As an example, consider the following:

<phpunit>
    <testsuite name="My Test Suite">
        <directory>./</directory>
    </testsuite>

    <filter>
        <whitelist>
            <directory suffix=".php">../library/</directory>
            <directory suffix=".php">../application/</directory>
            <exclude>
                <directory suffix=".phtml">../application/</directory>
            </exclude>
        </whitelist>
    </filter>

    <logging>
        <log type="coverage-html" target="./log/report" charset="UTF-8"
            yui="true" highlight="true"
            lowUpperBound="50" highLowerBound="80"/>
        <log type="testdox-html" target="./log/testdox.html" />
    </logging>
</phpunit>

First thing to note, relative paths are relative to the configuration file. This allows you to run your tests from anywhere in your tests tree. Second, providing a directory directive to the testsuite directive scans for all files ending in Test.php in that directory, meaning you don't have to keep a list of your test cases manually. It's a great way to automate the suite. Third, the filter directive allows us to determine what classes to include and/or exclude from coverage reports. Finally, the logging directive lets us specify what kinds of logs to create and where.

Drop the above into tests/phpunit.xml in your application, and you can start writing test cases and running the suite immediately, using the following command:

$ phpunit --configuration phpunit.xml

I like to group my test cases by type. I have controllers, models, and often library code, and need to keep the tests organized both on the filesystem as well as for running the actual tests. There are two things I do to facilitate this.

First, I create directories. For instance, I have the following hierarchy in my test suite:

tests/
    phpunit.xml
    TestHelper.php
    controllers/
        IndexControllerTest.php (contains IndexControllerTest)
        ErrorControllerTest.php (contains ErrorControllerTest)
        ...
    models/
        PasteTest.php           (contains PasteTest)
        DbTable/
            PasteTest.php       (contains DbTable_PasteTest)
        ...
    My/
        Form/
            Element/
                SimpleTextareaTest.php

controllers/ contains my controllers, models/ contains my models. If I were developing a modular application, I'd have something like blog/controllers/ instead. Library code is given the same hierarchy as is found in my library/ directory.

Second, I use docblock annotations to group my tests. I add the following to my class-level docblock in my controller test cases:

/**
 * @group Controllers
 */

Models get the annotation @group Models, etc. This allows me to run individual sets of tests on demand:

$ phpunit --configuration phpunit.xml --group=Controllers

You can specify multiple @group annotations, which means you can separate tests into modules, issue report identifiers, etc; additionally, you can add the annotations to individual test methods themselves to have really fine-grained test running capabilities.

Astute readers will have noticed the TestHelper.php file in that directory listing earlier, and will be wondering what that's all about.

A test suite needs some environmental information, just like your application does. It may need a default database adapter, altered include_paths, autoloading set up, and more. Here's what my TestHelper.php looks like:

<?php
/*
 * Start output buffering
 */
ob_start();

/*
 * Set error reporting to the level to which code must comply.
 */
error_reporting( E_ALL | E_STRICT );

/*
 * Set default timezone
 */
date_default_timezone_set('GMT');

/*
 * Testing environment
 */
define('APPLICATION_ENV', 'testing');

/*
 * Determine the root, library, tests, and models directories
 */
$root        = realpath(dirname(__FILE__) . '/../');
$library     = $root . '/library';
$tests       = $root . '/tests';
$models      = $root . '/application/models';
$controllers = $root . '/application/controllers';

/*
 * Prepend the library/, tests/, and models/ directories to the
 * include_path. This allows the tests to run out of the box.
 */
$path = array(
    $models,
    $library,
    $tests,
    get_include_path()
);
set_include_path(implode(PATH_SEPARATOR, $path));

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

/**
 * Store application root in registry
 */
Zend_Registry::set('testRoot', $root);
Zend_Registry::set('testBootstrap', $root . '/application/bootstrap.php');

/*
 * Unset global variables that are no longer needed.
 */
unset($root, $library, $models, $controllers, $tests, $path);

The above ensures that my APPLICATION_ENV constant is set appropriately, that error reporting is appropriate for tests (i.e., I want to see all errors), and that autoloading is enabled. Additionally, I place a couple items in my registry — the bootstrap and test root directory.

In each test case file, I then do a require_once on this file. In future versions of PHPUnit, you'll be able to specify a bootstrap file in your configuration XML that gets pulled in for each test case, and you'll be able to even further automate your testing environment setup.

Hopefully this will get you started with your application testing; what are you waiting for?

Setting up your Zend_Test test suites was originally published 11 September 2008 on https://mwop.net by Matthew Weier O'Phinney.