06 January 2015

Separating business logic from persistence layer in Laravel

There are several reasons to separate business logic from your persistence layer.  Perhaps the biggest advantage is that the parts of your application which are unique are not coupled to how data are persisted.  This makes the code easier to port and maintain.

I'm going to use Doctrine to replace the Eloquent ORM in Laravel.  A thorough comparison of the patterns is available here.

By using Doctrine I am also hoping to mitigate the risk of a major version upgrade on the underlying framework.  It can be expected for the ORM to change between major versions of a framework and upgrading to a new release can be quite costly.

Another advantage to this approach is to limit the access that objects have to the database.  Unless a developer is aware of the business rules in place on an Eloquent model there is a chance they will mistakenly ignore them by calling the ActiveRecord save method directly.

I'm not implementing the repository pattern in all its glory in this demo.  For a more purist approach to the pattern you can read this.  The reason that I'm choosing this approach is to cut down on the number of classes, cut down on the composer autoload, and to ensure my code is portable.  I also do not have to make any changes to my app aliases in config or create new Laravel services.

I'm going to use three objects to refer to my user table:
  • The UserEntity is a Doctrine entity to be accessed via the Doctrine entity manager by the Repository.  
  • The UserRepository is an intermediary layer akin to the data access object of other languages.  It uses the Entity to gather information that the Service layer needs.  
  • The UserService implements business logic and exposes methods to the controller.  It is the "fat model" in the "fat model / skinny controller" paradigm.
In order to be able to use Doctrine within Laravel I'm using the mitchellvanw/laravel-doctrine package.  I also use "raveren/kint" for access to the debugging "dd" shortcut.

The decision to use constructor injection when instantiating the user service is to make it easier to use a mock object when testing.  

I've deviated from the common practice of using private properties on a Doctrine entity and rather exposing getters and setters.  This is primarily so that in my user service layer I can conveniently reference properties of the entity in a manner that is not likely to change if I swap to another ORM.

I decided against marking the entity private and using reflection to retrieve the private properties in my repository.  I felt it was an unnecessary complication and not worth the processing cycles to ensure compatibility between methods of accessing a model property between ORMs.

The Doctrine entity class is incapable of persisting itself so if a developer instantiates it and modifies properties in the controller they won't be able to persist it unless they call the EntityManager class.  Hopefully this is more PT than calling save() on an ActiveRecord object.  Our design philosophy of avoiding doing this in controllers should also help to discourage mistakes here.

The files I created are listed below.  The drawback of avoiding any Laravel specific code is the rather ugly way of instantiating the service in the controller.  I believe, however, that my code will be easier to port to another framework than if I were to declare a Laravel service provider to make a static call to user.

You must include "app/models/user" into your composer autoload section and run the composer dump-autoload command from your shell once you've set up the directory.

app/models/user/UserEntity.php

 namespace User;  
 use Doctrine\ORM\Mapping AS ORM;  
 /**  
  * @ORM\Entity  
  * @ORM\Table(name="users")  
  */  
 class UserEntity  
 {  
      // see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html for info on mapping  
      /**  
       * @ORM\Id  
       * @ORM\GeneratedValue  
       * @ORM\Column(type="integer")  
       */  
      private $id;  
      /**  
       * @ORM\Column(type="string")  
       */  
      private $name;  
      /**  
       * @ORM\Column(type="string")  
       */  
      private $password;  
      /**  
       * @ORM\Column(type="datetime")  
       */  
      private $created;  
      /**  
       * @ORM\Column(type="datetime")  
       */  
      private $modified;  
      public function getId()  
      {  
           return $this->id;  
      }  
      public function getName()  
      {  
           return $this->name;  
      }  
      public function setName($name)  
      {  
           $this->name = $name;  
      }  
      public function setPassword($password)  
      {  
           $this->password = $password;  
      }  
 }  

app/models/user/UserRepository.php

 <?php namespace User;  
 class UserRepository  
 {  
   protected $entity;  
   public function __construct( UserEntity $userEntity )  
   {  
     $this->entity = $userEntity;  
   }  
   public function getUserById($userId)  
   {  
     $user = \EntityManager::find('User\UserEntity', $userId);  
     return $user;  
   }  
   public function getUserByName($userName)  
   {  
     $user = \EntityManager::getRepository( 'User\UserEntity' )->findBy( [ 'name' => $userName ] );  
     if( !is_array( $user ) || empty( $user ) )  
     {  
       return false;  
     }  
     return $user[0];  
   }  
   public function setPassword( $userDetails, $password )  
   {  
     // If user variable is numeric, assume ID  
     if ( is_numeric( $userDetails ) )  
     {  
       // Get user based on ID  
       $user = $this->getuserById( $userDetails );  
     }  
     else  
     {  
       // Since not numeric, lets try get the user based on Name  
       $user = $this->getuserByName( $userDetails );  
     }  
     $user->setPassword( $password );  
     $this->persist( $user );  
     return true;  
   }  
   public function persist( UserEntity $user )  
   {  
     // do any last moment validations here  
     \EntityManager::persist( $user );  
     \EntityManager::flush();  
   }  
 }  

app/models/user/UserService.php

 <?php namespace User;  
 /**  
  * Our UserService, containing all useful methods for business logic around Users  
  * Do not reference the entity in here.  
  */  
 class UserService  
 {  
   // Containing our user repository to make all our database calls to  
   protected $userRepo;  
   /**  
    * Loads our $userRepo with the supplied userRepository  
    *  
    * We use constructor injection to make it easier to unit test.  
    *  
    * @param userInterface $userRepo  
    * @return userService  
    */  
   public function __construct( $userRepository )  
   {  
     $this->userRepo = $userRepository;  
   }  
   /**  
    * Method to get user based either on name or ID  
    *  
    * @param mixed $user  
    * @return string  
    */  
   public function getUserName($user)  
   {  
     // If user variable is numeric, assume ID  
     if (is_numeric($user))  
     {  
       // Get user based on ID  
       $user = $this->userRepo->getuserById($user);  
     }  
     else  
     {  
       // Since not numeric, lets try get the user based on Name  
       $user = $this->userRepo->getuserByName($user);  
     }  
     // If user entity returned (rather than null) return the name of the user  
     if ($user != null)  
     {  
       return $user->getName();  
     }  
     // If nothing found, return this simple string  
     return 'user Not Found';  
   }  
   public function setPassword( $user, $password )  
   {  
     // perform any validations  
     if( strlen( $password ) < 6 )  
     {  
       throw new \ValidationException( 'Password may not be shorter than 6 characters' );  
     }  
     // perform any hashing on the password  
     $password = \Hash::make($password);  
     return $this->userRepo->setPassword( $user, $password );  
   }  
 }  

app/controllers/HomeController.php

 <?php  
 class HomeController extends BaseController {  
      public function showWelcome()  
      {  
           return View::make('hello');  
      }  
      public function setPassword( $userDetails, $password )  
      {  
           $userService = new User\UserService( new User\UserRepository( new User\UserEntity ) );  
           try  
           {  
                $response = $userService->setPassword( $userDetails, $password );  
           }  
           catch ( ValidationException $e )  
           {  
                // set error message for frontend  
                echo 'An exception was thrown ('.$e->getMessage().') - this will result in a frontend message';  
           }  
           dd( $response );  
      }  
 }  

app/routes.php

 Route::put('/password/{user}/{password}', 'HomeController@setPassword');  
Tip