When an object has different representations… what's the OO pattern?

Question

I've an AbstractMessage object (a hierarchy, actually). It represents a small text message and can be sent using different transport methods: HTTP, REST and a "mailer" transport. Each transport relies on an external library for executing the transport itself, injected using a DI container.

Message itself may have different representations (query string, resource string or an instance of\Swift_Message), based on the transport used. A transport should use the more appropriate representation, again injected using constructor injection.

interface TransportInterface
{
    public function executeTransport(AbstractMessage $message, array &$fails = array());
}

class HttpTransport implements TransportInterface
{
    /**
     * @var \Guzzle\Service\Client
     */
    private $client;

    /**
     * @var Converter\MessageConverterInterface
     */
    private $converter;

    public function __construct(Client $client, MessageConverterInterface $converter)
    {
        $this->client    = $client;
        $this->converter = $converter;
    }

    public function executeTransport(AbstractMessage $message, array &$fails = array())
    {
        $representation = $this->converter->convert($message);

        /* ... */
    }
}

class RestTransport implements TransportInterface
{
    /**
     * @var \Guzzle\Service\Client
     */
    private $client;

    /**
     * @var Converter\MessageConverterInterface
     */
    private $converter;

    public function __construct(Client $client, MessageConverterInterface $converter)
    {
        $this->client    = $client;
        $this->converter = $converter;
    }

    public function executeTransport(AbstractMessage $message, array &$fails = array())
    {
        $representation = $this->converter->convert($message);

        /* ... */
    }
}

class MailerTransport implements TransportInterface
{
    /**
     * @var \Swift_Mailer
     */
    private $mailer;

    /**
     * @var Converter\MessageConverterInterface
     */
    private $converter;

    public function __construct(Swift_Mailer $mailer,
        MessageConverterInterface $converter)
    {
        $this->mailer    = $mailer;
        $this->converter = $converter;
    }

    public function executeTransport(AbstractMessage $message, array &$fails = array())
    {
        $representation = $this->converter->convert($message);

        /* ... */
    }
}

The MessageConverterInterface and the actual helper may be fairly simple:

interface MessageConverterInterface
{
    /**
     * @param AbstractMessage $message
     * @return mixed
     */
    public function convert(AbstractMessage $message);
}

class MessageHelper
{
    /**
     * @var Transport\TransportInterface
     */
    private $mailer;

    public function send(AbstractMessage $message, array &$fails = array())
    {
        $this->transport->executeTransport($message, $fails);
    }

}

Question: is this a good OO pattern for the library design? Does the pattern have a name?

Answer 1

I would use an abstract class instead of, or in addition to, an interface. You have quite a bit of repetition that could be removed by doing so. The only problem then would be that you would have to use protected instead of private properties and methods, at least for those that you need to share between the abstract class and inheriting class, but I don't think that should make too much of a difference. Remember: You can't create an instance of an abstract class, so you have to use some other "initiator" and call that in each constructor.

abstract class AbstractTransport {

    protected
        /** @var \Guzzle\Service\Client */
        $client,

        /** @var \Swift_Mailer */
        $mailer,

        /** @var Converter\MessageConverterInterface */
        $converter
    ;

    protected function initClient( Client $client, MessageConverterInterface $converter ) {
        $this->client = $client;
        $this->converter = $converter;
    }

    protected function initMailer( Swift_Mailer $mailer, MessageConverterInterface $converter ) {
        $this->mailer = $mailer;
        $this->converter = $converter;
    }

    public function executeTransport( AbstractMessage $message, array &$fails = array() ) {
        $representation = $this->converter->convert( $message );
    }
}

You might also want to be careful with referencing. It can sometimes be hard to determine where a variable was changed if you don't know that it was assigned by reference somewhere. This is entirely your choice, just a suggestion. I would, however, like to point out that if this parameter is referenced, then setting a default value to it is kind of pointless. If the parameter has not been set, then that value can't be used and should therefore not be used at all to avoid the overhead.

I've never heard of, nor could find a library design pattern, so I can't be sure. As for the name of the pattern you are using? I honestly don't know. But it doesn't matter. Functional code is much better than any code that adheres to a design pattern just for the sake of doing so. Many times I see programmers attempting to force their code into a design pattern, and some times its not even the right pattern. Design patterns are not necessary at this stage. Code for functionality. Once you are comfortable with OOP, then you can start worrying about design patterns and how and when to apply them.

Now, as to whether this is good OOP or not; It appears to be fine, however, this code is incomplete, so it is hard to tell. The concepts seem fine, but the implementation is unsure. You are using encapsulation, inheritance, and a sort of polymorphism. Those are some of the main points of OOP, and you seem to grasp them fairly well, though you could probably stand to look into polymorphism a bit more. You are also using interfaces and dependency injection. These are also important concepts. A couple more points that might help is to ensure you are following the Single Responsibility Principle (can't be sure) and the "Don't Repeat Yourself" (DRY) principle. As I pointed out above, you could use some help with DRY.

Finally, your code samples could have easily been reduced to a single interface and class with a note that the other related classes only differed in the commented area. The other classes, except that last, are redundant, whereas that last is unnecessary in this context. If you would have submitted complete classes, this would not be the case. The second interface was slightly relevant, but was also unnecessary.

I hope this helps!

EDIT

Example implementation of above code:

class RestTransport extends AbstractTransport {
    public function __construct( $client, $converter ) {
        $this->initClient( $client, $converter );
    }
}

Per comment, here's how to do it with separate classes for each type:

//only worth it if both client and mailer implementations share more than this
abstract class AbstractTransport implements TransportInterface {
    public function executeTransport( AbstractMessage $message, array &$fails = array() ) {
        $representation = $this->converter->convert( $message );
    }
}

class Client extends AbstractTransport {
    public function __construct( Client $client, MessageConverterInterface $converter ) {
        $this->client = $client;
        $this->converter = $converter;
    }

    public function executeTransport( AbstractMessage $message, array &$fails = array() ) {
        parent::executeTransport( $message, $fails );

        /*
        assuming there will be shared aspects unique to clients
        you can use polymorphism to further extend method
        same in the mailer
        otherwise it is unnecessary to redefine here
        */
    }
}

class RestTransport extends Client {
    public function executeTransport( AbstractMessage $message, array &$fails = array() ) {
        parent::executeTransport( $message, $fails );

        /* ... */
    }
}

And you'd do pretty much the same thing with the mailer, and any of its classes. The problem with this implementation is that the parent classes, in this case "Client", can be instantiated, and by itself it doesn't do anything. This is why I was originally suggesting the abstract class.

Answer 2

@Gremo the use case you've outlined looks like it would be a good candidate to apply the Decorator pattern. Interfaces and Abstract classes are great, but that locks you into an inheritance chain that you might not want in the future. What if you need to modify the message in some way, e.g adding data in a REST call.

A Decorator (or a series of decorators) could handle the responsibilities of your different transport messages, while still supporting dependency injections. The lose coupling this offers, frees you up to design other types of decorators that could handle your messages in other ways that may be completely unrelated to your transport mechanisms (such as persisting the message in a datastore.)

In any case, I've whipped up a rough example of how you might accomplish that.

/**
 * IDecorator
 * 
 * Interface
 * 
 */
interface IDecorator
{
    # +------------------------------------------------------------------------+
    # ACCESSORS
    # +------------------------------------------------------------------------+

    public function __get($index);

    public function __set($index, $value);

    public function __call($method, $args);

}


/**
 * MessageDecorator
 * 
 */
class MessageDecorator implements IDecorator
{
    # +------------------------------------------------------------------------+
    # MEMBERS
    # +------------------------------------------------------------------------+
    protected $message;

    # +------------------------------------------------------------------------+
    # ACCESSORS
    # +------------------------------------------------------------------------+
    /**
     * Fluent interface for getters
     * 
     * @param   mixed   $index  The property
     * @return  mixed           The return value
     */
    public function __get($index)
    {
        return $this->message->$index;
    }

    /**
     * Fluent interface for setters
     * 
     * @param   mixed   $index  The property
     * @param   mixed   $value  The property's value
     */
    public function __set($index, $value)
    {
        $this->message->$index = $value;
    }    

    /**
     * Supports a fluent interface into the decorated class
     * 
     * @param   method    $method       A class method
     * @param   mixed     $args         One or many arguments
     * @return  mixed                   The results of the method call if the method exists
     *                                  or a reference to the current decorator (proxy)
     */
    public function __call($method, $args)
    {
        try
        {
            $obj = call_user_func_array( array( $this->message, $method ), $args );

            return ( $obj === $this->message ) ? $this : $obj;
        }
        catch( Exception $e )
        {
            throw new Exception(__METHOD__ . ' threw an exception: ' . $e->getMessage());
        }
    }

    /**
     * Get/set the original content for reference if needed.
     * 
     * @return  AbstractMessage Returns a AbstractMessage instance 
     */
    public function message( AbstractMessage $message = null )
    {
        if( $message != null )
        {
            $this->message = $message;
        }
        else
        {
            return $this->message;
        }
    }

    # +------------------------------------------------------------------------+
    # CONSTRUCTOR
    # +------------------------------------------------------------------------+
    public function __construct( AbstractMessage $message, array &$fails = array() )
    {
    }

}

/**
 * HTTPMessageTransport
 * 
 */
class HTTPMessageTransport extends MessageDecorator
{

    public function __construct( AbstractMessage $message, array &$fails = array() )
    {
        parent:__construct( $messsage, $fails );
    }

    public function send(Client $client, MessageConverterInterface $converter)
    {
        /* Message deployment logic... */
    }
}

/**
 * RESTMessageTransport
 * 
 */
class RESTMessageTransport extends MessageDecorator
{

    public function __construct( AbstractMessage $message, array &$fails = array() )
    {
        parent:__construct( $messsage, $fails );
    }

    public function send(Client $client, MessageConverterInterface $converter)
    {
        /* Message deployment logic... */
    }
}

/**
 * MessageCache
 * 
 * Assumes a DAOMessageDecorator implementing IDecorator
 */
class DAOMessage extends DAOMessageDecorator
{

    public function __construct( AbstractMessage $message )
    {
        parent:__construct( $messsage );
    }

    public function save( PDO $pdo )
    {
        /* Message persistence logic... */
    }
}

Example usage:

// Original message
$message = new AbstractMessage(...);
$fails = array(...);

// HTTP
$http_transport = new HTTPMessageTransport( $message, $fails );
$http_transport->send( $client, $converter );

// REST
$rest_transport = new RESTMessageTransport( $message, $fails );
$rest_transport->send( $client, $converter );

or

$message = new AbstractMessage(...);
$fails = array(...);

// HTTP
$http_transport = new HTTPMessageTransport( $message, $fails );
$http_transport->send( $client, $converter );

// REST
$rest_transport = new RESTMessageTransport( $http_transport->message(), $fails );
$rest_transport->send( $client, $converter );

// RDBS
$db_cache = new MessageCache( $rest_transport->message );
$db_cache->save( $pdo );

Even though the different transports are extending the MessageDecorator class in the examples above, you could always create a new category of decorators that implement the IDecorator interface. In the end your original message can still be preserved and passed around amongst other decorators (unrelated to the message transport decorators)