PHP Interfaces, Traits, and Inheritance, how and when to use them

Hi all

So this one is going to be fairly short and simple, I hope! What I am going to cover, and this does assume so prior knowledge, is what interfaces, traits, and inheritance are; and some different use cases for them.

So the first one, and maybe the easiest one to cover, first:

Inheritance

In its simplest term, and I’m going to try and keep things simple in this article. In very brief terms, inheritance is about extending something which exists. Of course, you may well have created this base on which you’re extending.

Simple use case: User class, extended by an Administrator class. This would be because that an Administrator can do everything a user can do, but a User can’t necessarily do everything an Administrator can do.

The way you would do this in PHP would look like:

class User
{
    // Regardless of whether you're a standard user or an administrator you would have access to this method
    public function getUserId() : int
    {
        return $this->id;
    }
}

class Administrator extends User
{
    // Only administrators can delete users
    public function deleteUser(int $userId)
    {
        // Do something here
    }
}

Of course, there are a million ways of using this, but essentially what you’re doing here is following a single line of inheritance, each extension gaining its own functionality. Something else of note is that you can override (except where the final keyword is used) methods and classes.

There are many ways you might want to do this, including several layers of inheritance, or multiple classes extending the same base.

Interfaces

This is concept defines a set of interfaces (or integration points), though the key theme here is that an interface can be applied to anything. You’re specifying very little, except that the class implementing this interface must abide by the rules laid out.

interface Notifiable
{
    public function getEmailAddress() : string;
}

Now the thing to note here is that the interface simply doesn’t care how you retrieve that email address, but you must have a way of doing it, and any class this is applied to must follow those rules.

The easiest use case for an interface, that I can think of, is something like the above. Notifiable, anything within your system could be notifiable. An instance of the system, a user, an organisation, a team or department. It doesn’t matter, applying the interface means that it could be parsed and handled, through a notification service.

Traits

I’ve tried to explain this one recently, and the use case for it. The easiest way I found of explaining it recently has been: An interface lets you define the input and output of some methods, inheritance lets you gain functionality from parent classes. Traits are for where you don’t want to use parent classes (because you can only extend one class at a time), but want to bring the “meat” of some methods across.

At the risk of causing some controversy here (again) I’m going to say the easiest use case to explain with traits is a logging class, which might look something like

trait Logger
{
    // PSR-3 compliant functionality here
}

class MyThingDoer
{
    Use Logger;
}

All this does is allows the MyThingDoer class to do anything that the Logger trait specified.

In Summary

I’m not necessarily advocating the use of these three sets of functionality, or how they should be used, or anything like that. I’m simply documenting their existence and usage in a way that those moving from PHP procedurally into a structured OOP environment might understand it.

I understand there are dependency injection arguments regarding traits, and I think that is a conversation for another day.

So, in a sentence. When you want to have a base class, and things which logically make sense to be extensions – use inheritance. When you want to ensure conformity to a set of rules, so that objects can be parsed into service providers, use interfaces. When you want to simply share functionality across multiple classes, use traits.

I hope this has helped, of course, if you have anything to add, anything you’d like to say or anything to contribute, stories, personal experiences, etc. as always feel free to drop it in the comments.

Quick and Easy PHP Singleton

Hi guys

A really short one today, just because someone asked me about it a couple of days ago. I also though it potentially best to avoid something as controversial as my last post about Eloquent and the Single Responsibility Principle, which caused a bit of a stir during the week.

So, you want to make sure you only ever use one specific instance of a class (maybe a DB connection) and need a quick and easy way to do it. Personally, this is the technique I would use:

<?php

class MySingleton{
  
  // This will hold the instance of the class
  private static $instance = null;
  
  // Declare this as private to stop anybody being able to use the "new" keyword
  private function __construct()
  {
    // Your usual constructor stuff in here
  }

  // This is where you get your instance
  public static function getInstance()
  {
    if(is_null(self::$instance)){
      self::$instance = new self();
    } 
    return self::$instance;
  }

}

All we’re doing here really, in a set of steps:

  • You need a way to hold an instance of the object which is persistent throughout the execution
    This is what the private static $instance is doing
  • You don’t want anybody to be able to directly use the new keyword, because then you’ve lost control of the instances of the object
  • You need to be able to get an instance of the class, which is what the getInstance method is for
  • In getInstance all we’re doing is instantiating the object if one hasn’t get been stored against the $instance static

So, to fetch your instance is simply:

$singleton = MySingleton::getInstance();

Wherever you run that throughout your code you will receive the exact same instance. Particularly useful in things like Database connections, loggers/debuggers and things like that.

Using Git to effectively manage your code

Hi everyone

This time I thought I would give a quick insight into the ways which I have found to be best when working with Git. Especially if you’re in the position where you’ve never had to manage or decide the direction of how to use source control.

I’m sure you all know the benefits of source control, whether Git or other, but I thought it would be worth highlighting them anyway:

  1. Structured, integrated development (that is, you can have multiple people working on the same project/release at any given time)
  2. Simplified deployments
  3. Easy way to track where your code is in the SDLC (Software Development Life Cycle)
  4. Easy way to rollback if terrible bugs have somehow gotten through onto a live environment

Introduction

If you’re faced with the somewhat daunting task of introducing source control to your digital team there are a few things you’re going to need to consider.

  1. What are you hoping to achieve by source control? Are you just hoping to see who has done what, or are you looking to version control your code, etc?
  2. What is the skill level with Git on the command line like in your team, do you need to set aside some time for training on this?
  3. What kind of software are you managing, are there lots of different systems, or a single all encompassing one?

The answers to these questions will largely dictate how you need to go about doing this. I will also strong recommend, if you have dependencies, using something like Packagist and composer to manage this as, trust me from experience, it will greatly lessen your pain of staging and production deployments.

Setting up the repositories

This is where there is some debate. Take WordPress, for example, do you source control the whole installation? Or just specific parts?

For me, personally, I feel the best thing to do is source control the specific part you can install, in WordPress this might be a theme or a plugin, in Moodle it’ll be a module or something like that. The reason for this, in my mind, is that there is already version control on everything else within there. WordPress and Moodle both support version numbers, as does Joomla and I’m sure Drupal does too.

So why source control someone else’s code? They’ve already done this for you.

Woah there, Nelly! There’s a huge “gotcha”…

The worst thing you can do in any kind of version control, in my personal opinion, especially if the repository is publicly accessible: do not store passwords, encryption keys, API or access keys in your repository. It’s a terrible idea, and there is a vulnerability with Git that, unless explicitly disallowed, someone can access your .git directory (where all of your source code, references and everything else are stored) and could access your passwords.

The easy way around this is to add a .gitignore to hide your configuration files. Laravel does this itself, as the configurations and keys are stored in a .env file, WordPress will not do this, you’ll need to add /wp-config.php to your .gitignore file, then it will be automatically ignored from your repository forever.

Another word to the wise, if you forget to do this in the first instance, and then decide to delete the file or anything like that; this is version control – change your passwords – the previous commit, including the configuration with all of your passwords and keys and such will still be accessible.

We have repositories, what do we do now?

Now you need to have a working and uniformed way of managing those repositories and the commits. A bunch of non-descript commits is not actually going to do anything to help you manage your source code, I mean, it’ll be there, but it’s not going to be of any use to anyone; it’ll just be handy to say “we have Git”.

I’m going to break the management of your Git repositories into three major parts: commits, branches and tags; which I’ll cover below.

#1 – Commits

In my team I have a rule. Whenever you have completed a job, microtask, fixed an issue, etc. then you need to commit. Anything that you’d be gutted if you lost. We also always push to the remote repository straight away. Git is no use if it only exists on your machine, which you then drop and smash into a quadrillion pieces, is it?

So, for me, push little and often; and explain your thinking in your commits. Here are some terrible commit messages I’ve seen in the past, which will make you realise why, when you’re trying to investigate a bug, you should make sure your messages are good.

Example One: Fixed bug

Fixed what bug?! What was the issue, how did you rectify it, what were you thinking?

Example Two: Various code updates

Well yes, but why?

You can see why this would be frustrating when you’re trying to understand what the code changes were for, especially if you’re investigating an issue on staging or live.

A good commit message usually entails something like this:

1.3 Specification Boilerplating

– Added framework functionality to do something really important, it was important because we had to consider this terrible design flaw

– Improved performance with password hashing; comparison method is now leaner, and is handling the string in a different way to previously

– Resolved Jira issue #GIT-219

So, in summary, commit little and often – with a good message as to why you’re committing, what you’ve just changed/added and what the purpose of it is.

In case you’re unfamiliar with the Git syntax:

git add -A // Add all of the files that have been changed
git add MyClass.php // Specifically add this file to your commit
git add Namespace/AnotherClass.php // Specifically add a file in that directory to your commit
git commit -m "My commit message"

// If you want to get really snazzy

git commit -m "My Commit Subject

A detailed description of everything I did in this commit"

This can be handy if you want to break the files down into specifically what you did to each one.

#2 – Branches

Personally I think any major or minor version should be in its own branch. It’s usually a good idea to name this branches based on the version number and the fact that they’re development (Composer also recognises this)

I also then like to branch for each developer, this makes it easy to keep committing and not worry about conflicts until you explicitly want to merge your stable code – just because it has been committed does not mean that it is, at this point, stable.

My personal preference looks something like this:

| master            - representative of live
|- dev-1-3          - 1.3 version development "hub"
|-- dev-1-3-johno   - my specific development branch

What happens is I branch from master to create my development branch for this version, then I branch from my development branch to do my work, I can commit and push to this branch without any issues. Let’s say Gary joins the party and is going to be developing alongside me; he would then branch from dev-1-3 and create a dev-1-3-gary branch.

When I’m happy my code is stable and ready for integration, I merge my branch into the dev hub branch. But there is a specific way of doing this to avoid conflicts – you do not, under any circumstance, want to be breaking the dev 1.3 branch; what if you have 5 developers merging down from it? You do not want to be that unpopular guy!

Merging looks something like this, in English:

Commit to dev-1-3-johno > Switch to dev-1-3 > Pull > Switch to my branch & merge > Switch to dev hub, merge my branch in

The reason for doing this is any breakages and merging issues you want to handle on your branch; without breaking the dev hub. Then you can merge back without issue.

Assuming no merge conflicts your Git commands are going to look something like this:

// For completeness, this is how you would create your branches
git checkout master
git branch dev-1-3
git checkout dev-1-3
git branch dev-1-3-johno
git checkout dev-1-3-johno

// I'm on my development branch
git commit "My commit message" // My code is committed
git push // My code is now on the remote repository
git checkout dev-1-3 // Jump to the 1.3 development branch
git pull // Get the latest changes, who knows if Gary has pushed something to it
git checkout dev-1-3-johno // Jump back onto my branch
git merge dev-1-3 // Merge Gary's work back in
git push // Push my branch, which now also has Gary's code
git checkout dev-1-3 // Jump back onto the development branch
git merge dev-1-3-johno // Merge my code onto the development branch
git push // Push the development branch, which now has both mine and Gary's code on it

I’ve seen various different ways of managing branches, using versions, everyone having their own development branch, etc. but it is important, I think, to remember the core purpose of the branches – to separate out your commits and code until it’s ready to go onto live.

So, from what I’ve seen, the best way to do your branching is by version. This means you can jump between versions with ease. Maybe you actually start the 1.4 development, which is a long task, before finishing the 1.3 development.

Once you’ve finished the development of 1.3 and it has been released, merge your development branch into master. We’ll cover using tags to help with deployment shortly.

Another Gotcha, this time with branches

One massively important thing to remember with branches, let’s say we’re working on version 1.3 and committing away. A security patch (let’s say version 1.2.12) could be pushed onto master, which you could well lose with your new changes – thus losing the security fix and reintroducing the vulnerability.

Make sure you are merging master back into your main development branch frequently, otherwise you run the very real risk of overwriting bug fixes and patches.

#3 – Tags

The key difference between a branch and a tag is simple: a branch changes over time, a tag does not.

I personally like to use tags to represent a stage in the development process. Following Composer conventions (that’s what international conventions are for) I like to represent the three major checkpoints of any version release:

  1. Ready for staging deployment
  2. Stage passed – release candidate
  3. Deployed onto live  and successfully tested – release

This is quite an easy one really. Composer uses the prefix “v” (for version) when tagging releases and various other conventions which can be found on their website.

So tagging up your code would look something like this

// Depending on your tagging convention, you might tag by version
git tag staging-1-3-0

// Or perhaps staged by month and increment
git tag staging-2017-08-001

// For completeness, on the staging server you would go to the root of the repository
git checkout staging-2017-08-001

// If you are already checked out onto a branch (on live, for example)
git pull origin master --tags

// It will now say you've pulled a new tag, let's say the release candidate for 1.3.0
git checkout rc-1-3-0

// Successful test pass - still checked out onto your RC, which remember, can't change
git tag release-1-3-0
- or - 
git tag v1-3-0

// Failed test - quick rollback to last release, let's say 1.2.12
git checkout release-1-2-12
- or -
git checkout v1-2-12

// At this point it would be a good idea to merge your development branch into master, no separation needed, this code is on live
// Somewhere other than your live environment:
git checkout master
git merge dev-1-3

Be prepared, and have a convention ready, for when something fails staging or fails live deployment. And don’t forget, once your live deployment is finished to tag up the code, because this is now a successful release.

Other gotchas, and things are broken

People who haven’t used Git much before in the past will almost always find a way (and I’m often dumbfounded) to break their repositories. This can be for various reasons; but here are a couple of quick fixes (not for the faint hearted! You will break things)

You can nuke all of your changes by doing this:

Don’t do any of this unless you have a backup of any code you do not want to lose otherwise you will lose it

// Let's just pretend you weren't even at work since your last successful push
git reset --hard; git clean fd;

Alternatively, if it really is FUBAR and you’ve no way of figuring out how to fix it (or don’t have the time) this old chestnut will never fail you

// Let's just pretend this was never a repository
rm -rf .git
git init
git remote add origin {your repository URL}
git pull

The last one really is a last resort and can sometimes get a bit messy. Probably a good idea to have a backup of any code you don’t want to lose if using any of the commands in this section.

In summary, Git will enrich your life

Ultimately, all of this stuff will enrich your development team. It will help you manage your source code effectively, have an easier time with deployments, rollbacks, and seeing what is going on. It also help you to really change the way that you’re working; knowing you always have a nice way of rolling back to any given point.

What the branching structure does is help keep master clean, it also allows lots of developers (I think 8 is the busiest I’ve seen) work on the same version, without constant merge conflicts, which can be a real pain; slow down development, and cause a lot of lost time and frustration.

A word of caution, with this tale: When done badly, Git can be your worst enemy. You have to make sure everybody in your team is singing from the same hymn sheet, so to speak. Otherwise you’re going to end up with all kinds of problems. A single developer not committing their code until the end of a version (when it’s ready for staging, theoretically) can really screw everything up if the other developer has been using Git properly. Education is key on this one. And a few broken repos and salvages of code are lessons hard learned.

Thanks for reading 🙂

Johno

Setting up Private Packagist & BitBucket or GitHub

Hi all

This is a really quick tutorial, because frustratingly I couldn’t find one that offered me this quick guide that had an integrated approach to doing this.

I’m going to mostly cover the bits that I had to learn myself through Googling etc. in the hope that you won’t have to waste hours on Stack Overflow and so on trying to figure out how to get it working.

I’ve used composer a million times, but always as a consumer, not as a publisher. Least of all as a publisher on private packages.

This tutorial makes a couple of assumptions:

  1. You understand what Composer is and how it works
  2. You manage some private repositories and you’re dealing with private packagist for closed source code
  3. You have a basic understanding of what an SSH key is and how to generate one

Step #1 – Get signed up for a packagist.com account

The first thing you will need to do, if you’re using private packagist for your packages, is sign up for an account on packagist.com this will allow you to privately package your code using the usual composer method.

Don’t get confused between packagist.org (which is free and for open source stuff) and packagist.com which is private, and is paid for. Though you do get a free trial which is handy.

Step #2 – Allow access to your organisation/repository

Okay, this is the bit that annoyed me the most I think. BitBucket allow you to do stuff with organisation and app access and stuff.

Both BitBucket and GitHub allow you to grant access to private repositories via an SSH key. Private Packagist provide you with their SSH key, give this key access so that Packagist can access the repository to get the information from your composer.json file.

Step #3 – Generate an SSH key for your machine or server

I’m not going to explain how to do this. A quick google will reveal this, it’s well documented.

Step #4 – The gotcha, what to do with your SSH key

This is the bit that caused me some errors and got quite annoying. I usually use my various accounts to do my pulls, checkouts, etc. so I’ve not used my SSH key with my repositories.

Your SSH key must be allowed on both Packagist and your chosen repository provider (BitBucket or GitHub, usually).

What happens is, you fire off your Composer command. This goes to Packagist.com using your SSH key and will get the information it needs about the package, then it goes off to your repository to get the appropriate code. If you enable on Packagist and not your repository the require/install will fail. If you enable it on your repository and not on Packagist, it’ll tell you that your package wasn’t found.

Step #5 – Minimum Stability

This one is well documented, but still frustratingly buried within a pile of other documentation. There are a whole heap of tags and stuff that you can use, but ultimately the stability of a package is determined from the repository itself.

Learn about how Composer works with your repository here.

Let’s assume you couldn’t be bothered to read that, you just want a quick way to test that this is set up properly. Add a tag of v1.0.0 or whatever version number you’re using. It will assume this is a release and is consequently stable.

Summary

It’s actually remarkably easy getting this running. It’s just frustrating if, at the time like myself, you don’t know what you’re doing when it comes to creating packages, let alone managing closed source stuff through it.

Once it is running, however, it becomes beautiful. It’s a very elegant of managing dependencies, and keeping multiple sets of source code up to date. And for a very small price tag of about €14 per seat, per month; it’s definitely a cost saver. (Plus whatever you spend on repository hosting as well, of course).

I realise there are plenty of ways of hosting your repositories yourself, and of hosting your packages yourself too. This approach is more suited to companies whose development teams are too busy to want to manage this infrastructure; it’s, obviously, up to you to determine whether there’s enough value in managing this in-house, or whether it makes more sense, commercially, to pay a really small fee and not have to worry about it.

Some quick translations, OO PHP to C#

So a recent project has facilitated me brushing up on my C# – so I thought I would share some basic translations of things that can be frustrating when you know the usual programming principles (object orientated programming), but not all the syntax.

A quick couple of points to note:

  1. C# is a strictly typed language, that means you have to know about what your variables are going to be, and yes, you have to declare them somewhere sensible
  2. Accessing methods and properties within your class does not require usage of $this – you’re talking about true scope of variables and methods, so you don’t have to worry about it
  3. Public, protected and private are essentially the same
  4. You have to declare the return types on every method, none of this return an object or false stuff
  5. Namespacing is essentially the same as if you were following the PSR-4 standard
  6. Everything, including strings, are objects
  7. A single quote and a double quote are fundamentally different things

Declaring a variable

Okay, so starting with the basics, declaring a variable is basically the same, except you have to declare the type, so declaring age as a variable, integer, with the value of 25 would look like this in PHP:

$age = 25;

However, in C# it would look like this

int age = 25;

Moving into this being a property in a class, you must rather than optionally, or have to if you’re conforming to PSR-2, so in PHP it looks like this

public $age = 25;

In C# it’s going to look like this:

public int age = 25;

Declaring methods

Okay this is an easy one in PHP, it looks something like this. Using PHP 7.1 we can strictly type the return.

public function myMethod(MyClassOne &$argumentByReference, MyClassTwo $argumentByValue) : ObjectClass

{

    // Do something in your method here

}

// This would be called by doing something like
$object->myMethod($parsedByReference, $parsedByValue);

This one gets slightly different when translated into C# for a couple of reasons. You must declare the types of the parameter, the type of the response(s), it also gets a bit different when calling the method too:

public ObjectClass myMethod(ref MyClassOne argumentByReference, MyClassTwo argumentByValue)

{

    // Do something in your method here

}

// Now calling your method would look slightly different

Object.myMethod(ref parsedByReference, parsedByValue);

Using Objects

Instantiating objects isn’t much different either, really; it looks different but that’s because it’s strictly typed.

Main difference between use statements in PHP and C# (other than that it is using in C#) is that you use a namespace, the classes contained therein (this namespace only, not its children) are automatically available.

In PHP I want to include a class and then instantiate it, will look something like this:

use Vendor\Project\Namespace\ClassName;

// Then you have all of your usual declarations, which we'll get to

$myObject = new ClassName();

However when you want to do this in C# it looks something like this:

using Vendor\Project\Namespace;

// Then all of your usual declarations

ClassName myObject = new ClassName();

Declaring Classes, using Inheritance and Interfaces

This gets a bit different, but only syntactically. We’re going to create Person as an abstract class, this will be extended by the Employee class. Employee is going to implement an interface called Emailable.

For the sake of ease I’ve not separated these into different files

In PHP it would look like this:

abstract class Person{

    // Shared functionality here

}
interface Emailable{

    // Interface requirements here

}

class Employee extends Person implements Emailable{

    // Employee functionality, including Emailable requirements, in here

}

In C# however it would look like this

namespace ObjectOrientatedPrinciples.MyExample
 {
    abstract public class Person
    {
        
    }
    interface Emailable
    {
        
    }
    public class Employee : Person, Emailable
    {
        
    }
 }

You will see from this that C# doesn’t necessarily draw the distinction between classes being extended and interfaces being implemented.

Arrays and Lists

This is actually the only thing I found to be a little bit painful, however there is a decent tutorial on arrays on the Microsoft Developer Network (MSDN)

Closing Off

I’ll leave it at that for tonight. But a quick few bits that I thought might help someone out, it would’ve helped me if I could’ve found this article this morning. Though admittedly probably only saved me an hour or so. Not the point though, here it is 🙂