Most Recent Articles

Monitoring a PHP application

Thu, 28 May 2020 06:41:21 +0000

After months and months of development, our PHP application is finally live and running. What is going to happen next?

In an imaginary world, we sit and relax. We watch our application get popular and users flood in. And the application will just handle itself nicely because we have done all the testing. Right? Unfortunately, that is not the truth.

As users come in, errors start happening. No matter how many tests we have done. It is impossible to cover all the edge cases caused by real users.

Monitoring is the next step after development. It is the next thing we need to do after our application goes live.

In this tutorial, we discuss what things to monitor and their related services we have used.

Request monitoring

For each web request, we want to monitor its metrics such as its URI, request method, response time, status code, and so on.

From the metrics above, we can derive average response time, error rates, and so on.

Related services:

Datadog: https://www.datadoghq.com/
Amazon CloudWatch: https://aws.amazon.com/cloudwatch/

Exception monitoring

Exceptions from our codebase typically indicate some critical errors or edge cases in our system. We want to fix them before users get affected by their occurrence.

Related services:

Raygun: https://raygun.com/languages/php
Rollbar: https://rollbar.com/error-tracking/php/
Bugsnag: https://www.bugsnag.com/platforms/php

Log monitoring

When it comes to debugging and troubleshooting. Logs are essential. They contain information we need to fix errors and trace user behaviors.

Related service:

Loggly: https://www.loggly.com/
Papertrailapp: https://papertrailapp.com/

Dependencies monitoring

Modern PHP applications use external services(dependencies) such as MySQL, Elasticsearch, Redis, and so on. We need to monitor their performance to ensure the whole application's health.

Related tool:

Solarwinds: https://www.solarwinds.com/server-application-monitor/use-cases/mysql-monitor

End

What other information do you monitor and what tools do you use? Please leave a comment to let us know.

Server testing using curl

Thu, 28 May 2020 06:39:07 +0000

Project curl is a command-line tool that is used to do Internet transfers for resources specified as URLs using Internet protocols. You can read more about its history at https://ec.haxx.se/.

In this tutorial, we learn about using curl to do some simple server testing.

Examine response header

To verify if a proxy server cache is working, we can check the response's header "x-proxy-cache" value.

Examine response header using curl:

curl -I https://yoursite.com

Output:

Show response time

Response time is a simple yet straightforward metric to benchmark when optimizing our site.

To check response time using curl:

curl -s -w "%{time_total}\n" -o null https://yoursite.com

Options: + -s: run it in silent mode. Do not show progress info. + -w: format the output string using a placeholder. + -o: write the output to a file. Here we discard it by writing to null.

Send request header

When we need to send "no-cache" request to the header to test the proxy cache server. We can do so via curl too.

Send request header using curl:

Output:

End

We hope this simple tutorial helped you with your development.

The 3 rules of thumb to make your PHP application horizontal scale ready

Sun, 26 Apr 2020 08:13:45 +0000

In simple terms, to horizontally scale a PHP application means adding more servers instead of upgrading the existing servers.

However, to technically achieve that, your PHP application must be ready for the scale. In this article, we share 3 rules of thumb to make your PHP application ready for a horizontal scale.

Table Of Content

Remote database connection
Centralised file storage
Centralized session storage
The end

Remote database connection

When the database server is sitting independently, we do not have to worry about breaking our database while upgrading our web servers. Hence our PHP application must allow remote database connection.

It is recommended to use PDO when working with a database in PHP. And PDO supports remote database connection out of the box.

Centralised file storage

File uploads are commonly stored in a web server, however, this can cause a major issue when scaling web servers horizontally, since common approaching is to remove the old server and migrate to a new server.

So files must be stored in a centralized location. There are cloud storage services such as Amazon S3, Azure Storage, and Google Storage. All of them are a good fit for centralized file storage.

Centralized session storage

Almost every PHP application involves user authentication and most of the authentication in PHP is using session storge.

In PHP, We use the file as session storage by default. It is out of the box and it is super handy to pick up, we almost have to do nothing. However, it comes with a huge trade-off. When you migrate a web server to a new one, you lose all your users' sessions instantly.

To scale PHP application horizontally in peace, your session storage must be centralized. Cloud services such as Amazon DynmoDB and Amazon ElastiCache can be used as centralized session storage.

The end

We hope you find this article tutorial and make your PHP application horizontal scale ready!

Types of caching in a PHP web application

Sun, 26 Apr 2020 08:08:46 +0000

As a web developer, you must have heard the term "cache" in various situations. To help you fully understand what cache means, we wrote this article.

Table Of Content

OpCode Cache
Application Cache
HTTP Cache
Proxy Cache
End

OpCode Cache

When running a PHP script. The interpreter will parse the script into a series of operation codes, commonly known as "opcodes".

By caching the opcode in memory, we can gain significant performance improvement. This is known as opCode cache.

There is a list of well-know opCode cache engines and they are:

Zend OpCache
APC User Cache
Alternative PHP Cache
Xcache

By default, PHP ships with Zend OpCache.

Application Cache

When building an application, we can utilize some cache strategies to avoid slow response:

Store data that is not changed often in a cache.
Store time-consuming computed data in a cache.

Above are known as application cache.

When implementing the application cache, we have a lot of options in where to store the cache values. Following solutions are typically used to store the cache values:

Redis
Memcached
Database
File system

HTTP Cache

Most of our PHP applications are built for the web and accessed by a browser. The browser interacts with our application via HTTP protocol.

By utilizing the HTTP cache headers, a browser stores the response locally in its cache, this saves it from requesting the same data again via the network. This is known as HTTP cache.

Commonly used HTTP Cache headers are:

Cache-control
Pragma
Expires
Etag
Last-Modified

Proxy Cache

OpCode cache, application cache, and HTTP cache are great to help with application speed improvement. However, all the requests still go through the webserver. When the concurrency of the application is high, the web server may have a difficult time handling the requests.

By placing a proxy server in front of the webserver, we can not only significantly reduce the web server's load, but also we can improve the speed greatly because proxy server stores the cached response inside its memory.

The strategy above is known as a proxy cache.

Well-known proxy cache servers are:

Nginx
Squid
Varnish

End

We hope you have understood different cache means through this article.

Setup CakePHP 3 in a subdirectory using Nginx

Fri, 03 Apr 2020 02:59:34 +0000

When placing a CakePHP 3 project to a subdirectory, it will not work out of the box. Some specific Nginx setups are required for it to work.

For demonstration purposes, suppose we want to place a CakePHP 3 project to a subdirectory called demo.

Table Of Content

Serving static files
Serving PHP content
The End

Serving static files

Static files are served directly from the webroot folder, so the Nginx configuration blocks looks like something below:

Serving PHP content

Other requests will be directed to index.php file which leads to the CakePHP's router:

The End

In this tutorial, we demonstrate how to set up a CakePHP 3 in a subdirectory using Nginx. Hope you find this technique useful.

Redis caching engine for CakePHP 3

Fri, 03 Apr 2020 02:56:25 +0000

CakePHP provides various options as an application's caching engine out of the box. CakePHP's documentation is detailed and provides most of the answers we need. But it lacks the information of setting up Redis server itself in a server.

In this tutorial, we will show you how to setup Redis server in a ubuntu 16.04 machine.

Table Of Content

Update APT package list
Install Redis
Install PHP Redis extension
Connect CakePHP to Redis
The End

Update APT package list

Update the APT package list by running:

Install Redis

Install Redis server on Ubuntu:

Install PHP Redis extension

Connect CakePHP to Redis

Now we have Redis running and the PHP extension is ready. We can connect our CakePHP application to the Redis server by providing the configuration setting at https://book.cakephp.org/3.0/en/core-libraries/caching.html#redisengine-options.

End

Redis is an in-memory cache engine, so it is blazing fast. Hope you find this tutorial helpful.

Benefits of using value objects

Mon, 02 Mar 2020 07:33:31 +0000

The value object is a term crafted from Domain-Driven Design book. According to Wikipedia, a value object is a small object that represents a simple entity whose equality is not based on identity.

Money is a combination of a number and a currency. A period is a combination of a start time and end time. Both concepts are perfect candidates for value objects.

In this article, we share some benefits of using value objects.

Built-in validation

A value object is always valid since its existence. Which means, to guard its validity, we have to handle the validation from its constructor.

Safe usage

A value object is immutable, which means alter its attribute, it will return a brand new copy of itself. We never have to worry about changing a value object by reference.

The end

The concept of value objects is very helpful. It can improve our object-oriented design a lot, so we can write easy-to-maintain codebase.

Benefits of using application service classes

Mon, 02 Mar 2020 07:31:03 +0000

In today's tutorial, we share an architect pattern called service class.

Definition of a service class

Writing clean and reusable code is not easy, we learn different patterns to achieve that. The MVC(Model-view-controller) pattern is probably the first architect pattern you got to know.

Stage 1: fat controller

It is very convenient to write all the business logic inside the controller, that seems like the natural choice when we first using MVC. At this stage, our controllers are very big and it consists of most of our domain business.

Stage 2: fat model

At this stage, we learn about TDD (test-driven development), it is absolutely the way to go. TDD does not only help us think before coding but also improves the overall project quality because we can now do refactoring!

However, it is pain in the ass to write unit tests for controllers. Because controller tests are basic end-to-end tests, we need to prepare data seeds, send HTTP requests and assert against the database results. These unit tests are time-consuming to write and slow to run.

Therefore, we move our business logic to model and start writing fat models.

Stage 3: service class

When the business logic only involves one model, it is easy to decide where to place the code. When it involves multiple models, the struggle begins.

For instance, a user purchases a ticket. Shall we place the fat logic inside the user model, the ticket model or the order model? Whenever this happens, we tend to struggle with the best solution.

This is when a service class comes to the play. Service class fits best to how we model the process:

Why use a service class

So we have seen the benefits of using a service class:

Easy to test similar to the fat model
Easy to model the business logic

Debug MySQL slow query

Sun, 02 Feb 2020 02:04:43 +0000

Slow MySQL query is a common cause of the application bottleneck. Slow queries are often discovered when a large dataset is added, which means they often happen in a production environment.

In this tutorial, we will learn how to debug slow MySQL queries.

Table Of Content

Enable MySQL slow query log
Clean up
More useful techniques
The end

Enable MySQL slow query log

Select the database you are trying to debug:

Enable slow query log:

Set the query running time threshold in seconds:

We can verify if the settings are done properly by running the command below:

The command above would show the log file path as well.

Test if the logging is working:

The log file should show a log belongs to the query above.

Now we have successfully enabled MySQL slow query log and we can now investigate and debug which query is causing the problem.

Clean up

When we have identified the problem, always remember to turn off the slow query log since it would add additional time to each query we run.

We can run the command below to turn it off:

Verify if it is turned off successfully:

More useful techniques

We also introduce some useful MySQL commands you may find useful.

Running query without cache by adding the keyword SQLNOCACHE:

The end

We hope you find this tutorial helpful.

How to search JSON data in MySQL

Sun, 02 Feb 2020 01:58:19 +0000

As of MySQL 5.7.8, MySQL supports a native JSON data type. In this tutorial, we will learn how to search for JSON data in MySQL.

Table Of Content

Sample data
Select a JSON field
Remove double quotes from selection result
Use dot notation in the selection path
Use the selected field as a condition
The end

Sample data

For demonstration purpose, suppose we have created a database table with the following data:

The column "data" is a JSON type. It currently holds a user JSON data with three fields:

id
name
mobile_no.

Select a JSON field

To select a particular field from JSON, we can use the JSON_EXTRACT function. For example, to select the name field:

This will output

Remove double quotes from selection result

You may have noticed double quotes in the previous sample. To remove the double quotes from the selection result, we can use JSON_UNQUOTE function:

This will output

Betty

Use dot notation in the selection path

In our sample data, it contains a JSON field called "mobile_no.", pay attention to the ending dot notation. You cannot use the dot notation directly in the selection field, because it will be treated as a denominator.

To use dot notation in the selection path, we can wrap it with double quotes:

This will output:

Use the selected field as a condition

It is common to use the selected JSON field as a condition. To do this, we can use the HAVING clause:

The end

We hope you find this tutorial helpful!

PHP Generator - reading file content

Tue, 07 Jan 2020 06:56:29 +0000

In PHP, to fetch content from a file, a common implementation is to loop its content and store them in a temporary variable. In today's tutorial, we want to introduce a solution by using the generator.

Read file using a loop

Normal we will load the file content to memory and read its content using a loop.

Read file using a generator

We can do the same using a generator function. Inside the function, we open the file and yield its content line by line:

Generator

As we can see, when using a generator, we have greatly reduced memory usage.

The reason is that when we yield results from a generator function, it saves its current state until it is called next time.

The end

Hopefully this simple tutorial helped you with your development.

PHP Generator - processing dataset

Tue, 07 Jan 2020 06:49:42 +0000

In PHP, to work with a dataset, the natural thing to do is to use a loop, store the result to an array and return it. In today's tutorial, we introduce a solution by using a generator.

Return in a loop

For demonstration purposes, imagine we need a function that returns a series of numbers from one to twenty. Typically we will solve it this way:

However, storing a large set of data into an array is memory intensive.

We can do a simple benchmark by checking the memory used at run time:

The output is:

As we can see the memory used while looping the result set is about 1368 byte.

Yield in a loop

We can solve the problem using a generator, and the only difference is that we use yield instead of return:

And let's run the benchmark again, the output is shown s as below:

As we can see, we are using far less memory when using a generator.

The end

There is one pitfall when using a generator though, we need to be aware, we are trading the speed with the memory utilization. It is like everything else in programming, there is no right solution but trade-offs.

How to Build a PHP Booking Calendar with MySQL

Thu, 17 Oct 2019 14:30:58 +0000

In this tutorial, we will build a nice booking calendar using PHP and MySQL. Booking calendars are very common applications, you will learn how to write PHP code that separates business logic from presentation through this tutorial.

After this tutorial, you should be able to build a working booking calendar as shown below:

Table Of Content

Prepare the database
Build a Booking class
Build a Calendar class
Putting it Together
Final and Source Code

1. Prepare the database

All the booking dates will be stored inside the MySQL database. Let's design a simple database table.

Run the SQL statement below from your database console to create a table: bookings.

CREATE TABLE bookings ( 
    id int auto_increment, 
    booking_date DATE, 
    constraint pk_example primary key (id) 
);

All bookings will be stored inside the table above, and each booked date is saved inside booking_date column.

2. Build a Booking class

In this section, we will build a PHP class that interacts with the database. It is capable of listing all the bookings, inserting a booking as well as deleting a booking.

Create a php file Booking.php and place the code below:

<?php

class Booking
{

    private $dbh;

    private $bookingsTableName = 'bookings';

    /**
     * Booking constructor.
     * @param string $database
     * @param string $host
     * @param string $databaseUsername
     * @param string $databaseUserPassword
     */
    public function __construct($database, $host, $databaseUsername, $databaseUserPassword)
    {
        try {

            $this->dbh =
                new PDO(sprintf('mysql:host=%s;dbname=%s', $host, $database),
                    $databaseUsername,
                    $databaseUserPassword
                );

        } catch (PDOException $e) {
            die($e->getMessage());
        }
    }

The code above will connect to a database when it is instantiated using PDO. When working with a database in PHP, we should always use PDO as it provides great security and friendly API.

Create a function index() inside the Booking class:

public function index()
{
    $statement = $this->dbh->query('SELECT * FROM ' . $this->bookingsTableName);
    return $statement->fetchAll(PDO::FETCH_ASSOC);
}

This function will list out all the booking records and return them as an associated array.

Create a function add() inside the Booking class:

public function add(DateTimeImmutable $bookingDate)
{
    $statement = $this->dbh->prepare(
        'INSERT INTO ' . $this->bookingsTableName . ' (booking_date) VALUES (:bookingDate)'
    );

    if (false === $statement) {
        throw new Exception('Invalid prepare statement');
    }

    if (false === $statement->execute([
            ':bookingDate' => $bookingDate->format('Y-m-d'),
        ])) {
        throw new Exception(implode(' ', $statement->errorInfo()));
    }
}

This function inserts a booking into the bookings table. We are using PDO's prepare statements to do the insertion, which provides auto escaping.

Create a function delete() inside the Booking class:

public function delete($id)
{
    $statement = $this->dbh->prepare(
        'DELETE from ' . $this->bookingsTableName . ' WHERE id = :id'
    );
    if (false === $statement) {
        throw new Exception('Invalid prepare statement');
    }
    if (false === $statement->execute([':id' => $id])) {
        throw new Exception(implode(' ', $statement->errorInfo()));
    }
}

This function deletes a booking from the bookings table by taking the primary key.

That is all for Booking class, and the complete Booking.php is shown as below:

<?php


class Booking
{

    private $dbh;

    private $bookingsTableName = 'bookings';

    /**
     * Booking constructor.
     * @param string $database
     * @param string $host
     * @param string $databaseUsername
     * @param string $databaseUserPassword
     */
    public function __construct($database, $host, $databaseUsername, $databaseUserPassword)
    {
        try {

            $this->dbh =
                new PDO(sprintf('mysql:host=%s;dbname=%s', $host, $database),
                    $databaseUsername,
                    $databaseUserPassword
                );

        } catch (PDOException $e) {
            die($e->getMessage());
        }
    }

    public function index()
    {
        $statement = $this->dbh->query('SELECT * FROM ' . $this->bookingsTableName);
        return $statement->fetchAll(PDO::FETCH_ASSOC);
    }

    public function add(DateTimeImmutable $bookingDate)
    {
        $statement = $this->dbh->prepare(
            'INSERT INTO ' . $this->bookingsTableName . ' (booking_date) VALUES (:bookingDate)'
        );

        if (false === $statement) {
            throw new Exception('Invalid prepare statement');
        }

        if (false === $statement->execute([
                ':bookingDate' => $bookingDate->format('Y-m-d'),
            ])) {
            throw new Exception(implode(' ', $statement->errorInfo()));
        }
    }

    public function delete($id)
    {
        $statement = $this->dbh->prepare(
            'DELETE from ' . $this->bookingsTableName . ' WHERE id = :id'
        );
        if (false === $statement) {
            throw new Exception('Invalid prepare statement');
        }
        if (false === $statement->execute([':id' => $id])) {
            throw new Exception(implode(' ', $statement->errorInfo()));
        }
    }

}

3. Build a Calendar class

In one of our previous tutorials, we have built a powerful calendar class that comes with hooks. In this tutorial, we will utilize it to accomplish our goal.

Create a file Calendar.php, copy and paste the following code:

<?php

class Calendar
{

    /**
     * Constructor
     */
    public function __construct()
    {
        $this->naviHref = htmlentities($_SERVER['PHP_SELF']);
    }

    /********************* PROPERTY ********************/
    public $cellContent = '';
    protected $observers = array();

    private $dayLabels = array("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun");
    private $currentYear = 0;
    private $currentMonth = 0;
    private $currentDay = 0;
    private $currentDate = null;
    private $daysInMonth = 0;
    private $sundayFirst = true;
    private $naviHref = null;

    /********************* PUBLIC **********************/
    /* @return void
     * @access public
     */
    public function attachObserver($type, $observer)
    {
        $this->observers[$type][] = $observer;
    }

    /*
    *
    * @return void
    * @access public
    */
    public function notifyObserver($type)
    {
        if (isset($this->observers[$type])) {
            foreach ($this->observers[$type] as $observer) {
                $observer->update($this);
            }
        }
    }

    public function getCurrentDate()
    {
        return $this->currentDate;
    }

    /**
     * Set week labels' order.
     * When it is set to false,
     * monday will be listed as the first day.
     *
     * @param boolean
     * @return              void
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              public
     */
    public function setSundayFirst($bool = true)
    {
        $this->sundayFirst = $bool;
    }

    /**
     * print out the calendar
     *
     * @param string
     * @param string
     * @param array
     * @return              string
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              public
     */
    public function show($month = null, $year = null, $attributes = false)
    {
        if (null == $year && isset($_GET['year'])) {
            $year = $_GET['year'];
        } else if (null == $year) {
            $year = date("Y", time());
        }

        if (null == $month && isset($_GET['month'])) {
            $month = $_GET['month'];
        } else if (null == $month) {
            $month = date("m", time());
        }

        $this->currentYear = $year;
        $this->currentMonth = $month;
        $this->daysInMonth = $this->_daysInMonth($month, $year);

        $content = '<div id="calendar">' .
            '<div class="box">' .
            $this->_createNavi() .
            '</div>' .
            '<div class="box-content">' .
            '<ul class="label">' . $this->_createLabels() . '</ul>';
        $content .= '<div class="clear"></div>';
        $content .= '<ul class="dates">';
        for ($i = 0; $i < $this->_weeksInMonth($month, $year); $i++) {
            for ($j = 1; $j <= 7; $j++) {
                $content .= $this->_showDay($i * 7 + $j, $attributes);
            }
        }
        $content .= '</ul>';
        $content .= '<div class="clear"></div>';
        $content .= '</div>';
        $content .= '</div>';
        return $content;
    }

    /********************* PRIVATE **********************/
    /**
     * create the li element for ul
     *
     * @param string
     * @param array
     * @return              string
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              private
     */
    private function _showDay($cellNumber, $attributes = false)
    {
        if ($this->currentDay == 0) {
            //1 (for Monday) through 7 (for Sunday)
            $firstDayOfTheWeek = date('N', strtotime($this->currentYear . '-' . $this->currentMonth . '-01'));
            if ($this->sundayFirst) {
                if ($firstDayOfTheWeek == 7) {
                    $firstDayOfTheWeek = 1;
                } else {
                    $firstDayOfTheWeek++;
                }
            }
            if (intval($cellNumber) == intval($firstDayOfTheWeek)) {
                $this->currentDay = 1;
            }
        }

        if (($this->currentDay != 0) && ($this->currentDay <= $this->daysInMonth)) {
            $this->currentDate = date('Y-m-d', strtotime($this->currentYear . '-' . $this->currentMonth . '-' . ($this->currentDay)));
            $cellContent = $this->_createCellContent($attributes);
            $this->currentDay++;
        } else {
            $this->currentDate = null;
            $cellContent = null;
        }


        return '<li id="li-' . $this->currentDate . '" class="' . ($cellNumber % 7 == 1 ? ' start ' : ($cellNumber % 7 == 0 ? ' end ' : ' ')) .
            ($cellContent == null ? 'mask' : '') . '">' . $cellContent . '</li>';
    }

    /**
     * create navigation
     *
     * @return              string
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              private
     */
    private function _createNavi()
    {
        $nextMonth = $this->currentMonth == 12 ? 1 : intval($this->currentMonth) + 1;
        $nextYear = $this->currentMonth == 12 ? intval($this->currentYear) + 1 : $this->currentYear;

        $preMonth = $this->currentMonth == 1 ? 12 : intval($this->currentMonth) - 1;
        $preYear = $this->currentMonth == 1 ? intval($this->currentYear) - 1 : $this->currentYear;

        return
            '<div class="header">' .
            '<a class="prev" href="' . $this->naviHref . '?month=' . sprintf('%02d', $preMonth) . '&year=' . $preYear . '">Prev</a>' .
            '<span class="title">' . date('Y M', strtotime($this->currentYear . '-' . $this->currentMonth . '-1')) . '</span>' .
            '<a class="next" href="' . $this->naviHref . '?month=' . sprintf("%02d", $nextMonth) . '&year=' . $nextYear . '">Next</a>' .
            '</div>';
    }

    /**
     * create calendar week labels
     *
     * @return              string
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              private
     */
    private function _createLabels()
    {
        if ($this->sundayFirst) {
            $temp = $this->dayLabels[0];
            for ($i = 1; $i < sizeof($this->dayLabels); $i++) {
                $tmp = $this->dayLabels[$i];
                $this->dayLabels[$i] = $temp;
                $temp = $tmp;
            }
            $this->dayLabels[0] = $temp;
        }


        $content = '';
        foreach ($this->dayLabels as $index => $label) {
            $content .= '<li class="' . ($label == 6 ? 'end title' : 'start title') . ' title">' . $label . '</li>';
        }

        return $content;
    }

    /**
     * create content for li element
     *
     * @param array
     * @return              string
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              private
     */
    private function _createCellContent($setting = false)
    {
        $this->cellContent = '';

        $this->cellContent = $this->currentDay;

        //observer
        $this->notifyObserver('showCell');

        return $this->cellContent;
    }

    /**
     * calculate number of weeks in a particular month
     *
     * @param number
     * @param number
     * @return              number
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              private
     */
    private function _weeksInMonth($month = null, $year = null)
    {
        if (null == ($year))
            $year = date("Y", time());

        if (null == ($month))
            $month = date("m", time());

        // find number of weeks in this month
        $daysInMonths = $this->_daysInMonth($month, $year);

        $numOfweeks = ($daysInMonths % 7 == 0 ? 0 : 1) + intval($daysInMonths / 7);
        $monthEndingDay = date('N', strtotime($year . '-' . $month . '-' . $daysInMonths));
        $monthStartDay = date('N', strtotime($year . '-' . $month . '-01'));
        $monthEndingDay == 7 ? $monthEndingDay = 0 : '';
        $monthStartDay == 7 ? $monthStartDay = 0 : '';

        if ($monthEndingDay < $monthStartDay) {
            $numOfweeks++;
        }
        return $numOfweeks;

    }

    /**
     * calculate number of days in a particular month
     *
     * @param number
     * @param number
     * @return              number
     * @author              The-Di-Lab <thedilab@gmail.com>
     * @access              private
     */
    private function _daysInMonth($month = null, $year = null)
    {
        if (null == ($year))
            $year = date("Y", time());

        if (null == ($month))
            $month = date("m", time());

        return date('t', strtotime($year . '-' . $month . '-01'));
    }

}

We are not going to explore the details of this class, since we have already covered it at https://www.startutorial.com/articles/view/php-calendar-class-with-hooks, feel free to read more there.

Create a file BookableCell.php, copy and paste the following code:

<?php


class BookableCell
{
    /**
     * @var Booking
     */
    private $booking;

    private $currentURL;

    /**
     * BookableCell constructor.
     * @param $booking
     */
    public function __construct(Booking $booking)
    {
        $this->booking = $booking;
        $this->currentURL = htmlentities($_SERVER['REQUEST_URI']);
    }

    public function update(Calendar $cal)
    {
        if ($this->isDateBooked($cal->getCurrentDate())) {
            return $cal->cellContent =
                $this->bookedCell($cal->getCurrentDate());
        }

        if (!$this->isDateBooked($cal->getCurrentDate())) {
            return $cal->cellContent =
                $this->openCell($cal->getCurrentDate());
        }
    }

    public function routeActions()
    {
        if (isset($_POST['delete'])) {
            $this->deleteBooking($_POST['id']);
        }

        if (isset($_POST['add'])) {
            $this->addBooking($_POST['date']);
        }
    }

    private function openCell($date)
    {
        return '<div class="open">' . $this->bookingForm($date) . '</div>';
    }

    private function bookedCell($date)
    {
        return '<div class="booked">' . $this->deleteForm($this->bookingId($date)) . '</div>';
    }

    private function isDateBooked($date)
    {
        return in_array($date, $this->bookedDates());
    }

    private function bookedDates()
    {
        return array_map(function ($record) {
            return $record['booking_date'];
        }, $this->booking->index());
    }

    private function bookingId($date)
    {
        $booking = array_filter($this->booking->index(), function ($record) use ($date) {
            return $record['booking_date'] == $date;
        });

        $result = array_shift($booking);

        return $result['id'];
    }

    private function deleteBooking($id)
    {
        $this->booking->delete($id);
    }

    private function addBooking($date)
    {
        $date = new DateTimeImmutable($date);
        $this->booking->add($date);
    }

    private function bookingForm($date)
    {
        return
            '<form  method="post" action="' . $this->currentURL . '">' .
            '<input type="hidden" name="add" />' .
            '<input type="hidden" name="date" value="' . $date . '" />' .
            '<input class="submit" type="submit" value="Book" />' .
            '</form>';
    }

    private function deleteForm($id)
    {
        return
            '<form onsubmit="return confirm(\'Are you sure to cancel?\');" method="post" action="' . $this->currentURL . '">' .
            '<input type="hidden" name="delete" />' .
            '<input type="hidden" name="id" value="' . $id . '" />' .
            '<input class="submit" type="submit" value="Delete" />' .
            '</form>';
    }
}

Two major APIs of this class we should take a look at:

Function update(Calendar $cal): this function is called when the Calendar class renders each cell. We render different content for the cell depends on its booking status. If this date is booked, we will render a cell with a cancellation link, otherwise, we render a booking link.
Function routeActions(): this is a very simple routing function. It checks the $_POST parameter and decides whether to delete a booking or add a booking.

The BookableCell connects to the Calendar class via a hook, we call BookableCell a plugin for Calendar.

4. Putting it Together

Now it is time to put everything together and present our booking calendar to the world.

Create a file index.php with the following code:

<html>
<head>
    <link href="calendar.css" type="text/css" rel="stylesheet"/>
</head>
<body>
<?php
include 'Calendar.php';
include 'Booking.php';
include 'BookableCell.php';


$booking = new Booking(
    'tutorial',
    'localhost',
    'root',
    ''
);

$bookableCell = new BookableCell($booking);

$calendar = new Calendar();

$calendar->attachObserver('showCell', $bookableCell);

$bookableCell->routeActions();

echo $calendar->show();
?>
</body>
</html>

Let's go through the code above from top to bottom.

Instantiate a BookableCell plugin object.
Instantiate a Calendar object.
Hook the BookableCell object into Calendar object.
Call the BookableCell object's routing function.
Render the calendar.
Last missing puzzle is the css file, create a file calendar.css, copy and paste the code below:

/*******************************Calendar Top Navigation*********************************/
body {
    font-family: "Arial";
}

div#calendar {
    margin: 0px auto;
    padding: 0px;
    width: 602px;
}

div#calendar div.box {
    position: relative;
    top: 0px;
    left: 0px;
    width: 100%;
    height: 40px;
    background-color: #3FA7D6;
}

div#calendar div.header {
    line-height: 40px;
    vertical-align: middle;
    position: absolute;
    left: 11px;
    top: 0px;
    width: 582px;
    height: 40px;
    text-align: center;
}

div#calendar div.header a.prev, div#calendar div.header a.next {
    position: absolute;
    top: 0px;
    height: 17px;
    display: block;
    cursor: pointer;
    text-decoration: none;
    color: #FFF;
}

div#calendar div.header span.title {
    color: #FFF;
    font-size: 18px;
}

div#calendar div.header a.prev {
    left: 0px;
}

div#calendar div.header a.next {
    right: 0px;
}

/*******************************Calendar Content Cells*********************************/
div#calendar div.box-content {
    border: 1px solid #3FA7D6;
    border-top: none;
}

div#calendar ul.label {
    float: left;
    margin: 0px;
    padding: 0px;
    margin-top: 5px;
    margin-left: 5px;
}

div#calendar ul.label li {
    margin: 0px;
    padding: 0px;
    margin-right: 5px;
    float: left;
    list-style-type: none;
    width: 80px;
    height: 40px;
    line-height: 40px;
    vertical-align: middle;
    text-align: center;
    color: #000;
    font-size: 15px;
    background-color: transparent;
}

div#calendar ul.dates {
    float: left;
    margin: 0px;
    padding: 0px;
    margin-left: 5px;
    margin-bottom: 5px;
}

/** overall width = width+padding-right**/
div#calendar ul.dates li {
    margin: 0px;
    padding: 0px;
    margin-right: 5px;
    margin-top: 5px;
    line-height: 80px;
    vertical-align: middle;
    float: left;
    list-style-type: none;
    width: 80px;
    height: 80px;
    font-size: 25px;
    background-color: #FFF;
    color: #000;
    text-align: center;
    position: relative;
}

:focus {
    outline: none;
}

div.clear {
    clear: both;
}

li div {
    display: flex;
}

li div form {
    display: inline;
    align-self: center;
    margin: 0;
    position: absolute;
    bottom: 2px;
}

div.open {
    background: #59CD90;
    width: 100%;
    height: 100%;
    display: flex;
    justify-content: center;
    flex-direction: column;
    text-align: center;
}

div.booked {
    background: #D36135;
    width: 100%;
    height: 100%;
    display: flex;
    justify-content: center;
    flex-direction: column;
    text-align: center;
    line-height: inherit;
}

.submit {
    box-shadow:inset 0px 1px 0px 0px #ffffff;
    background:linear-gradient(to bottom, #ffffff 5%, #f6f6f6 100%);
    background-color:#ffffff;
    border-radius:3px;
    border:1px solid #dcdcdc;
    display:inline-block;
    cursor:pointer;
    color:#666666;
    font-size:10px;
    font-weight:bold;
    padding:3px 12px;
    text-decoration:none;
    text-shadow:0px 1px 0px #ffffff;
}

.submit:hover {
    background:linear-gradient(to bottom, #f6f6f6 5%, #ffffff 100%);
    background-color:#f6f6f6;
}
.submit:active {
    position:relative;
    top:1px;
}

5. Final and Source Code

If you have followed along correctly. Head over to index.php from your browser. You should see a beautiful PHP booking calendar as shown below:

If you follow along with the tutorials step by step, you will get all the source code in place. However, if you are feeling lazy or need to download the complete source code from us. You can do so by paying us a small fee. Your support will enable us to produce better and more in-depth tutorials.

Download Source Code ($9)

Modern PHP Developer - TDD

Mon, 05 Feb 2018 13:43:40 +0000

Table Of Content

PHPUnit
TDD by example
The end

If you have not heard of Test Driven Development(TDD), you should begin to familiarise yourself with it. Though PHP community is a bit late on TDD practice compared to other languages such as Ruby, once the benefits TDD were realized, it has become almost essential for a modern PHP developer.

TDD is a software development technique. The basic idea behind TDD is that, we create tests before we actually code any thing. Writing test against no code is more of a mindset shift than anything else. It is opposite of traditional coding habit, where we create code first, then manually run the unit to make sure it does what we intended manually. The benefits that TDD brings to us are enormous. At first it forces us to think about code design before we create any concrete code, then it allows us to refactor our code base without worrying about the side effect. It makes our code easy to maintain in the long run.

TDD consists of three phases: which are Red, Green and Refactor.

Red phase

In red phase, as the developer, we will plan out what the code will look like without actually writing it. This is to say, we will design our class or class methods, without implementing its details. Initially this phase is hard, it requires us to change our traditional habit of coding. But once we get used to this process, we will naturally adapt to it and realize that it helps us design better code. It is about changing our mindset, as we should focus on the input and output of the API, instead of the details of the code. The result of this phase is successful creation of red test.

Green phase

In green phase, it is all about writing the quickest piece of code to pass the tests. In this phase, we should not spend too much making the code clean or refactoring. Though we all want to write the most beautiful piece of code, that is not the task at hand in this phase. The result of this phase is green tests.

Refactor phase

In refactor phase, we focus on making the code clean. Since we have tests created above to guard bugs from side effects, we gain confidence for carrying out refactor. If by chance, a bug is introduced from refactoring, our tests will report it as soon as it appears. So the natural way of refactor is to run the test as soon as you have modified any code.

1. PHPUnit

TDD lets us test drive our development cycle. When practicing TDD in PHP, obviously we need to define the kind of test we will do. The most common test in TDD is Unit Test which tests the smallest testable parts of an application it considers a unit, which is typically a class method.

Now imagine writing unit tests manually and building an automated method to run them. It is definitely a lot of work. Fortunately, there are already unit testing frameworks out there for us to use. Among a number of unit testing frameworks, PHPUnit is the most popular one and it is widely used in the PHP community.

Getting started with PHPUnit

Installation

The easiest way to install PHPUnit is via Composer. Open up your terminal and in your project folder, simply run composer require phpunit/phpunit . By default, the bin file of PHPUnit will be placed into vendor/bin folder, so we can run vendor/bin/phpunit directly from our project's root folder.

Your first unit test

Time to create your first unit test! Before doing so, we need a class to test. Let's create a very simple class called Calculator and write a test for it.

Create a file with the name of Calculator.php and copy the code below to the file. This Calculator class only has an Add function. :

Create the test file CalculatorTest.php, and copy the code below to the file. We will explain each function in details.

Line 2: Includes class file Calculator.php. This is the class that we are going to test against, so make sure you include it.
Line 8: setUp() is called before each test runs. Keep in mind that it runs before each test, which means, if you have another test function, it too will run setUp() before.
Line 13: Similar to setUp() , tearDown() is called after each test finishes.
Line 18: testAdd() is the test function for add function. PHPUnit will recognize all functions prefixed with test as a test function and run them automatically. This function is actually very straightforward: we first call Calculator.add function to calculate the value of 1 plus 2. Then we check to see if it returns the correct value by using PHPUnit function assertEquals.

The last part of the task is to run PHPUnit and make sure it passes all tests. Navigate to the folder where you have created the test file and run the commands below from your terminal:

You should be able to see the successful message as below:

Data Provider

When to use data provider

When we write a function, we want to make sure it passes a series of edge cases. The same applies to tests. This means we will need to write multiple tests to test the same function using different sets of data. For instance, if we want to test our Calculator class using different data, without data provider, we would have multiple tests as shown below:

In this case, we can use data provider function in PHPUnit to avoid duplication in our tests.

How to use data provider

A data provider method returns a variety of arrays or an object that implements the Iterator interface. The test method will be called with the contents of the array as its arguments.

Some key points to keep in mind when using data provider are:

Data provider method must be public.
Data provider returns an array of a collection data.
Test method use annotation(@dataProvider) declares its data provider method.

Once we know the key points, it is actually quite straightforward to use data provider. First, we create a new public method, which returns an array of a collection data as arguments of the test method.Then, we add annotation to the test method to tell PHPUnit which method will provide arguments.

Add data provider to our first unit test

Let's modify our tests above using data provider.

Line 18: Add a data provider method. Take note that a data provider method must be declared as public.
Line 27: Use annotation to declare the test method's data provider method.

Now, run our test again and it should pass. As you can see, we have utilized data provider to avoid code duplication. Instead of writing three test methods for essentially the same method, we now have only one test method.

Test Double

When to use test double

As mentioned in the first part of this series. One of PHPUnit's powerful features is test double. It is very common in our code that a method of a class calls another class's method. In this case, there is a dependency between these two classes. In particular, the caller class has a dependency on the calling class, but as we already know from part 1, unit test should test the smallest unit of functionality. In this case, it should test only the caller function. To solve this problem, we can use test double to replace the calling class. Since a test double can be configured to return predefined results, we can focus on testing the caller function.

Types of test doubles

Test double is a generic term for objects we use, to replace real production ready objects. In our experience, it is very useful to categorize test doubles by their purpose. It not only makes it easy for us to understand the test case, but also make our code friendly to other parties.

Accordingly to Martin Fowler's post, there are five types of test double:

Dummy objects are passed around but never actually used. Usually they are just used to fill parameter lists.
Fake objects actually have working implementations, but usually take some shortcuts, which make them not suitable for production.
Stubs provide canned answers to calls made during the test, usually not responding at all to anything outside what's programmed in for the test.
Spies are stubs that also record some information based on how they were called. One form of this might be an email service that records how many messages it was sent. Mocks are pre-programmed with expectations that form a specification of the calls they are expected to receive. They can throw an exception if they receive a call they don't expect and are checked during verification to ensure they received all the calls they were expecting.

How to create test double

PHPUnit's method getMockBuilder can be used to create any similar user defined objects. Combining with its configurable interface, we can use it to create basically all five types of test doubles.

Add test double to our first unit test

It is meaningless to use test double in our calculator test case, since currently the Calculator class has no dependency on other classes, however, to demonstrate how to use test double in PHPUnit, we will create a stub Calculator class and test it.

Let's add a test case called testWithStub to our existing class:

getMockBuilder() method creates a stub similar to our Calculator object.
getMock() method returns the object.
expects() method tells the stub to be called any number of times.
method() method specifies which method it will be called.
will() method configures the return value of the stub.

We have introduced some basic usage of PHPUnit, which provides almost all the features we would need to create unit tests. You should always try to find more information from its official manual as you needed.

TDD by example

In this section, we will demonstrate the process behind TDD through a very simple example. You should concentrate on how the three phases of TDD are carried out in this example.

Suppose we are given a task of building a price calculator for our e-commerce system. The class we are going to develop will be PriceCalculator. Let's first setup the project's folder and file structure as well as its dependencies.

As usual, we will use Composer as our package manager and PSR-4 as our code standard. The only third party dependency is PHPUnit. To set things up, we will create a folder src for placing our source files, and a folder tests for placing test files. We will also create src/PriceCalculator.php and tests/PriceCalculatorTest.php respectively. Finally, we will create a composer.json file as below:

This file tells Composer to download PHPUnit and tells autoloader that our source code follows PRS-4 standard.

By running command composer install, we should end up with a folder structure as below:

The final piece we need for the setup is a phpunit.xml file to config PHPUnit. Let's create it as the folder root.

Our final folder structure should be as shown below:

Red phase

At this phase we will plan how our API will look like and create failing test. In this example, the required API method is very simple. We just want a method that accepts an array as its parameter and calculate the total price. We will name this method total .

Let's create some tests in tests/PriceCalculatorTest.php file before we write any source code.

We have created three tests for PriceCalculator:

public function object_can_created() : This test assures the object can be instantiated. Some may argue that this is unnecessary, but from a TDD point of view, we like to have such a simple test. When this test is passed, we can naturally move on to ones testing its real behaviour.
public function should_sum_price() : This method tests whether total method does its job as described.
public function empty_items_should_return_zero() : This method tests an edge case, where there is no item in the order. In such case, total method should return zero.

Now if we run vendor/bin/phpunit from terminal, we should get error as expected as below:

Green phase

The task of this phase is to make the failing tests above pass with the easiest but not necessarily the best code. The ultimate goal of this phase is the green message.

The implementation is fairly easy. All we need to do is to sum up the value with a foreach loop.

Now if we run vendor/bin/phpunit from terminal, we should get a green message as below:

Refactoring phase

This is the final phase of TDD, which we believe is the most valuable part of TDD. In this phase, we will take a look at the code we have written previously, and think of ways to make it cleaner and better.

We are using a foreach loop inside total method. It loops through $items array and returns the sum of the each individual element. This is actually a perfect use case of array_reduce method. Function array_reduce iteratively reduces the array to a single value using a callback function. Let's refactor our code by replacing foreach loop with array_reduce .

If we run our tests again and they all still pass, we are good to go. Because we need to run the tests constantly to make sure refactoring does not break anything, it is important to keep our code fast.

We have cleaned up our code from five lines to two lines. There is no more temporary variable. The method has become easier to debug. There might not be apparent benefits for doing so in this example, but imagine this in a large scale project, even cleaning up one line of code could potentially make development easier.

This is the end of TDD. To emphasize again, the spirit of TDD is to let tests drive our development. Using PHPUnit in a project does not necessarily make it a TDD driven project. It is the three phases processes involved in the development that make it TDD.

The end

Hopefully this simple tutorial helped you with your development.
If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
If you have questions or find our mistakes in above tutorial, do leave a comment below to let us know.

Modern PHP Developer - Exception

Mon, 05 Feb 2018 13:42:42 +0000

Since PHP 5 was released, Exception is added to PHP as an object-oriented programming language feature. By definition, an Exception is an exceptional event during program execution. In PHP, an Exception is simply an object (an instance of Exception class). When an exception occurs, PHP will halt current execution flow and look for an handler, and then it will continue its execution by the handler's code. If no handler is found, a PHP Fatal Error will be issued with an "Uncaught Exception ..." message and the program terminates.

Table Of Content

When to use Exception
How to use Exception
Create your first custom exception 5.3
SPL exceptions
RuntimeException
The end

1. When to use Exception

Exception is good for handling exceptional cases of your program, however it is not the solution for all error cases. Sometimes it is perfectly fine to return a boolean FALSE. Sometimes you are much better off throwing exceptions instead of returning weird error codes. Therefore it is very important to understand when to use Exception and when not to.

By now, we all know an exception should be thrown when an exceptional situations occurs. But if exceptional situation seems rather arbitrary, what qualifies as an "exceptional" situation?

Here is a good rule of thumb: since exceptional situations don't happen frequently, if you supply correct values to your function and remove the thrown exception, if the function then fails, the exception is used incorrectly.

Let's take a look at some concrete examples:

If you create a function to save a user's input to database, when a database connection fails, an exception should be thrown.
For the same function, you create a validator for checking a user's input. When an invalid value is supplied, you should not throw an exception. Invalid value is a rather frequent case for a validator class.

A good use case of Exception

Here we have an example of returning error codes to indicate error cases:

Client code might be something similar to the below:

Here we can spot a couple of problems with error codes:

Error codes do not contain error related information by themselves, which make them very hard to maintain.
Error codes result in number of if/else statements in client's code, depending on how many there are. (Conditional statements should be eliminated as much as possible, in order to make our code clean).

Let's refactor the code to use exceptions:

And client code can be refactored as:

As we can see, by using exceptions, the second code sample conveys messages about the errors much more clearly. Beyond that, in the client code, by eliminating conditional statements, the code become self-explanatory.

A case of misusing Exception

One common way of misusing exceptions is using them to control the flow of application logic. It is not only confusing, but also slows down your code. To emphasize again, exception is used to raise exceptional situations.

Below is one example of of misusing exceptions, which is discouraged.

The function register() uses exceptions to delegate account creation tasks. This is obviously against rules of exceptions. Though PHP does not stop you, you should religiously forbid yourself from doing this.

2. How to use Exception

Four key words are associated with Exception. They are: throw , try , catch and finally . An exception object is thrown( throw ) in a method when an exceptional event happens. Clients that call the method will normally place the method in a try block and catch it with some handling code. A finally block ensures the code inside the block will always be executed.

Throw

All exceptions in PHP are a class or subclass of Exception. It takes three optional parameters in its constructor.

$message: The exception message. This message provides some human readable information. And normally supply this parameter when instantiating an exception.
$code: It is useful for identifying types of exceptions that belong to the same class.
$previous: The exception before current one. This is normally used when we want to re- throw an exception in a catch block.

Below is an example of PHP syntax to throw an exception

The keyword here is throw . Note that we first need to initiate an exception object.

Catch

When we need to catch exceptions, we place the callee in a try-catch block as below:

The catch block is where we place our handler code. Detailed exception handling implementation varies depending on application design. For example, we could try to recover the exception as much as we can, and if that is not possible, we could redirect users to a customer support page. If we leave it unhanded, PHP will eventually terminate the program and leave users with a page of meaningless error message, which is discouraged.

Exception bubble effect

If you are using some kind of frameworks, exceptions are likely handled even if you never actually create any handler for them. That is because exceptions bubble up, and your framework will eventually handle them. A simple example of exception bubble effect is:

In the sample code, when methodC is called, it calls methodB, which directly invokes methodA. An exception is thrown in methodA, since methodB does not handle it. It then bubbles up to methodC, which gracefully handles the exception. In this example, though methodC does not call methodA directly, because exception bubbles up the stack, it is still handled gracefully at the end.

Multiple catch blocks

A method might contain different exceptions: some might be directly thrown by themselves and some might be bubbled up from their underlying stack. The catch block is designed to handle multiple exceptions, so we can have multiple catch blocks for handling different exceptions. A caveat here is that the position matters.

In multiple catch blocks, PHP picks the first block that matches the thrown exception's type. A good rule for positioning catch blocks is from a more specific one to a less specific one.

Let's see it in an example.

In the sample code, it is obvious ExceptionA catch block will get picked. Now let's change the method to throw ExceptionB.

Which catch block do you think it will be picked? The answer is still ExceptionA. Because ExceptionA is a parent class of ExceptionB, when ExceptionB is thrown, ExceptionA catch block comes first and matches the thrown exception's type, giving ExceptionB is an instance of ExceptionA.

This can be fixed by positioning them from the the more specific type to a less specific type, as shown below:

trace message

Since exceptions can be thrown anywhere in your program, it is very important to find the root cause. Exception provides various APIs to make it easy to trace where the exception comes from.

Seven public methods are extracted from PHP manual file:

final public string getMessage ( void )
final public Exception getPrevious ( void )
final public mixed getCode ( void )
final public string getFile ( void )
final public int getLine ( void )
final public array getTrace ( void )
final public string getTraceAsString ( void )

And we can use them to trace details of the thrown exception:

Exception::getMessage — Gets the Exception message
Exception::getPrevious — Returns previous
Exception Exception::getCode — Gets the Exception code
Exception::getFile — Gets the file in which the exception occurred
Exception::getLine — Gets the line in which the exception occurred
Exception::getTrace — Gets the stack trace
Exception::getTraceAsString — Gets the stack trace as a string

Let's put it in action.

For demonstration purpose, let's pretend we have a createAccount() method, which throws an Exception when an email address is invalid.

What information can we get if we trigger the exception?

Running the script from CLI, we get the following:

Beside obvious trace information, we can also tell that, the default code is 0 and previous exception is null when instantiating an exception object.

One more point we want to address here is that an exception is created when it is instantiated, not when it is thrown. So Exception APIs will give you information related to the time an exception is instantiated.

For example, in the method below, Exception::getLine will return 2.

finally

Before PHP 5.5, there was not finally block in PHP. A problem surfaced. If we wanted to ensure that one piece of code always ran regardless of which catch block got picked, we had to put that piece of code into each one of catch blocks.

To solve this problem, finally block was introduced since PHP 5.5. Code inside finally block will always be executed after catch block. We can even use try/catch only without catch .

This block is a place for us to do some clean up jobs. Tasks such as rolling back database transactions, closing database connections, releasing file locks and so on. Its usage is pretty straightforward.

For example, to use it alongside try/catch blocks:

Use try/finally block only:

3. Create your first custom exception

Throwing custom exception allows client code to handle the error case in a recognized manner. For example, when a database exception is thrown, it is reasonable to shut down the process completed. However, in the case of an invalid user input, we might just want to log an error message.

By creating custom exceptions, we express error cases of our code proactively. This not only helps the clients to avoid pitfalls, but also gives them enough information to handle the error cases confidently.

As all exceptions in PHP 5.x use Exception as the base, we are actually extending Exception to create our custom exception. In this example, let's revisit our previous code.

We have two custom exceptions here (InvalidCredentialException and LoginAttemptsException). They should actually be under one type. And they will be assign different messages.

Since InvalidCredentialException and LoginAttemptsException are error cases for an invalid login runtime error, it is reasonable to create an exception called InvalidLoginException, and use it for the two error cases above.

It is simple enough to create a custom exception with only one line of code.

We can refactor previous code to use the newly created exception class:

A little trick

A potential issue might appear shortly, if we are using InvalidLoginException with too many different messages. The issue is easy to illustrate.

Imagine somewhere in our code, we need to throw another InvalidLoginException when an user account is blocked. We will throw the exact InvalidLoginException, but with different messages. The same thing happens again, and we will repeat the same actions. The list adds up. Now imagine doing this for different types of exceptions. We would lose track as the developer.

So here is a little trick: we shift the exception creation task to InvalidLoginException class.

Now the client code becomes:

When the instantiation of exception is shifted to a function block, we gain much more space and freedom to do more interesting stuff, compared to a single line within the if block previously.

By keeping all of them in a centralized location, which is the exception class itself, not only does it create a more maintainable code base, but also give clients an opportunity to take a quick glance what exact exception they would expect.

4. SPL exceptions

Creating your own custom exception is great, but it does take some mental energy to come out as a meaningful name. Naming is hard, arguably one of the hardest thing in programming.

The Standard PHP Library (SPL) provides a set of standard Exceptions. We should use them for our own benefit. They cover a list of common error cases, which can save us energy if we were to come out on our own. Additionally, we can also expand from these standard Exceptions to make them more specific to our own domain.

In this sections, we will go through 14 SPL Exceptions, explaining them in simplest terms, so that you can use them next time in your own project.

There are two main categories of SPL Exceptions. They are LogicException and RuntimeException, Under each one of them, there are a few sub exception classes describing more specific error cases.

Logic Errors

LogicExcetpion

It's not hard to tell from its name that, LogicException covers error cases related to logics. As it is a parent class for a few more specific exceptions, it is a bit generic. When your code is returning or receiving something that is not logic, there is a logic error. When an error case is determined to be a logic error, use LogicException if you cannot find a better fit from its subclasses.

BadFunctionCallException

When an non-existing function get called, or wrong parameters are supplied to a function, this exception gets thrown. As this exception covers function scope, not method in a class, it is mostly thrown by PHP.

BadMethodCallException

When an non-existing method of a class gets called, or wrong parameters are supplied to that method, an BadFunctionCallException can be thrown. While this exception is similar to to BadFunctionCallException, it is designed for class scope.

DomainException

Domain here refers to the business our code works for. When a parameter is valid by its datatype, but invalid to the domain, a DomainException can be thrown.

For example, in an universal image manipulation function, transformImage($imageType) , DomainException should be thrown when $imageType contains an invalid image type. To this domain, an invalid image type is a domain error.

InvalidArgumentException

This one is simple, as its name says: it should be thrown when an invalid argument is supplied.

PHP5 introduces type hinting, however it does not yet work for scalar types such as int, string yet. To make it work, we throw InvalidArgumentException when a scalar type does not meet the requirement.

LengthException

We can use this exception when length of something is invalid. For example, password needs to be at least 8 characters.

OutOfRangeException

Use this exception when an invalid index is accessed. The keyword here is range.

5. RuntimeException

RuntimeException is a name derived from compile language, such as Java. In Java, there are two main categories of exception: checked exceptions and runtime exceptions. A complier won't compile the code until all checked exception are handled (in a catch block). Runtime exception can only be detected at run time and is not required to place these exceptions in a catch block.

Since PHP is not a compile language, we can think of its "compile time" as the time we write the code, and its "run time" as the code execution time. "Compile time" exceptions can be detected in development time, for example invalid datatype parameter.

To avoid confusion, keep in mind that logic exceptions discussed above are for "compile time".

RuntimeException's subclasses cover more specific scenarios. Use this exception if you cannot find a better fit from its subclasses.

OutOfBoundsException

This exception is used when an invalid index is called. Not to be confused with OutOfRangeException, OutOfBoundsException is a run time exception.

For example, when a user creates an array data structure and when an invalid index is called, an OutOfBoundsException should be thrown. Whereas trying to obtain the day of week using 8 should throw an OutOfRangeException.

OverflowException

When a container with limited capacity is asked to fill more than it can hold, this exception can be thrown.

RangeException

This exception is for generic error cases related to range at "run time".

UnderflowException

Opposite of OverflowException is UnderflowException. When an empty container is asked to remove an element, this exception can be thrown.

UnexpectedValueException

As simple as its name says, when an unexpected value is raised or accessed, we throw this exception.

That is all the exceptions provided by PHP SPL. We should always throw the most accurate exception for an error case. Inevitably, one exception may fit under multiple exceptions in which case, it is fine to pick one.

An meaningful exception message goes a long way towards a maintainable project.

6. The End

Hopefully this simple tutorial helped you with your development.
If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
Did we miss out anything? Do leave a comment below to let us know.

Modern PHP Developer - Iterator

Mon, 05 Feb 2018 13:41:43 +0000

Table Of Content

Your first iterator class
Why iterator?
SPL Iterators
ArrayObject vs SPL ArrayIterator
Iterating the File System
Peeking ahead with CachingIterator
Generator
The end

If you have used a for loop in PHP, the idea of iteration is most likely not foreign to you. You pass an array to a for loop, and perform some logic inside the loop, but did you know that you can actually pass data structures other than arrays to a for loop? That's where Iterator comes into play.

Below is summarised definition of an iterator from Wikipedia:

In computer programming, an iterator is an object that enables a programmer to traverse a container, particularly lists.[...] Note that an iterator performs traversal and also gives access to data elements in a container, but does not perform iteration [...]. An iterator is behaviorally similar to a database cursor.

Some key points to remember here:

Iterator enables us to traverse a container. It is similar to arrays.
Iterator does not perform iteration. In our previous example, for does the iteration. Other loop types such as foreach and while do iteration.

Now that we know the definition of Iterator, the concept may still be somewhat obscure, but do not worry, we aren't done yet. We have now established that Iterator works similar to array and it can be loop through in a for loop.

It is helpful to understand how array actually works in a for loop. Let's take a look at the code below:

Here is how an array works in a for loop:

In step 1, we set $i to 0.( $i=0 )
In step 2, we check to see $i is less than the length of $data. ( $i
In step 3, we increase $i value by 1. ( $i++ )
In step 4, we can access the key of the current element. ( $key = $i )
In step 5, we can also get the value of current element. ( $value = $data[$i] )

We can abstract the steps as simple functions as below:

Step 1 = rewind().
Step 2 = valid().
Step 3 = next().
Step 4 = key().
Step 5 = current().

In abstract level, we can imagine that, as long as an object provides the five functions above, it can be loop through by a for loop.

In fact, an iterator is nothing but a class implements all five steps mentioned above. In PHP, The Standard PHP Library(SPL), which is a collection of interfaces and classes that are meant to solve common problems, provides a standard Iterator interface.

1. Your first iterator class

Now that we understand what an iterator is, it's time to build our first one.

Our first iterator represents top 10 stared PHP repositories from Github. We can pass it into a foreach and loop through it just like an array. We will name it TrendingRepositoriesIterator.

First, we need to make our class implement the Iterator interface.

An iterator must always implement the five methods described above. Final code of TrendingRepositoriesIterator is as follow:

public function populate(): We will not go in-depth regarding this function as that will defeat the purpose of this chapter. Basically this function fetches top 10 stared PHP repositories from Github via Github public API and store them into $repos property.
private $repos: We use this property to store fetched repositories.
private $pointer: We can use array's internal pointer to do the job, however since we are building our own iterator, we want to retain full control.
public function __construct(): The property fetches target repositories when an object is instantiated.
public function rewind(): We can use this to set pointer to first position.
public function valid(): As long as the value of current pointer is set, it is valid.
public function next(): This is used to increase the pointer by 1 position.
public function current(): We can return value of current pointer through this function.

Let's see the use case of TrendingRepositoriesIterator, which can used just like an array:

Awesome! Now we have written our first iterator and as you can see, it is actually very easy and straightforward.

2. Why iterator?

You might still wonder why we need to use iterator. Can't we just use array? The answer is yes and no. In most cases, array is sufficient for the job, although iterator does come with some key advantages, which we will share next. Keep in mind, we are by no means suggesting using iterator in all circumstance.

Encapsulation

In our first iterator, TrendingRepositoriesIterator, the details of traversing Github repositories is completed hidden from outside. We can update how we get the data, where we get the data from, and how we want to traverse the resources. No change is needed from the client code. This, known as Encapsulation, is one of the key concepts of Object- Oriented Programming.

Additional examples include:

To iterate through MySQl results, we can use:

To iterator through content of a text file, we can:

With iterator, we can encapsulate the process of traversing the recourse so that the outside world is not aware of the internal operations. In fact, the outside world does not need to know where we get the data from or how it is traversed in a loop. All they need to know is that, they can iterate through it as simply as:

Encapsulation is a very powerful concept and it enables us to write clean code.

Efficient memory usage

Efficient memory usage is a key benefit of iterator.

In our TrendingRepositoriesIterator class, we can actually fetch resource dynamically, meaning we will only fetch data from Github API when the next() method is called. This technique is called Lazy Loading. It helps us save a very significant amount of memory as value is only generated when it is needed.

Easy to add additional functionalities

Another benefit of using iterator is that we can decorate it to add additional functionalities. Take our TrendingRepositoriesIterator class for example. We want to exclude "laravel" from the resource. One obvious method is to update our original class, although that is of course not what we would do here.

We can decorate the original iterator using SPL's CallbackFilterIterator and no change is needed for TrendingRepositoriesIterator at all.

The cool part of this is that there is no duplication of objects. The callback fires only when TrendingRepositoriesIterator hits the next() method, and then the logic it will be applied accordingly. This is a great way to save memory as well as boost performance.

3. SPL Iterators

Now that we understand the power and benefits of using iterators, it is good practice to use iterators to solve suitable problems. However if we were to write iterators by ourselves whenever we encounter a new problem, it would be very time consuming since it does require us to implement a set of pre-defined functions.

Luckily PHP has done a good job of providing a set of iterators for solving some common problems. In the following sections, we will work through a set of common iterators provided by SPL. As a refresher, SPL standards for Standard PHP Library was built to provide a collection of interfaces and classes that are meant to solve common problems.

4. ArrayObject vs SPL ArrayIterator

In PHP, array is one of the eight primitive types. PHP provides 79 functions for handling array related tasks (reference). It is completely suitable to use array, however there are times, depending on how much you embrace Object-Oriented programming, that you may want to use array as an object. In this case, PHP provides two classes to make array a first class citizen in Object-Oriented code.

ArrayObject

The first option we have is ArrayObject. This class allows objects to work as arrays.

Let's take a look at its class signature:

As we have seen above, ArrayObject implements IteratorAggregate. What is IteratorAggregate? It is an interface to create an external iterator. In simple terms, it is a quick way to create an iterator, instead of implementing Iterator interfaces with five methods: rewind,valid,current,key and valu, IteratorAggregate allows you to delegate that task to another iterator. All you need to do is implement a single method getIterator().

ArrayObject implements IteratorAggregate. It creates an external ArrayIterator for iterator feature.

As ArrayObject implements IteratorAggregate, we can use it in a foreach loop just as an array.

The primary reason we want to use ArrayObject is to use array in Object-Oriented fashion.

ArrayIterator

ArrayIterator works similar to ArrayObject.

Let's take look at its class signature as well:

It is almost identical to ArrayObject in terms of interfaces they implement. The only difference is, instead of ArrayIterator interface ArrayObject implements, it implements SeekableIterator.

We use ArrayIterator the same way as we use ArrayObject in a foreach loop:

Use array in Object-Oriented fashion:

Comparison

You may be wondering when to use ArrayObject and when to use ArrayIterator. It is important to know the difference and the relationship between ArrayObject and ArrayIterator.

As we have already discovered in the ArrayObject section, ArrayObject actually creates ArrayIterator as an external iterator. It is fair to say ArrayIterator does what ArrayObject does, and it provides more functionality, specifically seeking to a position. This is accomplished by implementing SeekableIterator.

Besides moving a pointer from top to bottom as iterator, it allows you to randomly jump to a position.

At last, ArrayIterator is part of SPL whereas ArrayObject is not.

5. Iterating the File System

It is a very common task to list outthe content of a given directory. PHP provides lots of functions for handling a file system. One of them is scandir().

Suppose we are given a task to list out all files in a given directory as below:


---books
|   ---book_item_1.txt
|   ---book_item_2.txt
|   ---book_item_3.txt
|    ---book_item_4.txt

We can accomplish it through scandir() as shown below:

These are two virtual directories("." and "..") you'll find in each directory of the file system.

As this chapter is about iterators, we are going to introduce some iterators for handling filesystem. Hopefully in your next project, you will be able to utilize some of them. Three iterators come in handy: DirectoryIterator, FilesystemIterator and RecursiveDirectoryIterator.

Before we look into each one of them, it is useful to take a look at their inherit relationship:

DirectoryIterator

The DirectoryIterator class provides a simple interface for viewing the contents of filesystem directories.

To accomplish the same task, we can use DirectoryIterator:

The only parameter needed to create a DirectoryIterator object is a directory's path. Compared to scandir function, instead of the file name as a string, DirectoryIterator returns an object. The object holds various information relating to a file, which we can make use.

FilesystemIterator

To accomplish the same task by using FilesystemIterator, we can use:

This looks almost the same as DirectoryIterator, except that FilesystemIterator has automatically filtered out the two virtual directories.

Are they really the same? We can use a simple method to tell the differences:

The result of running above script from CLI is:

Now we can see they are actually quite different internally:

DirectoryIterator returns an integer as the key and a DirectoryIterator as the value in a loop.
FilesystemIterator returns a string of full path as the key and a SplFileInfo object as the value in a loop.

In fact, FilesystemIterator comes with a bit more flexibility. When creating a FilesystemIterator object, it accepts a directory's path as the first parameter similar to DirectoryIterator. Moreover, you can optionally pass a second parameter as a flag. This flag is able to configure various aspects of this function.

FilesystemIterator::CURRENT_AS_PATHNAME: This flag will make FilesystemIterator return file path instead of SplFileInfo object as the value.
FilesystemIterator::CURRENT_AS_FILEINFO: This flag will make FilesystemIterator return SplFileInfo object as the value. This is the default behavior. You don't have to set it explicitly.
FilesystemIterator::CURRENT_AS_SELF: This flag will make FilesystemIterator return FilesystemIterator itself as the value.
FilesystemIterator::KEY_AS_PATHNAME: This flag will make FilesystemIterator return file path as the key. This is the default behavior. You don't have to set it explicitly.
FilesystemIterator::KEY_AS_FILENAME: This flag will make FilesystemIterator return file name and extension instead of file path as the key.
FilesystemIterator::FOLLOW_SYMLINKS: This flag will make RecursiveDirectoryIterator::hasChildren() follow symlinks.
FilesystemIterator::NEW_CURRENT_AND_KEY: This flag helps set two other flags(FilesystemIterator::KEY_AS_FILENAME and FilesystemIterator::CURRENT_AS_FILEINFO) at once.
FilesystemIterator::SKIP_DOTS: This flag will make FilesystemIterator ignore virtual directories ("." and "..").
FilesystemIterator::UNIX_PATHS: This flag will make FilesystemIterator use Unix style directory separator() despite what system the PHP script runs on.

6. Peeking ahead with CachingIterator

In this section, we will introduce an iterator with the ability of peeking into next element in an iteration. This feature enables us to do a lot useful things such as, executing something different when iterator reaches the end of the list.

The class with this great power is CachingIterator.

Let's first take a look at it class signature, then, we will go into details of its usage.

CachingIterator inherits from IteratorIterator. What is IteratorIterator? It is simply a wrapper around another iterator, under the hood. It will forward the five Itertator methods( rewind() , current() , key() , valid() , next() ) calls to the iterator it wraps around. We can also retrieve the inner iterator by calling method getInnerIterator() .

Due to the nature of this class, the inner iterator's pointer always moves one step ahead of CachingIterator, and CachingIterator provides a method hasNext() to tell us if it reaches the end of the list. That is how CachingIterator peeks ahead.

Now, let's put it into action.

Result of running above script in a CLI:

Similar to other iterators, to create an CachingIterator instance, we pass in an iterator as the first parameter to the class contractor. As we can see, the real magic behind peeking ahead is provided by method hasNext() . This method is able to tell us if there is an immediate next element.

Beside the first parameter, CachingIterator also optionally accepts a second parameter as a flag.

CachingIterator::CALL_TOSTRING: It will return __toString of the current element as value. This is the default behavior.
CachingIterator::CATCH_GET_CHILD: It will capture all exceptions thrown when accessing children.
CachingIterator::TOSTRING_USE_KEY: It will return the key value when casting the iterator to a string in a loop.

CachingIterator::TOSTRING_USE_CURRENT: It will return the current value when casting the iterator to a string in a loop.

CachingIterator::TOSTRING_USE_INNER: It will return the inner iterator casted to a string when casting the iterator to a string in a loop. If we set this flag in the same code as previous example, it will throw an exception. This is because ArrayIterator does not implement the __toString() method.
CachingIterator::FULL_CACHE: A CachingIterator won't have a key word "caching" in its name if it is not able to do some sort of cache. When this flag is set, it will cache the results, should they ever be iterated for future use.

7. Generator

You are now convinced by the benefits of iterators. They encapsulate the details of traversing and they are much more efficient than creating in-memory arrays. However, everything has its price. To create an iterator, we still have to implement the SPL Iterator interface. You might be terrified of iterators and not want to implement those five methods contracted by Iterator interface. It is time consuming and sometimes even complex to implement them.

Starting from PHP 5.5, you won't be intimidated any more. PHP introduces something, Generators, which provide an easy way to implement simple iterators without the overhead or complexity of implementing a class that implements the Iterator interface.

What is exactly a generator? A generator is like a normal PHP function, except that it has a special keyword , "yield", in it.

Below is a simple example of a generator function. We won't have such a generator in the real world application - it is here for demonstration only:

Internally PHP realizes a generator function when it spots the yield keyword. When a generator function is called for the first time, PHP creates a Generator object. This Generator object is an instance of an internal class Generator and Generator class implements the Iterator interface. This way, users are able to create iterators without writing the contracted code, all thanks to PHP generator.

The yield is called when we need to provide the step values. Think of it as return in a function or current method in a regular iterator.

Let's turn one of our first iterator class TrendingRepositoriesIterator to a generator function:

It turns out to be much less code with a generator. We can also use it in a foreach loop, in the same way as we did with TrendingRepositoriesIterator:

Note that generators themselves do not provide anything special - they just make creating iterators simpler. In other words, they are definitely not replacements for iterators.

8. The End

Modern PHP Developer - PDO

Mon, 05 Feb 2018 13:40:17 +0000

PHP Data Objects, most commonly known as PDO, is a PHP extension built to solve database access problems. It provides a unified interface to access databases.

PDO creates an abstraction layer for data-access, so developers can write portable code without worrying about the underlying database engines. In layman's terms, you use PDO to develop an application using MySQL as the database storage. If you want to switch to PostgreSQL at any point in time, all you need to do is to change the PDO driver. No other code change is required.

PDO consists of three main types of objects: They are PDO object, PDOStatement object and PDOException object. We should not necessarily neglect the PDO Drivers, but these three types of objects together form the main interface of the PDO extension.

Table Of Content

Why use PDO?
Running PDO Queries
Data manipulation
PDO API
The end

1. Why use PDO?

If you have developed any MySQL database driven application before, but have never tried PDO, you must be wondering what the benefits are to use PDO, especially when comparing it to its two alternatives.

MySQL

The oldest way to interact with MySQL is to use mysql extension. It was introduced in PHP 2.0.0, however it was deprecated as of PHP 5.5.0, and has already been removed in PHP 7.0.0. It is not recommended to use this extension at all given the factor that it is not supported in newer PHP versions.

MySQLi

Since PHP 5.0.0, an improved version of mysql extension, known as mysqli was introduced. It brought a lot of benefits over the mysql extension, such as object-oriented interface, prepare statements, multiple statements, transaction support, enhanced debugging capabilities and embedded server support.

The main differences between MySQLi and PDO are:

PDO supports client-side prepared statements, whereas MySQLi does not. We will discuss client-side prepare statements in details in later sections. It basically means it will emulate prepared statement if the chosen database server does not support it.
MySQLi supports both object-oriented API and procedural API, whereas PDO religiously uses objected-oriented API.
The biggest advantage of using PDO is to write portable code. It enables developers to switch databases easily, whereas MySQLi only supports the MySQL database.

Ultimately, we recommend using PDO to build your applications.

It enables developers to write portable code.
It encourages object-oriented programming.

Lastly, we want to emphasize that, by no means are you forbidden to use MySQLi.

In the following sections, we will start with some common ways of running queries using PDO. Then we will demonstrate how to perform various MySQL data manipulation statements using PDO. Finally, we will focus on a few PDO APIs, which serve the same purpose but in different ways.

2. Running PDO Queries

We summarize the different ways of running PDO queries into four categories, classified by number of steps involved from carrying out the query to getting its result. These categories were created to ease the efforts of remembering PDO APIs and include:

exec
query fetch
prepare execute fetch
prepare bind execute fetch

Establish database connection

Before we get into each category, you will first need to be familiar yourself with establishing a database connection using PDO. This is the absolute the fundamental of PDO, as it is used in every piece of code below:

To establish a database connection, we instantiate a PDO object with three parameters. The first parameter specifies a database source (known as the DSN), which consists of the PDO driver name, followed by a colon, followed by the PDO driver-specific connection syntax. The second and third parameters are database username and password.

An exception will be thrown if the connection fails. You can catch the exception and handle it gracefully. Kudos to exception in this case, we no longer need to put the connection in a if statement due to a clean and easy to read code base.

In the following code samples, we will neglect this piece of code, to avoid clutter. Keep in mind, you will always need to make the connection first before proceeding with any PDO operations.

exec

This is the simplest form of running a query. We can use it to run a quick query and normally we do not expect it to return any results.

Though PDO::exec does not return the result corresponding to your query, it does return something. Regardless of what query you run with PDO::exec, it returns the number of affected rows on success. It also returns Boolean FALSE on failure.

A caveat when checking the return type: since it PDO::exec returns 0 when there is no row affected, we should always use === comparison operator to verify success of running the method.

If you are building the query string with user input and manually handling security issues as such escaping characters, you should use other alternatives, which we will discuss later.

query fetch

When running query such as SELECT statement, we do expect a return of corresponding results. The easiest way of accomplishing this is use:

Note that methods $dbh->query() and $statement->fetch() , are how we name our categories, by the sequences of calling PDO APIs.

Because PDO::query returns a result set as a PDOStatement object on success (It will return Boolean FALSE on failure, do similar check as PDO::exec if you want to verify). PDOStatement class implements the Traversable interface, which is the base interface for Iterator, meaning it can be used in an iteration statement as such as a loop . Naturally, there is a short version of previous code:

You might have noticed, when calling either PDO::query or PDOStatement::fetch, we have supplied a flag parameter. This parameter specifies what type of data structure we want from the callee.

A few of the options include:

PDO::FETCH_ASSOC: returns an associative array indexed by column name.
PDO::FETCH_NUM: returns an numerically indexed array.
PDO::FETCH_BOTH (default): returns an array indexed by both column name and 0- indexed column number as returned in your result set. (Combination of PDO::FETCH_ASSOC and PDO::FETCH_NUM).

There are a lot more options. We recommended that you take a quick look at them at PHP Manual. Though this parameter is optional, we should always specify it unless we really want an array indexed by both column name and number. PDO::FETCH_BOTH takes twice as much memory.

prepare execute fetch

We frequently need to accept user's input in order to run a database query. There are two major concerns if we were to use A query fetch approach.

First, we will have to make sure the sql query passed to PDO::query is safe. Escaping and quoting the input values must be well taken care of. Second, PDO::query executes an SQL statement in a single function call, which means if we need to run the same query multiple times, it will use multiple times of resources. There is a better way of doing this.

PDO introduces prepare statement for the first time. So what is prepare statement? According to Wikipedia.

In database management systems, a prepared statement or parameterized statement is a feature used to execute the same or similar database statements repeatedly with high efficiency. Typically used with SQL statements such as queries or updates, the prepared statement takes the form of a template into which certain constant values are substituted during each execution.

Prepare statement solves two concerns raised above. It not only improves the efficiency of running multiple similar queries, but also takes care of escaping and quoting user input values.

Below is how we implement prepare statement using PDO:

Note the steps we have taken here:

PDO::prepare is used to create a sql query containing a variable parameter. Naming convention for parameters are either named variables prefixed by a colon(:) or a question mark (?).
PDOStatement::execute is called to execute a query with parameters' value. When ? is used in the prepare statement, they are numbered parameters. We can bind the values using a numeric indexed array. Note in the foreach , it uses the same statement to carry out the query after binding the value. It returns Boolean FALSE upon failure. We can use PDOStatement::errorInfo() to get the error information associated with the operation.
PDOStatement::fetch is used to fetch result with desired data structure.

prepare bind execute fetch

A minor issue you might have OBSERVED in previous code is what happens when there are a lot of parameters in the prepare statement. We can easy create code piece like this:

The list can go on and on. This makes code very difficult to read. However, a more important thing to notice here is that, PHP will cast user input value to match its database field type if they do not match exactly, which is prone to bugs.

Here is where PDOStatement::bindValue comes in to save. The recommended way of running previous is:

Instead of using PDOStatement::execute to bind value to parameter, we used PDOStatement::binValue. It adds a few significant improvements to our code:

Readability: it makes the code easy to read for other developers, as it indicates the exact data type a parameter should accept.
Maintainability: The third parameter, which specifies datatype of passing variable, prevents PHP from casting incompatible datatype, which is prone to bug. In the long run, it also makes the code easier to maintain, as future developer will be able to spot the datatype at a glance.

These four techniques are definitely not official: they are just naming conventions made to memorize PDO APIs. There is no need to follow them strictly. In fact, most of time we combine these techniques together.

3. Data manipulation

Let's put what we have learned into action. In this section, we will use PDO to accomplish some of the most common MySQL tasks.

Sample database table

We will need a database table to play around with.

For demonstration purpose, we will create a very simple database table:

Insert data

Our first task is to insert some data into the table. For this use case, let's suppose we accept data from a user input form via a POST request, and then we insert whatever data is from the form into the customers table.

We are using the prepare->execute->fetch techinique in this code sample, except we removed the fetch part since we do not expect it to return any result set.

The first step is to connect to the database as usual.
Then, we create a prepare statement. Note that we also handle failure case by throwing an exception.
And lastly, we execute the prepare statement. Failure case is also handled. We are able to output useful information by calling PDOStatement::errorInfo method.

Update data

The second common task is to update existing data. Assume the use case is the same as the previous case, except the user is able to pass in an additional parameter ($id).

As you have probably guessed, beside the additional parameter $id ,the code is identical to previous code sample.

Delete

The third common task is to delete an existing data record (similar use case here). User is able to pass in a single parameter ($id), and the corresponding record should be deleted.

Again, this is a very similar code sample as the previous one (prepare->execute->fetch techinique with fetch part). That is the "beautify" of PDO - its object-oriented design makes code easy to write.

Select

Our final task is to select all data records from customers, but this time, we won't ask for user's input.

In this example, we have used the query->fetch technique. As we mentioned earlier and it is worth mentioning again, when calling PDOStatement::fetch, it is a good habit to always specify the fetch mode.

Now we have run through some quick samples of using PDO for various tasks. These samples are very simple, yet they have showed us a very easy to use and consistent API provided by PDO.

4. PDO API

So far, we have demonstrated some common PDO APIs. PDO still provides a lot more than we have shown above. In this section, we will explore PDO APIs for the last time and try to cover as many useful APIs as we can. It is nearly impossible to cover every aspect of this topic but always keep in mind that there is a manual page that can be referenced when you are in doubt. (PDO Manual page)

Fetch methods

We have covered one(PDOStatement::fetch) of the fetching methods used to retrieve result sets. In fact, PDOStatement provides three additional fetching methods.

PDOStatement::fetchAll

Working similarly to PDOStatement::fetch, PDOStatement::fetchAll also accepts a flag as first parameter, which is to specify fetch mode. We should always specify the fetch mode the same way we do for PDOStatement::fetch method. It differs from PDOStatement::fetch in that it returns all result at once.

A caveat of this method is that, since it loads all result sets at once, it might result in heavy memory usage depending on how much data is available. You should use this method with attention.

PDOStatement::fetchColumn

A handy method for retrieving data from the desired column is PDOStatement::fetchColumn. It returns a single column from the next row of a result set. It is similar to PDOStatement::fetch, however it returns the next single column only instead of a next array of result reset.

PDOStatement::fetchColumn accepts a single parameter(column name) optionally. The parameter is a 0-indexed number specifying the column to retrieve data from. When this parameter is omitted, it defaults to column number 0.

Two points to not when using this method:

PDOStatement::fetchColumn will return Boolean FALSE when it reaches the end of the result set, so it should not be used to retrieve Boolean type from the database.
PDOStatement::fetchColumn moves its pointer one step forward when it is called, so there is no way to retrieve another column from the same row. (Obviously the pointer has already moved to the next row when we call it using different column number).

PDOStatement::fetchObject

This method is an alternative to PDOStatement::fetch() with PDO::FETCH_CLASS or PDO::FETCH_OBJ style. Its purpose is to make our code easier to read when called separately, when this method is called, it will return next result set as a PHP object:

We can also pass in our custom PHP class as first parameter, PHP will instantiate one instance of our custom PHP object with data retrieved and return it:

Bind methods:

Previously, we have used PDOStatement::bindValue. This method binds desired value to the placeholder of the query. This method is not the only method for that task though.

bindParam

This method is almost identical to PDOStatement::bindValue and it's no surprise that some people use these two methods interchangeably, however there is a very significant different between these two methods, and it might cost you a fortune if you are not aware of it.

Unlike PDOStatement::bindValue(), the variable is bound as a reference and will only be evaluated at the time that PDOStatement::execute() is called.

Let's see what it means by example.

Do you spot the difference? These two pieces of code are identical except one is using $statement->bindParam and the other is using $statement->bindValue. The result produced is entirely different.

PDOStatement::bindParam binds variable $user as a reference. At the time of PDOStatement::execute is called, $user variable is changed to 'Tom' whereas PDOStatement::bindParam variable as a value, it remains as 'Andy' from the time PDOStatement::bindValue is called.

Make sure you understand the difference between these two and choose them according to your needs. Switching these two methods without a fair amount of consideration is discouraged.

bindColumn

Different from PDOStatement::bindValue and PDOStatement::bindParam, this method is not a method for binding variable to prepare statement. In fact, it is quite the opposite: it binds columns from resulting set to PHP local variables.

This is an interesting method to observe. Previously, we discussed that a method PDOStatement::fetchObject, can return result set as a defined object. Here, with PDOStatement::bindColumn, we can bind columns from result set to variables.

The first parameter which specifies the table column, accepts both string column name and 0-indexed number as a value. So the following is valid too.

Conditions:

In the last section, we will discuss some tips when working with PDO.

IN clause

Building IN clause in a prepare statement is an interesting task. Take a look at following code and imagine this is what we need to build:

At first glance, it seems legitimate. Take a closer look. It won't work because prepare statement only accepts scalar types (e.g. string, int and so on).

The ultimate task becomes building a comma separated string containing equal question marks(?) to the binding array variable. This is how we can build a legit IN clause string.

Wildcard characters

When building a LIKE clause, we might be tempted to do this:

However, that won't work in PDO. We need to shift the wildcard characters to the variable itself:

5. The end

Modern PHP Developer - PSR

Mon, 05 Feb 2018 13:19:29 +0000

Prior to PHP Standards Recommendation (PSR), there were no truly uniformed standards for writing PHP code. For instance, for coding style, some people preferred Zend Framework Coding Standard, and some liked PEAR Coding Standards, and still others chose to create their own naming conventions and coding style.

A group of people, representing various popular PHP projects came together in 2009 and formed something called Framework Interoperability Group(FIG). The purpose of FIG is for project representatives to talk about the commonalities between their projects and find ways to work together.

At the time of this writing, there are six accepted PSRs: two of them are about autoloading, two of them are related to PHP coding style and the remaining are about interfaces.

In this chapter, we will discuss each PSR briefly. The purpose of this chapter is to introduce you to the ideas of PSRs. For further details on each one, the respective link are provided.

Table Of Content

PSR-0 & PSR-4
PSR-1 & PSR-2
PSR-3 & PSR-7
PSR Specifications
The end

1. PSR-0, PSR-4

Both PSR-0 and PSR-4 are standards for autoloading. If you aren't familiar with autoloading, it is basically a way for PHP to include classes without writing cluttered include/require statements everywhere.

Let's take a look at the history of autoloading. This will give you a clear picture how autoloading in PHP has involved during the years.

In PHP language, we have to make sure a class's definition is loaded prior to using it. Normally, we will create our PHP classes in their own class files for better organization. Then we will load them with require or include statements in the files they are being called.

This approach quickly raises some issues. Imagine you have tens of external classes to be used in a file and you start writing lines of require/include statements right at the beginning of a source file. They are ugly and clutter our codebase with repetitive lines of include statements.

Starting in PHP 5, a new magic function was introduced to solve this issue:

__autoload is essentially a helper function, doing what we were doing with include statements. We can define this function anywhere in our codebase, and PHP will automatically use this function to load a class's file when an undefined class is called. This is the last chance to load a class definition before PHP fails with an error.

__autoload quickly became obsolete due to the fact that it can only allows one autoloader function. What this means is that since autoload is the one and the only one magic that PHP engine will call, we need to define this particular magic function wherever we want an autoloading feature. Theoretically, this includes every file in a solid object-oriented codebase.

PHP 5.1.2 was shipped with another autoloading function( spl_autoload_register ) for coping with __autoload 's limitation. spl_autoload_register is a replacement for __autoload , and it provides more flexibility. It works by registering PHP user land functions with the autoload queue. It effectively creates a queue of autoload functions, and runs through each of them in the order in which they are defined. This means we can have multiple autoloader functions and there is no need for creating autoload function in each one of our source files anymore.

Autoloading was such a great idea that every project started to use it. Inevitably everyone created their own version of autoloader as uniform standards were lacking. Clearly, PHP desperately needed a standard for autoloader, which is how PSR-0 was born.

Today, Autoloader standard has evolved significantly. Even PSR-0 is officially depreciated due to some constraints, such as its unfriendiness to Composer.

The latest accepted autoloader standard is PSR-4. You should follow PSR-4 to create your desired autoloader. For specification of PSR-4, please read more from its official page.

2. PSR-1, PSR-2

PSR-1 and PSR-2 are for PHP coding standards. PSR-1 focuses on the basics, whereas PSR-2 expands upon PSR-1 and provides a more comprehensive coding style guide.

PSR-1 lists a set of simple rules for naming conventions and file structures. Its main purpose is to ensure a high level of technical interoperability between shared PHP codes. In a project that is incorporated with various packages, it can be a mess if each uses different coding standard, which is what PRS-1 was designed to solve.

A quick overview of PSR-1:

Files MUST use only <?php and <?= tags.
Files MUST use only UTF-8 without BOM for PHP code.
Files SHOULD either declare symbols (classes, functions, constants, etc.) or cause sid effects(e.g. generate output, change .ini settings, etc.) but SHOULD NOT do both.
Namespaces ad classes MUST follow PSR-0.
Class names MUST be declared in StydlyCaps.
Class constants MUST be declared in all upper case with underscore separators.
Method names MUST be declared in camelCase.

Building on top of PSR-1, PSR-2 provides more comprehensive guidelines with more detailed rules as basic as code indention. It also covers varicose aspects of coding style, from naming conventions to namespace, classes, properties, methods, control structures and closures. It is possible to find any specification you need from PSR-2. Adapting your codebase to this standard for interoperability is highly encouraged.

3. PSR-3, PSR-7

After autoloading and coding standards, we can finally associate PSR with PHP code. These are PSR-3 and PSR-7. PSR-3 contains a logger interface and PSR-7 contains interfaces for HTTP message interfaces.

PSR-3

PHP desperately needed a standard for Logger interface before PSR-3. Logging is such a common task that every project built its own version of logger. Without a standard, the only way to use a third-party logger was to write a wrapper around it, so it could work with our existing codebases. It was not only a painful process, but also felt wrong, because after all, they were all doing the same type of work: logging. We should be able to switch them around.

PSR-3 provides common interface for logging libraries. As long as they implement the PSR-3 logger interface, they should be theoretically interchangeable with any other PSR-3 logger libraries.

Let's take a look how PSR-3 Logger interface improves our code reusability in a concrete example.

Suppose we have written a simple authentication class User below. It appends an audit message to a log file once an user logins in successfully. It is using our custom logger class, which exposes a single method addMessage .

Our custom Logger class is injected to User class following dependency injection principle, this seems to make our User reusable. We can switch to other logger class simply via the constructor. But if we take a look closely, we can't do that, User class is still highly coupled to our custom Logger class, it is aware of custom method addMessage . If we use another third-party logger library in our code, it won't work, because they do not have a method called addMessage.

We can modify our code to use PSR-3 Logger interface instead. According to Dependency Inversion principle SOLID, we should depend upon abstractions rather than concretions. PSR-3 Logger interface provides a perfect abstraction for our case.

By changing a few lines of our code, we have replaced our custom logger with PsrLogLoggerInterface. Now our code is highly reusable. We can use, switch to, or change to, any third-party logger library that is compliant with with PSR-3 Logger interface.

PSR-7

HTTP messages are essential for web applications. Every action a user takes is a combination of a HTTP request and HTTP response. PSR-7 is the latest accepted standard. It provides abstractions around HTTP messages and the elements composing them. It will have a huge impact on projects that implement details of HTTP messages, since HTTP is a rather complex subject and most of vendors have their own implementation, it is a lot of refactoring for vendors to adapt PSR-7.

As a user of HTTP messages, we can now deal with HTTP messages universally thanks to PSR-7. Similar to PSR-3, PSR-7 makes our lives much easier to build a reusable codebase.

4. PSR Specifications

We have summarized each PSR briefly and you should now have an understanding of what each PSR is for.

You should refer to the official page whenever you need detailed specifications of each PSR.

PSR-1: http://www.php-fig.org/psr/psr-1/
PSR-2: http://www.php-fig.org/psr/psr-2/
PSR-3: http://www.php-fig.org/psr/psr-3/
PSR-4: http://www.php-fig.org/psr/psr-4/
PSR-7: http://www.php-fig.org/psr/psr-7/

5. The End

Modern PHP Developer - Composer

Mon, 05 Feb 2018 13:10:03 +0000

Table Of Content

Package Manager
Composer vs PEAR
Install Composer
Use Composer
Power of community
The end

1. Package Manager

In general, a block of code forms a method, a group of methods forms a class and a set of classes form a package.

A reusable package can be dropped into any project and be used without any need to add functionality to it.

A package exposes APIs for clients to achieve a single goal.

Packages help our applications achieve DRY (Don't Repeat Yourself), a principle of software development, which reduces repetition of information of all kinds.

In most cases, packages have dependencies. When "Package A" requires "Package B" in order to work, we say "Package A" depends on "Package B". It is quite common to see that a package has a chain of dependencies("Package A" depends on "Package B", "Package B" depends on "Package C", the list goes on).

Imagine there is no such thing as a package manager. What would we need to do in order to get "Package A", which has a dependency of "Package B" to work? First we download source code of "Package A", then discover it depends on "Package B", so we try our best to find source code of "Package B". It might still not work, because we also need to make sure that we download the correct version of "Package B". The story can go on and on. We are only talking about one single dependency here; it would soon turn to be a nightmare if "Package A" has multiple dependencies or there is a chain of dependencies.

We do need a package manager, a package manager that can solve all of these dependency headaches for us.

Composer vs. PEAR

PEAR

Prior to Composer, there was something called PEAR. If you started with PHP early on, you may be aware of PEAR, as it has been in existence since 1999. PEAR is made for the purpose of promoting reusable packages, similar to Composer. However, it has been discouraged by developers due to the following reasons:

Unlike Composer, PEAR is a system-wide package manager. When you have multiple projects, which share the same dependencies, but each has different versions, this approach causes a lot of confusion and frustration.
A certain number of up-votes is required in order to have your code accepted into PEAR's repository. This discouragement slows down growth of its repository. At the end of day, developers want to write code, not promote code.

Composer

Composer is an application-level package manager for PHP. It is inspired by NodeJs's NPM and Ruby's Bundler, and is currently the recognized package manager by the community.

The Composer ecosystem consists of two parts: the Composer, which is the command-line utility for installing packages, and the Packagist, the default package repository.

An application-level package manager means it manages dependencies on a per project basis. This makes managing multiple projects easy and keeps your machine clean as it only downloads packages to your project directory.

Everyone is welcome to submit their packages to Packagist. Unlike PEAR, there is no need to get up-votes whatsoever. You do, however, get starts if people like your packages.

Packagist

As mentioned earlier, Packagist(packagist.org) is the default package repository for Composer. As of the time of this writing, September 2015, 69,568 packages are available on Packagist. Next time you need a PHP package, instead of building one from scratch on your own, there is a good chance you can find it on Packagist. As a developer, it is recommended you leverage the power of Packagist as it will save you countless hours and energy.

Now, it's time to get our hands dirty.

Install Composer

We will assume you are a Mac user.

There are two scopes when installing Composer: local scope and global scope. From professional experience, we suggest installing Composer globally on your system. After all, it is very likely we will use Composer to manage dependency for every PHP project. Global installation saves us a lot of hassle.

Global Installation

Run commands below from your Terminal to install Composer globally:

If you encounter any errors related to permissions, run commands above in sudo mode (append sudo to each command)

Local Installation

Run commands below from your project root directory to install Composer locally:

For a more detailed installation guide on Composer, check out: https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx

Verification

To verify if Composer is installed properly, run command below from the directory Composer is installed (Anywhere if Composer is installed globally).

If you see an output similar to the one below, you are ready to go.

Use Composer

Composer is now ready to use. Let's demonstrate its usage through a simple example:

Imagine we have completed an awesome project and we want to generate simulated data, for example, people's names and addresses, to show our client. It would be cool if the data is random and yet makes sense, so the demo would look real. One solution would be to type some fake names and addresses, store them in an array, then pick entries out of the array randomly using array_rand. As you have probably realized, this solution sounds tedious and impractical. What happens if we need hundreds of users' data? We need a savior.

It turns out there is a package on Packagist, which does exactly what we need. The best part is that it is even called Faker.

Let's install Faker using Composer.

From our project root folder, run command:

It will take Composer a few seconds to download the required files. Under the hood, Composer downloads the zip file of Faker from Github. Besides downloading the required package, Composer will also create some internal files, which we will look into later.

Now take a look at our project directory and you should be able to discover some newly created folders and files as shown below:

composer.json
composer.lock
vendor

composer.json

This file describes the dependencies of your project. It is a simple JSON file and shows you what packages are installed in your project.

Whenever you run composer require from command line, composer.json and composer.lock will be automatically updated to reflect package change. Conversely, if you add a package to composer.json file, you run composer install to download the new package. If you want to update all packages' versions to the latest specified by their version constraints, you can run composer update.

There are three basic commands of Composer:

composer require

This command is used to add an individual package to the dependencies. Whenever we need a new package, we can just run it. It is convenient because we do not have to touch the composer.json file at all.

Another usage of this command is to update an existing package's version. For example, we have installed the latest version(1.4.0) of Faker using composer require fzaninotto/faker as Composer fetchesthe latest version of a package if we do not specify its version constraint. Since our application is incompatible with 1.4.0, we need to install 1.2.0 in order to run composer require fzaninotto/faker:1.2 0 . It will download a specific package and update all relevant Composer files accordingly.

composer install

This command first looks for composer.lock file, if it is present, exact version of the packages defined, will be installed and composer.son will then be ignored. If it is not present, the command will check packages defined in the composer.json file and download the latest versions of the packages that match the supplied version constraints. Can you spot the difference? When composer.lock is used, exact versions are downloaded, whereas using composer.json, Composer will always attempt to retrieve the latest version of a package that matches the supplied version constraint. When version constraint is defined as an exact number, both actions have the same result. However this is rarely the case.

This command is used when we begin a new project - we define a list of dependencies and run this command to get all packages installed. Or, when kick-start someone else's project, we check out their code from Github and run this command to get all dependencies installed.

In some deployment strategies, we run this command in production to install the application after pulling its source code from repository.

composer update

This command only reads from composer.json file which is different from composer install . It updates existing packages to the latest versions that match supplied version constraints defined in composer.json. Meanwhile, it downloads any new packages added to composer.json file.

We can use this command to update existing packages' versions, similar to composer require. The difference is that composer require does not require us to touch the composer.json file manually, it feels more intuitive.

The fact that this command only reads from composer.json brings up a common pitfall, which is running this on production. We should never run composer update in production. Here's why:

If your application is working well with Faker 1.2.0 on your local development environment, you push your code to production and run composer update. Without your knowledge, the latest version of Faker has already been updated to 1.4.0, so Composer downloads version 1.4.0 of Faker in production, because you have defined its version constraint as 'fzaninotto/faker: 1.*' in composer.json. As a result, your production is now using a different package from your development. This is not the intended outcome.

We recommend deploying composer.lock along with compose.json and running composer install in production. This will ensure your production has the same packages as your development.

composer.lock

While composer.json file lets us define packages we need using versions constraints, composer.lock tracks exact versions of packages installed in our project. In other words, it stores the current state of our project. This is a very important point to remember.

The fact that composer install reads first from composer.lock, makes it a much safer command to use. Here's why:

If you delete vendor completely from the project, this will remove all packages Composer downloaded. Now run composer install again and it will obtain the exact versions of packages as it previously did.

This brings up our next point. If we are using a version control system such as Git, should we commit composer.lock?

The answer is "It Depends". Most of time we want to make sure everyone is sharing identical source code at anytime. So we will commit composer.lock. This is very common since most of us work with a team. The rare case of not committing composer.lock is when we develop a package(library), because users rarely need to run composer install in our package.

Composer gives us a lot of flexibility in using its commands, however there are a couple of rules we try to follow to prevent liability.

composer install is our friend - use it in production for deployment.

A fair standard Composer workflow:

Defined some dependencies in composer.json: run composer install
Need an individual package: run composer require some/package
Need multiple packages: define them in composer.json file and run composer update
Want to test out one single newly released package: run composer require some/package:new-version
Ready to test out all the latest versions of packages released: run composer update

Autoloading

You have probably used a lot of include/require statements. The problem with These statements is that, they make our code cluttered. And the worst part is, whenever we update our directory structure, we end up doing a lot of find&replace work.

The solution is autoloading. It allows you to define paths to search for classes so you do not have to do it manually with include/require. But of cause, we should keep in mind that under the hood, autoloading is still using include/require.

Now, let's jump back to our awesome project. There is one place we have not really explored yet, and that is the vendor directory created by Composer. By default, Composer downloads all packages to this directory.

Composer also generates a vendor/autoload.php file, which provides autoloading to us for free, making it really easy to use vendor code.

In our case, we want to use Faker so we can simply include the below file and Faker will be autoloaded.

Now we can just start using Faker.

Power of community

You should now have a fair understanding of Composer. Start using it to manage your project's dependencies. We guarantee it will make your and your co-workers' lives much easier. Next time your project needs something, start looking for them on Packagist. Embrace the power of community!

The end

Understanding Design Patterns - Facade

Sat, 03 Feb 2018 04:30:07 +0000

Provides a unified interface to a set of interfaces in a subsystem. Facade defines a higher- level interface that makes the subsystem easier to use.

As a software developer, one main task we all have to do is deployment. Similar to all of us, when Eric was just starting his career as a developer, he was doing all the deployment jobs manually. He was using a pretty standard way to do this: set server to offline mode, transfer source code files, update the database’s schema, and set server back online:

This seemed like the ideal way to do it; the process was easy and straightforward. However, as more and more procedures were being introduced, human errors started happening. New procedures such as running tests before transferring files became more frequent. There was one time when his colleague saw Eric rushing back into the office after he had logged out of work for the day. They asked, “Hey Eric! What's the rush?" Eric replied without breaking his stride, “I forgot to update the database before setting the server back online!” As we all know, human errors are inevitable, but they can be minimized. We realize we need a better solution.

What if we are able to encapsulate all the procedures into one simple method? That is so we will not have to worry about forgetting any step. To update the procedures, we just need to update on place. In this case, we can use the Facade Pattern.

Let us see how it looks in code:

Now every time Eric needs to do a deployment, he just has to do the following:

You may quickly recognize that in reality we are already using something similar to DeployFacade, that is the deployment script. It is an example of the Facade Pattern. In our example, by using Facade Pattern, it provides a unified interface (DeployFacade) to a set of interfaces (Server, FileSystem and Database) in a subsystem. Facade defines a higher level of interface that makes the subsystem easier to use. No more forgetting any step ever again.

The end

Understanding Design Patterns - Adapter

Sat, 03 Feb 2018 04:26:19 +0000

converts the interface of a class into another interface the clients expect. Adapter lets class work together that couldn’t otherwise because of incompatible interfaces.

Today, there are 15 types of electrical outlet plugs in use worldwide. When you travel from China to Singapore, you might find yourself in trouble if you do not have a socket adapter. Marina, who was travelling to Singapore for a symposium, was very upset when she realized that she cannot charge her phone and gadgets in her hotel room because the plug and socket don't match. She went to the reception area and asked the hotel staff if they have any adapters. The hotel staff was quite courteous but they informed her that they don't and Marina would have to buy one from the local hardware.

In Singapore, the outlet plugs in use are type G, whereas electronic devices from China are using the type A plugs. The type G socket interface is not compatible with a type A plug, which expects a type A socket interface. In this case we need to use a type G to type A socket adapter.

This is an example of the Adapter Pattern. Let us see how it looks like in code.

First, we have a TypeAPlug class and a TypeGSocket class:

As we can see, connect() method of TypeAPlug class expects a TypeASocketInterface type and it calls a method connectTwoPins() of TypeASocketInterface type. We need to create a type G socket interface to type A socket interface adapter. We will name it GtypeToAtypeSocketAdatper:

GtypeToAtypeSocketAdatper class implements TypeASocetInterface interface, and it accepts an TypeGSocket class when it is instantiated. The composition-favored technique used here is very similar to the one in the Decorator Pattern. The key difference is that the Decorator Pattern retains the class type of the class it wraps. But the Adapter Pattern changes the class type of the class it wraps to the one clients expects.

Finally, let us see how type G socket is adapter to type A socket and used by type A plug:

In the Adapter Pattern, there are some components to help you get familiar with the pattern:

Adaptee: This is the class, that exists before the adapter class is introduced. In our case, it would be the TypeGSocket class.
Adapter: This is the class, that wraps an adaptee class and makes it compatible with what client class expects. This class decouples adaptee class from client class. In our case, it is the GtypeToAtypeSocketAdatper class.
Client: This is the class that makes requests to the Adapter and receives what it expects. It is not aware of existence of the adaptee class. In our case, it is the TypeAPlug class.

In our example, the Adapter Pattern converts the interface of a class (TypeGSockt class) into another interface (TypeAPlugInterface interface) the clients (TypeAPlug) expect. The Adapter(GtypeToAtypeSocketAdatper) allows class to work together what couldn’t otherwise work because of incompatible interfaces.

The end

Understanding Design Patterns - State

Sat, 03 Feb 2018 04:25:24 +0000

Allows an object to alter its behavior when its internal state changes. The object will appear to change its class.

John works as a customer support representative in a popular telephone support company. In a customer-service-oriented company, the company's priority is to make sure that the customers are satisfied and happy. To improve the service, the company invested a lot of money on improving the support representative’s service. Recent studies show that a support representative’s emotions affect how they perform on the job. John himself admits that his first few words when he answers the phone usually indicates the kind of mood he is in. When he is in a happy mood, he would normally greet the customer with a jolly “Hi there!” or “Hello, How can I help you?” When he is angry and in a dark mood, his answer would be a curt “Hello” or “Yes?” If John is in a moderate mood, he would open the conversation with “Hi” or a mellow “Hello.”

Let's put the above information into code:

The code above is pretty straightforward and can help us study the representative’s behavior. However, as research progresses and more information is introduced, the code may not be sufficient. Research show that a person’s mood will change depending on the number of calls he's had and of course his current mood.

When John picks up five to ten phone calls, his mood will change from “happy” to “moderate,” this is probably because he is getting tired or is getting stressed from the calls. If he gets more than 10 phone calls, his mood will change from “moderate” to “angry,” it is indeed quite taxing to be handling too many support calls.

Let us rework our code to add additional logics:

Do you see anything wrong with the code above? No, there is nothing wrong with it except that it is cluttered with those if-else statements. It does not even look object-oriented to us, and the worst part is that it clearly violates the single responsibility principle (SRP). There are multiple reasons for this class to change. When you have additional logics for either happy state, moderate state, or angry state. It introduces code modification and remember we are just talking about sayHi() function here. What happens when the mood-based conditions apply to every aspect of a sales representative?

Its time for a change. In this case, we are ready to use the State Pattern. the State Pattern allows us to encapsulate the part that varies, which is the sayHi function. It varies depending on the representative’s mood.

First, let us create a StateInterface, which all subsequent states have to implement:

Then we will create three state's classes, and each implements its own logic:

Finaly, we need to rework SupportRep class.

As you can see, the sayHi() function of SupportRep class delegates its responsibility to state class. It no longer violates SRP. Three states classes are still able to change the main class’s state via composition.

Now SupportRep has become cleaner, and if any additional logic needs to be added, it can be done as an in individual state class. Additional functions of SupportRep can be delegated to states classes.

In our example, the State Pattern Allows an object(Support Rep object) to alter its behavior (sayHi function in individual state class) when its internal state changes (changing between HappyState, ModerateState, and AngryState). The object will appear to change its class.

The end

Understanding Design Patterns - Decorator

Sat, 03 Feb 2018 04:24:14 +0000

Attaches additional responsibilities to an object dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

Coffee is a constant in almost everyone's day. The caffeine shot it gives to jump-start the day is something that most people cannot do without. Waking up to the smell of coffee brewing in the kitchen is enough to perk up anyone's day. The aroma, the taste, and the energy boost you get after a cup of coffee has made this dark drink an indispensible part of our mornings. No wonder why coffee shops like Starbucks and the Coffee Bean are doing so well in their business.

A cup of black coffee is served as a beverage without cream or milk, and it looks like this in code:

However, black coffee is not really a popular choice because of its overpowering bitter taste. Most people prefer to have milk in their coffee; this not only subdues the strong flavor of the coffee but also gives a sweet mellow flavor to the drink.

To create it in code, what we would normally do is use subclassing. Inheritance seems to be a natural choice:

Now that we've added milk to our coffee, we realize that its not the only add-on we put in our drink. Some people like sugar, some prefer cream and sugar and some want milk and sugar. What if we need to create all the possible varieties? Supposing cream, milk, and sugar are the three available condiments, then there are six possible ways to make a cup of coffee. For every coffee variant, we will need to create a subclass:

In reality, there are even more variants. Choices can be as simple as less milk or less sugar, but the impact of those variations need to be taken note of. Now when you think about the add-ons like cocoa powder, cinnamon and other flavors that can enhance coffee, this can be a maintenance nightmare.

We will need a better solution. This is when the Decorator Pattern comes in handy. We will create decorator classes that adds condiments to the coffee objects. First, let us create a decorator class that adds milk to a coffee:

Note that, the WithMilkDecorator class still implements Beverage interface as Coffee class does.

Let us also create two other decorators:

Now, instead of having six subclasses of Coffee, we will have three decorators and they will achieve the same goal that we need. For example, to make a cup of coffee with milk and sugar:

Clearly, by using the Decorator Pattern, we create less classes to maintain and avoid introducing bugs with more codes. What's more, Decorator Pattern adds additional feature to the wrapper class at run time, so it is flexible to add/remove features compared to inheritance via subclassing.

In our example, the Decorator Pattern attaches additional responsibilities (milk condiment, sugar condiment and cream condiment) to an object (Coffee object) dynamically. Decorators provide a flexible alternative to subclassing for extending functionality.

The end

Understanding Design Patterns - Composite

Sat, 03 Feb 2018 04:23:20 +0000

Allows you to compose objects into tree structures to represent part-whole hierarchies. Composite lets clients treat individual objects and compositions of objects uniformly.

Agnes has been working at Walmart for more than a year; she started as an inventory assistant and has recently been promoted as an inventory clerk. Agnes’s main job as an inventory clerk is to do daily stock recording. On her third day on the job, Agnes was approached by the manager with a concern. “Agnes, the inventory for the toy cars is inaccurate, not all boxes have the same number of cars inside. It is because some toy cars are bigger than the others so less cars will fit in the box.” After apologizing to the manager, Agnes went back to work. Being new to the job, she realized that this job was harder than she thought, she had to figure out a way to record the boxes accurately.

Below is how Product class looks like:

Below is how Box class looks like:

Below is how Agnes’s job looks like:

The entire inventory process seems to be pretty straightforward; however, that is not the case. In most cases, a big box consists of a dozen of small boxes, and in some cases, a product is packaged with a smaller box. This is quite a task for Agnes, and it often takes more time than it should because she has to sort everything out, creating a different category for the boxes according to their content and the amount of products within. This makes her work more tedious that I should be.

One possible solution to this problem is to place some conditions on the code. However, the packaging for the products may change in the future, and there is no way to tell what the actual contents of upcoming products will be. This makes the possible solution impractical and the codes difficult to maintain.

Agnes needs a better solution, a sustainable solution that is easy to maintain.

This is when the Composite Pattern comes into place. There is a part-whole hierarchy of objects in our case. A box may contain a box or a product. We can make the InventoryClerk class to treat Product object and Box object uniformly using the Composite Pattern.

In the Composite Pattern. there are four elements:

Component: It is the interface that has both Left and Composite to implement. This class defines the abstract functions that the client uses. In our case, the function is getName().
Leaf: It is the class that has no child classes as its name implies. It implements Component interface as mentioned. In our case, Leaf is our Product class.
Composite: It composites abstract Component classes. So it can composite concrete Product class, Composite class or both, besides implementing Component interface. Composite also provides functions for adding, removing, and getting child components.
Client: It treats both Leaf and Composite classes uniformly by calling the common function defined in Component class.

Let us rework our classes. First, we will need to create an interface ProductComponent:

Rework Product class. It needs to implement ProductComponent interface:

Rework Box class. Beside implementing ProductComponent interface, it needs to have functions for adding, removing, and getting ProductComponent:

Finally, rework InventoryClerk class; it has became very lean:

Now that we have applied the Composite Pattern to our case, our code has become much easier to maintain, and it is flexible too. Regardless of how many boxes there are within a box or no matter if the boxes have varying sizes and content, our code will work.

Let us take as an example two toys products wrapped in a small box individually and then the two small boxes are placed into a big box:

For the Inventory Clerk, to record the big box, it will be as easy as this:

In our example, the Composite Pattern allows us to compose objects (Product objects and Box objects) into tree structures to represent part-whole hierarchies. Composite lets clients (InventoryClerk objects) treat individual objects (Product objects and Box objects) and compositions of objects uniformly (via ProductComponent abstraction).

The end

Understanding Design Patterns - Iterator

Sat, 03 Feb 2018 04:22:21 +0000

Provides a way to access the elements of an aggregate object sequentially without exposing its underlying representation.

As a store manager, Eric’s job includes checking in products from each department. There are actually two departments in the store. One is called men's department, which holds products for men, and the other one is called women's department for women's products. Each department stores their products using different storage structures (data structures).

The Men's department stores products using array structure:

The women's department stores products using SqlStack structure:

So for Eric, the store manager, the code would look like this. Pay attention to function checkIn():

Depending on the data structure the department uses, we need to use different way to iterator the storage. This will quickly introduce a problem. Imagine if the women's department decides to use an array to store products too. We will not only need to update the WomenDepartment class, but we will also need to alter checkIn() method. This will apparently violate the single responsibility principle (SRP). This is because a class should have only one reason to change. Here the checkIn() method depends heavily on data structure that the two departments use. It has at least two reasons to change.

What if we can hide the underlying data structure that a department uses to store product and provide a universal way to iterator products? This is when we will need the Iterator Pattern.

Let us rework our code base.

First, we will need to create an interface called Iterator:

The Iterator interface defines two methods that the StoreManager will use to iterate the products.

Let us create a concrete iterator for MenDepartment class:

We need an internal pointer in MenDepartment to keep track of the current index.

Let us create a concrete iterator for WomenDepartment class:

Now we need to create a new method (createIterator) for MenDepartment and WomenDepartment. What this method does is to instantiate a concrete iterator designed previously. So that we can get their iterator directly:

Lastly, let us see how StoreManager has changed. Rest all remain the same, the only place we need to change is checkIn() method, and we also need to add a facilitate method checkInByIterator() to make the code cleaner:

As we can see now, StoreManager is anti-fragile. It does not concern the data structures a department uses to store products. The code is now easier to maintain.

In our example, the Iterator Pattern provides a way to access the elements (products) of an aggregate object (MenDepartment and WomenDepartment objects) sequentially without exposing its underlying representations (Array or SqlStack).

The end

Understanding Design Patterns - Strategy

Sat, 03 Feb 2018 04:21:01 +0000

Defines a family of algorithms, encapsulates each one, and makes them interchangeable. Strategy lets the algorithm vary independently from clients that use it.

Commuting is a part of our daily lives. Every day, when we leave our house for work, we have to choose transportation. As commuters, we have a lot of options - taxi, bus, or train - it really depends on our mood and the situation we are in. Like if you were in a hurry because you woke up late, then you will probably take a taxi. On another day, when you want a no-fuss seat and you have time to spare, then a bus is a good choice. On days when we want to make sure we get to a certain location on time without the hassle of getting stuck in traffic, we would take a train.

This is a perfect sample of the Strategy Pattern.

A bus, a train, and a taxi are all modes of transportation but they of course vary in many ways. They are different from one another in terms of cost, and they take different routes to get you to your destination. They are the same because they are all ways for you to get to your destination, although in varying length of travel time. They all belong to one family, which is transportation.

Let us first create a Transportation interface:

Create a Bus class that implement Transportation interface:

Create a Train class that implement Transportation interface:

Create a Taxi class that implement Transportation interface:

Lastly, we need to create a Passenger class, that represents us:

Let us see, how Passenger uses different transportations in a context:

Bus, Train and Taxi classes vary independently from Passenger class, because they all implement Transportation interface.

In our example, by applying the Strategy Pattern, we defined a family (Transportation family) of algorithms (Bus, Train and Taxi), encapsulates each one (Passenger class is only aware ofTransportation interface), and makes them interchangeable (They implement common interface). Strategy lets the algorithm vary independently from clients (Passenger class) that use it.

The end

Understanding Design Patterns - Template Method

Sat, 03 Feb 2018 04:19:34 +0000

Defines the skeleton of an algorithm in a method, deferring some steps to subclasses. Template Method lets subclasses redefine certain steps of an algorithm without changing the algorithm’s structure.

Managing the daily itinerary of company employees can be a time-consuming task. It would be much easier if the daily tasks can be programmed to occur automatically using a program. Mark has been working for Yahaa Inc for the past four years; he is a programmer, and his daily routine is exclusive doing programming-related tasks. Elisa is a marketer for the same company; like Mark, she has her daily routine set, and hers is exclusive doing marketing tasks.

As a programmer, Mark's daily routine in the company looks like this:

When Mark the programmer enters the company, the first thing he has to do is to mark his attendance in the attendance tracking system; this makes sure that he will be paid for the day (markAttendance()).
After that, he then proceeds to do his job according to his role (doingProgrammingTask()).
Finally, he writes a detailed daily report about what he has completed for the day (reportDailyCompletion()).

Now Elisa the marketer has almost the same routine as Mark except for step two. As a marketer, the second part of routine is to do marketing-related tasks.

We can easily spot the code duplication in those two classes above. Both programmer and marketer share some common procedures.

How can we make the code better?

We can obviously make it better if we can define some common procedures in the super class but still give flexibility to the subclasses to define its own function. This is the time to apply the Template Method Pattern.

It is time to rework our code. Let's define an abstract class with some predefined functions:

This class looks very similar to either Programmer or Marketer class, except we have removed the function that varies between the two classes and replace it with an abstract class doWork().

Now let us rework both Programmer and Marketer classes:

As we can see, both Programmer and Marketer classes have become much cleaner and there is no more code duplication.

In our example, we define the skeleton of an algorithm in a method (workRoutine() method in Employee class), deferring some steps (doWork()) to subclasses (Programmer and Marketer classes). Template method (doWork() method in Employee class) let subclasses (Programer and Marketer class) redefine certain steps (doWork()) of an algorithm without changing the algorithm's structure.

The end

Understanding Design Patterns - Command

Sat, 03 Feb 2018 04:18:29 +0000

Encapsulates a request as an object, thereby letting you parameterize other objects with different requests, queue or log requests, and support undoable operations.

Battles are meant to be won, and no battle can be won without a good plan or strategy. Most battles that are lost are those where the commander orders his men into the battlefield without any plan or, worse, without the capacity to command his men while they are in battle. The result is havoc with every man fighting for himself instead of the group fighting as a group and protecting each other. A carefully laid out plan, with each man knowing his position and what to do at the right time, is the perfect battle plan. Have you ever thought of how battlefield plans are made? If we simulated it in our code, do you think it would be complicated or interesting? As it turns out, it is quite interesting, and if programming was used in battle, it would be the simplest thing to win one battle after another.

In this chapter, we will see how battle plans are made with programming using Command Pattern.

In a typical Command Pattern, there are five elements. They are command interface, client, receiver, invoker, and concrete command.

We will explain them in detail later in the chapter.

But first, let us complete the code for our battle plan:

Now let us use as an example the four elements in the Command Pattern:

Let us rework the code.

Command interface: it defines a common method, so all concrete command classes have to implement it.
Client: it is responsible for creating concrete command objects and receiver objects. In our battlefield example, the commander is the client.
Invoker: it contains concrete command objects and call the execute() method at some point of time. Please note that it holds concrete command objects by its interface(Command interface), it does not actually know the exact type of objects it holds (Programming to abstraction), so only execute() method of concrete command objects is exposed to it. In our battlefield example, the battle plan is the invoker.
Receiver: it performs the specific tasks. In our battlefield example, Gunner is the receiver.
Concrete Command: this class implements the Command interface and implement the execute() method. Its purpose is to encapsulate the request as an object. To accomplish this, it binds a set of receiver’s actions together and exposes the execute()method to the outside. In our battlefield example, GunnerFireCommand is a concrete command.

In our battlefield example, by using Command Pattern, we encapsulate a request (fire()method of Gunner class) as an object (GunnerFireCommand). It lets us parameterize other objects with different requests, queue, or log requests (commander is able to make different battle plans with different commands, for example, he can make a command to request a sniper and a gunner to attack together).

The end

Understanding Design Patterns - Observer

Sat, 03 Feb 2018 04:17:26 +0000

Defines a one-to-many dependency between objects so that when on object changes state, all of its dependents are notified and updated automatically.

Mary just became a new Mom! Like all new mothers, she is very excited about her new baby boy, Nathan. Life just turned very rewarding but also challenging for Mary. As a new mom she is experiencing the joys and challenges of caring for a new born baby. The baby is a light sleeper and easily gets disturbed by small noises grown-ups make. So to make sure the baby is well rested and happy, Mary and her husband have decided to turn their guest room into a nursery. This is perfect for the baby with a little sacrifice on Mary's end because she has to check on the baby several times at night to make sure everything is fine.

This is how it looks like from the coding point of view:

The baby is doing fine in his new nursery, but her husband noticed that Mary is looking a little tired. “Honey, why do you look so tired this morning?” he asked his wife. Mary explained that she has to make several trips to the baby's room last night to make sure that the baby is fine. Obviously, this nightly routine of getting up at odd hours to check on little Nathan is becoming exhausting for Mary. She is losing sleep and feels tired in the morning. It will only be a matter of time until Mary will be sleep lagged and too exhausted during the day to take care of the baby. This can take all the fun out of having a new baby. She knows that she needs to find a way to improve this because she can get stressed and even sick. Luckily, her good friend Rose came to visit and introduced her to a tool called baby audio monitor. The audio monitor is placed inside the baby's room, and the moment little Nathan cries or makes a fuss, the audio monitor gives out a sound to tell Mary that her baby needs her. Mary was so happy with this new tool because instead of pro-actively waking up to check on the baby, she can sleep soundly and only wake up to check on Nathan if the monitor tells her she needs to. Without knowing, Mary has used the Observer Pattern here. Let us see how it applies. With the help of the baby audio monitor, Mary registered herself as an observer of the subject (Nathan). Whenever the subject’s state changes (Nathan cries or makes any noise), the observer(Mary) is notified automatically.

Let us rework the code.

First, we need to create two interfaces. The Observable interface, which is the interface of the Subject, and the Observer interface, which is the interface of Observer.

Observable:

Observer:

Then we need to modify Son class to implement Observable interface:

And Mother class needs to implement Observer interface:

Second, let us register Mary as an observer of Nathan at run time.

With the help of the Observer Pattern, Mary has improved her daily routine and is now enjoying mommy life more. Some nights, she does not even have to wake up at all. As Nathan grows up, Mary will certainly no longer need to use the baby audio monitor. That is when she can remove herself as an observer of her son:

The end

Understanding Design Patterns - Singleton

Sat, 03 Feb 2018 04:16:24 +0000

Ensures a class has only one instance, and provides a global point of access of it.

The health clinic has recently offered free medicines if you come in for a checkup. The promotional stint is working so well, and it is just a matter of time before the front staff will have more patients than they can handle. Everyone was so busy that instead of having an organized waiting room, it was a total chaos. After several days of patients flooding in the receptionist, Anne was frustrated and stressed, she went into the the clinic head's office and blurted, "We need to organize the patients, or we are going to go down the drain".

The head of the clinic called a meeting and asked the staff for suggestions, and they came up with the idea of a ticketing system. The aim was to get the patients organized so that it can ease the front staff's task from doing manual registration.

Let us see how we can help.

Before we do any code design, we need to know the condition and capability of the the health clinic. The clinic has only one physical printer.

We could design our TicketPrinter class similar to:

The printerTicket() method will have to check the paper’s status every time it does the print job. If it runs out of paper, it should automatically load more (let's assume that is possible).

Looks like we need to check the ink’s status too. So let us add that also:

It seems that we have a working TicketPrinter, but before we move on, let us examine the situation again. Since we have only one physical printer in the clinic, what will happen if by accident we create two instances of TicketPrinter class. Because they are using the same shared printer, it will surely cause a big problem.

You may argue that we can always just create another instance of TicketPrinter but how can you make sure everyone follows that? So I propose we use the Singleton pattern in this case.

Let us rework TicketPrinter class a bit:

Because constructor of TicketPrinter has become private it can not be instantiated by constructor as normal. To obtain an instance of TicketPrinter, we instead do:

As you can see. Singleton Pattern has ensured that there is only one existence of TicketPrinter’s instance at any point of time across the system.

The end

Understanding Design Patterns - Abstract Factory

Sat, 03 Feb 2018 04:15:17 +0000

Provide an interface for creating families of related or dependent objects without specifying their concrete classes.

Business is bombing at Dragon Inc. and the CEO wants to franchise all overseas branches. The first problem that comes to his attention is how they can ensure the quality of the products. They do not want franchisees to cut costs and use low quality components. Low quality toys would definitely destroy Dragon brand’s reputation. So, the CEO wants to franchise the business, but they still want to have factories located in each location to provide components. Developers gather and start to brainstorm solutions. There are three types of components used by toys; engines, wheels and rotor blades. For example, a toy car needs an engine and four wheels, while a toy helicopter uses a rotor blade and an engine.

Let us first create an abstract factory class, the back bone of all concrete factories. Note that the abstract factory essentially consists of a group of factory methods:

Then create a location specific factory (The concrete factory for creating concrete components). Let us create one for New York:

The Toy class also needs to be modified. Engines, wheels and rotor blades need to be clarified, and prepare() function needs to be abstract (This method will be implemented by a concrete class. In the implementation, a child class uses its location specific ComponentsFactory to create concrete components). Modify Toy class:

Let's modify the NyCar and NyHelicopter classes to implement prepare() method.

Lastly factory method of concrete ToysFactory needs to be modified. This is where to added location specific ComponensFactory. Let's complete the code for NyToysFactory:

Now each franchise will have their components supplied by a component factory, which is controlled by Dragon Inc. HQ.

Throughout the course, we've built a franchise framework, giving Dragon Inc. control and enough freedom for each franchise to do what they're good at.

The end

Understanding Design Patterns - Factory Method

Sat, 03 Feb 2018 04:12:57 +0000

Define an interface for creating an object, but let the classes that implement the interface decide which class to instantiate. The Factory method lets a class defer instantiation to subclasses.

With Simple Factory in place, developers are now enjoying their day at Dragon Inc. Despite the thorough discussion of toys, we haven't really looked the toy classes yet. Toy is an abstract class with the functions prepare(),package(), and label().

The concrete class Car and Helicopter inherit from super class Toy. They are pretty straightforward.

Car:

Helicopter:

Back to Dragon Inc. The CEO walks in to the developers' office with a smile on his face, but we know there's bad news coming. The CEO happily announces that Dragon Inc. is going to open several factories in US. They'll be located in different States, and the first two factories will be in New York and California. All toys will be produced locally with their own properties, which means that for the same type of toy Car, the ones produced in New York will be NyCar and those from California will be CaCar. Simple Factory will make this task a cinch for the development team. All they need to do is create a location specific SimpleFactory class and a location specific ToysFactory class. Simple Factory simplifies the task and makes the developers' job easy.

For example, for New York we could do:

The developers finish the new code quickly and hand it over to the US factories. After two weeks, the phone starts ringing in the developers’ office because the New York factory was having production issues. It turns out that the NyToysFactory class has been modified by developer of the remote branch because staff there do not want to do packaging and labeling work. They have modified produceToy() function by removing label() and package() functions.

It seems like Simple Factory won't work in this scenario. We don't want branches in US to be able to modify produceToy() function. produceToy() should consist of a set of standard procedures and the branches should only be responsible for creating location specific toys. What if they can create an abstract class? And the abstract class they created will have a concrete produceToy() method which will implement a set of standard operating procedure that all branches have to follow. Inside the produceToy(), it calls its own abstract method createToy() to obtain a toy object. This way createToy() is able to encapsulate object creation and, since it's abstract, it delegates the creation to its subclasses.

That sounds like exactly what they need in their case:

Now in New York branch, all they need to do is to implement createToy() method in the subclass:

For the factory in California, they have to create another subclass CaToyFactory to produce toys locally:

In the code above, function createToy() in ToysFactory class is called factory method. Factory Method pattern defines an interface(createToy) for creating an object. But it delegates the actual creation to subclasses(NyToysFactory and CaToyFactory). This way subclasses decide what object to create.

The end

Understanding Design Patterns - Simple Factory

Sat, 03 Feb 2018 04:00:58 +0000

This series has been written for developers new to software design patterns and those who find software design patterns difficult to understand.

Dragon Inc. is one of the top toy manufacturers in China. In fact, they're a pioneer in toy manufacturing. They started production at a time when few toys were being produced commercially. Hence, they dominated the market and became the leader in the toy production industry.

Their produceToy() function looked like below:

Initially they only manufactured toys "Car" and "Helicopter". For this simple task the function worked well and everyone was happy. But not long after that, a cool new toy, the "Jumping Frog" was introduced by the design team. Jumping Frog looked cool and they knew it was going to sell really well, it was time to change the productToy() function:

As the business grew, more and more toys came into production and the CEO was very happy with the business's financial growth. However, in the development team's office the nightmare was just beginning. The developers were tasked to modify the produceToy() function with the introduction of every new toy. It has violated the open/close principle. Which states "software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification". Every new toy brought in modifications of the produceToy() function.

It was time for refactoring. Let's us take a look at the situation here. What was the real issue with produceToy() function? Concrete classes were instantiated inside ToysFactory and messed up the produceToy() function. The ToysFactory class was tied to the concrete classes of toys. That's the issue.

First, let us create a class to encapsulate the concrete class instantiation.

Second, we'll use SimpleFactory with our brand new class longer need to touch to create the desired toys:

With our brand new class SimpleFactory, things just became cleaner. The Developers no longer need to touch SimpleFactory when a new toy was introduced, and they'll use SimpleFactory to produce a new toy instead of using the former messy code.

Tha is the Simple Factory. It is not a real design pattern per se, but it's a useful technique that you can apply to your own needs. With Simple Factory, concrete class instantiation is encapsulated. It decouples the client code from the object creation code.

The end

Data Structure and Algorithm - Shell Sort

Mon, 14 Aug 2017 06:48:19 +0000

In this tutorial, we will learn a simple sorting algorithm - Shell Sort.

Table Of Content

Problem to Solve
Pseudocode
PHP Implementation
The end

1. Problem to Solve

Given a list of numbers as shown below, please sort them in ascending order.

Requirements:

You are required to use Shell Sort algorithm when sorting the numbers.
You are required to implement the algorithm in PHP language.

2. Pseudocode

Shell Sort is a generalisation of Insertion Sort. Unlike Insertion Sort, instead of comparing contiguous items, it breaks the master list into several sub-lists using an interval i (which is known as the gap), then sorts the sub-lists with Insertion Sort.

We repeat the steps above until the gap becomes 1, then we essentially apply a standard Insertion Sort.

Apparently, the gap sequence plays an important role in this sort algorithm. Unfortunately, there is no perfect gap sequence, so to speak. Different researchers have come out a couple of different gap sequences, their performance depends heavily on the input data size.

Some popular gap sequences:

Shell Sequence: FLOOR(N/2k)
Pratt Sequence: 2p3q
Knuth Sequence: (3k â€“ 1) / 2

We are using Shell Sequence in this tutorial.

Pseudocode of Shell Sort algorithm can be written as follows:

3. PHP Implementation

We need a FOR loop and a WHILE loop. We are using the FOR loop to iterate the master list and the WHILE loop to locate the position to insert the item.

The implementation is similar to Insertion Sort, except that we are comparing items that are $gap apart until the $gap values become 1. Then we perform a standard Insertion Sort.

4. The End

If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
If you have questions or find our mistakes in above tutorial, do leave a comment below to let us know.

Data Structure and Algorithm - Selection Sort

Mon, 14 Aug 2017 06:46:38 +0000

In this tutorial, we will learn a simple sorting algorithm - Selection Sort.

Table Of Content

Problem to Solve
Pseudocode
PHP Implementation
The end

1. Problem to Solve

Given a list of numbers as shown below, please sort them in ascending order.

Requirements:

You are required to use Selection Sort algorithm when sorting the numbers.
You are required to implement the algorithm in PHP language.

2. Pseudocode

Selection Sort works by maintaining a sorted sub-list, finding the smallest item from the master list and swap it to the last element of the sub-list until all items are sorted.

The sorted sub-list's length is increased by one, whereas the master list's length is shrunk by one after each swap.

Pseudocode of Selection Sort algorithm can be written as follows:

3. PHP Implementation

We need an outer FOR loop to iterate through the master list and an inner FOR loop to find the smallest item from the master list.

Take note that the inner loop starts from i.

4. The End

Data Structure and Algorithm - Quick Sort

Mon, 14 Aug 2017 06:45:19 +0000

In this tutorial, we will learn a simple sorting algorithm - Quick Sort.

Table Of Content

Problem to Solve
Pseudocode
PHP Implementation
The end

1. Problem to Solve

Given a list of numbers as shown below, please sort them in ascending order.

Requirements:

You are required to use Quick Sort algorithm when sorting the numbers.
You are required to implement the algorithm in PHP language.

2. Pseudocode

Quick Sort is also a divide and conquer algorithm, similar to Merge Sort. It works by choosing an element(pivot) from the list and placing elements that are less than the pivot on its left side and elements that are greater than the pivot on its right side. We repeat the steps for both left side and right side until the list can no longer be divided.

Choosing a pivot can be tricky, normally we just use the first or the last element.

Pseudocode of Quick Sort algorithm can be written as follows:

3. PHP Implementation

As we can see, we are using recursion for this algorithm. Typically, a divide and conquer algorithm implies the algorithm can be written recursively.

Quick Sort is indeed very simple to implement as a divide and conquer algorithm.

4. The End

Data Structure and Algorithm - Merge Sort

Mon, 14 Aug 2017 06:43:08 +0000

In this tutorial, we will learn a simple sorting algorithm - Merge Sort.

Table Of Content

Problem to Solve
Pseudocode
PHP Implementation
The end

1. Problem to Solve

Given a list of numbers as shown below, please sort them in ascending order.

Requirements:

You are required to use Merge Sort algorithm when sorting the numbers.
You are required to implement the algorithm in PHP language.

2. Pseudocode

Merge Sort is a divide and conquer algorithm. It works by continually splitting a list in half until both halves are sorted, then the operation merge is performed to combine two lists into one sorted new list.

When splitting a list, we consider the list is sorted if it contains zero or one element.

Split:

Merge:

Pseudocode of Merge Sort algorithm can be written as follows:

3. PHP Implementation

As we can see, there are two procedures in this algorithm. This leads us to two PHP functions, where the first function(mergeSort) involves a recursion.

We have followed the pseudocode strictly to implement the algorithm in PHP. The only parts that we want to highlight are a couple of built-in PHP array functions:

array_slice: It extracts a slice of the array. This function is handy when we want to a certain part of the array.
array_shift: It remove an element from the beginning of an array. This function is handy when we want to remove the first element of the array.

4. The End

Data Structure and Algorithm - Insertion Sort

Mon, 14 Aug 2017 06:40:28 +0000

In this tutorial, we will learn a simple sorting algorithm - Insertion Sort.

Table Of Content

Problem to Solve
Pseudocode
PHP Implementation
The end

1. Problem to Solve

Given a list of numbers as shown below, please sort them in ascending order.

Requirements:

You are required to use Insertion Sort algorithm when sorting the numbers.
You are required to implement the algorithm in PHP language.

2. Pseudocode

Insertion Sort works by maintaining a sorted sub-list, extracting the master list's items one by one and inserting them into a the sub-list until all items are moved from master list to the sub-list.

Pseudocode of Insertion Sort algorithm can be written as follows:

3. PHP Implementation

We need a FOR loop and a WHILE loop. We are using the FOR loop to iterate the master list and the WHILE loop to locate the position to insert the item.

The only piece that needs a bit of explanation is the probably the WHILE loop. Pay attention to the conditions of the loop, besides the constraint of the sub-list's length, we also need to make sure that we do not run the loop when we extract the first element ($positionFound=0).

4. The End

Data Structure and Algorithm - Bubble Sort

Mon, 14 Aug 2017 06:36:13 +0000

In this tutorial, we will learn a simple sorting algorithm - Bubble Sort.

Table Of Content

Problem to Solve
Pseudocode
PHP Implementation
The end

1. Problem to Solve

Given a list of numbers as shown below, please sort them in ascending order.

Requirements:

You are required to use Bubble Sort algorithm when sorting the numbers.
You are required to implement the algorithm in PHP language.

2. Pseudocode

Bubble Sort works by comparing two values at a time and does it pair by pair. And it iterates until all elements are in place. After each iteration, at least one element is moved to the end of the list. Below is an illustration of the first iteration.

Pseudocode of Bubble Sort algorithm can be written as follows:

The inner loop is considered one iteration and the outer loop makes sure we iterate enough times to sort the list.

3. PHP Implementation

To implement Bubble Sort in PHP, all we need is two loops. Note that the termination of both loops is: the length of the list - 1. This is to prevent from accessing un-indexed element.

4. The End

Your first GraphQL API - Search

Mon, 15 May 2017 22:06:01 +0000

Search is another complementary technical when working with a large dataset. It takes an existing list, and removes items based on criteria that match/don't match.

In this tutorial, we are going to implement a search for our data table.

Table Of Content

Understanding GraphQL searching mechanism
Implementing searching
The end

1. Understanding GraphQL searching mechanism

Search happens when we pass in a search parameter and it scans multiple fields behind the scene to get the data we want. We can use the same idea to implement filters, except that filters work in one single field.

Search can go together with pagination or alone. In our case, we are going to combine search and pagination.

2. Implementing searching

An imaginary searching request would look like this:

Note that we are using a generic "search" parameter for the query argument:

Since in a search request, we are trying to narrow down the result, there is no need to paginate the result.

Let's add "search" parameter to the ArticlesConnection field.

Modify build method of ArticlesConnection class:

Next step is to make resolve method capable of searching the results based on our request. Normally this method will delegate to the other service class from business layer, and the service class will search the results with some sort of database calls. However, because our fake repository class simply returns a static array, we are going to sort with PHP array method array_filter.

Modify resolve method of ArticlesConnection class:

That is all the change we need for ArcilesConnection class and the final file should be as shown below:

Lastly, we need to create a simple request to search the result using "search" parameter:

Create a new file tutorial-search.php:

Access the page from the browser of your choice via the URL http://your-local-php-server/tutorial-search.php.

You should expect a JSON output as shown below if you have followed this tutorial correctly:

Try to change the "search" parameter's value and see how GraphQL searching reflects.

4. The End

Next tutorial, we are going to show you how to implement nested queries in GraphQL and see how GraphQL loads data dynamically on the fly.
If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
If you have questions or find our mistakes in above tutorial, do leave a comment below to let us know.

Your first GraphQL API - Sorting

Sat, 13 May 2017 22:50:40 +0000

Similar to pagination, sorting is another complementary technical for loading large data set.

In this tutorial, we are going to implement sorting for our articles table.

Table Of Content

Understanding GraphQL sorting mechanism
Implementing sorting
The end

1. Understanding GraphQL sorting mechanism

The mechanism behind sorting is much simpler comparing to pagination. We pass in a field and its order to the request and we get the results accordingly.

In most cases, sorting goes together with pagination and we are going to do the same for our example.

2. Implementing sorting

An imaginary sorting and pagination request would look like this:

The only additional code block is the sort parameter:

GraphQL Extensions provides reusable classes for sorting similar to pagination.

First step is to add available sort parameters to the ArticlesConnection field. To keep our tutorial simple, we will make "id" field available as the only sort parameter.

Modify build method of ArticlesConnection class:

We are using the SortingParamsType class from GraphQL Extensions to build the sorting parameter.

Next step is to make resolve method capable of sorting the results based on our request. Normally this method will delegate to the other service class from business layer, and the service class will sort the results with some sort of database calls. However, because our fake repository class simply returns a static array, we are going to sort with PHP array method uasort.

Modify resolve method of ArticlesConnection class:

Note the value of "DESC" is -1 and "ASC" is 1 from $args.

That is all the change we need for ArcilesConnection class and the final file should be as shown below:

Lastly, we need to create a simple request to sort the result using id field:

Create a new file tutorial-sorting.php:

Access the page from the browser of your choice via the URL http://your-local-php-server/tutorial-sorting.php.

You should expect a JSON output as shown below if you have followed this tutorial correctly:

Try to change the order parameter's value(DESC or ASC) and see how GraphQL sorting reflects.

4. The End

Next tutorial, we will implement search feature.
If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
If you have questions or find our mistakes in above tutorial, do leave a comment below to let us know.

Your first GraphQL API - Pagination

Wed, 03 May 2017 06:20:01 +0000

Pagination is a common technique for loading large data set. It provides good user experience without sacrificing server performance.

In this tutorial, we are going to implement pagination for our data table.

Table Of Content

Creating more data for pagination
Understanding GraphQL pagination mechanism
Implementing pagination
The end

1. Creating more data for pagination

It may cause a performance issue if you have a huge amount of records in your database and you try to load them at once. The idea of pagination is to ease server from loading huge amount of data at once, by allowing users to navigate all your records page by page.

We need to create more records to demonstrate pagination properly in this tutorial. Open ArticlesRepository file and let's add some more records:

src/Repository/ArticlesRepository:

2. Understanding GraphQL pagination mechanism

There are a number of different ways of implementing pagination in general. Whereas in GraphQL, the best practice is using cursor based pagination.

There is a full page explaining what cursor based pagination is in GraphQL official page. We encourage that you take look at it and understand the basis of it. However do not worry about too much if you are not able to get the full understanding of it at first try, we will go through the process of implementation later on.

In short, cursor based pagination returns cursors along with data records as well as some page related information such as whether it has reached the end, has previous page, has next page and so on.

3. Implementing pagination

An imaginary pagination request would look like this:

As you might have noticed. Some parts of the request have some arbitrary names such as edges, node, cursor as well as pageInfo. They seem reusable and we can make some generic class for them.

It turns out that those pagination related classes are indeed created by someone else and make them into a generic package.

The package is called GraphQL Extensions and it provides a lot of useful utility classes for youshido/GraphQL.

Install GraphQL Extensions:

The algorithm for implementing GraphQL pagination is explained at https://facebook.github.io/relay/graphql/connections.htm#sec-Pagination-algorithm. Basically two directions we can go when traversing with a cursor and they are forward and backwards. And the algorithm is around how we deal with the directions. Read the article and get a rough idea how the algorithm works, it is actually quite straightforward.

With a rough idea of the algorithm in mind, create a field class ArticlesConnections that will resolve the pagination request:

We will run through each method from ArticlesConnection class:

getType(): It addresses the return type of the field, which is a cursor based pagination result. CursorResultType is the reusable class that does the actual work.
build(): Here yet we used another utility class that helps us set available arguments for pagination.
resolve(): You should know by now, this is the resolver method that returns results based on the request. Normally, this method will delegate to the other service class from business layer, and the service class will trigger database calls based on the algorithm mentioned above. However, because our fake repository class simply returns a static array, we can use another utility class ArrayConnection from youshido/GraphQL. The method looks at an array and filter results with request's arguments. It uses the base64 value of array index as the cursor value.

The last thing we need to do is to add ArticlesConnection to the schema. Meanwhile, we will create a simple request to our schema:

Create a new file tutorial-pagination.php:

Access the page from the browser of your choice via the URL http://your-local-php-server/tutorial-pagination.php.

You should expect a JSON output as shown below if you have followed this tutorial correctly:

Try to change different arguments (first, after, last and before) and see how GraphQL cursor based pagination reflects.

4. The End

Next tutorial, we will implement sort feature.
If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
If you have questions or find our mistakes in above tutorial, do leave a comment below to let us know.

Your first GraphQL API - Introduction

Wed, 03 May 2017 06:19:04 +0000

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

In a nutshell, GraphQL provides a few significant benefits to making the life of API development easier:

Ask for what you need, get exactly that.
Get many resources in a single request.
Describe whatâ€™s possible with a type system.
Move faster with powerful developer tools.
Evolve your API without versions.
Bring your own data and code.

Head to official site if you want to read about more the benefits GraphQL brings for us. In this series of tutorials, we will start from the basics of building GraphQL API then slowly evolve to more advanced topics.

Table Of Content

Setting the Goal
Installing the Youshido/GraphQL package
Reading an Article with ID
The end

1. Setting the Goal

The library that we are going to use in these tutorials is Youshido/GraphQL. It is a package that will help us implement GraphQL without re-inventing the wheel. Youshido/GraphQL is a very well written and maintained project. Its excellent Object-Oriented design makes it super easy to implement GraphQL in OOP fashion and that is the main reason we have chosen to work with Youshido/GraphQL over other PHP GraphQL implementation.

We will be using the OOP fashion of Youshido/GraphQL across all tutorials. We believe OOP makes the code easy to maintain and simple to explain the concepts.

We are going to build a GraphQL API for a simple blog. This blog has a series of articles and each article belongs to an author. Features of our API provides include read, write, pagination, search and so on. To make these tutorials focused, we will skip stuff like user authentication, sophisticated business logic and other framework related stuff.

To keep things clear and focused, we are not going to use Database. However in reality, mostly you store articles and authors records in some sort of Database.

Just keep in mind, the whole purpose of these tutorials is to demonstrate how we can use the package Youshido/GraphQL to implement GraphQL for our own application.

2. Installing the Youshido/GraphQL package

Create a folder blog to hold our code sample.

Then we will install the Youshido/GraphQL package using Composer. Navigate to blog folder and run command as show below:

Create three more sub-directories under src folder:

src/Repository: This directory stores some fake repositories that will give us some static articles and authors' records. As mentioned earlier, we are not going to use Database in these tutorials. These fake repository classes pretend to be your real repository classes.
src/Field: This directory stores Youshido/GraphQL Field classes.
src/Type: This direcotry stores Youshido/GraphQL Type classes.

We will use Composer to manage our own classes' auto-loading, add following content to the bottom of composer.json file:

Run the following command from your command line interface to refresh Composer loader:

Complete our fake repository classes by copying following content to their respective files:

src/Repository/ArticlesRepository.php:

src/Repository/AuthorsRepository.php:

3. Reading an article with ID

In a quick summary, GraphQL is a query language and it works by defining a schema that describes how and what data can be queried by clients.

There are two types of Operations in GraphQL:

Query: a read-only request that is not supposed to do any changes on the server.
Mutation: a request that changes(mutate) data on the server and followed by a data fetch.

We are going to create a Query that will allow us to read an article with its ID.

The first thing we need to do is to create an ArticleType class as shown below:

src/Type/ArticleType.php:

Type classes in Youshido/GraphQL define the fields and their values' types that a Type possesses.

Next, we need to do is to create an ArticleField class as shown below:

src/Field/ArticleField.php:

Field classes in Youshido/GraphQL will resolve users' request and respond with data types defined above in Type classes. We also define acceptable arguments in Field classes.

Lastly, we will define a schema attached with ArticleField. Meanwhile, we will create a simple request to our own schema right from PHP:

Create a new file tutorial-introduction.php:

Access the page from the browser of your choice via the URL http://your-local-php-server/tutorial-introduction.php.

You should expect a JSON output as shown below if you have followed this tutorial correctly:

Try to change the ID argument or add other fields, see how GraphQL gives you exactly what you ask.

4. The End

Now we have set our goal clearly and had our first simple GraphQL end point. Next tutorial, we will implement a Field that can resolve a list of articles and explain how we can accomplish pagination in Youshido/GraphQL.
If you like our post, please follow us on Twitter and help spread the word. We need your support to continue.
If you have questions or find our mistakes in above tutorial, do leave a comment below to let us know.

How to integrate Facebook login with CakePHP 3

Mon, 01 May 2017 15:23:36 +0000

Previously, we have learned how to integrate Facebook login using a plugin called Facebook Login. A lot of things have changed since then, include Facebook SDK and the maintenance of Facebook Login plugin. It has become obviously that we need a new way to integrate Facebook login with CakePHP application.

In this tutorial, we will show you how to integrate Facebook login with CakePHP 3 application using another CakePHP plugin.

Table Of Content

Setup Users Table
Setup CakePHP HybridAuth Plugin
Setup Controller
Setup Event Listener
Setup View
The End

1. Setup Users Table

A database table is required to store users' information such as email, password and so on. To keep it simple, we will create a very simple users table. It contains fields required to demonstrate Facebook login only.

If your users table has fields, as shown above, it should work for this tutorial. You can use your own users table in that case.

2. Setup CakePHP HybridAuth Plugin

CakePHP HybridAuth Plugin is a wrapper around HybridAuth library. HybridAuth library builds an abstraction layer on top of various social login. Which makes the task of integrating social login a breeze.

Install

Install CakePHP HybridAuth using Composer:

Load

Load the plugin using Bake command:

This will basically append a line of code as shown below to your app's config/bootstrap.php. So you can do it manually if you wish to.

Configuration

Make a config file config/hybridauth.php:

Replace "facebook-id" and "facebook-secret-key" with your own. If you do not know where to find them, refer to this link.

In some case, you might wonder if you could place this configure values in other config files. The answer is yes. As long as you make sure HybridAuth config values exist. This plugin will happily pick them up.

3. Setup Controller

Next, we need a controller action to allow users to log in.

Create src/Controller/UsersController:

A caveat here. Do not place any special logic after the $this->Auth->identify() call. Because this method is not guaranteed to return, it redirects users away to the social site for authentication.

One more step for the controller work. Add CakePHP HybridAuth's authentication handlers to our application's auth component.

Add the handler in app/AppController.php

4. Setup Event Listener

The event HybridAuth.newUser will be fired if CakePHP HybridAuth plugin could not find a user record from the users table. So an event listener is needed to create a brand new user record.

Add an event listener in app/AppController.php

Note that we created a random password using current timestamp. This way, we can avoid having an empty password.

5. Setup View

There is not much to setup in a view, besides understanding how to create a login link.

In HybridAuth library, a social login URL follows current format:

http://your-website-url/login?provider=facebook

In CakePHP, we can generate the link above with HtmlHelper:

For now, your application should be integrated with Facebook login. Try it out and enjoy the benefits it brings for your users.

6. The End

Preview email with DebugKit in CakePHP 3

Mon, 01 May 2017 15:17:16 +0000

The ability to preview an email's look and feel during development is a huge time saver for developers.

The de-facto CakePHP development tool DebugKit, shipped along with CakePHP 3, already provides a way to preview an email during development. It renders the email right inside the browser so that we can edit the email view and refresh the browser to get instant feedback.

In this tutorial, we introduce you DebugKit mail panel, a way to preview your email during development without actually sending it.

Table Of Content

Installation
Create an Email with Mailer class
Create MailPreview class
The End

1. Installation

Email preview only works for CakePHP 3.1+. So you are out of luck if you are in an older version.

Install DebugKit 3+ via composer:

Load the plugin via Bake command:

Now you should be able to see DebugKit toolbar showing at the bottom of your application.

If for some reasons, it does not show up. Run the command below, it is to make sure DebugKit's assets(js/css files) can be loaded properly.

2. Create an Email with Mailer

Email preview is implemented with MailPreview class and MailPreview integrates with CakePHPâ€™s Mailer class. Your email needs to be implemented using Mailer class in order to get the preview feature.

Create an email using the Mailer class under src/Mailer/UserMailer:

If you are not sure how to use Mailer class, take a look at https://book.cakephp.org/3.0/en/core-libraries/email.html#creating-reusable-emails.

4. Create MailPreview

Create a MailPreview class for UserMailer under src/Mailer/Preview/UserMailPreview.php:

That's all the steps to get the email preview from DebugKit. Now refresh your browser and you should be able to see your emails showing up at the preview panel:

4. The End

Your first GraphQL API - Nested Queries

Thu, 27 Apr 2017 06:46:54 +0000

Typically our database is designed with some relationships. When retrieving data from our GraphQL, we would want them to present in a relationship hierarchy as well.

In this tutorial, we will learn how to build nested queries using Youshido/GraphQL.

In our blog example, there is a series of articles and each article belongs to an author. When retrieving articles' data, it makes more sense to fetch belonging author's data as well instead of "author_id".

Table Of Content

Add AuthorType.php
Add AuthorField.php
Modify ArticleField.php
The end

1. Add AuthorType.php

Apparently, we need AuthorType in order to resolve the type.

Add src/Type/AuthorType.php

As we can see, it is a super simple type with an id(integer) and name(string) fields.

2. Add AuthorField.php

We will use AuthorField to resolve the request.

Add src/Field/AuthorField.php

Let's take a close look at the resolve method.

When getting the $authorId, we fetch it directly from the $value variable as shown below:

This is because $value is configured to contain values from the parent. Which is article is our case. And because we know article will return an author_id, we fetch it directly from $value variable.

The rest of the code is self-explanatory, we find the author that article belongs to using our fake repository and return it.

3. Modify ArticleField.php

We are almost done. The last piece is to modify ArticleField.php to wire ArticleType and AuthorType up.

To do this, open src/Type/ArticleType.php. And change

Our final src/Type/ArticleType.php file looks like this after the modification:

In the first tutorial, we are getting articles data using a query similar to:

Now we can get full author data using:

The magic here is that, if you do not ask for author's data. The resolve method(AuthorField::resolve) will never be called. The Youshido/GraphQL library takes care of the job of figuring out which resolve methods to call.

4. The End

PHPUnit Tip - Access Private Properties of an Object via Closure

Tue, 28 Mar 2017 05:51:15 +0000

In this tutorial, we share a tip on how we can access a private property of an object without using getter/setter methods.

Sometimes, when writing out tests, to inspect the private properties of our testing class, we have no choice but using setter/getter methods. There setter/getter methods exist solely for the purpose of assisting the tests, which feel wrong to us.

Recently we came across a great article at https://markbakeruk.net/2017/03/05/closures-anonymous-classes-test-mocking-1/. Which shares how we can use Closure to access the private properties of an object.

In this tutorial, we would like to share how we can use Closure in our PHPUnit tests:

Disclaimer: the code samples in this tutorial are for purpose of demonstrating the tactic, they might not be the perfect testing code.

Table Of Content

About PHP Closure
Get Private Properties without Getter
Set Mock without Setter
The end

1. About PHP Closure

In simple terms, a Closure is an anonymous function, but it can access variables outside the scope that it was created.

Most of people have used Closure before, for example, using it in array_filter.

However, most of the people are not aware that we can do this:

Pay attention to how Addison's name is changed by $changePropertyClosure to Benjamin, though the name is a private property of Person class.

The uncommon method of Closure class we have shown above is Closure::bindTo. It allows us to duplicate the closure with a new bound object and class scope. You can check out the method details at http://php.net/manual/en/closure.bindto.php.

In simple terms, we can use Closure's method bindTo to access private properties of any classes. With that in mind, let's move on to specific use cases.

2. Get Private Properties without Getter

Imagine we have an object which has getter methods to return private properties, but these are only used by the tests to check the state of the object and are never called, or intended to be called, by the client.

In the code above, we have a getter method getName(). Its sole purpose is to get the private property $name for out test. So that we can write a test for the hide() method.

By using Closure, we can actually eliminate the getName() method.

As you can see from the code above. The Closure $assertPropertyClosure is able to look inside the Person object and get the private property $name using $this context.

Another nice trick we used is that since $this has been bound to the bound object, we just assigned it to a new variable $that, so that we can still use the assertion inside the Closure.

3. Set Mock without Setter

Imagine we have an object which has a setter method to set collaborator, but this setter is only used by the tests to set a mock of the collaborator, it is not used by the client.

In the code above, we have a setter method setPhone(). Its sole purpose is to set the private property $phone for out test. So that we can write a test for call() method.

By using Closure, we can actually eliminate the setPhone() method.

As you can see from the code above. The Closure $setPhoneClosure is able to look inside the Person object and set the private property $phone using $this context.

4. The End

Quick tip on working with timezone in CakePHP 3

Tue, 28 Mar 2017 05:49:28 +0000

In a recent project, we need to allow users to set start and end time of their events and the application is targeted worldwide clients, which leads us to discover some tips on working with timezone in CakePHP 3.

In this post, we share some tips we have learned.

Table Of Content

Set Application Timezone to UTC
Convert Inputs to UTC Base
Convert Database DataTime to a User's Timezone
The End

1. Set Application Timezone to UTC

If you are working on an application that is for a single timezone, then you can happily set the timezone to that timezone.

However if your application is across time zones, to make time calculation and conversions easier, you should set the application's timezone to UTC (If you need a review of UTC, here you go).

We can do that from config/bootstrap.php file:

This will set our application's default timezone to UTC. Any method calls to DateTime instance will take UTC as the timezone. This means all datetime database columns will use UTC-based time.

2. Convert Inputs to UTC Base

The whole idea of using UTC is to keep times in database in sync, it becomes the single point of truth. When we need to do stuff like calculation and conversions, we can safely assume its base is UTC.

Therefore, when saving time to database, we need to convert users' input which is based on their own timezone to UTC, in order to keep our database as the single point of truth.

CakePHP 3 uses Cake\I18n\Time as the class for handling time. We can use it to do the conversion. For example:

3. Convert Database DataTime to a User's Timezone

When displaying the time from the database to user, we need to convert it back to user's timezone. Otherwise, the user will definitely be confused.

We do it as simply as:

CakePHP 3 ORM will return Cake\I18n\Time instances for DateTime columns. Thus we do not have to instantiate it.

4. The End

Dealing with date range

Mon, 20 Feb 2017 00:00:43 +0000

In this tutorial, we walk through a few different scenarios of using league/period. The package league/period is from PHP League and its purpose is to make handling date range in PHP easier for developers.

Table Of Content

Installing package
Checking if a date falls in between a date range
Checking if a date falls in between a date range
Checking if a date range falls in between another date range
Checking if two dates can form a valid date range
The end

1. Installing package

First thing first, let's install the league/period using composer as normal:

2. Checking if a date falls in between a date range

If you have a $startDate and $endDate, how can you check if a date given by the user falls within that range?

For example, if we have dates as shown below:

We can use the method contains() of Period class to accomplish that:

3. Returning all dates between two dates in an array

Given a date range between $startDate and $endDate, how can you get all dates between these two dates in an array?

For example, if we have dates as shown below:

We can use the method getDatePeriod() of Period class to accomplish that:

4. Checking if a date range falls in between another date range

Given a date range between $startDate and $endDate:

How can you verify if the dates below are in the range of the date range above?

We can use the method contains() of Period class to accomplish that:

5. Checking if two dates can form a valid date range

Suppose you accept two user inputs $startDate and $endDate from a form. How do you valid if these two dates can form a valid date range. Normal Dates comparison would work, but it requires you to write your custom objects to handle that validation elegantly.

We can use Period class since it already handles those validations for us. It will make sure it is a valid date range upon instantiation of a Period instance.

6. The end

Markdown Processing in PHP

Sun, 19 Feb 2017 23:56:58 +0000

Markdown is a text-to-HTML conversion tool for web writers. It has gained its deserved popularity after its introduction on 2004. Markdown allows you to write text while providing a format in an easy and clean way.

Though it is developed by Perl, it has been ported to different languages such as PHP. In this tutorial, we will show you how to parse markdown in PHP. There is already a library league/commonmark developed by PHP League and it supports full CommonMark spec. We will be using this package across the tutorial.

Table Of Content

Processing headers
Processing lists
Processing image
Processing table
The end

1. Processing headers

First thing first, let's install league/commonmark using Composer as usual.

In the first example, we need to parse file headers.md which contains content as shown below:


# This is an H1

## This is an H2

###### This is an H6

We will first include the autoloader from Composer vendor folder. Then we will import CommonMarkConverter class and instantiate an instance of it. At last, we use the method convertToHtml to parse the content of headers.md.

The outcome of running the script above is as shown below:

2. Processing lists

In this example, we need to parse file lists.md which contains content as shown below:


* This is a
* This is b
* This is c

+ This is A
+ This is B
+ This is C

Similar to the previous example, we use the same method convertToHtml to do the job for us.

The outcome of running the script above is as shown below:

3. Processing link

In this example, we need to parse file link.md which contains content as shown below:

[this is a link](www.google.com)

Similar to previous example, we use the same method convertToHtml to do the job for us.

We will again use the same method:

The outcome of running the script above is as shown below:

4. Processing table

In this example, we need to parse file table.md which contains content as shown below:


th | th(center) | th(right)
---|:----------:|----------:
td | td         | td

CommonMark is not able to parse table out of box, we need to install an extension to make that possible.

We will create an environment, then add the table extension to the environment. Then create a converter using the environment. At last, we parse the markdown file as normal.

The outcome of running the script above is as shown below: