DEV Community: Ibrahim Alausa

A comprehensive guide on how to design future-proof controllers: Part 2

Ibrahim Alausa — Sat, 02 Apr 2022 11:23:39 +0000

Introduction

This article is the second part of a series of articles where we talk about how separating code based on functionality can improve the quality of your codebase. If you have not read the first part, check it out here.

This article will focus on separating the request validation concern from the rest of the code in the Controller. I will be using Laravel in this tutorial. Still, you can apply the ideas we will be discussing here to any programming language that supports any form of code separation into packages, modules, etc., in such a way that you can use code written in file A in file B.

Prerequisites

Reading the first part of this article here to understand some concepts and terminologies
Knowledge of Object-Oriented Programming (OOP) is required
Basic knowledge of Laravel
If you want to test the code on your system, then you **MUST **have PHP installed on your system

Let's dive in 🚀

You can find all the code from this article here.

What we currently have

Let's look at a simple controller function that adds a new user to the database during a registration process. I have added comments to illustrate how we can identify the three concerns involved in the register function.

  /**
   * create a new account
   * @param \Illuminate\Http\Request $request
   * @return \Illuminate\Http\Response
   */
  public function register(Request $request)
  {
    /*----Concern (Request validation)----*/
    $validator = Validator::make($request->all(), [
      'email' => 'required|email|unique:users',
      'name' => 'required|string',
      'password' => 'required|min:6'
    ]);

    if ($validator->fails()) {
      /*----Concern (Sending response to the client)----*/
      return response()->json(
        [
          "status" => false,
          "message" => $validator->errors()
        ],
        422
      );
    }

    /*----Concern (Handling business logic (In this case, hashing the user's password and interaction with database)----*/
    $password = Hash::make($request->password);
    $user = User::create([
      'name' => $request->name,
      'password' => $password,
      'email' => $request->email
    ]);

    /*----Concern (Sending response to the client)----*/
    return response()->json(
      [
        "status" => true,
        "message" => 'User account created successfully',
        "data" => $user
      ],
      201
    );
  }

Separating the Request Validation Concern

We will discuss two approaches to separate the Request validation concern from the Controller.

The first approach involves building a request validation class and writing all your validation logic in the validation class. The Class needs to contain some public methods to ensure that the Controller can execute the validation logic.
The second approach is called Form request validation. This approach is specific to Laravel, and the validation class has to follow a particular pattern. It's a powerful feature.

Approach 1: Building a Request Validation Class

Create a folder called Validators inside the app/Http directory
Create a new file called AuthValidator.php in the newly created Validators folder
The code below should be the content of the AuthValidator.php file

<?php

namespace App\Http\Validators;

use Illuminate\Support\Facades\Validator;


class AuthValidator
{
  protected $errors = [];

  /**
   * validate user registration data
   *
   * @param  array $requestData
   * @return \App\Http\Validators\AuthValidator
   */
  public function validateRegistrationData(array $requestData)
  {
    $validator = Validator::make($requestData, [
      'email' => 'required|email|unique:users',
      'name' => 'required|string',
      'password' => 'required|min:6'
    ]);

    $this->errors = $validator->errors();

    return $this;
  }


  /**
   * get the errors that occurred during 
   * validation
   *
   * @return array
   */
  public function getErrors()
  {
    return $this->errors;
  }
}

What exactly does the code do? 😕

First, we have a property in the Class called $errors and set the value as an empty array
Then, we create a method called validateRegisterationData(), which will be responsible for executing the actual validation logic
The result of the validation check ($validator->errors()) is stored in the $errors property of the current object. If all the data in the request are valid and no validation error(s) occurred, the validator returns an empty array.
Finally, we return the current object ($this)
The second method, getErrors() simply returns the $errors property for the current object. This property would contain the actual errors that occurred during validation or an empty array if no errors occurred

How do we use the AuthValidator in the Controller? 🤔

Create a constructor method (__construct()) in the AuthController class and pass the Authvalidator class as a parameter in the constructor. Then the value of the parameter is stored in a class property.

class AuthController extends Controller
{

  protected $authValidator;

  /**
  * __construct
  * 
  *  @param \App\Http\Validators\AuthValidator $authValidator
   * @return void
   */
  public function __construct(AuthValidator $authValidator)
  {
   $this->authValidator = $authValidator;

  }

Now we can remove the existing validation logic in the register() method of the Controller and use the logic in the AuthValidator class we created ☺️.

  /**
   * create a new account
   * @param \Illuminate\Http\Request $request
   * @return \Illuminate\Http\Response
   */
  public function register(Request $request)
  {
    $errors = $this->authValidator
      ->validateRegistrationData($request->all())
      ->getErrors();

    if (count($errors)) {
      return response()->json([ "status" => false,"message" => $errors],
        422
      );
    }

Since the validateRegistrationData() method returns an object, we can immediately execute the getErrors() method on the returned object without assigning it to a variable first. This pattern is called Fluent interface. count($errors) checks if there is at least one element in the errors array returned from the validator and returns a response to the client if any error exists.

With the code designed this way, the Controller does not care how the validation logic works. The Controller knows that the validator will do its job and return a response after completing the validation process. Then the final response is sent from the Controller. So we can add, remove or modify the validation logic, and the Controller still works perfectly without any issues. Sweet right. If you think this is great, let's look at the second method, which is using Laravel Form Requests.

Approach 2: Using Laravel Form Requests

Form requests are custom request classes containing their validation logic, just like we did in the first approach. Laravel Form requests are also awesome because they contain authorization logic by default. To create a form request class, you may use the make:request artisan command provided by Laravel.

php artisan make:request CreateNewUserRequest

Laravel will generate a form request class in the app/Http/Requests directory with the name passed as the file name. In our case, a new file, CreateNewUserRequest.php will be created.

By default, Form request classes generated by Laravel come with two methods, authorize() and rules(). The authorize() method contains the logic that determines if the user making that request has the permission to do so. Of course, you can modify the logic to fit your specific use case at any time. In our case, we do not require any special permission or authorization for the CreateNewUserRequest Class, so we return true.


/**
   * Determine if the user is authorized to make this request.
   *
   * @return bool
   */
  public function authorize()
  {
    return true;
  }

On the other hand, the rules() method returns the validation rules that should apply to the request's data.


/**
   * Get the validation rules that apply to the request.
   *
   * @return array
   */
  public function rules()
  {
    return [
      'email' => 'required|email|unique:users',
      'name' => 'required|string',
      'password' => 'required|min:6'
    ];
  }

How do we use the rules in the CreateNewUserRequest class in the Controller? 🤔

Change the type of the parameter in the register function from \Illuminate\Http\Request to \App\Http\Requests\CreateNewUserRequestwith(this is the path to the Laravel form request class we just built)
Remove the validation logic in the register() function
Since Laravel internally checks for errors and returns an appropriate response when using Form requests, we do not need an if statement to check if the validation failed

/**
   * create a new account
   * @param App\Http\Requests\CreateNewUserRequest $request
   * @return \Illuminate\Http\Response
   */
  public function register(CreateNewUserRequest $request)
  {
    /*--------Concern 2 (Business logic execution)------------------*/
    $password = Hash::make($request->password);
    $user = User::create([
      'name' => $request->name,
      'password' => $password,
      'email' => $request->email
    ]);

    /*--------Concern 3(Response formatting and return)------------------*/
    return response()->json(
      [
        "status" => true,
        "message" => 'User account created',
        "data" => $user
      ],
      201
    );
  }

And voila! Our Controller has absolutely no idea about the validation logic, and changes to the validations rules do not affect the Controller. So once again, we can change the validation logic however we want, and the Controller will remain the same and work perfectly.

Let's explore Form Requests a little further 💪🏿

Here is a sample error response from the CreateNewUserRequest class after sending a request with an empty value as the name of the new user

{
    "message": "The given data was invalid.",
    "errors": {
        "name": [
            "The name field is required."
        ]
    }
}

Now, let's assume that due to our team's convention, we need to change the structure of the error response sent back to the client after a failed validation. We can achieve this by overriding the default failedValidation() method in all Laravel form request classes that extend FormRequest, just like our CreateNewUserRequest Class.

Now we have an extra method, failedValidation(), that looks like this.

/**
   * Handle a failed validation attempt.
   *
   * @param  \Illuminate\Contracts\Validation\Validator  $validator
   * @return void
   *
   * @throws \Illuminate\Validation\ValidationException
   */
  protected function failedValidation(Validator $validator)
  {
    throw new HttpResponseException(
      response()->json(
        [
          'status' => false,
          'message' => 'Validation errors occurred',
          'errors' => $validator->errors(),
        ],
        422
      )
    );
  }

After making our changes on how we want the error message to be structured, our response looks like this.

{
    "status": false,
    "message": "Validation errors occurred",
   "errors": {
        "name": [
            "The name field is required."
        ]
    }
}

What's next? 💭

In the next part of this series, we will be looking at how to use Actions to separate business logic away from the Controller. Believe me, that would be awesome, and you don't want to miss it.

Quick recap 🔄

The controllers in your codebase should know what validation class to call to a particular request but have zero knowledge about the validation rules that apply to the request's data. That is the responsibility of Validators
You can build your validator class or use Laravel form requests. I don't think any approach is better than the other. It all depends on whichever approach you prefer
The Laravel form request class can also handle user authorization even before checking if the data from the client passes all the validation rules, and this is done via the authorize() method
The advantage of building your validators is that your methods can follow any naming convention you want. However, when using Laravel Form requests, the method handling the data validation must be named rules while the method that handles authorization must be named authorize.

It's a wrap 🎉

You can check out all the code in this article on Github. After reading this, I sincerely hope that you have learned something, no matter how small. If you did, kindly drop a thumbs up.
Thanks for sticking with me till the end. If you have any suggestions or feedback, kindly drop them in the comment section. Enjoy the rest of your day. Bye 😊.

A comprehensive guide on how to design future-proof controllers: Part 1

Ibrahim Alausa — Thu, 13 Jan 2022 10:55:55 +0000

Introduction

When you are still in that learning phase with any technology, your focus is to make your app work, but I think the exponential progress starts coming when you begin to ask yourself "How can I make this better?". One simple principle that you can immediately apply to your existing or new codebase for cleaner and more maintainable code is the Separation of Concerns principle.

Most of the server-side codebases I have come across have controllers that contain code specifying the real-world business rules on how data can be created, stored, and changed on the system. If you want to learn how to build controllers that are clean, concise, and easily maintainable, then this series is for you.

What you will learn after reading this article

You will have a solid understanding of the Separation of concerns principle
You will be able to identify the major steps involved in the lifecycle of a request on the server-side
You will understand the role of the controller on the server side. This will ensure that the lines of code present in your controller functions are the ones that **absolutely **need to be in the controller

Prerequisites

Understanding of client-server architecture
Familiarity with model-view-controller architecture
A basic understanding of Object-Oriented Programming

With all that out of the way, let's move 🚀

Understanding Separation of concerns

What is a concern?

A concern is a section of a feature or software that handles a particular functionality in the system. A good example of a concern in a well-designed backend system is request validation, which means there is a part of the code that accepts the data coming from the client to make sure all the information is valid or at least in the right format before sending it to the other parts of the system.

What does the term Separation of concerns mean?

Since we know what a concern is, understanding the idea behind the Separation of concerns will not be difficult. Separation of concerns promotes the idea of building software in such a way that our code should be broken down into separate components or layers such that each layer handles a specific concern. An example is a feature that retrieves data from the database and then formats the data based on the client’s request. Placing both logic in the same function is a really bad idea since retrieving data from the database is a specific concern, then formatting the retrieved data is another concern.

Lifecycle of a request on the server

I have worked on building many backend systems that provide services to clients and many of them usually follow a similar pattern with 3 major steps which are mainly.

Request validation: This refers to the part of your code that ensures that the data sent by a client is in a valid and acceptable format. A simple example is making sure that a value sent from the client as an email is actually a valid email address.
Business logic execution: This is the section of your codebase that contains the code that enforces real-world business rules. Let's use an app that allows a customer to transfer money from one account to another. A valid business rule is that you cannot transfer an amount that is greater than your current balance. For this app to work properly, there has to be a section of your code that compares the amount you are trying to transfer and your current balance and makes sure the business rule is obeyed. That is what we refer to as business logic.
Response formatting and return:This refers to the section of your codebase responsible for making sure the data returned to the client after business logic execution is properly formatted and well presented. eg JSON, XML

I have come across a lot of codebases that perform these three steps using a single function or method, where line 10 to 15 handles request validation, line 16 to 55 handles all the business logic with long if-else statements, loops, etc, then line 56-74 formats the response based on certain conditions, and finally, line 75 returns the data to the client. That’s about 65 lines of code in a single function! That is a ticking time bomb waiting to explode when a new engineer joins the team or when you come back to add more changes to the code.

Understanding the role of the controller in the backend request lifecycle

Imagine we have 3 tasks involving the same feature.

Fix a bug in request validation
Change the way data is retrieved from the database (use Eloquent ORM instead of raw queries)
Add extra meta-data to the response returned to the client

If our controllers are designed in a way where each method contains all these three major steps involved in fulfilling a request on the server-side, then the flow looks something like the image below

Handling these tasks become a nightmare because everyone in the team will be modifying the same function, and good luck merging all these changes without the need to resolve merge conflicts 🙄.

So, what exactly should the controller do?

The controller should serve as a delegator, meaning that the controller accepts a request with the associated data from the client, then the controller should assign the different tasks involved in fulfilling the client’s request to different parts of the codebase, then finally, the controller sends a proper response (success or failure) to the client depending on the result of the executed code.
I have illustrated this using the image below.

If our controllers are built this way, making changes will be incredibly easy, bugs will be easy to trace and the responsibility of each class and other classes it depends on to fulfill its tasks will be immediately visible even to someone looking at the code for the first time.

There is more juicy stuff to come 😋

Like I said at the beginning of the article, this is going to be a series because there is a lot of information to digest and I want to make sure you can remember a lot after reading each article. I want to separate the concerns you know 😂, so that this article does not become massive like the controllers we will be refactoring starting from the next part. If you didn't get that joke, then maybe next time.

In the next article, Part 2. We will be refactoring a controller function with a specific focus on the Request validation concern. We will build a Request validator class and abstract all the logic involved in validating the client's request away from the controller. I will be using Laravel in the rest of the series.

Quick Recap

Separation of concerns is simply a concept that promotes the idea that you should always look at your code to identify the different functionalities involved, and think of how you can break down the code into smaller components for clarity, easy debugging, and maintenance among other benefits.
All the logic involved in fulfilling a client's request on the server-side should not be in a single location, like a controller.
The controllers should serve as classes that delegate tasks to other parts of the codebase and get's back a response from those other parts. Depending on the response received by the controller, the controller decides if the response to send back to the client should be a success or failure response.
More code might be involved when trying to break down a feature into smaller components but remember, it pays off in the long run.

It's a wrap 🎉

I sincerely hope that you have learned something, no matter how small, after reading this. If you did, kindly drop a thumbs up.

Thanks for sticking with me till the end. If you have any suggestions or feedback, kindly drop them in the comment section. Enjoy the rest of your day...bye 😊.

PHP 8: Constructor Property Promotion

Ibrahim Alausa — Mon, 29 Nov 2021 10:38:06 +0000

Introduction

If you have been a software engineer for a while, you know that software engineers love using scary names to describe simple things. The term constructor property promotion should not scare you because you might be using it in your codebase already without realizing it has a fancy name.

Here are the things you will achieve after reading this article.

You will be able to refactor a PHP class to use constructor property promotion instead of using the default syntax used when setting class properties in the constructor function.
You will know the different ways of accessing class properties after setting them using the constructor property promotion syntax.
You will know the common mistakes that lead to errors when using the constructor property promotion syntax in your PHP class and how to avoid them.

Interested? Let's move 🚀

Prerequisites

A basic understanding of Object-Oriented Programming in PHP
You must have PHP 8 installed to enjoy this feature in your code or project. Alternatively, you can test this feature on phpsandbox by selecting PHP8 as your preferred version

What is Constructor Property Promotion? 🤔

Constructor property promotion is a feature introduced in PHP 8 that allows values passed to a constructor to be automatically set as class properties without the need to write the assignment statement in the body of the constructor.
For a better understanding of the concept, let's take a look at the way values were assigned to class properties before the introduction of the constructor property promotion feature in PHP8.

Before constructor property promotion 🥱

Before constructor property promotion was introduced, here’s how you will typically set the
firstName and lastName properties passed to the Employee class through the constructor.

<?php

class Employee
{

  protected $firstName, $lastName;

  public function __construct(string $firstName, string $lastName)
  {
    $this->firstName = $firstName;
    $this->lastName = $lastName;
  }
}


$employee = new Employee('Ibrahim', 'Alausa');

In the code above, we are declaring the properties firstName and lastName without any initial value. Then, in the body of the constructor, we set the firstName and lastName properties to the value passed to the constructor. In this example, that is **Ibrahim **as the value of the firstName property and **Alausa **as the value of the lastName property.

The new way for the cool programmers 😎

Now, let's rewrite the Employee class to use constructor property promotion. Let's see what our code will look like in this case

<?php

class Employee
{
  public function __construct(protected string $firstName, protected string $lastName)
  {
  }
}


$employee = new Employee('Ibrahim', 'Alausa');

That's it. Yes. Isn't this beautiful? Just in case your answer is *NO * well, that was a rhetorical question, my friend. It is beautiful.

What exactly is different

By adding an access modifier (protected, private, etc) to each parameter in the constructor, PHP understands that you are trying to “promote” the constructor parameter to a class property.

Important points to note when working with constructor property promotion

1. Accessing class properties 🔐

Within the constructor, promoted properties can be accessed with or without the $this keyword since they are still within the function scope where they were declared. Let's see what our code will look like in this case

<?php

class Employee
{
  public function __construct(protected string $firstName, protected string $lastName)
  {
    var_dump($firstName);  Ibrahim ✔️
    var_dump($this->firstName); Ibrahim ✔️
  }
}


$employee = new Employee('Ibrahim', 'Alausa');