PHP: Adding Behavior to a URL Class

While it’s fair to say that it's not one of the most popular design patterns, like Factory, Singleton and Decorator, Value Object is a simple, yet powerful pattern. It can be used for fabricate value objects, or expressed in other words, objects whose equality is based on the values assigned to their fields, and not on an identity.

Classic examples of value objects that are often modeled in modern applications are dates, email addresses, phone numbers and so forth. Naturally, it’s possible to have multiple types of value objects, other than the ones I just mentioned, depending on how they behave within the context of a given domain. Also,  despite their rather intimidating name, value objects are dead simple to model, as in most cases they’re simple data containers whose properties are populated according to predefined constraints. Consider the case of an email address, for example; its parts must be compliant with the specifications of RFC 5321 and RFC 5322.

In the case of PHP, however, creating value objects can be a challenging task, especially when it’s necessary to make them immutable. Unlike other more mature languages like Java or C#, PHP doesn’t support natively immutable value objects. However, the process is fairly straightforward, and most importantly, it can be mastered in a snap.

To demonstrate how easy it is to achieve this, in the introductory installment of this series I started building a trivial class, which was responsible for modeling immutable URL objects. Although in its current state the class effectively prohibits the assignment of new values to its fields once they’ve been populated through the constructor, its behavior is limited to housing those values and exposing them to client code via a bunch of getters. Sad but true.

Considering this situation, it’d be useful to provide this sample class with some kind of simple behavior, so you can see how it reacts against any attempt to modify its properties. In consonance with this idea, in this second part of the series I’m going to add to the URL class a method that will append a few additional parameters to its existing query string.

The question that comes up here is: will this method break the class’s immutability? Well, the answer is resounding no! But, if you wish to learn how this will be accomplished, keep reading.

Creating immutable value objects in PHP: a quick look at an earlier example

Since my goal is to show how to preserve the immutability of the URL class developed in the previous tutorial after expanding its core functionality, it’d be useful to take a quick look at the class, so that you can recall how it was defined initially. 

With that said, here’s the source code of this sample class. As I said, it is responsible for modeling simple and immutable URL objects:

(Url.php)

<?php

final class Url
{
    private $_scheme; 
    private $_host;
    private $_path;
    private $_queryString;
   
    // constructor
    public function __construct($url)
    {
        if (!filter_var($url, FILTER_VALIDATE_URL, array(FILTER_FLAG_SCHEME_REQUIRED, FILTER_FLAG_HOST_REQUIRED))) {
            throw new UrlException('The specified URL is invalid.');
        }
       
        $url = parse_url($url);
        $this->_scheme = $url['scheme'];
        $this->_host = $url['host'];
       
        if (isset($url['path'])) {
            $this->_path = $url['path'];
        }
       
        if (isset($url['query'])) {
            $this->_queryString = $url['query'];
        }
    }
   
    // get the scheme part of the URL
    public function getScheme()
    {
        return $this->_scheme;
    }
   
    // get the host part of the URL
    public function getHost()
    {
        return $this->_host;
    }
   
    // get the path part of the URL
    public function getPath()
    {
        return $this->_path;
    }
   
    // get the query string of the URL
    public function getQueryString()
    {
        return $this->_queryString;
    }
}     

(UrlException.php)

<?php

class UrlException extends Exception{}

As you can see from the above code fragment, the “Url” class bases its immutability on the deliberate absence of setter methods. Of course, there are a few other approaches you can use for achieving a similar result, but I used this one because I found it easier to implement and read.

Other than that, there’s not much more that can be said about this class, since at this moment it only takes a URL string through its constructor and then dissects each part, which is in turn assigned to a different field. Although this example does show that creating immutable value objects in PHP is a pretty straightforward process, it doesn’t demonstrate the full potential of the Value Object pattern. Consider, for instance, the situation discussed earlier, which introduces the possibility of adding some kind of behavior to the class, such as appending extra arguments to the existing query string.

Well, in a case like this, the task should be performed by a discrete method, which for obvious reasons should keep the immutability of the class untouched. At a glance, it seems like this is a complex thing to achieve, right? Fear not, as coding such a method is much simpler that you might think, trust me.

To demonstrate this, in the following segment I’m going to extend the functionality of the previous “Url” class by adding to it the method just mentioned. As usual, to learn the full details of this process, leap forward and read the lines to come.