Anchoring or focalism is a cognitive bias where an individual depends too heavily on an initial piece of information offered to make subsequent judgments during decision making. Once the value of this anchor is set, all future negotiations, arguments, estimates, etc. are discussed in relation to the anchor.

Source: https://en.wikipedia.org/wiki/Anchoring_(cognitive_bias)

The important part to remember here is that subconsciously your brain can and will fixate on the first piece of information it finds. When it comes to fault finding, this can be the first error we see or the first reported information provided. This information (and therefore bias) can then cloud our judgement when it comes to further diagnostics of a fault, as we gravitate back to that singular piece of information instead of considering the bigger picture.

An IT person’s job is normally 90% fault finding, 10% doing. As the saying goes: “I’m not a geek, I’m just better at Googling than you”. What’s more, the saying is right. Nobody wants to spend 3 hours diagnosing the cause of a fault if they can simply jump straight to the fix.

Programmers are no different here too, the moment there’s a fault or error message it’s straight to Google to try and find someone else who’s had the same issue so that they can copy and paste the code to fix.

While finding the right result in Google can and does lead to a quick fix in many cases, it can also lead to a fallacy in your decision making process. In many cases, the focus is then on finding the right result for the error message, not why the error message existed in the first place.

A real world example

This is where Anchoring bias will rear its ugly head. If we see an error message about backups failing because it couldn’t run a certain command, we’re straight onto Google to find someone else who’s experienced that error message. IT faults can usually be broken down into three parts:

To start with, we normally only have the result and the output. For example:

In this scenario (which was a real world one), it’s very easy to race to the conclusion that the filesystem has the wrong permissions and start to google for “Vendor X error file permissions” or to even start instantly running commands to widen permissions.

Scenarios like this are what have led to so many S3 bucket leaks, where the wrong fix is applied to a backup failure fault and while it may fix the problem it’s created a far worse one behind the scenes.

Because the focus was all on what the error said, we lost sight of the actual fault itself. In this real world scenario, here was the resultant fault:

The true fault ended up being that the backup system had run out of disk space. The particular vendor (seemingly) had no check in place to determine if it should try to create a new backup file and therefore failed during that particular area of the code.

But why the wrong error message? It’s normally because we see error messages where a try / catch or other similar error handling is too broad. For example, here’s some pseudo code for the above example:

try {
   create_backup_file();
   set_backup_permissions();
   start_backup();
}
catch (err) {
   panic("Failed to start the backup. Tried to set the backup permissions but couldn't do so");
}

Because there’s multiple potential points of failure handled by a singular error message, it means the error itself may not be enough to effectively fault find.

Those who remember Windows 95 and had filled their hard drive may have been greeted with this error:

This one is obvious of course, but a simple example of how the wrong conclusion to a fault has led to a scenario which doesn’t make sense.

It gets worse

Even worse, when there’s no corresponding error message or log output for the fault at all, we can sometimes attribute the fault to one of the other (unrelated) error messages. This scenario still involves Anchoring bias as we’ve fixated on the first message seen and means we drift even further off track trying to find the fault. Time is now spent chasing errors which aren’t even related to the original fault, leading to the possibility of applying fixes which will make things worse instead of better. These “fixes” can then induce further faults, leading to a huge mess or catastrophic failure instead of a minor one.

Biases can also be combined subconsciously with other cognitive faults as well. As it was distinctly put by Erik Dietrich, you can also have Expert Beginners:

The difficulty is that as you learn, you can fall into the false trap that you understand a system well enough that your learning plateaus. This is normally due to only having a narrow view or understanding of a system, whereby you’ve only dealt with a small component of a large system and therefore reach the logical fallacy that you’ve learnt everything there is to know.

This narrowed view combined with anchoring bias leads will often strip you of the ability to consider wider views of the systems and the complexities involved.

How do we get around it?

There’s a few quick steps we can take:

Acknowledge the existence of bias: Like any bias, the first step is to acknowledge the existence. Once you know to be wary of this bias, it means you can compensate for it. There’s more than a dozen different biases which can affect your fault finding and decision making processes too, so it’s worth understanding how and where they may affect your thinking.

Write the fault out on paper: In the same way that Rubber duck debugging can help you because it forces you to put all the pieces together, writing it out on paper can also achieve the same thing. I also find drawing a timeline or flow diagram also helps, again because your brain will skip parts unless you force it to explicitly detail each stage.

Treat error messages with scepticism. Unless you can see the code itself to confirm, expect that they may not cover every fault scenario fully and may be generic messages. Think about the error message in context, does it fit the fault scenario? Did it occur timing wise when you’d expect it to trigger? Could it be triggered by a different scenario?

Look for the cause, not the symptom: This is the most effective method. Many of these examples can be traced back to the fault if you look for the cause. This isn’t to say we ignore the symptoms as such, but in a broad sense we use them as guidance not as gospel. 

In our storage scenario, we can use the fact that it can’t set file permissions as a guide that the fault is to do with the filesystem and not as narrow as just file permissions themselves.

Running through rudimentary system checks in these scenarios (ie, looking at space, system load, network errors etc) can potentially serve as a quick sanity check and identify root causes early. At the very least, they will give you some confirmation that there’s not a high level or systemic fault.

While within WordPress you can automatically search and find many thousands of free plugins and themes, developers often have a “pro” or premium version where they provide additional functionality and features for their paid version. The free versions are often a great way to try the basics of a product and in many instances they offer enough functionality that you may not even require a more comprehensive version.

However, when you do there’s a temptation for some to go and find a “nulled” version of the plugin for free so that you don’t have to pay for it.

What is a “nulled” plugin?

The original term “nulled” used to refer to paid applications where any copyright protection (such as remote license checks) are disabled or bypassed. While it used to be mostly focussed around desktop software, it also applies to the web as well.

This software is illegal.

However, rather than just being altruistic notions to release software for free so that everyone can use it, nearly all nulled WordPress plugins and themes contain malware. This malware will vary in payload, but in nearly all instances will infect your site beyond just the plugin and add hooks into the core and/or other components so that third party entities can upload other malicious code to use your website for illegal means.

This illegal usage could vary from sending spam, conducting phishing campaigns and even be as severe as to delete your data and hold it to ransom through cryptoware. 

Why do I have to pay for some plugins and themes? 

The simple answer is, software is written by humans and humans need to eat. Yes, while many developers may seem advanced and futuristic boffins at times, they still succumb to the rat race of work-eat-sleep. 

In fact, if you get value from the plugin or theme then paying for it is a good way to ensure that the developer can afford to continue to work on it. Given that some CMS platforms in the enterprise world charge upwards of $60,000 per year, paying $99 (for example) is still outstanding value and still one of the cheapest parts of running a business or website.

Should I use a nulled plugin or theme?

NO.

The only reason I have this here so bluntly is so that there is no ambiguity whatsoever. 

While the previous section should clearly articulate why, many don’t heed the warning signs and continue down the path of nulled plugins or nulled themes.

If you require the services of a paid plugin and can’t afford to purchase it, you have three options:

1. Find an alternative.
2. Go without it.
3. Find a way to pay for it.

The great thing about WordPress is the amount of choice you have, so if you find that a plugin is too expensive then there may be alternative out there already.

What sites offer nulled plugins?

If you’re not downloading it directly from the plugin author’s site after paying for it, chances are it’s a nulled plugin. There is only one site to trust for downloads, and that’s wordpress.org. 

Any other site should be displaying a high degree of caution and you will need to verify the site. There are a few ways to check this:

1. Is the site linked from a free version within wordpress.org or within the plugin / theme itself?
2. Does the URL of the site match the website contained within the official social media sites?
3. Are there any deals on the site which seem “too good to be true” ?
4. Have you arrived at the site from a trusted link?

If there’s any ambiguity in the above four steps, STOP. Verify the site with your web developer or trusted technical advisor before downloading and before paying any money.

What should I do if I discover I have a nulled plugin?

We recommend you immediately contact your web developer and check what backups you have for your site. Once a nulled plugin or theme has been installed, it may have completely compromised your website and this may require a restoration from backup.

We’d also recommend installing WordFence and running a full scan of your website. This can identify and correct security issues in many instances. While we’ve found that WordFence is the best security tool out there, you shouldn’t ever be 100% reliant on a singular tool to correct any security issues.

You should also contact your hosting provider, as they may have additional tools to scan your website and may be able additional information about the level of compromise to your website.

Lastly, you should check your Google Search Console for any warnings or notifications. If Google has detected that your site has a security compromise amd/or is being used for phishing then it will either display a warning message or completely block access and have a potential SEO impact.

Conclusion

As the saying goes, prevention is better than the cure. The only way to 100% ensure any infection or compromise is removed is to restore the site from a backup prior to the nulled plugin or theme being installed.

We highly recommend that you show your support for your favourite plugins and themes by playing for them. By ensuring that the developers have a sustainable income from the plugins and themes they provide, you’re also ensuring that development continues and it’s highly likely that new features will continue to be released.

Cover photo by Markus Spiske on Unsplash.

Here at Conetix we have been using the Laravel PHP Framework for many internal business automation projects for the last 2 years, we have also noticed a growing range of software coming on the market using the Laravel Framework. We host a lot of WordPress sites (also Joomla, Drupal, Magento) and as these are all PHP based like Laravel, it seams natural for us to be able to support it and use it. As our skill set has risen so has the need to implement features not found natively in the framework.

Recently I wrote a number of articles on Laravel, some have been geared towards refactoring such as this article "Developing applications with Laravel 5 – Part 2". In fact I find each release of Laravel requires me to do some degree of refactoring and as I learn more and more about the framework I go back and refactor a lot of code removing big chunks of code that is already provided in the framework. In this article, I'm going to outline a simple date based mechanism for rendering themes in any Laravel Application. For this tutorial I have used Laravel v5.3 and the code does not require any additional packages other than what comes standard.

To implement Themes, the design concept is simple, use a directory in the resources/views directory called "Themes" and under that a "default" directory to hold our basic fully functional application code prior to any theme specific code. To add another theme, you simply create a sub-directory under "Themes" and provide the required directories for the various components the software requires. If you only provide a sub-set of the directories then the "default" theme components are used instead.

For this tutorial, the default theme directories (located under resources/views/Themes/default) are:

• Home
• Header
• Footer
• Errors
• Includes
• Support

Additional directories can be added by you over time as your application evolves, so you have the flexibility to craft your own directory structures.

In this tutorial, Themes are activated based on the date, but there is no reason why you cannot use a field in your "users" table to add a theme name and specify a "per user theme". I will outline it in the provider code below. But I've used the date based mechanism so you can use the code in an eCommerce application, that way you can stage well in advance the look and feel of the site for various festival times of the year like Christmas, Halloween, New Years Eve etc. This is controlled from a database table called "themes". When no theme applies the "default" is automatically used.

Database Migration

For this tutorial we first need to have a database table to hold the theme name (case sensitive), a starting date and ending date the theme is active for. Keep in mind, when a theme is not found, the default is active.

Using the "artisan" tool, we can create our Model and Migration template as such:

#php artisan make:model Theme --migration

After defining the fields, the migration file looks like this:

<?php

use IlluminateSupportFacadesSchema;
use IlluminateDatabaseSchemaBlueprint;
use IlluminateDatabaseMigrationsMigration;

class CreateThemesTable extends Migration
{
    /**
    * Run the migrations.
    *
    * @return void
    */
    public function up()
    {
        Schema::create('themes', function (Blueprint $table) {
        $table->increments('id');
            $table->string('theme_name');
            $table->date('theme_date_from');
            $table->date('theme_date_to');
            $table->timestamps();
        });
    }

    /**
    * Reverse the migrations.
    *
    * @return void
    */
    public function down()
    {
        Schema::dropIfExists('themes');
    }
}

After you have created the migration file, you can run it using the following command:

#php artisan migrate

The database table should be created and look like this:

MariaDB [teststore]> desc themes;
+-----------------+------------------+------+-----+---------+----------------+
| Field | Type | Null | Key | Default | Extra |
+-----------------+------------------+------+-----+---------+----------------+
| id | int(10) unsigned | NO | PRI | NULL | auto_increment |
| theme_name | varchar(255) | NO | | NULL | |
| theme_date_from | date | NO | | NULL | |
| theme_date_to | date | NO | | NULL | |
| created_at | timestamp | YES | | NULL | |
| updated_at | timestamp | YES | | NULL | |
+-----------------+------------------+------+-----+---------+----------------+
7 rows in set (0.01 sec)

Model Code

The Model code created by the Laravel "Artisan" tool is pretty basic, I added one line of code, the $table variable. And changed the namespace to AppModels as I keep all my Model code in app/Models. See my previous article on Namespaces In Laravel Applications

<?php

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class Theme extends Model
{
    protected $table = "themes";
}

Service Provider

As hinted to earlier, the correct theme to apply is determined in the service provider.  Laravel service providers live in the app/Providers directory, and for our tutorial I have called ours "ThemeServiceProvider.php".

The provider has to read our theme table using a single Eloquent call, to get all themes then, using today's date, work out the theme name to apply and finally determine the correct Theme paths and create the global variables for the Views and Controllers that need to know about where the blade templates are located.

If you were to build a per user based theme, then you could get the user ID, read the users table and set the $theme_name variable to the desired theme and not process any date specific code, the rest of the path determining code remains the same.

The working Provider code is as follows:

<?php
/**
* @author Sid Young
* @date 2017-09-04
* class ThemeServiceProvider
*
*
* [CC]
*/
namespace AppProviders;

use IlluminateSupportFacadesView;
use IlluminateSupportServiceProvider;
use AppModelsTheme;

/**
* brief Provides a series of global variables that can be used to access the required Theme Directory structure.
* See notes above for user based themes rather than date based themes.
*/
class ThemeServiceProvider extends ServiceProvider
{

/**
* Assign our theme paths, point to default theme path if named theme does not have the required path.
* That way you can implement but some components as needed (like a different header at certain times of the year).
*
* @return void
*/
public function boot()
{
$theme_name = "default";
$today = strtotime(date("Y-m-d"));
#
# 1. Get theme names from DB table, 
#    For "user" based themes, read the user table for the logged in user.
#
$theme_data = Theme::all();
foreach($theme_data as $t)
{
  #
  # 2. Test for the required date range.
  #    For "user" based themes, comment this out and just set the $theme_name variable.
  if(($today >= strtotime($t->theme_date_from)) && ($today <=strtotime($t->theme_date_to)))
  {
    $theme_name = $t->theme_name;
    break;
  }
}
View::share("THEME_NAME", $theme_name);
#
# 3. Build Paths, test and set path, if dir does not exist then set the default path.
#
$theme_directories = array("Home","Header","Footer","Support","Includes","Errors");
foreach($theme_directories as $theme_dir)
{
   $theme_u_dir = "THEME_".strtoupper($theme_dir);
   $blade_path = "Themes.".$theme_name.".".$theme_dir.".";
   $default_blade_path = "Themes.default.".$theme_dir.".";

    $path = resource_path("views/Themes/".$theme_name."/".$theme_dir);
    #echo "PATH: ".$path."<br>";
    if(file_exists($path) && is_dir($path))
    {
      View::share($theme_u_dir, $blade_path);
      Config::set($theme_u_dir , $blade_path);
    }
    else
    {
       View::share($theme_u_dir, $default_blade_path);
       Config::set($theme_u_dir, $default_blade_path);
    }
  }
}

  /**
   * Register any application services.
   *
   * @return void
   */
   public function register()
   {
   }
}

To make the "THEME_XXXXX" variables available to the application we use the View:share() method, this enables every directory we need to be defined, if the theme directory does not exist, we assign it to the equivalent "default" structure.

An example of the theme paths are:

• Themes/default
• Themes/<your_theme_name>
• Themes/<next_theme_name>

To make the theme variables available in our Controller we use the Config::set() in the Provider and Config::get() method in the Controller(s). The Theme Home variable becomes THEME_HOME and points to Themes/<your_theme_name>/Home but returns a string formatted for accessing a Blade, "Themes.<your_theme_name>.Home.", note the trailing ".", its for convenience when constructing Blade paths.

So if we created a theme called "modern", THEME_HOME would be:

            Themes.modern.Home.

We only need to add onto the end the view located in the /Themes/modern/Home/ directory to get the Blade to render.

The last step for the Service Provider is to enable it in our app.php config file, using "vi" or your favourite editor, open the config/app.php file and add this line to the end of the "providers" array:

...
AppProvidersThemeServiceProvider::class,
];

Save the file and test your development site, it should continue to render without error.

Controller Code

The Controller code needs to know the theme variable in order to call the appropriate view. Where we would normally invoke a view with something like:

return view('Users.testpage',['mydata'=>$mydata]);

We now use a Config:get('THEME_HOME') call like so:

$route = Config:get('THEME_HOME').'Users.testpage';
return view($route,['mydata'=>$mydata]);

Every time we need to call a view inside a Controller, we just use the theme configuration variables that are automatically set for us. No hard coding of theme paths and we still have the flexibility to implement a full theme or any subset by letting the Service Provider do the hard work for us.

View Implementation

The real simplicity of this approach becomes apparent in the view files. Using Laravel's Blade templates we can easily return the THEME variables inside any Blade and use them in Blade directives.

To test the correct processing of the theme variables, I created a simple blade in the resources/views directory, it looks like this:

views]# cat themeinfo.blade.php

<table cellpadding=5 cellspacing=5>
<tr><td>Theme Name</td><td>{{ $THEME_NAME }}</td></tr>
<tr><td>Home</td><td>{{ $THEME_HOME }}</td></tr>
<tr><td>Header</td><td>{{ $THEME_HEADER }}</td></tr>
<tr><td>Footer</td><td>{{ $THEME_FOOTER }}</td></tr>
</table>
views]#

To invoke the test blade, I added a single GET route to my routes file:

...
Route::get('/themeinfo', function() { return View::make('themeinfo'); });
...

As you can see the Blade uses the same {{ }} variables for any passed variables thanks to the use of the View::share() method in the Provider code. The output from the URL call gives us:

Now lets add a theme, for this tutorial I will just do an insert in mysql:

MariaDB [teststore]> insert into themes values (0,'test','2017-08-29','2017-10-30',0,0,0);
Query OK, 1 row affected (0.01 sec)

Now I will create the theme directory but only the Footer directory for testing and create a footer file with a couple of test lines:

resources/views#mkdir -p Themes/test/Footer
resources/views#vi Themes/test/Footer/footer.blade.php
<br/>
<br/>
<b>I'm the Test footer</b> used in {{ THEME_NAME }}
resources/views#

Re-running our themeinfo blade test we now get:

Note: To get the same results, adjust the dates in the insert SQL so today falls in the required date range.

My application calls the Theme/default/Home/frontend.blade.php file when the "/" page is called. Using our new "test" theme, lets add a new test homepage in Themes/test/Home/frontend.blade.php

resources/views#vi Themes/test/Home/frontend.blade.php
<p>I'm the test Frontend</p>
.
.
resources/views#

Calling the web site with no URL parameters now returns our message, so lets include the new Footer and use the THEME_FOOTER variable in a Blade directive.

resources/views#vi Themes/test/Home/frontend.blade.php
<p>I'm the test Frontend</p>
.
@include( $THEME_FOOTER.'footer')
resources/views#

Calling our home page gives us:

I'm the test Frontend

I'm the test footer used in test

That's it! You can use the $THEME_XXXXX variables in any directive and the string assigned will be returned!

The List of THEME_XXX variables created is defined in the Service Provider, the current list is:

• THEME_NAME
• THEME_HOME
• THEME_FOOTER
• THEME_HEADER
• THEME_ERRORS

You can extend this as you need by adding more directory names in the Service Provider code.

Enjoy!

-oOo-

If you have exposure to Object Oriented programming, then you will have been introduced to the concept of abstract classes and interfaces. A “Trait” is similar to an abstract class, in that it cannot be instantiated on its own but contains methods that can be used in a concrete class. Traits were introduced in PHP in version 5.4 and are used extensively in the Laravel Framework. They are ideal in reducing the limiting effect of single inheritance, thus enabling the exposing of methods as if they were defined in the calling class. The exact definition from the PHP site defines Traits as such:

“Traits are a mechanism for code reuse in single inheritance languages such as PHP. A Trait is intended to reduce some limitations of single inheritance by enabling a developer to reuse sets of methods freely in several independent classes living in different class hierarchies. The semantics of the combination of Traits and classes is defined in a way which reduces complexity, and avoids the typical problems associated with multiple inheritance and Mixins.

A Trait is similar to a class, but only intended to group functionality in a fine-grained and consistent way. It is not possible to instantiate a Trait on its own. It is an addition to traditional inheritance and enables horizontal composition of behavior; that is, the application of class members without requiring inheritance.”

Example File

Creating a Trait is just like defining a class, the following simple example (excluding comments) shows a single file with one trait which has 2 methods:

<?php namespace AppTraits;

trait ExampleCode
{
    public function printThis()
    {
        echo "Trait executed";
        dd($this);
    }

    public function anotherMethod()
    {
        echo "Trait – anotherMethod() executed";
    }
}

Our example looks just like a class definition, except we use the keyword “trait”, there is no constructor as it cannot be instantiated (just like an abstract class). It uses a name space of AppTraits to give it a clear grouping (you can use anything you like here). If you need to access code in other name spaces then just include the “use” statement (see example below) and create and call the method(s) as needed.

Within the file, function names must be unique and if they do conflict with existing methods then the following precedence takes effect:

1. An inherited member from a base class is overridden by a member inserted by a Trait.
2. Members from the current class override Trait methods.

Storing Traits

For convenience I created a directory under “app” called “Traits”, and placed my custom PHP files there. Each file uses the name of the Trait for logical correlation. By using a name space of “AppTraits” in each file the Framework was able to locate my files when I “use” them in another file.

Sample Usage Code:

<?php
/**
 * class AdminLoginJob
 * @date 2016-11-03
 */
namespace AppJobs;

use AppJobsJob;
use IlluminateContractsBusSelfHandling;

use AppTraitsExampleCode;

/**
 *  brief Example code using a Trait in a Laravel "Job"
 */
class AdminLoginJob extends Job implements SelfHandling
{
    use ExampleCode;
    
    /**
     * Call trait to print something. Note the use of "$this".
     * 
     * @return void
     */
    public function __construct()
    {
        $this->printThis();
    }

   /**
     * Do more stuff here.
     * 
     * @return void
     */
     public function handle()
    {
        // never gets called in this example.
    }
}

The printThis() method is in our trait and accessed using $this-> notation just as if it was in the Class file. Multiple traits can be used in this manor, just select names carefully.

Laravel 5.8 Working Example

Since the release of the original article, Laravel has evolved and some of the syntax has changed. Below is a fully working example, with code.

To kick it off, add a route to your routes file for a GET call to the controller, mine looks like this:

Route::get( ‘/example’,’Example@Example’);

app/Traits/ExampleCode.php

This is the actual Trait we will use in the example. It has two methods, for this example we will just use the first one “printThis()”.

<?php 
 namespace App\Traits;
 trait ExampleCode
 {
     public function printThis()     
     {               
         echo "Trait executed";    
         dd($this);           
     }
     public function anotherMethod()
     {
         echo "Trait - anotherMethod() executed";
     }
 }   

app/Jobs/ExampleJob.php

In our example, we have attached the Trait to a Job, you could use it anywhere but in this example we will dispatch a job and call the Trait code.

<?php
 /**
 \class ExampleJob
 @date 2019-07-31
 */
 namespace App\Jobs; 
 use App\Jobs\Job;
 use App\Traits\ExampleCode;
 /**
 \brief Example code using a Trait in a Laravel "Job"
 */
 class ExampleJob extends Job
 {
 use ExampleCode; 
 /**
 Call trait to print something. Note the use of "$this".
 *
 @return void
 */
 public function __construct()
 {
     $this->printThis();
 }
 public function handle()
 {
     // never gets called in this example.
 }
 } 

app/Http/Controllers/Example.php

Our controller is the entry point for the route and its sole purpose is to dispatch the Job.

<?php
 namespace App\Http\Controllers;
 use App\Http\Controllers\Controller;
 use App\Jobs\ExampleJob;
 class Example extends Controller
 {
     public function __construct()
     {
     }
     public function Example()
     {
         dispatch(new ExampleJob());
     }
 }

Browser Output

Web Browser output:

Trait executed
ExampleJob {#458 ▼
+connection: null
+queue: null
+chainConnection: null
+chainQueue: null
+delay: null
+chained: []
}

Yep! – that’s it a working example with the Trait attached to a Job being dispatched from a Controller in this example.

Documenting Traits with Doxygen

I think code documentation is critical, so it pays to make an effort to insert formatted comments that can be collected by a suitable tool and generated onto a web site for easy access. I tend to CRON my document generation, so as code is edited and saved new comments and code appear in the reports. Another handy feature is leaving TODO notes so code can be revisited to introduce new functionality. To achieve this I use Doxygen as my main tool but also run phpDocumentor2 and phpDox over the code, this given me lots of useful info in different formats.

By default Doxygen does not support PHP Traits in its documentation output, however several StackExchange posts cover a workaround:

• https://stackoverflow.com/questions/26585100/doxygen-php-traits

Related posts:

• https://stackoverflow.com/questions/26168273/doxygen-not-documenting-php-code-inside-if-tags/26206860
• https://stackoverflow.com/questions/24485609/double-include-prevention-code-in-php-prevents-doxygen-from-generating-documenta/25655189

Manual Page on input Filters:

• https://www.doxygen.nl/

Enjoy!

-oOo-
 

A name space allows you to partition code into logical groups by defining them into their own “namespace”. A text string after the “namespace” keyword identifies the name space and all code below it then lives within that name space. Name spaces also provide a way to group interfaces functions and constants.

As you application grows name spaces become essential to logically group code and to keep code separate from other code. Another great benefit to name spaces is when generating documentation. Name spaced code gets grouped accordingly by the most common PHP Documentors like Doxygen, phpDocumentor and phpDox.

Lets look at some simple examples so the idea is easy to follow and implement.

Without using a name space a simple class looks like:

<?php
/**
* brief Handle all User Option preferences
*/
class UserOptions
{
    public function getOptions()
    {
    …...
    }
}

To define a name space, use the “namespace” keyword followed by a path identifier. Here I have used AppUtilities to wrap the UserOptions class:

<?php
namespace AppUtilities;
/**
* brief Handle all User Option preferences for a normall user of the application
*/
class UserOptions
{
    /**
     * Given a user object retrieve all associated options for the user and return them in
     * an array and key-value pairs.
     */
    public function getOptions(User $user)
    {
    …...
    }
}

The “namespace” keyword must have no other keywords before it but comments are OK and needed for most documentation generators.

Now that we have the class defined inside a Utilities name space we can access it in two ways, and here it is assumed we are not trying to access it from another name space:

$userOption = new AppUtilitiesUserOptions();
$options = $userOption->getOptions();

or

use AppUtilities;

$userOption = new UserOptions();
$options = $userOption->getOptions();

If we are trying to use the class from within another name space then the “use” keyword will need to be changed to include the class name like so:

use AppUtilitiesUserOptions;

This allows the compiler to import the correct class name from the correct name space. Let see another example of this, first we define a class:

<?php

namespace AppThirdPartyInvoicing;

/**
* brief Invoice module options for all users from ThirdParty software sales.
*/
Class UserOptions
{
    public function getOptions()
    {
    ….
    }
}

In our example, we were given a new invoicing module and it also has a UserOptions class that has no relationship to our original UserOptions class and it even has a common method name. Let use both in a sample program.

Referencing the two classes in our code we get:

<?php namespace App;

Class TestExample
{
    /**
     * Do a billing run
     * 
     * @return void
     */
    public function BillingRun()
    {
    ….
    $userOptions = new AppUtilitiesUserOptions();
    $billingOptions = new AppThirdPatyInvoicingUserOptions();
    ...
    }
}

This looks messy and we can shorten it using an alias to the sub-name space as shown below:

<?php namespace App;

use AppUtilities as Util;
use AppThirdPatyInvoicing as Billing;

Class TestExample
{
    
    /**
     * Do a billing run
     * 
     * @return void
     */
    public function BillingRun()
    {
        ….
        $userOptions = new UtilUserOptions();
        $billingOptions = new BillingUserOptions();
        ...
    }
}

What if you don’t use namespaces?

In a Laravel application, you can’t take advantage of custom directories if you don’t use a name space., Instead, you need to add additional paths to your composer.json file to include the paths. This can be handy on a quick and dirty small application but at some point as the application grows you need to move to name spaces. Here is an example of the “autoload” class map entry from a Laravel composer.json file, it has a Models Directory and a ConfigHelprers directory defined:

"autoload": {
    "classmap": [
        "database",
        "app/Models",
        "app/ConfigHelpers"
    ],
    "psr-4": {
    "App\": "app/"
    }
},

Getting in early and using well thought out name space keywords in your application will save time down the track when the functionality expands. In a complex Framework like Laravel, name spaces are used everywhere and each release new third party composer based packages are being made available only compounding the usage.

Last week we took an introductory tour through AuraPHP and built a simple application using the Aura 2.x framework. This week, we're going to build on that foundation, by refactoring the code we wrote, so that it's more manageable and maintainable, as well as uses some of the other features on offer; such as logging, the response object, and the dependency injection container.

If you've not read the introductory post, please do, as you'll need that one to following along with this one. Assuming you have, let's get on with the code. To keep it clear and straight-forward, here's what we're going to do:

• Retrieve and use the configured logger service
• Redefine the Logger service configuration for the dev environment
• Configure a custom service, the ExtendedPdo connection object
• Refactor the data-view-sales dispatchable into an invokable class
• Access some query variables from the request object

That's quite a decent list of things to cover, but it helps give a more fleshed out understanding of the features on offer.

Retrieve and Use the Configured Logger Service

Projects, based on the AuraPHP 2.x framework come with a number of services configured, including logging, request, response, sessions,validation, and forms. These services are configured in a series of config files.

Let's refactor modifyWebRouter to retrieve and make use of the logger service, which uses the excellent Monolog library. If you're not familiar with Monolog, it's written by Jordi Boggiano, creator and maintainer of Composer.

Monolog's a PSR-3 style logging library, which can send logs to a range of locations and services, including files, sockets, inboxes, databases, as well as various web services, such as Loggly and ElasticSearch.

I've used it on numerous occasions and definitely recommend it.

public function modifyWebRouter(Container $di)
{
    $router = $di->get('aura/web-kernel:router');

    /** @var MonologLogger $logger */
    $logger = $di->get('aura/project-kernel:logger');

Firstly, we get access to the service, via its service name, from the DI container.

$router->add('hello', '/')
           ->setValues(array('action' => 'hello'));

    $logger->addDebug('Added default route');

    // Add an about page
    $router->add('about', '/about')
        ->setValues(array('action' => 'about'));

    $logger->addDebug('Added about page route');

    // Add a sales data display page
    $router->add('data-view-sales', '/data/view/sales')
        ->setValues(array('action' => 'data-view-sales'));

    $logger->addDebug('Added sales data page route');
}

Then, after each route is initialised, we add a call to the logger'saddDebug() method, logging the route which was just added.

Log Output

By default, the logger writes to a file on the filesystem, located under/tmp/log, who's name is that of the currently executing environment, appended with .log. As the environment's currently set to 'dev', then the file will be called /tmp/log/dev.log. If it already exists, it will be appended to. If not, it will be created and written to.

Here's a sample of the logged messages:

[2016-09-08 16:46:34] NULL.DEBUG: Added default route [] []
[2016-09-08 16:46:34] NULL.DEBUG: Added about page route [] []
[2016-09-08 16:46:34] NULL.DEBUG: Added sales data page route [] []
[2016-09-08 16:46:34] NULL.DEBUG: AuraWeb_KernelWebKernelRouter GET / [] []
[2016-09-08 16:46:34] NULL.DEBUG: AuraWeb_KernelWebKernelDispatcher::logControllerValue to hello [] []

Redefine the Logger Service Configuration for the Dev Environment

Now it's great that we can use an existing configuration, but what about being able to change one if it doesn't suit our needs? After all, how often do pre-packaged solutions and configurations always work for us, just as we would like or need them to?

So let's see how to redefine the logging service configuration, just for the development environment. To do that, open config/Dev.php. By default, it will look like the code below.

<?php
namespace AuraFramework_Project_Config;

use AuraDiConfig;
use AuraDiContainer;
use MonologLogger;

class Dev extends Config
{
    public function define(Container $di)
    {
        ini_set('error_reporting', E_ALL);
        ini_set('display_errors', true);
    }

    public function modify(Container $di)
    {
    }
}

Let's now redefine the service, similar to how it's defined in Common.php, but this time also making use of the ChromePHPHandler, in the code below.

protected function modifyLogger(Container $di)
{
    $project = $di->get('project');
    $mode = $project->getMode();
    $file = $project->getPath("tmp/log/{$mode}.log");

    /** @var MonologLogger $logger */
    $logger = $di->get('aura/project-kernel:logger');
    $logger->pushHandler($di->newInstance(
        'MonologHandlerStreamHandler',
        array(
            'stream' => $file,
        )
    ));
    $logger->pushHandler($di->newInstance(
        'MonologHandlerChromePHPHandler'
    ), Logger::DEBUG);
}

As you can see, it's just about the same code, but with three extra lines at the bottom, which adds a lazy-loaded initialisation of the ChromePHPHandler, at the level of debug.

public function modify(Container $di)
{
    $this->modifyLogger($di);
}

After that, we add a call to the modifyLogger() method, to themodify() function, which will override the setup when the code's running in the dev environment.

Configure a Custom Service

Now that's how to retrieve an existing service, but what about configuring and using a service which doesn't come with the project? To do that, we're going to refactor modifyWebDispatcher() so that theExtendedPdo object is no longer instantiated directly, but lazy-loaded instead. To do that, we first refactor the code into the define() method as below.

public function define(Container $di)
{
    $di->set('aura/project-kernel:logger', $di->lazyNew('MonologLogger'));
    // add the database connection as a service
    $di->set(
        'db-connection',
        $di->lazyNew(
            'AuraSqlExtendedPdo', [
                'dsn' => 'sqlite:./../db/database.sqlite'
            ]
        )
    );
}

What this does is configure a new service called db-connection, using the same configuration as before. But this time, the service will only be instantiated the first time it's requested, instead of straight-away, making the application much more performant.

Next, in modifyWebDispatcher(), we then replace the instantiation of ExtendedPdo, with a reference to the service, like this: $this->di->get('db-connection');

Refactor a Dispatchable into an Invokable Class

Now I want to take the process a step further, as I don't like how everything's initialised directly in the modifyWebDispatcher()method. Instead, I want to make it more maintainable, by refactoring the code in to a callable.

If you're not familiar with callables, here's a great explanation from Lorna Jane.

The refactored code's a bit long, so I've broken it down in to annotated chunks. Let's step through them and see how it all fits together.

<?php

namespace AuraSupplementalRouteDispatchablesSales;

use AuraDiContainer;

class DataView
{
    const TEMPLATE_DIR = './../src/templates/';

    /**
     * @var string The SQL statement to run
     */
    protected $statement = '
        SELECT t.TrackId, sum(il.unitprice) as "TotalSales", t.Name as "TrackName", g.Name as Genre, a.Title as "AlbumTitle", at.Name as "ArtistName"
        from InvoiceLine il
        inner join track t on (t.TrackId = il.TrackId)
        INNER JOIN genre g on (g.GenreId = t.GenreId)
        inner join album a on (a.AlbumId = t.AlbumId)
        INNER JOIN artist at on (at.ArtistId = a.ArtistId)
        WHERE g.Name like :genre
        group by t.TrackId
        HAVING at.Name = :artist_name
        order by sum(il.UnitPrice) desc, t.Name asc
    ';

There's no base class to extend, nor interface to implement, so we just create a standard PHP class. I've then added a class constant, which provides the base path to the template directory, mainly for tidiness' sake, and created a protected class member variable, $statement, to store the SQL statement.

protected $view;
    protected $di;

    /**
     * @param AuraDiContainer $di
     */
    public function __construct(Container $di)
    {
        $this->di = $di;
        $this->buildView();
    }

I've then setup two further protected class member variables to store the view and DI container objects, and a class constructor. The constructor takes one argument, $di, an instance of the DI container, as the closure previously did.

So far the same functionality exists. Next, $di is initialised with the passed in $di object, and a call is made to the buildView() method, which we'll look at next.

protected function buildView()
    {
        $view_factory = new AuraViewViewFactory;
        $this->view = $view_factory->newInstance();

        $layout_registry = $this->view->getLayoutRegistry();
        $layout_registry->set('default', self::TEMPLATE_DIR . 'sales.layout.php');

        $view_registry = $this->view->getViewRegistry();
        $view_registry->set('sales-data', self::TEMPLATE_DIR . 'data/sales/view.php');
        $this->view->setView('sales-data');
        $this->view->setLayout('default');

        // the "sub" template
        $view_registry->set('_result', self::TEMPLATE_DIR . 'data/sales/result.php');
    }
}

Now we refactor the view initialisation code into a distinct, utility method, so that it's kept separate from the rest of the code. The only real changes are that we use the TEMPLATE_DIR class constant instead of the base path, making the path that bit more flexible and adaptable, and initialise the protected member variable $view, with the result of calling$view_factory->newInstance(); instead of initialising a standalone variable.

We now have a two-step view ready to go.

/** Make the class an invokable/callable */
    public function __invoke($bindOptions = array())
    {
        $this->view->setData([
            'results' => $this->di->get('db-connection')
                ->fetchObjects($this->statement, $bindOptions, 'AuraSupplementalDatabaseObjectsEntitySalesData')
        ]);

        $response = $this->di->get('aura/web-kernel:response');
        $response->content->set($this->view);

        return $response;
    }

Finally, we define the magic __invoke() method, which will be called, when the object is invoked as though it were a function.

It receives one argument, an array, which contains the bind values which will be bound to the SQL statement, generating the SQL query, which will be passed to the database to retrieve the results, as before. I've not added any special error or exception handling for when errors occur or no the array is empty.

Now we call the fetchObjects() method on our lazy-loaded database connection service, passing in the statement, bind options, and the class to hydrate per result and store the result of the call as a view template variable 'results'.

Then, as before, we retrieve the response service, and pass the view member variable to the set() method on the response's content object, finishing up by returning the $response object. We need to do this as a callable doesn't automatically make this available, as a closure would.

That was a bit to go through, but except for a different structure, it's doing the same as before.

The Modified modifyWebDispatcher Method

With all of the code refactored, we now only need update thesetObject() method, where we define the dispatchable, as I have below. Firstly, the use statement was added to reference the class, then a new DataView object, $dataViewDispatchable, was instantiated, passing to the constructor the DI instance.

Following that, the request object service is retrieved, to make the code more concise.Finally, the setObject() method is updated, using the instantiated DataView object as a callable, passing in an associative array, where the two bind parameters are retrieved from the request query string.

use AuraSupplementalRouteDispatchablesSalesDataView;

//...rest of the existing code

$dataViewDispatchable = new DataView($di);

$request = $di->get('aura/web-kernel:request');

$dispatcher->setObject('data-view-sales',
    $dataViewDispatchable([
        'genre' => $request->query->get('genre') . '%',
        'artist_name' => $request->query->get('artist')
    ])
);

With all this done, a range of different bind parameters can be supplied, through a more flexible route, such as
https://localhost:8080/data/view/sales?genre=TV&artist=Lost.

Please note that I've done no sanitation or validation whatsoever on the query parameters, and in a real world application that's just insane. But for the purposes of a simple example, it's enough to demonstrate a series of features.

Suggestion: How about using the validation package to implement validation and filtering to make the code more safe?

Wrapping Up

And that's how to refactor the code so that it's more manageable and maintainable, as well as use some of the other features on offer, especially the dependency injection container.

If you have any issues, or just have questions to help flesh out your understanding, make sure to use the mailing list or the IRC channel (#auraphp).

Finally, Aura's definitely one of the more well designed and written frameworks for PHP, as well as one of the more elegant. I strongly encourage you to check it out.

I hope you've enjoyed this two-part introductory series to AuraPHP and the AuraPHP framework, as much as I've enjoyed researching and writing it. I'd love to know your thoughts in the comments.

However, recently, I was tasked, as part of my regular Education Station column for PHPArch Magazine, to write a 3-part series on Dependency Injection (DI), and the state of it in PHP. During the course of my research, I investigated four of the most notable Dependency Injection Containers (DiC) implementations in PHP, and one of them was Aura.Di.

During the course of my research, I took time out to talk with Aura project founder, and lead contributor Paul M. Jones, about the library. In the process, I discovered an excellent project, one where every component, whilst interoperable with the all the others, is not dependent upon them.

This stands in stark contrast with many of the existing frameworks and packages in PHP today, with some more recent, notable exceptions, such as Zend Framework 2.5. For so many packages, if you want just a component or two, often times you need a number of others, even if you don't use them.

Aura doesn't work this way!

Given that, it's unfortunate that it doesn't seem to get the same amount of coverage and exposure which other PHP frameworks do, such as the aforementioned Zend Framework and Laravel.

Perhaps because it's not as shiny as some of the others, or that it doesn't have a large, visible corporate presence to help it stand out from the crowd. But either way, if you're serious about professional coding practices, and software craftsmanship, this is the framework for you.

If you're yet to hear of it, and want to work with a very well designed set of packages, then today you're in for a treat. I'm going to give you a rapid introduction, to the 2.x implementation, followed by a run-through of a sample application built using the 2.x framework.

Note: The framework component is being phased out in version 3 of the project. But it still provides an excellent way of introducing the project.

In a follow up article, I'll be taking you through some of the changes both already implemented, and set to be implemented in version 3.x of the project. So keep an eye out for that.

What is Aura PHP

The simplest way is to quote the website:

Aura 1.x began as a rewrite of Solar, re-imagined as a library collection with dependency injection instead of a monolithic framework with service location.

The project centers around a collection of high-quality, well-tested, semantically versioned, standards-compliant, independent library packages that can be used in any codebase.

Each library is self-contained and has only the things it needs for its core purpose. None of the library packages depends on any other package. They are decoupled, not only from any particular framework, but also from each other. This means developers can use as much or as little of the project as necessary.

Requirements

Currently there isn't a long list of requirements. The key one is that your web server's running at least PHP 5.3. I'd like to think that this was a minimum, at the very least.

However, if you're running later versions, and I hope you are, it's good to know that Aura's tested against 5.5, 5.6 and HHVM. PHP 7 has also been successfully test against, even though it's still in alpha.

What's On Offer

Aura comes with a range of packages which you would expect from a PHP web project, which include:

• Autoloading: Compliant with PSR-4
• Dependency Injection: Complete with constructor and setter injection, lazy-loading and inheritable configuration
• Dispatching: Creates objects from a factory and invokes methods using named parameters; also provides a trait for invoking closures and object methods with named parameters
• Filtering: Provides filters to validate and sanitize objects and arrays
• Routing
• Sessions: Provides session management functionality, including lazy session starting, session segments, next-request-only "flash" values, and CSRF tools
• SQL: Provides lazy connections, array quoting, identifier quoting, query profiling, value binding, and convenience methods for common fetch styles, along with object-oriented query builders for MySQL, PostgreSQL, SQLite, and SQLServer; can be used with any database connection library
• Views: Provides an implementation of the TemplateView and TwoStepView patterns, with support for helpers and for closures as templates, using PHP itself as the templating language
• Escaping: Provides HTML escapers and helpers, including form input helpers

Have a look at the list of packages to get an overview of what's on offer. If you're keen to know more about any one, follow the link to the respective GitHub repository, and browse the code or peruse the project's README.

A Simple Application

Now that I've given you the big overview, let's get started creating a modest application using the 2.x framework. If you want to peruse the full application, it's available on GitHub. The application's not going to be too special, but take in a series of the components. It's going to have a routing table with three routes:

1. The Home Page
2. An About Page
3. A Data View Page

The home and about pages will be simple text output. The data view page will setup a PDOconnection to an SQLite3 database, which contains a copy of the Chinook example database, and will submit a SQL query to collate and return the episode's of Lost with the highest grossing sales. When rendered, the page will look like the screenshot below.

The Project Structure

Before we dive in to the code, let's first look at the directory structure. It contains 6 key directories, these are:

• cli
• config
• src
• tests
• tmp
• web

Most of these we don't need to be concerned about for the purposes of this example. The key ones, however, are config and web. In config, you'll see five files. Here's what they do:

• _env.php provides a default environment
• Common.php provides the default setup which is used across all environments
• Dev.php, Prod.php, and Test.php implement options specific to those environments

The web directory is similar to the more commonly used /public directory. It contains the bootstrap, or front controller, file, where all requests are routed through.

Looking at Common.php, you'll see a number of existing functions; these being define, modify, modifyLogger, modifyCliDispatcher, modifyWebRouter, and modifyWebDispatcher. These do largely what the names imply.

define sets up the DiC configuration, modify is a utility function for calling any sub-modify functions. modifyLogger sets up logging, modifyCliDispatcher andmodifyWebDispatcher set up the dispatch configuration for cli and web environments respectively.

And modifyWebRouter sets up routing for the web environment. Of these, the only one I'm going to modify is modifyWebRouter.
It already has one route setup, which is defined as:

$dispatcher->setObject('hello', function () use ($di) {
    $response = $di->get('aura/web-kernel:response');
    $response->content->set('Hello World!');
});

What this does is to create a named route, hello, and provide a closure, which receives the DiC, as its handler. Via the DiC it accesses the response object and sets the content of it to be the string Hello World!.

The About Page

Following in that vein, I'm going to add the about page, using the following configuration.

$dispatcher->setObject('about', function () use ($di) {
    // Create a new View object
    $view_factory = new AuraViewViewFactory;
    $view = $view_factory->newInstance();

    // Setup a Two-Step View
    $layout_registry = $view->getLayoutRegistry();
    $layout_registry->set('default', './../src/templates/default.layout.php');

    // Configure the view
    $view_registry = $view->getViewRegistry();
    $view_registry->set('about', './../src/templates/about.php');
    $view->setView('about');
    $view->setLayout('default');

    // Set the view output to be the response body
    $response = $di->get('aura/web-kernel:response');
    $response->content->set($view());
});

This will first setup a new named route, called about, also using a closure as it's handler. Inside the handler, I`ll create a new View object to handle the rendering of the view output, handled with templates. This is a lot simpler and more maintainable than creating the output in code.

You'll see above that there's a layout and view. The reason for this is that I love the two-step view pattern, as it makes it simple to separate reusable elements, such as headers, footers, and sidebars, from action-specific output, such as the about page's content.

I do this by making a call to getLayoutRegistry(), which sets the layout template, linked to the key 'default'. These are named as we may have multiple layout templates. Then I'll add a view template, linked to the key 'about.

With that done I'll tell the View which template to use for the content, and which to use for the layout, by calling setView() and setLayout() respectively.

With all this done, I'll set the response body to be the return result from calling $view as a function. In short, this will set the response body to be the rendered template result.

The View Data Page

The View Data Page is a bit more involved, so will take a bit more explaining. As such, I've broken the code up in to chunks, talking about them a piece at a time.

$dispatcher->setObject('data-view-sales', function () use ($di) {
    $view_factory = new AuraViewViewFactory;
    $view = $view_factory->newInstance();

As before, we've initialised a new view object.

$pdo = new ExtendedPdo(
        'sqlite:./../db/database.sqlite'
    );

    $extended_pdo = new ExtendedPdo($pdo);

Here we've initialised a new ExtendedPdo object, pointing to our SQLite database, which is a PDO extension that provides lazy connections, array quoting, identifier quoting, query profiling etc.

$stm = '
        SELECT t.TrackId, sum(il.unitprice) as "TotalSales", t.Name as "TrackName", g.Name as Genre, a.Title as "AlbumTitle", at.Name as "ArtistName"
        from InvoiceLine il
        inner join track t on (t.TrackId = il.TrackId)
        INNER JOIN genre g on (g.GenreId = t.GenreId)
        inner join album a on (a.AlbumId = t.AlbumId)
        INNER JOIN artist at on (at.ArtistId = a.ArtistId)
        WHERE g.Name like :genre
        group by t.TrackId
        HAVING at.Name = :artist_name
        order by sum(il.UnitPrice) desc, t.Name asc
    ';

    $bind = ['genre' => 'TV%', 'artist_name' => 'Lost'];
    $sth = $pdo->prepare($stm);
    $sth->execute($bind);

Next, we've specified a semi-complex SQL statement, using named parameters to aid in avoiding SQL injection attacks. The named parameters are for genre and artist name. These we've substituted for TV% and Lost. We've then called execute() to run the query.

$layout_registry = $view->getLayoutRegistry();
    $layout_registry->set('default', './../src/templates/sales.layout.php');

    $view_registry = $view->getViewRegistry();
    $view_registry->set('sales-data', './../src/templates/data/sales/view.php');
    $view->setView('sales-data');
    $view->setLayout('default');

    // the "sub" template
    $view_registry->set('_result', './../src/templates/data/sales/result.php');

As before, we've setup the layout and view templates for rendering the page.

 $view->setData([
        'results' => $pdo->fetchObjects($stm, $bind, 'DatabaseObjectsEntitySalesData')
    ]);

    $response = $di->get('aura/web-kernel:response');
    $response->content->set($view());
});

Finally, we've set a view template variable called results which will hold the value of querying the database. Note the third parameter. This indicates that every result in the resultset, will be a hydrated DatabaseObjectsEntitySalesData object. Now I didn't have to do this, but I find it makes working with larger datasets a whole lot simpler, as well as object-oriented.

Updating the Routing Table

With the new endpoints created, we now need to update the routing table, so that we can reach them. To do so, in modifyWebRouter(), add the following code:

// Add an about page
$router->add('about', '/about')
       ->setValues(['action' => 'about']);

// Add a sales data display page
$router->add('data-view-sales', '/data/view/sales')
       ->setValues(['action' => 'data-view-sales']);

These create named routes, about and data-view-sales, pointing to /about and/data/view/sales respectively. The setValues() function is how we pass view template variable data, which admittedly I've not used in the code so far.

The View Templates

Honestly, most of the templates are just plain HTML, which I've borrowed from the Twitter Bootstrap examples. However two templates are worth looking over. These are view.phpand result.php in src/templates/data/sales/. In view.php you'll see the following code:

<?php
  foreach ($this->results as $result) {
      echo $this->render('_result', array(
              'result' => $result,
          )
      );
  }
?>

This iterates over each result, rendering the template named _result, which isresult.php, passing it the current result. Looking at result.php, we see the following code:

<tr>
    <td><?php print $result->TrackId; ?></td>
    <td><?php print $result->TotalSales; ?></td>
    <td><?php print $result->TrackName; ?></td>
    <td><?php print $result->Genre; ?></td>
    <td><?php print $result->AlbumTitle; ?></td>
    <td><?php print $result->ArtistName; ?></td>
</tr>

Nothing too special, but it outputs the value of the six object member variables. I didn't have to separate the templates out, but felt that it was worth showing how to do so, and how to make the code more reusable.

Other frameworks, such as Zend Framework, would use the term Partial here. There's not a strict implementation of partials, but an in-situ one.

Running The Application

Now that everything's setup, let's get it running. As it's not making use of external services or databases, then I'm going to launch it using PHP's built-in web server. To do so, I'll run the following command:  

php -S localhost:8080 -t ./web

Wrapping Up

And that's all it takes to create a basic, database-enabled Aura application. Sure, I've only covered the basics. But in the follow-on article, I'll be adding a range of extra functionality, so that you get a better understanding, both of what's on offer, and how to better organise it, making better use of dependency injection.

But gladly, thanks to a range of modern tools such as continuous integration servers, the amount of work involved can be significantly reduced – if done properly. Travis CI, as we had a good introduction to in last week’s post, is one of those tools. And what’s more, depending on your needs – it’s free.

In case you missed the previous instalment, we started by looking at what Travis is, and how it’s configured. We then stepped through a series of builds, viewing the information provided, and how they work, and finished up configuring simple email notifications.

Now that’s great, but it only just scratches the surface of what’s possible. In this instalment, I’m going to take you further, showing you a richer range of functionality. We’re going to look at integrating notifications with third party applications and services, including IRC, HipChat, and CodeClimate.

Notifications

OK, let’s get started adding further notification options. We’ll start with IRC.

 IRC

If you’re not familiar with it, IRC is a simple, text-based, chat system, created in 1988 by Jarkko Oikarinen. It was one of the earlier chat systems, preceding most everything we know today; whether that’s ICQ, Facebook Messenger, Slack, HipChat, and so on.

Whilst it’s not nearly as popular as it once was, it’s still a very well used medium, with some reports saying it has a user base of around half a million active users, at any one time.

Like most software and protocols this old, there are a range of clients from it, both in the console and for the GUI. Some of the more popular GUI clients are mIRC, for Windows, Colloquy for MAC OSX, and XChat for Linux.

Now let’s get the IRC notification setup. For the purposes of this article, I’ve setup a new IRC channel on freenode called #conetix-blog. To configure it to use it, in your .travis.yml, add the following configuration.

irc:
    channels:
      - "irc.freenode.net#conetix-blog"
    use_notice: true
    on_success: always
    on_failure: always
    skip_join: true

Stepping through the options, the channel is set under channels, on_success and on_failure ensure that no matter the status of a build, a notification will be sent.

I’ve then set use_notice so that a notice style message is sent, instead of a normal message. This makes it simpler to distinguish between normal conversation and notification messages.

Finally, I’ve set skip_join to true, so that the bot doesn’t have to join before it can send a message. You may or may not like taking this approach. As always, commit and push the changes to .travis.yml to the repository. When the next build is done, in your IRC channel, you should see a message appear.

 HipChat

HipChat is one of the newer, cooler online chat services available today. Acquired by Atlassian in 2012, HipChat is a service providing both private and group chat, and instant messaging.

Available for Mac, Linux, and Windows, as well as Android and iOS, it’s one of the biggest services around, handling 60 messages per/second and containing over half a terabyte of searchable data.

If you’re team’s not already using it, and are looking for a chat solution, I’ve used it and thoroughly enjoy and recommend it. So that’s why we’re going to integrate with it today. To do so, add the following configuration to your .travis.yml configuration file.

hipchat:
    rooms:
      - <API_Token>@<Room_Name>
    format: html
    on_success: always
    on_failure: always

Stepping through the configuration, the rooms option requires an API token and the room name which the message will be sent to. To get the API token, you first need to login to your HipChat account, on the web, then under Rooms click the room name.

In the navigation on the left-hand side, click Tokens, where you’ll need to generate a new token, specifying the token’s scope. I’ve chosen “Send Notification” only. After that, you’ll see the token available in the Token list, as below. For the Room Name, you’ll find that at the top of the same page.

Finally, I’ve used format: html, which sets the format of the sent message to be HTML. Please be aware that it disables some features, such as @mentions. As with IRC, I’ve stipulated on_success and on_failure to be set to always so that notifications are always sent to the chat room.

Integrating with CodeClimate

Now that we’ve setup more powerful notifications, let’s look at adding code quality analysis. There are a range of tools available to do this, some open-source, some closed. But one I want to look at today is a 3rd party service called CodeClimate.

What is CodeClimate

In essence, in the words of the CodeClimate team, the service:

Consolidates the results from a suite of static analysis tools into a single, real-time report, giving your team the information it needs to identify hotspots, evaluate new approaches, and improve code quality.

CodeClimate is a great service which helps developers improve the quality of their code by analysing a range of key metrics. These include:

• Duplicated Code
• Excess Public Methods
• High Total Complexity
• Complex Methods
• Debug functions are present
• Short Variable Names
• Use of the system command

It integrates with a number of existing tools, such as PHPUnit for PHP, where it takes account of those tools in the overall calculation of the code’s GPA. We’ll see a bit of that soon when I add some code coverage to the project.

Logging In With GitHub

Before we can get everything setup, you’ll need to ensure you have an account. Gladly, you don’t need to register. All you need to do is click “Log in with GitHub” at the bottom of the login page. If this is your first time logging in with GitHub, you’ll be redirected to GitHub, where you’ll be asked to authorise Codeclimate for access to your GitHub credentials. Click OK and you’ll be redirected back to Codeclimate and logged in.

Adding Your Project

After that, you’ll see any projects you may already have listed, none if this is your first time. Otherwise you’ll see one, as I have in the screenshot below.

To add a new one, click “Add Open Source Repo” on the right hand side, where you can specify the account and repository name, under “GitHub repo name”, and click “Import Repo from GitHub” to start the import process.

Whilst that’s happening, you’ll see a page, similar to the one below. This page doesn’t refresh automatically. So to check the status, which shouldn’t take too long, reload the page after about 30 seconds – 1 minute. When everything is finished importing, you’ll see an initial page as below.

I think it’s pretty thoughtful how the ranking system is similar to a school report, where you get a GPA ranking for your code – so you know in a moment how it’s faired. A GPA of 4.0’s pretty good, don’t you think?

Updating Travis’ Configuration

Now that was the easy part. Next comes the fun. For this, you need to make a number of changes. Specifically, we’re going to need to:

1. Add a new Composer package
2. Update the PHPUnit configuration
3. Add a CodeClimate Configuration in .travis.yml

Let’s start at the top. Firstly, run composer require codeclimate/php-test-reporter –dev in the root of the project directory, which will add the CodeClimate test reporter for PHP package to the dev requirements section, and update the vendor directory.

Next, you need to update phpunit.xml.dist, to enable logging, specifically using the Clover format. To do that, add the following line to the file.

<logging>
      <log type="coverage-clover" target="./build/logs/clover.xml"/>
    </logging>

To ensure that the ./build/logs/ directory is always present, run the following command. This will ensure that it’s present and under Git control:

bash mkdir -p ./build/logs && touch ./build/logs/.gitkeep

Now we’re down to the last step, configuring Travis to work with CodeClimate. To do that, in .travis.yml, add the following further configuration options:

after_script:
  - vendor/bin/test-reporter
addons:
  code_climate:
    repo_token: <YOUR_TOKEN>

To get the token, to replace <YOUR_TOKEN> with, when viewing your project in CodeClimate, click Settings -> Test Coverage, and down under “PHP Instructions”, under Step 4, copy the token which it has listed there. This token is specific to this repo on Code Climate.

Note: This should be enough to get it working for you. However, if you see the lineUnexpected response: -60 server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none, in the job output, then, you need to add the configuration below, as this is a known issue.

Alternate Configuration

after_script:
  - CODECLIMATE_REPO_TOKEN="<YOUR_TOKEN>" vendor/bin/test-reporter --stdout > codeclimate.json
  - "curl -X POST -d @codeclimate.json -H 'Content-Type: application/json' -H 'User-Agent: Code Climate (PHP Test Reporter v0.1.1)' https://codeclimate.com/test_reports"

Adding Code Coverage

Now if we don’t change anything, the CodeClimate project Timeline’s not going to change, as we’ve not met the criteria for it to do so.

Gladly, they’re quite straight-forward, one of them being an increase in code coverage. So to do that, I’ve added a simplistic constructor to the entity, and a test class for the SalesData entity, which you can see below.

// new SalesData entity constructor
    public function __construct($data = array())
    {
        if (!empty($data)) {
            foreach(get_class_vars(__CLASS__) as $property => $value) {
                if (isset($data[$property])) {
                    $this->{$property} = $data[$property];
                }
            }
        }
    }

<?php
// SalesData entity test
namespace AuraFramework_Project;

use DatabaseObjectsEntitySalesData;

/**
 * @coversDefaultClass DatabaseObjectsEntitySalesData
 */
class EntityTest extends PHPUnit_Framework_TestCase
{
    /**
     * @covers ::__construct
     */
    public function testObjectIsInitiallyEmpty()
    {
        $salesData = new SalesData(array());
        foreach(get_object_vars($salesData) as $property) {
            $this->assertTrue(is_null($property), "Property {$property} should be null.");
        }
    }

    /**
     * @covers ::__construct
     */
    public function testObjectCanBeInitialised()
    {
        $data = [
            'TrackId' => 1, 'TotalSales' => 100, 'TrackName' => 'Hey Baby!',
            'Genre' => 'Bubblegum Pop', 'AlbumTitle' => 'Tragic Love Songs',
            'ArtistName' => 'Unknown'
        ];

        $salesData = new SalesData($data);

        foreach(get_object_vars($salesData) as $property => $value) {
            $this->assertEquals(
                $data[$property],
                $salesData->{$property},
                sprintf("Property %s should be set to %s", $property, $data[$property])
            );
        }
    }
}

When that’s done, commit all the changes and push them to the repository. When the next build’s done, you should see the timeline for your project in CodeClimate change to look something like the following.

Note: If you're keen to learn more about CodeClimate, either get started with them by adding an open source project of your own, or stay tuned for an upcoming article on them.

 Wrapping Up

And that’s how to use some of the more advanced configuration options and features of Travis CI, including notifications to HipChat and IRC, and integrating it with CodeClimate to help reduce the stress and overhead of managing your software projects.

Are you already using Travis? Share your thoughts in the comments. If this is your first time seeing Travis, are you keen to add it to your workflow?

After writing my last article on Developing Applications with Laravel – Part 3 I started on part 4 and I took a look back at early controller code I had written and realised there must be a better way to validate form data and then call the lower level model code that saves the data back to the database.

After some investigation I concluded that using both the Request classes and a Service Layer implementation would be a nice way to then use the Eloquent code we coded in the model classes in the previous article. So rather than just jump into part 4, I decided this shorter article would be a nice fit and provide a useful working implementation on the topic of Request and Service Layers.

As I delve more and more into Laravel I find myself constantly refactoring code into smaller more manageable and more reusable pieces. One area this has been beneficial has been in my business logic where I handle forms and save data back to the database.

In this article I am going to refactor some old code to use Request Validation and add a Service layer. Request Validation files can be found in /app/Http/Requests, in a fresh application you will not have any files until you manually create them.

Using the artisan tool, I have created each Request Validation class, a sample command follows:

php artisan make:request WorkFlowRequest

This will create a templated Request class in the directory mentioned above. The class comes with two methods by default, authorize() and rules().

For testing I edited the authorize() method to return "true;" rather than the default "false;",  this enables authentication when called. If you need custom authentication handling then this is where you put it and I will touch on that in another article. If authorize() returns false then a post of the form will display “FORBIDDEN” in the top corner of the web browser.

The rules() method is where we return an array of validation rules. The following are an example:

public function rules()
{
return [
    'workflow_name'=>'required|min:5|max:128',
    'workflow_description'=>'required|min:5|max:1024',
    'workflow_aid'=>'required',
    'workflow_create_date'=>'required',
    'workflow_status'=>'required'
    ];
}

If the completed form meets the validation then the controller code is executed for the given route provided the class is defined in the method call as shown below:

Before changes to Controller method:

public function SaveWorkflow($id)

After addition of Request Validation:

public function SaveWorkflow(WorkFlowRequest $request, $id)

There is no change to the route logic to include the request class.

In addition to the changes to the standard templated class file outlined above, I also added a messages() function so I can return failure messages back to the form automatically. The messages() method is not defined by the artisan “make” command so you need to manually add it. The method is simple enough:

public function messages()
{
    return [
        'workflow_name.required'=>'The workflow name is required',
        'workflow_name.min'=>'The workflow name must be at least 5 characters minimum',
        'workflow_name.max'=>'The workflow name must be between 5 and 128 characters',
        'workflow_description.required'=>'A description is required (>5 and < 1025 characters)',
        'workflow_description.min'=>'Description must be 5 or more characters',
        'workflow_description.max'=>'Description must be less than 1025 characters',
        'workflow_status.required'=>'Status field is required'
        ];
}

The complete Request file now looks like:

<?php namespace AppHttpRequests;

use AppHttpRequestsRequest;

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

    /**
     * Get the validation rules that apply to the request.
     *
     * @return array
     */
    public function rules()
    {
        return [
            'workflow_name'=>'required|min:5|max:128',
            'workflow_description'=>'required|min:5|max:1024',
            'workflow_aid'=>'required',
            'workflow_create_date'=>'required',
            'workflow_status'=>'required'
        ];
    }


    public function messages()
    {
        return [
            'workflow_name.required'=>'The workflow name is required',
            'workflow_name.min'=>'The workflow name must be at least 5 characters minimum',
            'workflow_name.max'=>'The workflow name must be between 5 and 128 characters',
            'workflow_description.required'=>'A description is required (>5 and < 1025 characters)',
            'workflow_description.min'=>'Description must be 5 or more characters',
            'workflow_description.max'=>'Description must be less than 1025 characters',
            'workflow_status.required'=>'Status field is required'
        ];
    }

Controller Code

Open the relevant controller file (for this example its called WorkflowController.php) and locate all the code that checks the validity of fields during insert and update operations, there may only be two places, an initial save method such as SaveWorkflow() and an UpdateWorkflow() method when you edit and save the form data.

Lets look at the original method before changes:

public function SaveWorkflow($id)
{
    $WF = new AppWorkflows();
    $form = Input::all();
    $name = $form['workflow_name'];
    $desc = $form['workflow_description'];
    $aid = $form['workflow_aid'];
    $status =$form['workflow_status'];
    $crdate =$form['workflow_create_date'];
    if(strlen($name)>8)
    {
        if($id == $form['id'])
        {
            $data = array(
                'workflow_name'=>$name,
                'workflow_description'=>$desc,
                'workflow_aid'=>$aid,
                'workflow_status'=>$status,
                'workflow_create_date'=>$crdate);
            $rv = $WF->UpdateWorkflow($id,$data);
            if($rv==1)
                Session::flash('flash_message','Workflow updated successfully!');
            if($rv==0)
                Session::flash('flash_error','No Workflow update needed!');
        }
        else
            Session::flash('flash_error','ERROR - Invalid Workflow record.');
    }
    else
        Session::flash('flash_error','ERROR - Workflow name is too short (more than 8 characters please).');
    return $this->ShowWorkflowList();
}

The original method does both the crude validation and saves the data back to the database via the Model code. It's acceptable but we can now refactor it to slim down our code. First, change the function signature to include the Request class, next remove all code that checks the fields and their lengths, that's now done for us in the Request validation rules() method.

The slimmed down code before we add a Service layer looks like this:

public function UpdateWorkflow(WorkFlowRequest $request,$id)
{
    $WF = new AppWorkflows();
    $data = array(
        'workflow_name'=>$request['workflow_name'],
        'workflow_description'=>$request['workflow_description'],
        'workflow_aid'=>$request['workflow_aid'],
        'workflow_status'=>$request['workflow_status'],
        'workflow_create_date'=>$request['workflow_create_date']);
    if($WF->UpdateWorkflow($id, $data) == 1)
    {
        Session::flash('flash_message','Workflow updated successfully!');
    }
    return $this->ShowWorkflowList();
}

We can shorten it even furthur IF the form field names match the database column names exactly to:

$data = $request->except(['_token'])

Already we have reduced the code significantly and made the framework do a lot of the work for us, as a bonus, our validation is in one place (the Requests directory) so additional fields can be changed in the validation logic without impacting any methods that use it.

However, there are two issues with this code, in this example it's duplicated for two methods (SaveXXXX() and UpdateXXXX() ) so we do have the potential of incorrectly saving some fields and not others if we do modifications. We also can't see our validation errors in the View when the validation fails, so we need to implement that facility as well. Our first step of the refactor is completed.

Capturing Errors in the View

Inside every form handling view, you can display the form validation errors using the following code. It first checks how many errors and returns a list. This code does not highlight the field that is at fault so you can add to it to do that later.

@if(count($errors)>0 )
    <div class="alert alert-danger col-xs-4">
        <ul>
        @foreach($errors->all() as $error)
            <li>{{ $error }}</li>
        @endforeach
        </ul>
    </div>
@endif

If there are no errors then this code does not render anything in the view, so an initial load of a “Save New” form will have no error list and only a blank form shown as expected. When we display the edit form, there will be no issues so the view renders accordingly. The Validation logic will fill the $errors array with the list of fields that failed validation in the Request class, so these will be listed in a unordered bullet list in a red div in our Bootstrap application framework.

The Service Layer

When you map out the directory structure of Laravel 5.2 you find there is no “Services” folder. Don't confuse this with ServiceProviders which are a different topic. To solve this we will add a new directory, and in this example it will be under the “app/Models” directory. We also need to map it in our composer.json file IF we don't use a separate namespace, if you use the App namespace then you need to include these mappings:

"autoload": {
    "classmap": [
        "database",
        "app/Models",
        "app/Models/Services",
        "app/Tasks"
        ],
        "psr-4": {
            "App\": "app/"
            }
    },

Now we go to our Models directory and create the Services directory.

# cd app/Models
# mkdir Services 
# cd ../..
# composer dump-autoload

By now doing a "composer dump-autoload", we will configure our project with the new directory. We can now add a Service class to handle saving our data back.

There is no Artisan tool to make the Services class, so we can change into the directory and create the file manually. The WorkFlowService class will have two public methods, insert() and update(). This will take the data from our request validation and persist it to our database. It provides a single place where both operations are performed and called from anywhere in the framework. The class file looks like:

<?php namespace App;

use AppHttpRequestsWorkFlowRequest;



class WorkFlowService
{

    public static function insert(WorkFlowRequest $request)
    {
        $WF = new AppWorkflows();
        if($WF->InsertWorkflow( $request) > 0)
        {
            Session::flash('flash_message','Workflow Saved!');
        }
    }




    public static function update(WorkFlowRequest $request)
    {
        $WF = new AppWorkflows();
        if($WF->UpdateWorkflow($request['id'],$request) == 1)
        {
            Session::flash('flash_message','Workflow updated successfully!');
        }
    }
}

Inside our controller we now change the previously refactored method yet again, this time to use the service layer:

public function SaveWorkflow(WorkFlowRequest $request,$id)
{
    AppWorkFlowService::update($request);
    return $this->ShowWorkflowList();
}

At the top of our controller include a use statement for the Service class.

use AppHttpRequestsWorkFlowRequest;
use AppModelsServicesWorkFlowService;

This exercise has considerably reduced our controller code, it has also placed our insert and update code into a single file where it can be maintained much easier with virtually no gremlins coming in as a result of column changes.

Now you can refactor all methods that handle form code and save considerable space.

-oOo-

Update August 2017: I am currently updating this article with more modern syntax and removal of a large number of now obsolete statements. Generally the code concepts are still valid however, please check back for updates in due course.

This is Part 3 of Developing Applications in Laravel 5. To recap so far:

• In Part 1 I covered developing a simple application that exercised the three essential components of the Laravel eco-system, that being Models, Views and Controllers.
• In Part 2 we looked at Views and we went through the steps of doing a refactor on an old blade template.

In this article we will look at Models, in particular using Laravel's Fluent Query Builder to build a Model to access the database and retrieve data using different queries. But first lets re-cap where a "Model" fits into the big picture. 

When a Request reaches our application, the Laravel framework looks up a route table for a matching path. In routes.php we typically define a Path, Controller and Method which allows our code to be called as needed. So for any path, typically a Controller is instanced and a method inside it is called. From this Method, Models are usually invoked, data retrieved and business logic applied which then results in data that needs to be displayed. The Controller returns a View object, passing the data with it which is then rendered back to the user using the Blade Templating engine.

For this article, the key point is when the Controller is invoked, it gets data from one or Models as a result of User input or program Actions. Models usually get their data from a database, sometimes a flat file or other external data source. One of the big mistakes I see in code samples in many tutorials is direct access to a database being called from within a Controller or View rather than via a Model, even worse the data access methods used are typically low level SQL calls. In reviewing these code samples I consider them to fail dramatically as "good" examples; for the following reasons:

1. In a large application, Database code cannot be maintained in the long term if its scattered with business logic.
2. Changes to the Database engine often introduce incompatibilities that are time consuming to refactor if code is not contained in a Model.
3. Poor coding skills and a lack of experience may lead to Database specific code being duplicated, introducing errors.
4. Limits enhancements to functionality.
5. Long term maintenance of production applications is hampered due to poor Database code design.

In Laravel there are several ways to get access to a database, you can:

• Use the low level interface if you wish (see: Database), I highly suggest you re-think that path if that is what you are use to doing.
• You could go the high level interface called Eloquent, which has some powerful features on offer, or
• You could go middle of the road and use the Fluent Query Builder.

When I initially started Laravel Development, the Eloquent path looked attractive, but I quickly found difficulties with my then limited knowledge to manipulate the data collections returned from simple queries. I investigated the Fluent Query Builder and immediately had results, I also found solutions to all my needs so I began to use it for all my applications, even if you have 100's of tables, Fluent is still  a viable solution.

Creating a Model

I find using the Artisan tool is a great way to create a model file, below is the syntax for it. When creating a Model it is often good to also create a Migration file with it, if you recall from the earlier articles in this series, the Migration file is where we define our database table and its columns.

# php artisan help make:model          
Usage:
  make:model [options] [--] <name>

Arguments:
  name                  The name of the class

Options:
  -m, --migration       Create a new migration file for the model.
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
      --env[=ENV]       The environment the command should run under.
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
 Create a new Eloquent model class

So if we create a table called Registrations we can use the command line:

#php artisan make:model Registrations --migration -vvv
Model created successfully.
Created Migration: 2016_03_24_111120_create_registrations_table
#

The Model file generated is bare at best, but it doesn't hurt to have it done via the tool, you will find the Model file in the "app" dicrectory:

<?php namespace App;

use IlluminateDatabaseEloquentModel;

class Registrations extends Model
{
    //
}

The migration file generated however does have extra support code in it.

<?php

use IlluminateDatabaseSchemaBlueprint;
use IlluminateDatabaseMigrationsMigration;

class CreateRegistrationsTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::create('registrations', function (Blueprint $table) {
            $table->increments('id');
            $table->timestamps();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::drop('registrations');
    }
}

Structuring a Model

Below is a file for a table called "account_plans" from a real application (still in development). I selected it as it has a reasonable number of columns, it's still under development so I can make changes if needed and I can refactor the code with no production issues.

<?php namespace App;

use IlluminateDatabaseEloquentModel;

class AccountPlans extends Model
{
protected $id;
protected $plan_name;
protected $plan_description;
protected $plan_status;
protected $plan_base_cost;
protected $plan_cnt_clients;
protected $plan_cnt_debtors;
protected $plan_cnt_users;
protected $plan_cnt_storage;
protected $plan_additional_clients;
protected $plan_additional_debtors;
protected $plan_additional_users;
protected $plan_additional_storage;
protected $plan_date_created;

#
#
#
public $timestamps = false;
#
#
#
protected $fillable = array('plan_name','plan_description','plan_status','plan_base_cost','plan_cnt_clients','plan_cnt_debtors','plan_cnt_users','plan_cnt_storage','plan_additional_clients','plan_additional_debtors','plan_additional_users','plan_additional_storage','plan_date_created');



    public function InsertPlan($d)
    {
        $today = date("Y-m-d");
        return DB::table('account_plans')->insertGetId(
            array(
                'plan_name'=>$d['plan_name'],
                'plan_description'=>$d['plan_description'],
                'plan_status'=>'A',
                'plan_base_cost'=>$d['plan_base_cost'],
                'plan_cnt_clients'=>$d['plan_cnt_clients'],
                'plan_cnt_debtors'=>$d['plan_cnt_debtors'],
                'plan_cnt_users'=>$d['plan_cnt_users'],
                'plan_cnt_storage'=>$d['plan_cnt_storage'],
                'plan_additional_clients'=>$d['plan_additional_clients'],
                'plan_additional_debtors'=>$d['plan_additional_debtors'],
                'plan_additional_users'=>$d['plan_additional_users'],
                'plan_additional_storage'=>$d['plan_additional_storage'],
                'plan_date_created'=>$today
                )
            );
    }



    public function getByID($id=0)
    {
        return DB::table('account_plans')->where(['id'=>$id])->get();
    }

}

The basic code shows two methods, InsertPlan() and getByID(), (with no comments). We will add more methods as we go (and comments) but these two methods will help us start building basic functionality for use in our Controller.

You will also notice there are two other variables defined in the Model file, $timestampes and an array called $fillable. "Timestamps" are automatically defined when you use Artisan to create a Migration and the framework will try to update a timestamp column it assumes is there, so settings this to false disables this behaviour. This line is not normally incuded in the pre-built Model, you need to add it and set it to false. 

"Fillable" is for mass assignment protection, if the variables in the table are not defined in "fillable", you cannot update them and attempts to do so will cause a Mass Assignment Exception in your application. You can also define an array called "guarded" to define columns that cannot be updated en-mass.

Lets look at the insert method, apart from the data we pass in, columns such as "status" and "date_created" are assigned set values during the insert which is a logical action to do. In our application, setting these makes the account plan go active immediately.

When the controller invokes this object it will use the following syntax:

$AccountPlans = new AppAccountPlans();

To then access a method (in this example the getByID() method, we will call the method using:

$rows = $AccountPlans->getByID($account_plan_id);

In its present form the Model has both methods for talking to the Database and it has protected variables to hold database parameters that can represent a single row in the table. Ideally an Insert, Update or getByID() method should update these values to reflect the row data in the Model, this effectively makes the Model a Data Transfer Object (DTO) which will be useful in our application down the track.

If we update our Model to also be a DTO then the code to do this will look something like:

 public function InsertPlan($d)
    {
        $this->plan_name = $d['plan_name'];
        $this->plan_description = $d['plan_description'];
        $this->plan_status = 'A';
        $this->plan_base_cost = $d['plan_base_cost'];
        $this->plan_cnt_clients = $d['plan_cnt_clients'];
        $this->plan_cnt_debtors = $d['plan_cnt_debtors'];
        $this->plan_cnt_users = $d['plan_cnt_users'];
        $this->plan_cnt_storage = $d['plan_cnt_storage'];
        $this->plan_additional_clients = $d['plan_additional_clients'];
        $this->plan_additional_debtors = $d['plan_additional_debtors'];
        $this->plan_additional_users = $d['plan_additional_users'];
        $this->plan_additional_storage = $d['plan_additional_storage'];
        $this->plan_date_created = $today;

        $today = date("Y-m-d");
        $this->id = DB::table('account_plans')->insertGetId(
            array(
                'plan_name'=>$d['plan_name'],
                'plan_description'=>$d['plan_description'],
                'plan_status'=>'A',
                'plan_base_cost'=>$d['plan_base_cost'],
                'plan_cnt_clients'=>$d['plan_cnt_clients'],
                'plan_cnt_debtors'=>$d['plan_cnt_debtors'],
                'plan_cnt_users'=>$d['plan_cnt_users'],
                'plan_cnt_storage'=>$d['plan_cnt_storage'],
                'plan_additional_clients'=>$d['plan_additional_clients'],
                'plan_additional_debtors'=>$d['plan_additional_debtors'],
                'plan_additional_users'=>$d['plan_additional_users'],
                'plan_additional_storage'=>$d['plan_additional_storage'],
                'plan_date_created'=>$today
                )
            );
        return $this->id;
    }

We can also add the code block to the "update" and "getByID()" methods and our object will be updated accordingly when these methods are called. We can even add a Constructor and pass in the row ID and fill the object that way if required.

Accessing and Manipulating Data

If we wanted to get a single row from our application, we can call the getByID() method in our model as follows:

$row = $AccountPlans->getByID($account_plan_id)[0];

Which at a lower level in the Model calls: 

public function getByID($id)
{
    return DB::table('account_plans')->where(['id'=>$id])->get();
}

The basic operations an application will typically perform on a database that will result in changes are Insert's, Update's and Deletes. Selects on the other hand will only read from the database and if no index is specified on the columns that form the selection then the SQL engine will perform a sequential read of the tables involved which can have significant performance implications.

We already have a basic insert using Fluent syntax, this form uses an array of columns and returns the inserted row ID. Lets add a delete method:

public function DeleteByID($id)
{
    return DB::table('account_plans')->where(['id'=>$id])->delete();
}

The where clause uses the row ID which is a primary key and the method will return the number of deleted rows. Inside the where clause you can see the 'id' parameters are encased in an array [] syntax. You will also see that the delete() method is chained to the where() method similar to our getByID() method above. When using the Fluent Query Builder, chaining will be used many times to join operations together.

Lets now look at an Update method, in this case we will use most of the columns in our UpdateAccountPlan() method (without saving the data into the Model):

    public function UpdateAccountPlan($d)
    {
        return DB::table('account_plans')->where(['id'=>$d['id']])->update(
        array(
                'plan_name'=>$d['plan_name'],
                'plan_description'=>$d['plan_description'],
                'plan_status'=>$d['plan_status'],
                'plan_base_cost'=>$d['plan_base_cost'],
                'plan_cnt_clients'=>$d['plan_cnt_clients'],
                'plan_cnt_debtors'=>$d['plan_cnt_debtors'],
                'plan_cnt_users'=>$d['plan_cnt_users'],
                'plan_cnt_storage'=>$d['plan_cnt_storage'],
                'plan_additional_clients'=>$d['plan_additional_clients'],
                'plan_additional_debtors'=>$d['plan_additional_debtors'],
                'plan_additional_users'=>$d['plan_additional_users'],
                'plan_additional_storage'=>$d['plan_additional_storage']
                )
            );
    }

As per the delete() call, there is a where clause which uses our ID of the row, passed in the array called $d. We don't update the date created field so its left out of the update statement. There is nothing wrong with creating other update methods such as:

public function UpdateStatus($id,$status)
{
    return DB::table('account_plans')->where(['id'=>$d['id']])->update(['plan_status'=>$status]);
}

If we chain "where" clauses we create an "AND" condition, for a logical "OR" clause we can use orWhere() instead and we can use Advanced Where Clauses to build as complex a query as we need.

A simple AND clause would look like:

public function GetClientsDebtors($client_count, $debtor_count)
{
    return DB::table('account_plans')
    ->where(['plan_cnt_clients'=>$client_count])
    ->where(['plan_cnt_debtor'=>$debtor_count])
    ->get();
}

Finding dates always seams to be an issue for people, but if you use YYYY-MM-DD formatting then using logic such as whereBetween() will return rows between these dates but not including the dates.

return DB::table('account_plans')->whereBetween('plan_date_created', ['2015-08-01', '2015-08-20'])->get();

So that's our basic Create, Update and Delete methods covered, lets look at some selects on this table, lets find all rows which have less than 10 clients and 10 users:

In our controller:

$AccountPlans = new AppAccountPlans();
$rows = $AccountPlans->ClientUserCount(10,10);
foreach($rows as $row)
{
    echo "Plan ID is: $row->id ";
}

And Our method in our Model:

public function ClientUserCount($clients=1,$users=1)
{
    return DB::table('account_plans')
        ->where(['plan_cnt_clients'=>$clients ])
        ->where([ 'plan_cnt_users'=>$users ])
        ->get();
}

By chaining our where() clauses one after the other we have created the AND logic needed to select on multiple columns.

We can extend the where clause to also use an IN clause, which is a popular method of restricting a query to a subset of records. Lets say we have a group of accounts that use account_plan 100, and we want to get all the clients under each account using that plan. So we need to build a list of accounts first, then use the list to get the clients.

public function getClientsByPlanID($plan_id)
{
    $accounts = DB::table('accounts')->where(['account_plan_id'=>$plan_id])->lists('id');
    return DB::table('clients')->whereIn('client_account_id', $accounts)->get();
}

The first line gets a list of  'id' columns's from the 'accounts' table that have a plan ID of what ever we passed into the function.

The whereIn() statement matches the list given to the column name in the 'clients' table and returns rows using the get().

So far a lot of our where clauses have been "this == that" so if you need to use the 'LIKE' operator, such as the function below for finding all DEMO users in our "users" table, then the where clause takes the form:

public function getDemoUsers()
{
    return DB::table('users')->where('usr_type','LIKE',"DE%")->get();
}

We could adds lots more examples here especially for inner joins, outer joins, unions, aggregators, groupBy and a host of SQL standard operations. One very handy feature is the increment and decrement operation. This method will select, increment and update an integer column (as an option you can also pass the increment value if greater than 1): 

public function IncrementAssigned($id)
{
    return DB::table('users')->where(['id'=>$id])->increment('user_assigned');
}

But lets divert our efforts to using the Model as a DTO and wrap up.

Earlier in this article we mentioned our protected variables that represent 1 row of data. We also mentioned that the Insert, Update and getByID() methods were ideal places to update the data held in the class. To make a DTO useable you will need to decide if you provide public access to the variables or provide individual accessor methods. The advantage of accessor methods is when you use an tool that has an intelligent IDE, it can provide syntax highlighting, auto-complete and documentation options. If you use the "magic hooks" method by providing a __get() method you circumvent these useful features.

For reference, the PHP "Magic Methods" code for accesing internal class variables looks like this:

A PHP class accessor method using __get()

	public function __get($name)
	{
		if(isset($this->$name))
		{
			return $this->$name;
		}
		else
		{
			return false;
		}
	}

Moving Forward

Each table in your project should have its own Model file. Its best to use the artisan tools as it may introduce features in later versions that add more versatility to the models it creates. The only issue I have with the creation of the model is it's placed in the 'app' directory rather than a special purpose "app/Models" directory. To fix this, I create an entry in my composer.json file to enable the inclusion of the classes in app/Models. The line to add looks like this:

   "autoload": {
        "classmap": [
            "database",
            "app/Models"
        ],
        "psr-4": {
      

You will need to do a clearing of the artisan caches using php artisan cache:clear and also config:clear. After that run a composer dump-autoload and the next time your application runs the model files in app/Models will be useable. You will need to move each newly created model into this directory as the artisan tool will still create them in the default location.