PHP Design - Avoiding Globals with Dependency Injection

Introduction
This question got me thinking...

Why shouldn't we use Globals?

This is a simple question without a simple answer.  How do you explain these concepts to a programmer who is coming from a background in procedural programming? 

There is a lot of deep background thinking that you need to understand in order to know why globals are considered to be a poor design choice today.  Singletons are just as bad as globals in many ways.  Often procedural programmers have looked at the global keyword as an expedient solution - a global declaration made inside your functions provided a simple reference to an external database connection.  Tightly-coupled code sets were the norm in programming just a few years ago, and the global keyword implemented tight coupling in a way that irrevocably bound certain objects into the fabric of the application.   If you're working alone on a standalone project, you can sometimes get away with using global objects, but if you want to come into the modern world of application design, and especially if you want to collaborate on anything important, you need to understand why global elements are considered harmful, and what the alternatives offer.

Global Variables Break Encapsulation
Encapsulation is a good thing because it means that your functions and variable names cannot collide with other variables in the script.  Consider a script that has a function called fetch_object().  There can be only one such function name; an attempt to define a duplicate function name will cause a PHP parse error in the script.  Consider a script that has a variable named $x.  If you have two definitions for $x in the same script, PHP will not complain but your programming logic may find you using one value for $x when you think you have another value for $x.  These sorts of confusions create the stuff of nightmares for experienced developers.  To get around this problem of confused and conflicting names, we use encapsulation by wrapping our functions and variables inside of classes.  We call class member functions methods and class member variables properties.  With appropriate encapsulation we can have two programmers working on the same application at the same time and we can be sure that they will not step on each others toes by using duplicate names for functions and variables.  PHP has two good ways of producing encapsulation: Classes and Namespaces.  Global declarations break them both.

You Cannot Test Anything That is Global
Today, formalized testing is the norm in application development.  In fact, many of the best teachers of software development recommend building your tests before you build any of the software!  Testing is so important that most open-source projects require unit tests before you make a pull request.  So why can't we test global objects?  Let's look at some testing tools and see how they work.  Look up PHPUnit and Mockery, get an idea of their concepts, then come back to this article.

By "test", we mean you cannot substitute a mock object for a global variable, because if you substitute it in one place, you've also substituted it in every other place.  It's global, and that means it is a single instance that is available in every scope or namespace.  Now go back and consider the $db variable from the original question.  If you create the $db in the initialization code and pass it into your methods and functions, you can use automated test tools to create a mock object for the $db, and you can mock it in each place it is used separately without affecting the other code or functionality of the site.  Your script depends on the $db variable, so we call it a "dependency."  This is the correct way to think about dependencies -- if you must depend on something you want to be able to substitute something else for the dependency.  The substitution facilitates automated testing; it also makes your application design more flexible.

With the global, you must test on your live database (WTF?!), or you must use a mirror database.  With dependency injection you can isolate the $db on a case-by-case basis.

You Cannot Remove a Dependency on a Global
It's global, after all - how do you unset() a global without causing "global" disruption in other parts of your application?  It may be no problem if you're the only programmer on a project, at least not until you make a mistake in a global element of the application.  But if there is more than one programmer working on a project (and anything of value will have more than one programmer) the project is at risk.  If the programmers have come to depend on a global, any change to the global means all the programmers must rerun all of their tests and perhaps remediate their code.  They may even be forced to rewrite their tests. 

Why might you want to unset() or nullify a dependency?  That is how you close a PDO connection.

Class Members (Properties and Methods) Are Confusing Enough
But at least there is a hierarchy of visibility among class members, and even when inheritance or traits seems to be distracting, you can find your way to the class members and change them secure in the knowledge that you will not clobber something outside of your scope and namespace. 

Unfortunately, globals are all-or-nothing, and once your code is exposed to a global, you're at the mercy of every bit of programming that runs as a part of the app, whether you wrote it or not.  In other words, if you use my global, you have to trust my global, whether you like it or not.  And it is possible that I'm doing things with my global that you may never encounter until you experience a run time failure, because I did not initialize my global correctly or mutated my global as a result of a run-time condition you did not expect.  

In contrast, if you use your own class members, whether by direct reference or dependency injection, you do not have to trust my programming -- your work can be decoupled and tested separately, and changes in my work do not affect your work.

But What About PHP Superglobal Variables?
Yes, superglobal variables are every bit as bad as the global variables you create yourself.  They are an artifact of PHP's long history, and we can't get rid of them without disrupting the design of existing web applications.  In retrospect, it is apparent that the early authors of PHP did not know very much about computer science.  If they had, we would never have created  something as unfortunate as Register Globals.  There is one saving grace, however.  We know the superglobals by their names and where they live, so we can deal with them carefully.

But Dependency Injection is Complicated
We all have to deal with the question of "I have a lot of dependencies and it's hard to remember how to write my function calls because of all the things I have to inject into the functions."  That can be a real problem because PHP function arguments are positional parameters, so you have to remember them in sequential order.  If you have a class method that needs half-a-dozen dependencies (also called function arguments) it's easy to confuse the order.  So here's an article that teaches a design pattern to simplify this problem.  It lets you use that uses type hinting and a parameter object containing named parameters which can be easier to remember.  In this design the sequential order of your arguments does not matter.
http://www.experts-exchange.com/articles/18409/Using-Named-Parameters-in-PHP-Function-Calls.html

But Dependency Injection is Complicated
Not really.  Every time you write a function call, even something as simple as $x = substr($y,0,2) you are using dependency injection.  To assign the value of the $x variable, your script depends on $y.  You're injecting $y into the substr() function.  That's dependency injection.  That's all there is to it.

This is a very simplified code example, but it will serve to illustrate the essential moving parts of a database dependency injection, showing how the $mysqli database object is not used as a global, but is injected into the function.  Injection into object methods is exactly the same as injection into inline functions.  You just name the thing you want to inject among the variables that are listed in the function definition, and use the thing inside the function or method.  You've been doing this all along!

Notice in our definition of the run_a_query() function we use a type hint to tell PHP that the only acceptable argument for $db is a MySQLi object.  Little things like that can make our programming easier to read, understand, and debug.

<?php // demo/mysqli_di_example.php
                      
                      /**
                       * Demonstrate Dependency Injection with a MySQLi Object
                       *
                       * Man Page References:
                       * http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration
                       * http://php.net/manual/en/mysqli.overview.php
                       * http://php.net/manual/en/class.mysqli.php
                       * http://php.net/manual/en/class.mysqli-stmt.php
                       * http://php.net/manual/en/class.mysqli-result.php
                       * http://php.net/manual/en/class.mysqli-warning.php
                       */
                      
                      // RAISE THE ERROR REPORTING LEVEL TO THE HIGHEST POSSIBLE SETTING
                      ini_set('display_errors', TRUE);
                      error_reporting(E_ALL);
                      echo '<pre>';
                      
                      // DATABASE CONNECTION AND SELECTION VARIABLES - GET THESE FROM YOUR HOSTING COMPANY
                      $db_host = "localhost"; // PROBABLY THIS IS OK
                      $db_name = "??";
                      $db_user = "??";
                      $db_word = "??";
                      
                      // OPEN A CONNECTION TO THE DATA BASE SERVER AND SELECT THE DB
                      $mysqli = new mysqli($db_host, $db_user, $db_word, $db_name);
                      
                      // DID THE CONNECT/SELECT WORK OR FAIL?
                      if ($mysqli->connect_errno)
                      {
                          $err
                          = "CONNECT FAIL: "
                          . $mysqli->connect_errno
                          . ' '
                          . $mysqli->connect_error
                          ;
                          trigger_error($err, E_USER_ERROR);
                      }
                      
                      // ACTIVATE THIS TO SHOW WHAT THE DB CONNECTION OBJECT LOOKS LIKE
                      // var_dump($mysqli);
                      
                      
                      // A FUNCTION OR METHOD THAT USES A TYPE HINT AND AN INJECTED DATABASE CONNECTION
                      function run_a_query(MySQLi $db, $query)
                      {
                          if (!$res = $db->query($query))
                          {
                              $err
                              = 'QUERY FAILURE:'
                              . ' ERRNO: '
                              . $mysqli->errno
                              . ' ERROR: '
                              . $mysqli->error
                              . ' QUERY: '
                              . $sql
                              ;
                              trigger_error($err, E_USER_ERROR);
                          }
                          $data = $res->fetch_object();
                          return $data;
                      }
                      
                      
                      // USE THE FUNCTION SHOWING THE INJECTION OF THE DATABASE OBJECT
                      $set = run_a_query($mysqli, 'SELECT 2+2 AS the_answer');
                      var_dump($set);

Select all Open in new window

What is a Singleton, Anyway?
A "singleton" refers to a class that can only be used to instantiate one object.  In our code example just above, we assigned the $mysqli variable to the database connection object, but we could just as easily have created other connection objects and assigned the other connections to other variables.  We might do this if we were using different databases at the same time.

With a singleton, we get the same problem we get with a global object.  Since you can't have more than one instance, you cannot create mock versions for testing.  The singleton design pattern is worth understanding since it is the 21st-century, object-oriented version of a global, and therefore is to be avoided. 

This code snippet shows a singleton database connection object.  By marking the properties and methods final and private we ensure that no unauthorized access or extension can occur.  We nullify the clone() and wakeup() methods to ensure that unwanted copies of the object cannot be created.  There is only one public method, getConnection(), and it must be called statically.  It is self-aware and will only return its own single database connection, hence the term, "singleton."

<?php // demo/oop_database_singleton.php
                      
                      /**
                       * A PHP example of a database class that illustrates the Singleton design pattern
                       *
                       * http://php.net/manual/en/language.oop5.php
                       * http://php.net/manual/en/language.oop5.object-comparison.php
                       */
                      error_reporting(E_ALL);
                      
                      
                      // SINGLETON DATA BASE CONNECTION CLASS
                      class Database
                      {
                          // CLASS PROPERTIES ARE ALL PRIVATE
                          private static $connection;
                          private static $instance;
                      
                          // PUT YOUR CONNECTION VALUES HERE
                          const DB_HOST = 'localhost';
                          const DB_USER = '??';
                          const DB_PASS = '??';
                          const DB_NAME = '??';
                      
                          // NULLIFY THE CLONE AND THE WAKEUP
                          final private function __clone() {}
                          final private function __wakeup() {}
                      
                          // OUR ONLY PUBLIC METHOD RETURNS THE CONNECTION
                          final public static function getConnection()
                          {
                              if (!self::$instance) self::$instance = new self();
                              return self::$connection;
                          }
                      
                          // CONSTRUCTOR CREATES THE CONNECTION
                          final private function __construct()
                          {
                              self::$connection
                              = new mysqli
                              ( self::DB_HOST
                              , self::DB_USER
                              , self::DB_PASS
                              , self::DB_NAME
                              )
                              ;
                              if (self::$connection->connect_error)
                              {
                                  trigger_error(self::$connection->connect_error, E_USER_ERROR);
                              }
                          }
                      }
                      
                      
                      // SHOW WHAT HAPPENS WHEN YOU TRY TO MAKE TWO CONNECTIONS
                      $dbc_1 = database::getConnection();
                      $dbc_2 = database::getConnection();
                      
                      
                      // PROVE THAT THESE VARIABLES POINT TO THE SAME OBJECT
                      if ($dbc_1 === $dbc_2) echo 'EQUAL! ';
                      
                      // SHOW THE OBJECT
                      echo '<pre>';
                      var_dump($dbc_2);

Select all Open in new window

Summary
As software development techniques mature we are better able to collaborate on projects.  We have learned about dependency injection and why it is wise to avoid global objects.  We have seen examples that show better, more flexible ways of accomplishing what we used to do with the global keyword.  We have seen how a singleton object has the same issues as a global variable.  We have learned a bit about the importance and techniques for unit testing.

Further reading on modern design patterns:
https://www.experts-exchange.com/articles/18329/SOLID-Design-in-PHP-Applications.html

Please give us your feedback!
If you found this article helpful, please click the "thumb's up" button below. Doing so lets the E-E community know what is valuable for E-E members and helps provide direction for future articles.  If you have questions or comments, please add them.  Thanks!