Simple open source package for Laravel RESTful APIs

Hi everyone

In my last post about creating simple search and filtering for Laravel I said I was considering creating a package to encapsulate this functionality.

Well, I got this done a few weeks ago and have now released it onto Composer (Packagist) as kya/laravel-rest

You can find the repository on GitHub here, and the documentation is in the Wiki.

There is space on there for issues and things, of course. So if you have any feature requests do let me know, the current release is v0.1.

I know it’s going to be useful for me, as I’ve used it a couple of times already; I hope it proves to be of some use for you, too.

Speak to you all soon, JTC

When to use GitHub, when to use BitBucket

This is always a bit of a hot topic, especially amongst teams just getting ready to start properly managing their code through remote repositories.

Disclaimer: I’m only going to talk about GitHub and BitBucket in this article. If your code is your bread and butter, your only offering; you probably should consider hosting your repositories yourself. I’m also sticking with these two as they’re the most widely adopted.

When should I use GitHub?

GitHub can be found at github.com – shameless plug, my user on there is @johnothecoder

Short answer: For anything/everything open source, or where you’d hope for community feedback and maybe even code contributions.

Personally, anything Open Source I think massively benefits from being on GitHub; it’s much more community orientated and you can host as many open/public repositories as you like.

It has some really handy graphs and charts about activity on your repository, and most developers who have anything to do with anything open source will have a GitHub account. On occasion I’ve even been contacted by recruitment agents who have found me through my GitHub, which is kind of cool.

The community on GitHub can be really helpful (though as with all things online there’s always a risk of being flamed) and GitHub, because of its huge market share has ready made integrations, if you’re looking to integrate something into your repository GitHub will almost definitely have it.

When should I use BitBucket?

Short answer: For professional development teams or closed source development

Bitbucket can be found at bitbucket.org

I personally find that, especially for new or small development teams, BitBucket is great. You also get unlimited free private repositories, pricing is instead based on the amount of seats you need (that is, developers on your team who need access to the repository).

So for a professional development team I would always recommend BitBucket, it has all of the features you need – and comes with one very handy thing, which in a professional context gives it, I think, the edge on GitHub: Jira.

Jira is probably, in my experience anyway, the most widely adopted tool for managing development of software. It has a whole host of awesome features, which I’m not going to bang on about as, frankly, they sell it well enough themselves on their website.

However, as most project managers, digital managers, development managers and developers have all used Jira the ready made integration really comes in handy. Those integrations, which will also support you if you make the decision to move into agile, are really handy for growing teams.

Comparison

When it comes to both of these tools (GitHub and BitBucket) they share a lot of handy functionality, which is one of the reasons I’ve never particularly wanted to stray (GitLab can be hosted on your own server and comes with these functionalities too); these features include bug/issue management, wiki, Packagist integration and various other things.

Realistically they’re no better or worse than one another – GitHub comes with integration into Basecamp as standard so that could be handy for digital agencies. Realistically, they will both serve you very well.

Links

GitHub: github.com

BitBucket: bitbucket.com

GitLab: gitlab.com

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

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 🙂

Tips for commercial WordPress, and open source, development

Hi everyone

So I’ve been using content management systems on and off for the best part of 10 years. From the by-gone days of PHP Nuke and when content management systems like PHP Fusion were all the rage. To using more modern, and definitely more widely adopted systems like Joomla and, of course, WordPress; and just to throw other open source stuff into the mix, platforms like Moodle.

Now I’ve returned to using WordPress on a daily basis, but from a different perspective; I don’t do too much development on WordPress personally; my skill set generally lies in building things on frameworks such as CodeIgniter and Laravel, if not bespoke. But I do use WordPress to the extent of managing multisite installations, managing production stability and servers, as well as deployments and migrations.

Having been in the unique position to pick up some legacy code in my time, and seen what does and does not make a WordPress site easy to work on, manage and maintain; I thought I would put together some tips for building WordPress sites, and functionality, which will stand the test of time.

1. Never modify the core

This is a deadly serious one. No matter what you’re working on it should have a specific way of extending functionality, whether through plugins and themes, extensions or a specific namespace where modifications should be added, never, ever, ever modify the core. The same applies to the core code on a plugin.

The reasons for this are really simple; you probably don’t know and understand the full architecture or what you might break by changing this, and more importantly the biggest strength of using something open source is that updates are generally frequently available. The moment you change something in the core you’re going to sabotage any upgrades; you will have to make the choice. Either update the software (absolutely critical) and lose your changes, or don’t update the software and risk leaving bugs, security vulnerabilities, and all kinds of other stuff in there. Not a good position to be in.

2. Choose the right one

WordPress is the most widely adopted content management system in the world. Impressive, right? And technically, yes, anything can be built on it. In the same way any system can be built using .txt files for data storage. It can be done, but that doesn’t mean it should be.

I’ve laboured this point a few times in a few articles and things, but a good developer will know the tools available to them and choose the best one for the job. It is worth spending six months for a content management system and blogging platform, that does exactly the same as WordPress? Of course not. Is it a good idea to build a secure intranet containing sensitive data about national security on WordPress? Of course not. It’s about knowing what’s available and making the best decision based on this.

This is a difficult one, however, as you need to choose the one that fits your needs right now, as well as being compatible with the long term visions of the site; or know from the start that a rebuild will be necessary.

3. Be wary of plugin dependencies

Why use plugin_function when cms_function does the same job, and is probably going to be better supported in the future? When installing plugins, extensions and add ons; always think about the eventualities? What if this plugin’s core is compromised and I need to disable it right now; what will break? What if the plugin stops being supported? How tied into using it am I right now? If you’re managing lots of websites, especially; be wary of the headache you’re going to have if you’re relying too heavily on too many plugins.

If you notice yourself using plugin X on every site you build, or relying on it super heavily, it might be worth doing one of a few things. Either building your own replacement, so you’re in control of the core. Or perhaps wrapping it in your own functionality, so if you want to swap it out, you can. Using a technique called Facading can help with this, hiding plugin functionality behind you facade means you can swap what’s behind the facade out if you need to.

Really the point here is don’t install things willy nilly, think about the dependency you’re creating on this plugin for your website, and how much of a pain it’s going to be if you want to remove it.

4. Always check the source

Depending on the project and the size reading the source code line for line probably isn’t going to be efficient; so that’s not what I’m suggesting here. By source I mean the author, the factory, the company; wherever it comes from. Make sure they’re trusted, WordPress, for example, examines all of the plugins and themes submitted to their public repositories and they’re pretty stringent on their standards, as well as ensuring they’re safe (from a security standpoint).

Most mainstream CMS have white hat security scanning tools that will uncover most, if not all, known security flaws and vulnerabilities. Running these can only be a good thing, as long as you act on the results you get.

5. Don’t be afraid to code things from scratch

There might not be a plugin which does what you want, or doesn’t do exactly what you want. You have 10 requirements from your client. Plugin X fulfils 9 of them. Do not try and hack it to fulfil the 10th, it will only go badly; honestly, I’ve been there and done it a bunch of times.

Just because you usually use X plugin and Y CMS, doesn’t mean you have to this time. Some things are best built from scratch, whether the whole site/software, or a specific functionality. Sometimes the best option is to get stuck in with coding the thing you want. You’d be surprised at how quick this can sometimes be. And just because your CMS offers a specific functionality doesn’t mean you have to use it. WordPress Custom Post Types are a beautiful example of this, as well as their taxonomies. These are both beautiful pieces of functionality; but they’re not the best way to store bespoke data, for example. They exist for a range of things, but primarily to give you a way to show bespoke content, like recipes, and linking them together in a specific way, dietary requirement for example. Storing anything that doesn’t fit into a custom post type and taxonomy doesn’t make sense, so don’t do it.