Good habits in application design for PHP developer

Dmytro Tus

Full Stack Web developer

While browsing in the internet for literature on effective web application design, my attention was drawn to a text which highlights a programming approach in PHP language. I found it very beneficial, when working on the development of large PHP projects.

I recommend to keep these rules in mind and grow habits. These habits will help to code large-scale PHP systems in the future.

1. Final by default

   This habit will help to follow the Open-Closed principle. If you want to prevent extending your class. you need to use final
   

   // Final class example
   final class Config {
       // Class implementation
      // Config is a final class that cannot be extended by any other class.
   }
   

2. Declare strict types by default

   Write declare(strict_types=1) by default

3. Provide void return types

   If a method return nothing, it should be indicated with void. This makes it more clear to another developers and makes better redeability of the code.
   

   <?php
   
   function exampleFunction(): void {
       // Your function code here
       echo "This function does not return any value.";
   }
   
   // Call the function
   exampleFunction();
   
   ?>
   

4. Optimizing Code Clarity.

   Add a description when it provides more context than the method signature itself. Use full sentences for descriptions.

   Good example: reveal what your arrays and collections contain

   // GOOD
   final class Album
   {
       /** @var list<string> */
       private array $urls;
   
       /** @var \Illuminate\Support\Collection<int, \App\Models\Song> */
       private Collection $songs;
   }
   
   // BAD
   final class Album
   {
       private array $urls;
       private Collection $songs;
   }

5. Describe types using PSALM

   In the code below, I added comments where errors appear, but psalm will highlight them automatically. (psalm.dev)
   

   <?php
   
   /**
    * @return array<string>
    */
   function takesAnInt(int $i) {
       return [$i, "hello"]; //// <------------error here
   }
   
   $data = ["some text", 5];
   takesAnInt($data[0]); //// <------------error here
   
   $condition = rand(0, 5);
   if ($condition) {
   } elseif ($condition) {} //// <------------error here

6. Concatenation and curly-braces

   If possible use {} instead of . in php code. Example is below.
   

   // GOOD
   $welcome = "Hello, my name is {$name}.";

   // BAD (hard to distinguish the variable)
   $welcome = "Hello, my name is $name.";
   // BAD (less readable)
   $welcome = 'Hello, my name is '.$name.'.';

   For cases where complexity is more, or when it’s not possible to use string interpolation, you can use sprintf function:

   $welcome = sprintf('Hello, my name is %s', ucfirst($name));

7. Use class name resolution whenever is possible

   It will help understand your code better by another developers
   

   // GOOD
   use App\Modules\Shop\Models\Product;
   echo Product::class;
   
   // BAD
   echo 'App\Modules\Shop\Models\Product';

8. Using the class name instead of the self keyword

   It is better to use the class name instead of the self keyword when indicating return types and when instancing the class.
   

   // GOOD
   public function createNewClient(string $name): Client
   {
       $client = new Client();
       $client->name = $name;
   
       return $client;
   }
   
   // BAD
   public function createNewClient(string $name): self
   {
       $client = new self();
       $client->name = $name;
   
       return $client
   }

9. Exception suffix

   Don’t use "Exception" suffix inside the child class
   

   // Bad Example (with "Exception" suffix):
   
   class SaveProductException extends \Exception {
       // Exception-specific code or details
   }
   
   // Good Example (without "Exception" suffix):
   class SaveProductError extends \Exception {
       // Exception-specific code or details
   }
   

10. Be clear about errors

    Maintain clarity on errors. Provide a clear understanding of any issues that arise.
    

    // GOOD
    abort(404, "The product with the ID {$productId} could not be found.");
    
    // BAD
    abort(404);

11. Use Type-casting

    Opt for type-casting over dedicated methods when converting variable types for improved performance.

    // GOOD
    $count = (int) '7';
    $isAdmin = (bool) $this->is_admin;
    
    // BAD
    $count = intval('7');
    $isAdmin = boolval($this->is_admin);

12. Use named constructors

    Using named constructors make the code more readable.
    

    // BAD
    final class Time
    {
        private $hours, $minutes;
        public function __construct($timeOrHours, $minutes = null)
        {
            if(is_string($timeOrHours) && is_null($minutes)) {
                list($this->hours, $this->minutes) = explode($timeOrHours, ':', 2);
            } else {
                $this->hours = $timeOrHours;
                $this->minutes = $minutes;
            }
        }
    }
    
    // GOOD
    final class Time
    {
        private $hours, $minutes;
    
        public function __construct($hours, $minutes)
        {
            $this->hours = (int) $hours;
            $this->minutes = (int) $minutes;
        }
    
        public static function fromString($time)
        {
            list($hours, $minutes) = explode($time, ':', 2);
            return new Time($hours, $minutes);
        }
    
        public static function fromMinutesSinceMidnight($minutesSinceMidnight)
        {
            $hours = floor($minutesSinceMidnight / 60);
            $minutes = $minutesSinceMidnight % 60;
            return new Time($hours, $minutes);
        }
    }

13. Use domain-specific operations

    From the SOLID we know about separating logic. But in some cases, we need to combine logic when it is useful for domain. When logic can be combined and still make sense to the business, we can use it.
    

    // GOOD
    
    // Models\User.php
    public function confirmEmailAfterRegistration(): void
    {
        $this->email = $this->email_register;
        $this->email_register = null;
    }
    
    // Controllers\UserEmailAfterRegistrationController.php
    public function store(): void
    {
        $user = auth()->user();
        $user->confirmEmailAfterRegistration();
        $user->save();
    }
    
    // BAD =====================================
    
    // Models\User.php
    public function setEmail(string $email): User;
    public function setEmailAfterRegistration(string $email): User;
    
    // Controllers\UserEmailAfterRegistrationController.php
    public function store(): void
    {
        $user = auth()->user();
        $user->email = $user->confirmEmailAfterRegistration();
        $user->email_register = null;
        $user->save();
    }

Implementing these habits into your coding practices will improve the quality, stability, and maintainability of your code.

Thanks for reading. Happy coding🙂

photo: Photo by Fausto García-Menéndez Unsplash