• What Exceptions can I expect?
• What Exceptions do I plan to catch?

In this post I’ll show some important aspects to consider when planning exceptions.

The Basic Exception

Let’s assume a Soap-based web-service client class used to submit order-data to a supplier’s web-service. The web-service client throws an exception if required configuration parameters are missing. The actual SoapClient object will be initialized when the first webservice method is called.

Web-service client class:

class WsSoapClient
{
    private $config;
    private $soapClient = null;
 
    public function __construct($config) {
        $this->config = $config;
    }
 
    public function submitOrder(Order $order) {
        $this->initSoapClient();
        $this->soapClient->submitOrder($order->toSoapParam());
    }
 
    private function initSoapClient() {
        if (!is_null($this->soapClient)) {
            return;
        }
        if (!$this->config->wsdl) {
            throw new Exception('Configuration error');
        }
        $this->soapClient = new SoapClient($this->config->wsdl);
    }
}

Application code:

$config = Registry::get('config');
$client = new WsSoapClient($config);
try {
    $client->submitOrder($order);
} catch (Exception $e) {
    // We need to act on this asap...
    $AppError->register_error($e);
    // Redirect to application error page
    $Redirect->error($e);
}

In case of a configuration error a redirect is performed to an application-error page. And (just an example) some mechanism is triggered that starts to bug a (or all) developers that there’s a problem that needs immediate attention.

Knowing what to catch

There are of course errors that are less disastrous. Web-services can be down so we need to cope with that, resulting in the modifications below:

class WsSoapClientException extends Exception {}
class WsSoapClientConfigurationException extends WsSoapClientException{}
class WsSoapClientConnectionException extends WsSoapClientException{}
 
class WsSoapClient
{
    // ...
    private function initSoapClient() {
        if (!is_null($this->soapClient)) {
            return;
        }
        if (!$this->config->wsdl) {
            throw new WsSoapClientConfigurationException(
                'Configuration error'
            );
        }
        try {
            $this->soapClient = new SoapClient(
                $this->config->wsdl, 
                array('exceptions'=>1)
            );
        } catch (SoapFault $e) {
            throw new WsSoapClientConnectionException(
                'Cannot load WSDL: '.$this->config->wsdl
            );
        }
    }
}

$client = new WsSoapClient($config);
try {
    $client->submitOrder($order);
} catch (WsSoapClientConnectionException $e) {
    // store the order in a queue to be processed later
    $Order->queue();
    $Redirect->Page('OrderQueued', $order);
} catch (Exception $e) {
    // Catch everything, also WsSoapClientConfigurationException
 
    // We need to act on this asap...
    $AppError->register_error($e);
    // Redirect to application error page
    $Redirect->error($e);
}

Two things have changed:

Extending exception types

Exception classes have been defined for specific errors. They both extend an Exception class that is specific for the WsSoapClient class. This allows us to catch specific exceptions, like is done with WsSoapClientConnectionException. We could also catch all exceptions directly thrown by WsSoapClient by catching WsSoapClientException. When defining exception types one might take SPL Exceptions as a starting point.

Rethrowing exceptions

A SoapFault exception is caught and a WsSoapClientConnectionException is thrown instead. Now one might wonder: Why? Couldn’t I just as well catch SoapFault in the application code? That brings us to the next section.

Knowing what to expect

In the previous example we simply used one WsSoapClient class to handle all web-service related communications. Now imagine that we have different suppliers that (inevitably) offer different types of web-services for us to use. Besides a client that handles Soap we now also need a client that handles XML-RPC.

After reading up a bit on Design Patterns we decide to introduce a Factory that returns the proper web-service client for the order, which we supply in the method call.

class WsClientFactory
{
    static public function getWsClient(Order $order)
    {
        switch ($order->supplier) {
            case 'supplierA':
                return new WsSoapClient(
                    Registry::get('config')->soap->supplierA
                );
            case 'supplierB':
                return new WsXmlRpcClient(
                    Registry::get('config')->xmlrpc->supplierB
                );
        }
    }
}

Briefly put: The point of a factory is to avoid the ‘new’ keyword by allowing it to return various class instances. To know what callable methods to expect on the returned object, the possible object types need to implement a common interface or extend a common (abstract) class. We define an interface WsClient and let the two client types implement it:

interface WsClient
{
    public function submitOrder(Order $order);
}
class WsSoapClient implements WsClient
{
    public function submitOrder(Order $order)
    {
        // submitting order to soap webservice
    }
}
class WsXmlRpcClient implements WsClient
{
    public function submitOrder(Order $order)
    {
        // submitting order to xml-rpc webservice
    }
}

Now if we take a look at our original application code it becomes obvious that we are not finished yet.

$client = WsClientFactory($order);
try {
    $client->submitOrder($order);
} catch (WsSoapClientConnectionException $e) {
    // Now what if there's a XML-RPC client throwing other exceptions?
}

We could catch WsXmlRpcClientConnectException as well but that’s not the way to go for two obvious reasons:

1. We would be duplicating the code in the catch blocks
2. If later we need to add a WsEmailClient class, we would need to update both the factory and all the try-catch blocks in the application.

Abstracting exceptions

As the client types implement a common interface we can also define a set of exceptions that are thrown by all classes implementing that interface:

class WsClientException extends Exception {}
class WsClientConfigurationException extends WsClientException{}
class WsClientConnectionException extends WsClientException{}
 
interface WsClient
{
    public function submitOrder(Order $order);
}

The classes implementing WsClient:

class WsSoapClient implements WsClient
{
    public function submitOrder(Order $order) {
        $this->initSoapClient();
        // ...
    }
 
    private function initSoapClient() {
        // Might throw: WsClientConfigurationException
        // Might throw: WsClientConnectionException
    }
}
class WsXmlRpcClient implements WsClient
{
    public function submitOrder(Order $order)
    {
        $this->initXmlRpcClient();
        // ...
    }
 
    private function initXmlRpcClient() {
        // Might throw: WsClientConfigurationException
        // Might throw: WsClientConnectionException
    }
}

The application code retrieving an object from the factory now knows what exception types to expect:

$client = WsClientFactory($order);
try {
    $client->submitOrder($order);
} catch (WsClientConnectionException $e) {
    // Now we know what to expect
} catch (Exception $e) {
}

Wrapping it up

What the above shows is that:

• Throwing a default ‘Exception’ is bad practice if you ever want to act on that specific error scenario. Without extending the Exception class you can only catch all or none.
• New exceptions can be thrown in catch blocks. That way it’s possible to prevent unexpected exception types to cross certain application design boundaries.
• Once class design involves abstract classes or interfaces it is wise to design exception structures as well and organize them in similar layers of abstraction.

Using above ‘rules of thumb’ will hopefully help in using exceptions to maximum effect. The above mainly covers the structure of exceptions and not so much functionally that can be added to an exception subclass. Ideas to consider:

• Adding listeners to an Exception that might write exceptions to a log. Beware though: There’s probably no need to log ‘expected exceptions’ and every disk-write is a small hit on performance.
• Adding the caught exception to the new exception that is being re-thrown.

Do you think I’ve left out important parts or are you using (entirely) different exception strategies? Feel free to comment.

One of the challenges we were facing was that on one hand we wanted to implement business rules in our Domain objects. In plainish english: On setting or changing properties of the object (like changing a status) we want to validate if that action is allowed. On the other hand we want to be able to initialize an object to whatever state corresponds with the data fetched from the persistency layer. Doing so we found that the business rules got in the way during initialization when fetching it from the persistency layer. So what we were looking for was a way to allow the service layer to construct a Domain object using methods that are hidden from the rest of the code. We found two ways:

1. Reflection (as of PHP 5.3)
2. A design pattern where the Domain object initializes itself using the provided Service object.

Das Model: DAO, Domain, Service and Persistency layer

First lets look at how such a Domain object might look like. See simplified example below of an ‘order’:

class Domain_Order
{
    protected $id;
    protected $orderDate;
    protected $articles;
    protected $customer;
    protected $invoices;
    protected $statusHistory;
 
    public function getArticles() {}
 
    public function setStatus(OrderStatus $status) {}
 
    // other getters and setters
}

The order has properties like it’s id, a list of articles, the customer that placed the order and the invoice(s) sent. Besides that it has a status history that actually is a stack of subsequent statuses that correspond to the business processes involved. Possible statuses could be:

• initiated
• confirmed
• payment_confirmed
• articles_deliverable
• shipped
• onhold_system_error
• resolved_system_error
• onhold_helpdesk
• resolved_helpdesk
• cancelled_helpdesk
• completed

Domain objects are fetched, stored and updated by using methods on Service objects. Those service objects implement the aforementioned ‘persistency layer’ (could be PDO, webservices, memory, files, etc.). Services are retrieved from a DAO instance that is fetched from a DAO registry. I’ll cover that more thoroughly in a later post so I’ll keep it brief:

Bootstrap:

// bootstrap. setup DAO registry  with 
// DAO instance that provides service objects
DAO_Factory->setInstance(
	new DAO_PDO($initialisedPdo)
);

Fetching an order by id:

// returns concrete DAO, in this case using PDO for persistency
$order = DAO_Registry->getInstance() 
	// the DAO instance returns an 'order' service instance
	->getServiceOrder()
	// the service instance provides methods for CRUD type operations
	->getById($reqOrderId);

Implementing logic

Now let’s illustrate the concept of putting business rules in the Domain object: If a customer contacts the helpdesk with a difficult question, the helpdesk can put the order on hold to prevent shipping. The status ‘onhold_helpdesk’ is added to the status history. But (in our imaginary shop) this can’t be done if the order is already shipped. So the setStatus() method will validate if the status given is actually allowed and only then perform the action.

The setStatus() method in the order class now looks like this:

class Domain_Order
{
    // ... properties and other methods
    public function setStatus(OrderStatus $status)
    {
		// determine if new status is allowed business-wise
		if ($newStatusAllowed) {
			array_push($this->statusHistory, $status);
		} else {
			throw new Domain_Order_InvalidStatus_Exception();
		}
    }
    // ... other methods
}

Calling the setStatus() method should handle the possible exception:

try {
	$order->setStatus(
		new OrderStatus('onhold_helpdesk');
	);
} catch (Domain_Order_InvalidStatus_Exception $e) {
	//  properly handle exception
}

No public access allowed

To continue the example: If an order is already shipped it can’t be put on hold. But (at least in this imaginary shop) the other way round goes too: If an order is ‘on hold’ the status ’shipped’ can’t be added. The issue has to be resolved first. From a given state this behaviour is good: invalid actions are prevented. The problem is that the public setters like setStatus() are not suitable for bringing a newly created domain object into it’s ‘persisted’ state. A possible solution might be to add methods that bypass the business logic, but as these methods are used by the service object they need to be public. This is not desired as it allows developers to cut corners that shouldn’t be cut.

So, back to the start of this post: How to set properties bypassing business-logic?

1 . ReflectionProperty (PHP 5.3)

As of PHP 5.3 the ReflectionProperty class of the reflection API has a method setAccessible() that allows access to protected and protected properties. Accessing the protected id property of the Order class would look like this:

class Service
{
    // ...
 
    public function getById($id)
    {
        // based on the id from the persistency layer 
        // data is retreived. In this demo the data is a hash. 
        // Now it needs to be put into the newly created 
        // Order that is returned.
        $order = new Order();
 
        $refId = new  ReflectionProperty('Order');
        $refId->setAccessible(true);
        $refId->setValue($order, $persistedData['id']);
 
        // ... set other properties
 
        return $order;
    }
 
    // ...
}

The major drawback of using this technique is that the Service class needs to be aware of the internals of the Order class. So, updating the Order class involves needing to update the Service class as well. This breaks basic concepts of OOP. (For a more useful example of reflectionProperty see this object freezer example by Sebastian Bergmann.

2. Protected Link Pattern?

Another way to bypass business-logic on creation without exposing that possibility is to create what could be called a ‘protected link’ between the Service and the Order object. See code below:

Service:

class Service_Order
{
    // ...
 
    public function getById($id)
    {
        return Order::_init($this,$id);
    }
 
    public function _getInitData(Domain_Order $order, $id)
    {
        // will return 'raw' data (hash/object) as
        // retrieved from the persistency layer
        return $data;
    }
 
    // ...
}

Domain:

class Domain_Order
{
    // ... 
    private __construct()
    {
        // no, no, go to the Service
    }
 
    public static function _init(Service_Order $service, $id)
    {
        // create brand new instance
        $order = new Domain_Order();
 
        // fetch persisted data
        $initData = $service->_getInitData($order,$id);
 
        // bring order in it's initial state
        $order->id = $initData['id'];
        $order->orderDate = $initData['orderDate'];
 
        // etc...
 
        return $order;
    }
 
 
    // ... 
}

A static _init() method, that has access to the Order’s protected properties, is provided with a Service instance and the id of the Order to be initialized. The static Order method then in turn fetches the data from the Service. The new Order instance is then put into the persisted state by directly setting attributes otherwise not accessible. The initialized instance is then returned to the Service which in turn returns it to the requesting code.

On a first glance this might look more complicated than needed: Instead of using a _getInitData() from the Order class we could also have provided the _init() method with a data object that implements a certain interface. But this leaves open the option to initialize an Order object with manipulated data that is not directly derived from the persistency layer.

What this does achieve is that it is now impossible to manipulate a Domain object bypassing methods that apply business logic. Yet at the same time that business logic doesn’t get in the way when initializing a Domain object from the Service layer. A benefit compared to the reflection solution is that the Service object doesn’t need to be aware of the Order’s internals. The existence of the Domain layer’s _init() and the Service layer’s _getInitData() methods are enforced by their respective interfaces or the abstract classes they extend. The design of the transported data (in these examples a hash) can of course also be limited to a certain object type.

A drawback is that there is now a public method _getInitData on the Service layer. In this example the impact thereof is reduced by requiring an instance of Domain_Order but that’s just sugar (or vinegar so you like): It’s just an indication for developers that they are on the wrong track when they are directly calling _getInitData().

As said, in later posts I plan to elaborate more on the Service and Persistency layers that are briefly shown here. If anyone knows of other ways to address the issue of ‘controlled initialization’ I’m of course very interested.

Screen resolution

Take the february 2009 stats of thecounter.com. Based on those stats a target resolution of 1024 seems reasonable: At least 78% of the people view websites at that resolution or higher.

Of course the need for the increased width depends on the specific elements that have to be displayed. When left- and right columns are narrow, a width of 1024 might lead to very long lines which are hard to read.

Accessibility guideline: text size

Accessibility guidelines (W3C WCAG 1.0 point 3.4) state that relative units are to be used when specifying text size. That way, users can easily adjust the size of text. For some time, browsers (except *sigh* IE6) allowed users to adjust the displayed text size by using key combinations or ctrl+scrollwheel. This posed a challenge to CSS coding as it wasn’t always easy to keep everything in place when text size was increased. Or, probably worse, text would flow out of the box and become unreadable. See below image of a page on eurogamer.net. In the left-column navigation and bottom parts of the page elements will overlap when text size is increased.

Eurogamer text size example

Nowadays quite some web browsers have replaced text scaling with page zooming. This definitely makes life easier for CSS coders. It will also help user experience when increasing text size because relative placement of elements is preserved, as opposed to situations where some columns are stretched in different amounts. But there is a side-effect.

The misinterpretation of statistics and its disastrous consequences

When a website already fills the entire viewport in it’s original size, as soon as display size is increased, horizontal scroll bars will appear and the rightmost content will move out of view. So now let’s turn the aforementioned stats around. At least 51% of the visitors have a screen resolution of 1024 or less. So basically this means that when a page is designed to have a minimum width of, say, 1000px, half of the visitors will have problems increasing the displayed size.

Although official accessibility standards don’t seem to mention horizontal scrolling, it’s safe to say that having to scroll horizontally doesn’t help accessibility. And from a usability perspective it’s most certainly bad practice.

Regarding accessibility standards not mentioning horizontal scrolling: I searched the standards document of the dutch government which includes all WCAG guidelines (and more). I searched for the words screen (dutch: scherm), horizontal (dutch: horiz) and scroll. Nothing. A downside of these kind of checklists: technology moves on continuously while standards only get update once every x years. But that’s a different subject…

Browser overview: Text scaling or Full page zooming?

Acknowledging this side-effect it’s good to know exactly how today’s browsers perform zooming. See the table below.

Browser zoom characteristics

Conclusion

Although stats suggest 1024 is a solid choice, it’s obvious that there are considerations to be taken into account. If liquid design with a minimum of 800px is not an option and one chooses to design for a (minimum) resolution of 1024px the least one can do is try to avoid putting essential navigation or use cues in the rightmost part of the site.

See image below of Play.com: The top part with the currency selectors and link to the visitor’s account-page do sticks to the right size of the screen.

In this case I think it’s a coincidence as the cart button does extend beyond the visible area. The selectors are positioned absolutely from the right size of a container that doesn’t have it’s css attribute position set to ‘relative’. So positioning is done with respect to the BODY element. Although that has a min-width of 990px it somehow works out this way.

Play.com header example

One last tip: IE7 keeps a centered column centered when zooming in, as opposed to Firefox and Opera. So when in IE7 horizontal scroll bars appear, bits are falling of the left side of the screen as well.

• It still works. The css, the javascript that keeps everything in place, the event-handling. It proves that standard-compliance can get you far.
• It uses a technique similar to what now is called Ajax. Content is loaded by javascript using hidden iFrames and then moved to the visible areas. I liked the days when there was less talking about Ajax…

Judge for yourself.

Maybe before the end of the decade I’ll look into that ‘twitter’ I keep reading about…