If your knowledge of constructors ends with “the place where I put my object initialization code,” read on. While this is mostly what a constructor is, the way a developer crafts their class constructor greatly impacts the initial API of a particular class/object; which ultimately affects usability and extensibility. After all, the constructor is the first impression a particular class can make.
Constructors, in their current form, have been in PHP since 5.0.0. Previous to 5.0, PHP loosely followed the style similar to that of C++ where the name of the method matching the name of the class would act as the class constructor. PHP 5 brought us the __construct() “magic method” which greatly formalized the new object initialization routine.
Before jumping into some of the topics covered in this post, there are a few things you might want to be familiar with. First, be familiar with the SOLID principles, particularly the S (single responsibility principle), the L (Liskov substitution principle, commonly referred to as the LSP), and the D (dependency inversion principle). More to the point of the latter, review a previous post on Dependency Injection in PHP for background dependency injection specific to PHP.
The Constructor Signature
In PHP, you create a constructor by adding a method called __construct() to your class. The __construct() method is an instance method and as such, is not marked static. For all intents and purposes, consider the __construct() magic method as a special type of static object factory, one which will always return the type of the object requested via the new keyword.
class Foo {
public function __construct() {
}
}
$object = new Foo();
In the above code, PHP will, upon executing new Foo(), internally create a new object from scratch, execute __construct() in the Foo class, and assign this object to the variable $object. Pretty standard stuff. What’s important to know here is that before new Foo(), the object did not exist. It is this fact alone that makes this completely different from any other kind of instance method. That said, without getting into the gritty details, it is this fact alone that excuses the __construct() method from the same rules of the LSP that might apply to other instance methods.
This means that all of the following are legal:
class Foo {
public function __construct() {
}
}
class Bar extends Foo {
public function __construct(ArrayObject $arrayObj, $number = 0) {
/* do stuff with $arrayObj and $number */
}
}
class Baz extends Bar {
public function __construct(Bar $bar) {
// yes, this is the proxy pattern
}
}
The above, with E_STRICT enabled, will not produce a warning. Yet, if you renamed all of the __construct methods to anything else, they will produce a E_STRICT warning like:
Strict standards: Declaration of Bar::somemethod() should be compatible with that of Foo::somemethod()
Why is this the case? Simply put, the LSP referrers to sub-types of a particular object, and since before the __construct() method, no type exists (yet). This rules simply cannot apply to something that does not exist. For a more detailed response, go here.
What you should take away from this is that the best-practice is that each concrete object has a constructor with a signature that best represents how a consumer should fully instantiate that particular object. In some cases where inheritance is involved, “borrowing” the parents constructor is acceptable and useful. Furthermore, it is encouraged that when you subclass a particular type, that your new type should, when appropriate, have its own constructor that makes the most sense to the new subtype.
At this point, it should be noted that most other languages do not allow constructors to be marked final, be abstract, or be marked as statics (see above on the static note). Moreover, constructors should not appear in interfaces. In PHP, these rules do not apply, and are all possible. For the reasons listed above, a developer should avoid the practice of marking constructors final, making them abstract, and putting them interfaces, assuming they are trying to utilize PHP’s OO model in a SOLID way. In PHP 5.4, it is also worth knowing that by having constructors in interfaces breaks the common expectation that subtypes are capable of creating their own constructors in favor of enforcing a particular method signature.
Constructor Overloading
PHP does not have method overloading. This also applies to constructors. A class of a specific type can only have one constructor. Since this is the case, PHP developers sometimes loosen a methods signature in order to accommodate multiple use cases. This is done by removing or reducing the types enforced in the constructors signature to allow for more varied types to be passed in by the consumer.
This is an acceptable best practice when done appropriately. What does appropriately mean? What is “appropriate” is, of course, very much subjective. Generally speaking, the differences in the various signatures supported should be minimal at best, yet meaning should still communicated through the name of the parameters. For example, let’s take this constructor:
class Db {
/**
* @var string|array|DriverInterface $driver
*/
public function __construct($driver) {
if (is_string($driver)) {
$driver = $this->createDriverFromString($driver);
} elseif (is_array($driver)) {
$driver = $this->createDriverFromArray($driver);
}
if (!$driver instanceof DriverInterface) {
throw new Exception();
}
}
}
The above signature __construct($driver) technically supports 3 effective signatures:
__construct(/* string */ $driver); __construct(/* array */ $driver); __construct(DriverInterface $driver);
The actual signature has not changed, but it is represented all 3 effective signatures that can be further described by the PHP DocBlock.
Constructor Injection
At this point in the PHP community and in PHP-centric developer circles, it is generally accepted that injecting your dependencies is a best-practice. How developers go about injecting these dependencies is still very much debated and, in-part, up to personal and/or team preference.
There are several such methods of dependency injection: interface injection, setter injection and constructor injection to name the primary forms. For the purposes of this post, constructor injection is our primary candidate for discussion.
In short, constructor injection is a pattern of injecting all of your required dependencies into a constructor. These dependencies are usually other objects, often called services. The primary benefit of constructor injection is that after you instantiate the target object, generally, it is in the complete “ready state,” meaning that it is ready to do real work. A typical constructor signature sporting constructor injection looks like this:
class UserMapper {
}
class UserRepository {
public function __construct(UserMapper $userMapper) {
$this->userMapper = $userMapper;
}
}
The above example clearly demonstrates that before a developer can use a UserRepository object, they must first inject it with a UserMapper object.
In PHP, while in recent times we’ve started favoring dependency injection (which can add some complexity to code), we have traditionally gravitated towards code that is easy write and easy to use. Practicing good dependency injection can be tedious at times and, in many cases, dependencies for objects can be stubbed by a sensible default. This practice is also known by the name of Poka-Yoke. It allows us to develop an API that supports explicit injection of dependencies while promoting ease of use in common or majority use cases. Consider the following code:
class UserMapper implements UserMapperInterface {
}
class UserRepository {
protected $userMapper;
public function __construct(UserMapperInterface $userMapper = null) {
$this->userMapper = ($userMapper) ?: new UserMapper;
}
}
While the UserRepository allows you to inject your dependency of the UserMapper, it will, if one was not provided, instantiate a sensible default UserMapper for you. The benefits are that in the most common use cases, it is a one step usage scenario (just instantiate the UserRepository). But in unit testing scenarios or scenarios where you want to inject an alternate implementation of a UserMapper, that can be achieved through the constructor.
Dynamic Class Instantiation
Generally speaking, the following code, while legal, should be used very seldom, and only when other possible instantiation patterns have been exhausted:
$obj = new $className();
if (!$obj instanceof SomeBaseType) {
throw new \InvalidTypeException();
}
Why is this a bad pattern? First, it makes the assumption up front that the constructor signature is free from any required parameters. While this is good for object types that are already known to this factory, it might not always be true of a consumers subtype of the base object in question. This patten should never be used on objects that have dependencies, or in situations where it is conceivable that a subtype might have dependencies because this takes away the possibility for a subtype to practice constructor injection.
Another problem is that instead of managing an object, or a list of objects, you are now managing a class name, or list of class names in addition to an object or list of objects. Instead, one could simply manage the objects.
If, on the other hand, you know this particular object type is no more than a value object (or similar), with no chance of it needing dependencies in subtypes, you can then cautiously use this instantiation pattern.
Prototype Pattern
So how does one create an unlimited number of objects of a particular type, with dependencies in tact, each with slight variations? Enter the prototype pattern. This is an important pattern to keep handy when you know that you’ll have objects that need to be replicated in some way and they also have service dependencies that need to be injected.
To draw a parallel, this is similar to how Javascript handles its object model. To sum prototyping up in Javascript: functions and properties are defined once per prototype rather than once per object. The new keyword instructs the engine/runtime to create a copy of the prototype and assign to a variable for further specification and interaction.
This is similar to what the Prototype Pattern does in an object-oriented inheritance model. Up front, you create a prototypical instance. This instance will have all its dependencies injected, and any shared configuration and/or values setup. Then, instead of calling new again, a factory (or the consumer) will call clone on the object (a shallow clone will be made), and a new object will be created from the original prototypical object. This newly cloned object can then be further specified, injected with the variations that make this new object unique, thus interacted with as a unique object.
Lets consider the following example involving a database connection and the Row Gateway pattern. We want to iterate a dataset from a database and during iteration, present each row as a RowGateway object. One way of handling this would be to get the array of data from the database, then during iteration, create a new RowObject from scratch injecting the database connection:
class DbAdapter {
public function fetchAllFromTable($table) {
return $arrayOfData;
}
}
class RowGateway {
public function __construct(DbAdapter $dbAdapter, $tableName, $data) {
$this->dbAdapter = $dbAdapter;
$this->tableName = $tableName;
$this->data = $data;
}
/**
* Both methods require access to the database adapter
* to fulfill their duties
*/
public function save() {}
public function delete() {}
public function refresh() {}
}
class UserRepository {
public function __construct(DbAdapter $dbAdapter) {}
public function getUsers() {
$rows = array();
foreach ($this->dbAdapter->fetchAllFromTable('user') as $rowData) {
$rows[] = new RowGateway($dbAdapter, 'user', $rowData);
}
return $rows;
}
}
A UserRepository will be constructed with a database adapter object. It will then query the database, returning an array of all the rows that satisfied that query. With each row of data, it will create a fresh RowObject from scratch, injecting all the dependencies, configuration and the row data.
At first glance, you might ask “what if I have a specialized version of RowGateway I want to use?” That solution can be easily handled by instead of hard-coding the RowGateway class, but by use the Dynamic Class Instantiation pattern described above:
class UserRepository {
public function __construct(DbAdapter $dbAdapter, $rowClass = 'RowGateway') {}
public function getUsers() {
$rows = array();
foreach ($this->dbAdapter->fetchAllFromTable('user') as $rowData) {
$rowClass = $this->rowClass;
$row = new $rowClass($dbAdapter, 'user', $rowData);
if (!$instance of RowGateway) {
throw new InvalidClassType();
}
$rows[] = $row;
}
return $rows;
}
}
This partially solves the problem in that now we can now use our own specialized class for the RowGateway implementation, but this too has its own special set of limitations. First, we are incorrectly making the assumption that the constructor signature of a subtype of RowGateway is exactly the same as the base type. This means that if a subtype has additional dependencies, that class will need to do the static dance in order to locate and consume those dependencies that it needs to achieve its specialized functionality. By making this assumption of the classes constructor signature, we’re limiting the consumers ability to practice polymorphism in the subtypes that they might need to have created.
For example, if a consumer wanted to be able to have a RowGateway object that wrote data to one specific database, but refreshed its data from a different database, how might one be able to inject two different DbAdapters into a RowGateway object to achieve this end result?
The answer is to use the Prototype Pattern, and in practice (via pseudo-code), looks like this:
class DbAdapter {
// same as before
}
class RowGateway {
public function __construct(DbAdapter $dbAdapter, $tableName) {
$this->dbAdapter = $dbAdapter;
$this->tableName = $tableName;
}
public function initialize($data) {
$this->data = $data;
}
/**
* Both methods require access to the database adapter
* to fulfill their duties
*/
public function save() {}
public function delete() {}
public function refresh() {}
}
class UserRepository {
public function __construct(DbAdapter $dbAdapter, RowGateway $rowGatewayPrototype = null) {
$this->dbAdapter = $dbAdapter;
$this->rowGatewayPrototype = ($rowGatewayPrototype) ? new RowGateway($this->dbAdapter, 'user')
}
public function getUsers() {
$rows = array();
foreach ($this->dbAdapter->fetchAllFromTable('user') as $rowData) {
$rows[] = $row = clone $this->rowGatewayPrototype;
$row->initialize($rowData);
}
return $rows;
}
}
By using a prototypical instance as the base for all future instances, we now allow the consumer the ability to extend this base implementation using sound object-oriented/polymorphic best-practices to achieve their end result. So, assuming our above example of the read/write adapter, a consumer can write:
class ReadWriteRowGateway extends RowGateway {
public function __construct(DbAdapter $readDbAdapter, DbAdapter $writeDbAdapter, $tableName) {
$this->readDbAdapter = $readDbAdapter;
parent::__construct($writeDbAdapter, $tableName);
}
public function refresh() {
// utilize $this->readDbAdapter instead of $this->dbAdapter in RowGateway base implementation
}
}
// usage:
$userRepository = new UserRepository(
$dbAdapter,
new ReadWriteRowGateway($readDbAdapter, $writeDbAdapter, 'user')
);
$users = $userRepository->getUsers();
$user = $users[0]; // instance of ReadWriteRowGateway with a specific row of data from the db
Parting Words
Be nice to people who want to consume and extend your code. A constructor is more than just a place for initialization code. How you craft your constructors, the patterns you use for their signatures, and how you expect to get new instances of objects greatly affects the ability of consumers to extend your code without having to jump through too many hoops in order form them to achieve their specialized use case. It is always better to fall back on SOLID object-oriented practices than to limit someones possibilities by forcing them into coding patterns that require reading in-depth documentation on how the original author expects someone to extend their code.