Let me know if this sounds familiar. Your project is following a coding standard but commits keep making it into master that don’t follow the coding standard. Or during a code review, you realize the author of the merge request hasn’t run it through a linter yet or that the unit tests are now failing. Instead of you having to be “that guy who asks everybody to clean up their code or fix the unit tests”, you could automate these code quality checks. Plus think of the time saved in the back and forth in the code review. The code review no-longer needs to be about code style or if the tests pass, and can instead focus on what matters; is the implementation sound, is there a better way it could be done, and is it properly tested?

You might say “well my IDE catches this type of stuff”, and it’s a common practice to run your linter and unit tests in your IDE. However, for IDE tooling, most code quality tools are up to the developer to set up or not. Plus, sometimes developers miss the warnings in their IDE’s or forget to run the tests before pushing up their merge request. That’s why having automatic code quality checks in the continuous integration (CI) pipeline is a great final catch before the code makes it into master. And don’t get me wrong, I think you should have these checks there as well, but if you wait for the CI pipeline to catch these before you fix them, it’s a much slower process than checking them locally. Especially if you have multiple issues, waiting for the CI pipeline multiple times can slow down your development process. Continuous local validation is quicker than remote.

Plus, wouldn’t it be better if this was caught before the pull request was created? Better yet, before the commit was created? Avoiding messy one-off fix commits or having to squash them constantly? This is where a pre-commit hook can come in handy. Let’s look at three great options to leverage git hooks as a solution.

Side note: If you’re curious why you should follow a coding standard, and how to set up a linter for PHP on the command line or in your IDE, checkout my previous article: Is Your Code Up To Sniff?

Git Pre-commit Hooks

Git provides hooks that allow you to run a script before commiting, before pushing, after merging, etc. If the script doesn’t report a success, it stops you from completing that git action until the script reports a successful execution. The git hook we’re specifically interested in is the pre-commit hook. A pre-commit hook runs when you type “git commit” but won’t bring up the prompt for entering a git commit message if the hook script doesn’t report a success first.

We’ll look at 3 popular tools to achieve this; GrumPHP, Husky (JS), and pre-commit.com (python). Husky is definitely the most popular of the three, but pre-commit.com has been gaining ground with support for multiple languages, and I feel like GrumPHP is really starting to catch on in the PHP community. You might think “why would I need a tool? Just call the lint command from the pre-commit hook” but the 3 biggest reasons to use these tools are:

1. Auto-install

How do you get your team to install the pre-commit hook? Do you ask each of them to manually install it, and to follow instructions on how to do it in your readme? Here’s the clever part: these tools can install the pre-commit hook automatically when developers use Composer or NPM; something they’d have to do to run your codebase anyway.

2. Only Lint Changed Files

A key feature to these tools is that you only want to lint the files which have changed (not the entire project), so that the pre-commit hook can run as fast as possible and not get in the way of getting your commit done. Which is important because running a linter across your entire codebase can take a minute or two if you’re working on big codebases, and having to wait that long each time you’re trying to get a commit created can drive people crazy. 

3. Task Parallelization

If you’re doing multiple tasks (eg. linting and running unit tests) in your pre-commit hook, but these tools can run all the tasks in parallel so they complete much faster.

GrumPHP

GrumPHP is “a PHP code-quality tool” with many features, one of which includes registering a pre-commit to use PHP_CodeSniffer or PHP CS Fixer to lint your code. Though there’s much more it can do on every commit, such as running a PHPUnit (or Pest) test suite, linting the commit message format, normalizing the composer.json file, or running PHPStan or Psalm for static code analysis. You can find a full-list of tasks GrumPHP can perform here.

Some popular open source packages utilizing GrumPHP are fruitcake/laravel-cors and league/omnipay to name a few.

Basic Config Example

Starting off, a great basic config would be to check for syntax errors and code styling. We’ll use `phplint` to check for syntax errors and `phpcs` to run PHP_CodeSniffer for linting code style.

// grumphp.yml
grumphp:
    tasks:
        { phplint: null, phpcs: null }

Advanced Config Example

While the previous example was a great starting point, you’ll most likely want to take advantage of some of the more advanced features:

• Turn on auto-fixers (no need to run fix commands, GrumPHP can fix the issues for you!)
• Add PHPUnit (or Pest) for unit testing.
• Add PHPStan for static code analysis.
• Add ESLint if your project uses frontend javascript eg. React, Vue, etc
• Optional: Turn off ASCII output (GrumPHP uses fun ASCII art in its pass/fail output, but as cool as the ASCII output is, maybe you need to be a little bit more “profesh” if using this in a work environment).

grumphp: {
    ascii: null,
    fixer: { enabled: true, fix_by_default: true },
    tasks: {
        phplint: null,
        phpcs: null,
        phpstan: null,
        phpunit: null,
        eslint: null
    }
}

Notes for Speed

PHPUnit and static code analysis can be slower tasks. You may wish to tweak or drop these types of pre-commit tasks if you find they’re slowing down your commit workflow too much.

PHPUnit

PHPUnit can be slow because it runs all your tests. Ideally, it would only check the test related to the code that changed, but it doesn’t know what other files and tests might be affected by the changed files, so it has to run them all. If you find your commits taking too long, alternatively, you could run only a subset of your unit tests by breaking them up into multiple test suites to make it complete at a satisfactory speed (maybe create a test suite that just includes critical or faster tests). 

Aside: It would be awesome if PHPUnit had the ability to run all tests for a given class (open source project opportunity here)! You could probably write a script to look for tests in two ways;

1. Run any test at “/tests/Unit/{same path as class}Test.php”. This assumes you follow the same folder and naming structure in /tests/Unit/ as you do in /app or /src, but I think that’s relatively common.
2. Run any test with @covers annotations for this class

Static Code Analysis

Unlike PHPUnit for Static Code Analysis it only runs on the changed files, but the process is just generally slower (it’s compute heavy, though they can leverage cache so multiple runs are quicker). I’ve opted for just PHPStan and not Psalm as well, as I found Psalm slower on my Laravel projects.

Alternative to GrumPHP: CaptainHook

CaptainHook is another popular git hook management tool in the PHP community. CaptainHook explains how it compares to GrumPHP on their site. If you plan on having a lot of custom tasks, this might be worth exploring as it’s a little more about managing cli commands, kind of like Husky for Javascript which we’ll talk about next actually. Captain Hook also has support for other git hooks as well (not just pre-commit0, while GrumPHP focuses on pre-commit hooks. A popular package utilizing CaptainHook is ramsey/uuid.

Husky + lint-staged

Is your project partially or completely written in Javascript? Husky might be the tool for you instead of GrumPHP! Husky can manage git hooks to run both JS linters and unit testing, though it can do your PHP or other language pre-commit tasks too. What really brings the power to Husky is lint-staged. lint-staged adds to Husky that concept of only running your hooks against the files that have changed.

Here’s some popular projects using Husky + lint-staged: Create React App, Angular, Electron, Babel, and Webpack. There’s even php community members using it, as an example check out Sebastian De Deyne’s blog post on using Husky for a PHP project.

Unique features: 

• lint-staged supports partially staged files so it will only look at the changed lines that are staged (not the whole file that’s been staged).
• If the fixer didn’t cause an error, any changes will be auto-added before commit (no need to make `git add` one of the subtasks). It will rollback any changes if it runs into an error.
• By default a backup stash will be created before running the tasks, and all task modifications will be reverted if any one of your pre-commit tasks reports an error. You can use the –no-stash option to disable creating the stash, and instead leave all modifications in the index when it aborts the commit.

Jest is great as a pre-commit hook:

As far as unit tests go, Jest provides a very cool argument –findRelatedTests which informs Jest to run only those test cases which get impacted by the changed files. This can make it significantly faster than other unit testing frameworks like PHPUnit mentioned above, because those ones have to run the whole test suite.

Basic Config Example

Husky setup:

// .husky/pre-commit
 #!/bin/sh
. "$(dirname "$0")/_/husky.sh"
lint-staged

lint-staged setup:

// package.json
{
   "lint-staged": {
     "**/*.js": [
       "eslint --fix",
       “jest --bail --findRelatedTests"
     ]
   }
}

Using Husky for PHP Tasks

As noted earlier, Husky can be used to run php pre-commit tasks too. This is because anything you can run on the command line, husky can run as a pre-commit task. Here’s an example of what a Husky setup might look like for running a bunch of php tasks equivalent to when we setup GrumPHP:

// .husky/pre-commit - Add phpunit
 #!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npm run phpunit
lint-staged

// package.json - Run PHP Lint, PHP CS Fixer, PHPStan, and ESLint
{
  "lint-staged": {
    "*.php": [
      "./vendor/bin/parallel-lint",
      "./vendor/bin/php-cs-fixer fix",
      "./vendor/bin/phpstan analyse"
    ],
    "resources/js/*.{js,jsx,ts,tsx}": "eslint --fix"
  }
}

PHPUnit and Other Long Running Tasks

Notice we’re running phpunit as a separate pre-commit task. This is because lint-staged passes all changed files as params to it’s tasks, this would pass the list of changed files to phpunit (not a list of test files), so we want to run PHPUnit on all tests since we can’t tell which ones have been affected. 

Pre-Push Hooks

If you commit often and squash (I’m looking at you “wip wip squash” devs) you may prefer to move PHPUnit to a pre-push commit hook instead. This is actually handy and not something GrumPHP can do because GrumPHP doesn’t have support for pre-push git hooks. 

PHP_CodeSniffer

PHP_CodeSniffer doesn’t work well with Husky. This is because the code fixer `phpcbf` returns an exit code of 1 after fixing but Husky expects an exit code of 0 for all successful tasks (PHP_CodeSniffer will fix this in v4). In the meantime, php-cs-fixer is a better option, I prefer it over PHP_CodeSniffer as it has more linter rules, although they don’t have PSR12 support yet (PSR2 is fine for now).

Pre-commit.com

If your company has codebases in languages other than Javascript and PHP, Pre-commit.com might be a good alternative to GrumPHP or Husky. Pre-commit.com aims to be a language agnostic solution for pre-commit hooks. I originally disregarded Pre-commit.com as an option because it’s written in Python and I don’t have codebases in Python, but it doesn’t require python (or pip) to install it as it can be easily installed via brew “brew install pre-commit“, and it has git hooks for projects in way more languages than Python (20+ languages actually).

Another neat concept with Pre-commit.com is you install it globally one time on your computer and then any project you git clone which has a .pre-commit-config.yaml in it, it can automatically run pre-commit hooks on if you enable this feature. Click here to see how to automatically enable pre-commit on repositories so that any time you git clone a repo with a .pre-commit-config.yaml file in it, it will automatically install and run those pre-commit hooks on.

Php isn’t listed under the languages supported but there are hooks for php maintained by 3rd party contributors. The main ones all still work, and I haven’t run into an issue with them, but just a heads up they are not maintained and a successor fork hasn’t really taken over in popularity so far.

Here’s an example pre-commit.com hook setup for php and javascript tasks similar to the examples for GrumPHP and Husky above: 

// .pre-commit-config.yaml
minimum_pre_commit_version: 2.18.0
repos:
 - repo: https://github.com/digitalpulp/pre-commit-php
   rev: 1.4.0
   hooks:
     - id: php-lint
     - id: php-cs
     - id: php-unit
     - id: php-stan
 - repo: github.com/pre-commit/mirrors-eslint
   rev: 8.25.0
   hooks:
     - id: eslint

Advanced Example

If you’re a fan of Conventional Commits we can have commit messages linted as well:

// .pre-commit-config.yaml
minimum_pre_commit_version: 2.18.0
default_stages:
 - commit
 - push
default_install_hook_types:
 - pre-commit
 - commit-msg
repos:
 - repo: https://github.com/digitalpulp/pre-commit-php
   rev: 1.4.0
   hooks:
     - id: php-lint
     - id: php-cs
     - id: php-unit
     - id: php-stan
 - repo: github.com/pre-commit/mirrors-eslint
   rev: 8.25.0
   hooks:
     - id: eslint
 - repo: https://github.com/compilerla/conventional-pre-commit
   rev: v1.2.0
   hooks:
     - id: conventional-pre-commit
       stages: [ commit-msg ]

Conclusion

So which one would I use, GrumPHP, Husky or Pre-commit.com? If your project is primarily PHP, use GrumPHP. If your project is primarily javascript, use Husky. If your company has codebases in 3 or more languages (or any of them are python) it might be handy to standardize on pre-commit.com. I do have to say though, as the newer kid in this space, I really love GrumPHP’s implementation. GrumPHP has a ton of common tasks built-in, there’s a good chance if you have a common setup, you don’t have to pass any custom params or manually script up anything. GrumPHP makes the config file very simple and easy to read. Husky leaves it up to the developer to discover or think up pre-commit tasks to use, but that also makes it more versatile, especially if you have unique pre-commit tasks you want to run. Whichever one you choose, just try it out, I’m confident you’ll get hooked.

Following coding standards in PHP is now easier than ever. Let’s go over the benefits of following a coding standard, how to enforce it, and look at how modern tooling and new features in IDE’s like PHPStorm makes it nicer than ever before.

Why Follow a Coding Standard?

1. Stop Wasting Time
   If you’ve ever worked with another developer or worked on a team, no doubt you’ve debated coding styles. Focus on what’s important (getting things done) and stop debating:
   – Tabs vs spaces
   – camelCase vs snake_case
   – Opening brackets {} on new line or same line
   – Control structure format
   – TRUE/FALSE/NULL vs true/false/null
   – Spacing that could go anywhere and everywhere
   – … the list is never ending.
2. More Readable Code
   Easier to read code comes from using a consistent code style. Your brain isn’t distracted by the personal preferences of the previous developer. In Jason McCreary’s book ‏Basecode, he does an excellent job of explaining a concept which Kevlin Henney has coined “visual honesty”. It’s the concept that you should be able to generally tell what’s happening in a function just by the shape of the code blocks. He illustrates this by showing that if all the characters were replaced with X’s, when code is formatted properly, you can still recognize what’s happening. I had noticed the benefits of this before, but had a hard time putting it into words; what an excellent way to demonstrate it!
3. Save Money
   Time is money, whether it’s your time or the company’s. Save time in both new developer on-boarding, as well as on code maintenance. New hire ramp-up time can be reduced if your codebase is in a popular format. It increases the chances the new developer has previous experience developing, reading and writing code in that format. For maintenance, code reviews are simpler, as there are less stylistic changes from developer to developer. As code reviews and new hires are a constant, this savings in developer time translates to real cost savings for the business over time.

EditorConfig

At the very least, a project in any language should add an EditorConfig. EditorConfig is a widely adopted open standard that helps maintain general coding styles. It’s a file which sits in the root of your project that many IDE’s will automatically (or with a plugin) read settings to set tabs vs spaces, tab length to 4 spaces, etc. PHPStorm now has EditorConfig support built-in since PHPStorm 2019.2, VS Code has a plugin, and so does almost all code editors. 

EditorConfig can only specify generic coding style settings, for the rest of the article we’ll look at standards and tools that go a lot further, specific to PHP.

PSR-12

In 2009, all the popular frameworks came together (PHP-FIG) and agreed on common coding standards PSR-1 and PSR-2. Since then, PSR-2 (which builds upon PSR-1) had become the defacto coding standard in PHP, which is nice because you know any framework or 3rd-party php package you come across will follow the same coding style. 

In August 2019, PSR-12 was approved, adding rules for new language features introduced in PHP 7. PSR-12 is now the recommended standard to follow.

But We Can’t Follow PSR-12 Because Of ________

Here’s some of the popular reasons holding team’s back from following PSR-12:

“We have so much code already, it’d be too much work to convert it all.”

“We have certain folders we can’t (or don’t want to) touch.”

“There’s certain rules in PSR-12 that would break our code”

“There’s rules in PSR-12 my team strongly disagrees with.”

Historically, it’s been difficult to perform large stylistic changes on an existing code base. Luckily there are tools which can convert all your files for you! We’ll walk through these tools in “Linters”. 

There might be disagreement around the merit of specific rules within a coding standard. The tooling today easily addresses these concerns. It’s super easy to extend the PSR-12 coding standard and exclude certain folders or rules. We’ll walk through how to do this in Creating a Configuration File.

Linters

PHP_CodeSniffer

PHP_CodeSniffer is a linter command line tool for following PHP coding standards. You can install it globally so that from any project you can run the phpcs command to analyze files and phpcbf to fix them. Starting in version 3.5 has support for PSR-12.

Install PHP_CodeSniffer (Globally)

// Install globally
composer global require "squizlabs/php_codesniffer=*"

// Set the coding standard
phpcs --standard=PSR12

// Scan a specific file
phpcs app/Controllers/HomeController.php 

// Scan all files
phpcs .

// Fix a specific file
phpbf app/Controllers/HomeController.php 

// Fix all files
phpcbf .

Install PHP_CodeSniffer (Project Dependency)

Having it installed globally is handy, the command is short so no matter what project you jump into it’s easy to remember. But I recommend also installing it as a composer dev dependency in your project. This way, no matter what, it’s installed for all your teammates and you all have the same version.

// Install locally
composer require --dev "squizlabs/php_codesniffer=*"

Then you can run it the same way as demonstrated globally above, you just need to specify the vendor bin path where composer installs it to.

// Scan
vendor/bin/phpcs --standard=PSR12 app/Controllers/HomeController.php

// Fix
vendor/bin/phpcbf --standard=PSR12 app/Controllers/HomeController.php

We can avoid potentially forgetting to pass --standard=PSR12 by creating a phpcs.xml configuration file like we’ll demonstrate below.

If you find it annoying to type out the entire vendor path or have a hard time remembering the vendor path, maybe create a composer run-script which we’ll also go over below.

Even so, I’ll be honest, I usually just use the globally installed version; it’s easier to just type phpcs, and PHP_CodeSniffer doesn’t change too much from version to version. But I install it as a dev dependency anyway so that it’s there if I need it to run it on a server or another system. Plus there’s an added benefit that by setting it as a dev dependency and creating the composer run-script, our teammates IDE’s can set the coding standard automatically for them.

Create a phpcs.xml Configuration File

Like I said above, you may Extend PSR-12 if you want to exclude files or folders, or exclude certain rules. By placing a phpcs.xml file at the root of your project, anyone who runs phpcs doesn’t have to worry about passing any arguments to set the coding standard to PSR-12 or any custom settings for your project. PHP_CodeSniffer will automatically read them from this config file instead.

As a simple example, here’s how you create a custom standard that extends PSR-12 but excludes the 120 character line length limit, adds a rule to disallow long array syntax, and ignores a /views/ folder.

phpcs.xml

<?xml version="1.0"?>
<ruleset name="My Company Coding Standard">
   <description>PSR12 with tweaks.</description>
   <rule ref="PSR12">
       <exclude name="Generic.Files.LineLength.TooLong"/>
   </rule>
   <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
   <exclude-pattern>*/views/*</exclude-pattern>
</ruleset>

Here’s a more complex example: https://github.com/squizlabs/PHP_CodeSniffer/blob/master/phpcs.xml.dist

And full documentation can be found here: https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset

Create a Composer Script

Remembering the path to the local installation of phpcs and typing it out every time can get tedious, not to mention remembering to pass the flag for what standard to use if you don’t need a phpcs.xml, so you can create a composer script to make it easier:

"scripts": {
   "phpcs": "vendor/bin/phpcs --standard=PSR12 app"
}

Then you only have to run:

composer phpcs

This has 2 additional benefits:

1. PHPStorm 2020.1 will provide play buttons to run composer run-scripts with just one click.
2. PHPStorm can automagically set your standard in PHPStorm.

PHP CS Fixer

PHP CS Fixer is an alternative linter to PHP_CodeSniffer. It doesn’t have PSR-12 yet, but they are working to add PSR-12 support. It does, however, include all the other same popular standards that PHP_CodeSniffer supports, like PSR-12’s predecessor PSR-2 and others. 

As well, PHP CS Fixer also includes support for the Symfony coding standard. It takes the PSR-2 coding standard (PSR-12 soon) and builds upon it with coding opinions common in their framework’s community. I personally really like it, except I do tweak a couple settings. I like to turn off yoda_style, and turn on a couple handy fixers that PHP_CodeSniffer doesn’t have, like sorting import statements alphabetically, and removing unnecessary fully qualified class names. 

Unlike PHP_CodeSniffer where you set the standard/rules in an xml file, for PHP CS Fixer you set them in a PHP file (either .php_cs or .php_cs.dist). Here’s an example for PHP CS Fixer on how to set the standard as the Symfony coding standard and make the other tweaks I just mentioned:

.php_cs.dist

<?php
$finder = PhpCsFixer\Finder::create()
   ->exclude([
       'views',
   ])
   ->in(__DIR__);
return PhpCsFixer\Config::create()
   ->setRules([
       '@Symfony' => true,
       'array_syntax' => ['syntax' => 'short'],
       'concat_space' => ['spacing' => 'one'],
       'yoda_style' => false,
       'fully_qualified_strict_types' => true,
       'ordered_imports' => true,
       'phpdoc_align' => false,
       'phpdoc_separation' => false,
   ])
   ->setFinder($finder);

Documentation for these and other settings can be here: https://github.com/FriendsOfPHP/PHP-CS-Fixer#config-file

IDE Support

PHPStorm

PHPStorm + PHP Linters = . IntelliJ has made linters a first class citizen in their PHPStorm IDE. There’s no plugin needed. You can utilize PHP_CodeSniffer or PHP CS Fixer right inside the IDE so you don’t have to run commands on the command line. What’s nice about this integration is that it will help you follow the PSR-12 coding standard in real-time as you write code.

Here’s the 3 steps you’ll need to do in order to get PHPStorm setup with either PHP_CodeSniffer or PHP CS Fixer:

1. Set the “Code Style”

By setting the code style we make sure that when you reformat entire classes, generate code, or refactor code, PHPStorm will follow PSR-12 when it rewrites your code for you. Starting in PHPStorm 2019.3, PSR-12 is available as one of the built-in code styles to pick from.

Preferences > Editor > Code Style > PHP > “Set from…” > Predefined Style > PSR12

2. Turn on “Code Quality Tools”

We need to validate that PHPStorm knows where the linter is installed for when it needs to use it to lint your code.

Preferences > Languages & Frameworks > PHP > Quality Tools > Code Sniffer

Click the ellipsis (…) and use the validate button to make sure it can detect where PHP_CodeSniffer is installed.

3. Turn on “Inspections”

By turning on Inspections for the linter, PHPStorm will put a squiggly line below any code for any issues the linter detects. Opening the intention actions menu on an inspection will even provide an action to fix the issue for you starting in PHPStorm 2019.1 for PHP_CodeSniffer (and PHPStorm 2018.3 for PHP-CS-Fixer). You can see this in action in the gif at the top of this article!

Preferences > Editor > Inspections > PHP > Quality Tools > PHP_CodeSniffer Validation

Set the Coding Standard Automatically for Teammates

PHPStorm recently made it super easy to have the coding standard set automatically for all your team members by simply adding a line to your composer.json:

https://www.jetbrains.com/help/phpstorm/using-php-code-sniffer.html#configure-tool-inspection-composer

Note: You’re teammates must use Composer through PHPStorm (eg. Tools > Composer > Install/Update) for it to automatically set the path and turn on the inspections for them.

Visual Studio Code

PHPStorm is probably the most popular IDE for PHP, but Visual Studio Code (VS Code) is becoming a very popular (and free) IDE for PHP developers. You can install the phpcs plugin for PHP_CodeSniffer integration or the php cs fixer plugin for PHP CS Fixer integration.

Sublime Text, Vim, Atom & Others

Sublime Text has sublime-phpcs. Vim has Syntastic or Ale. Atom has a linter-phpcs package. As for PHP CS Fixer, they have a list of plugins for various editors right on their Github readme. 

Taking It a Step Further

So now you’ve got linting working on the command-line, you’ve reformatted your codebase to PSR-12, and your IDE of choice is setup to lint in real-time! Now how do you keep your codebase PSR-12 compliant? Ever opened up a class to find others had committed a bunch of code that doesn’t follow PSR-12? Do you find yourself having to run phpcs across the whole codebase every couple months?

In my next blog post we’ll go over how to make sure PSR-12 errors never makes it into master again. I’ll go a step further and show how you can catch PSR-12 violations before they even make it into a commit! Subscribe via RSS, or follow me on twitter to find out about the next blog post comes out!

Laravel 5.5 launched with API Resources, a new feature for building APIs. API Resources serve as a way to transform models and collections to JSON formatted API responses. It standardizes how to define the output format of models and includes helper methods for common tasks like customizing metadata, headers and pagination. You can read how to write API Resources in the Laravel docs.

JSON API is a spec created from common conventions for building JSON powered APIs. The goal of JSON API spec is to help teams avoid wasting time debating API structure and features. JSON API encourages RESTful design, readability/discoverability, and object relationships through a flat document structure. There’s examples for almost every feature on the Specification page, and you can learn a lot about why JSON API is designed the way that it is by reading through the FAQ page.

JSON API was considered for the default format of API Resources, however in the end it was decided to be too much work for the average use-case of a Laravel-powered API. For this reason, API Resources don’t automatically output to JSON API format – but it is very similar, even including the same root offsets. In this article we’ll take a look at what it takes to make API Resources fully JSON API compliant.

Making API Resources JSON API Compliant

API Resources use the following same root offsets as JSON API: data, meta and links.

• data – the primary resource (or collection of resources)
• meta – additional information about a resource that is not an attribute or relationship
• links linkage eg. “self” link or pagination urls

With Laravel’s API Resources, you can generate two types of classes: resources and resource collections. A resource class is for outputting a single model you pass to it, and a resource collection is for multiple models (eg. a paginated list of items). A resource, without customizing it, will just call toArray() on the model and place the result under the data offset. A resource collection will do the same for each model, and add them as an array to the data offset. A resource collection will also automagically add pagination information to the meta and links offsets.

API Resources don’t however include automation for JSON API’s compound documents and their relationships / included offsets; a requirement in JSON API. Let’s take a look at at how we can write a resource and a resource collection to comply with the JSON API spec. We’ll use a sales platform concept for examples where we have orders of products, and for simplicity we’ll say an order can only be for one or more of a single product.

Resources

First let’s take a look at an endpoint which returns a single resource (eg. /orders/1). In this example we have an Order model, and each Order has a one-to-one relationship with a Product. By default when a model is passed to a resource class like OrderResource, it outputs a response in the structure of the one on the left in the table below. Compare this to the equivalent response in JSON API format on the right:

{
  "data": {
    "id": 1,
    "order_id": 246752514,
    "product_id": 2,
    "quantity": 9,
    "created_at": "2009-12-22 21:40:02",
    "updated_at": "2017-08-18 22:07:53",
    "product": {
      "id": 2,
      "name": "Nike Shoes",
      "created_at": "2017-08-17 19:49:32",
      "updated_at": "2017-08-17 19:49:32"
    }
  }
}

{
  "data": {
    "type": "order",
    "id": "1",
    "attributes": {
      "order_id": 246752514,
      "quantity": 9,
      "created_at": 1261518002,
      "updated_at": 1503094073
    },
    "relationships": {
      "product": {
        "data": {
          "type": "product",
          "id": "2"
        }
      }
    }
  },
  "included": [
    {
      "type": "product",
      "id": "2",
      "attributes": {
        "name": "Nike Shoes",
        "created_at": 1502999372,
        "updated_at": 1502999372
      }
    }
  ]
}

Note: If you are new to JSON API, it may appear that JSON API’s version of the output is at a disadvantage in response size, but keep in mind the product may not be included by default. In addition, JSON API is providing added clarity that the related product’s data will not be able to be PATCH’ed on this endpoint; it should instead be updated via it’s own resource’s endpoint (eg. PATCH /products/6). You could add a links offset to the product object with a self url to further encourage discoverability.

How to write Resource classes to output to JSON API format

After creating the resource class, update the toArray() function to serialize the model in the correct format. This includes setting the type and id fields required by JSON API, and putting the rest of the resource’s data under attributes.  You can also add a with()function to include any additional root offsets. We’ll use with() to add the related Product resource in the included offset. Here’s an example of what the OrderResource class would look like:

class OrderResource extends Resource
{
   public function toArray($request)
   {
       return [
           'type' => 'order',
           'id' => (string) $this->id,
            'attributes' => [
                'name' => $this->name,
                'created_at' => $this->created_at,
                'updated_at' => $this->updated_at,
           ],
           'relationships' => [
              'product' => [
                  'data' => [
                      'type' => 'product',
                      'id' => (string) $this->product_id
                   ]
              ]
           ]
        ];
    }

    public function with($request)
    {
        return ['included' => [new ProductResource($this->product)]];
    }
}

Now when you use the OrderResource you’ll automatically get JSON API compliant output.

Resource Collections

Now let’s take a look at endpoints that return a collection of resources (eg. /orders?page=2). On the left we have the the default output from a ResourceCollection class OrderCollection, and on the right what the equivalent would look like following JSON API format:

{
  "data": [
    {
      "id": 18,
      "order_id": 344501705,
      "product_id": 6,
      "quantity": 2,
      "created_at": "2010-01-22 03:36:03",
      "updated_at": "2015-07-23 12:19:02",
      "product": {
        "id": 6,
        "name": "Tommy Jersey",
        "created_at": "2017-08-17 19:49:32",
        "updated_at": "2017-08-17 19:49:32"
      }
    },
    {
      "id": 19,
      "order_id": 446228260,
      "product_id": 6,
      "quantity": 2,
      "created_at": "2010-01-22 07:23:13",
      "updated_at": "2010-01-22 07:25:52",
      "product": {
        "id": 6,
        "name": "Tommy Jersey",
        "created_at": "2017-08-17 19:49:32",
        "updated_at": "2017-08-17 19:49:32"
      }
    }
  ],
  "links": {
    "first": "http://api.dev/orders?page=1",
    "last": "http://api.dev/orders?page=330",
    "prev": "http://api.dev/orders?page=6",
    "next": "http://api.dev/orders?page=8"
  },
  "meta": {
    "current_page": 7,
    "from": 13,
    "last_page": 330,
    "path": "http://api.dev/orders",
    "per_page": "2",
    "to": 14,
    "total": 659
  }
}

{
  "data": [
    {
      "type": "order",
      "id": "18",
      "attributes": {
        "order_id": 344501705,
        "quantity": 2,
        "created_at": 1264131363,
        "updated_at": 1437653942
      },
      "relationships": {
        "product": {
          "data": {
            "type": "product",
            "id": "6"
          }
        }
      }
    },
    {
      "type": "order",
      "id": "19",
      "attributes": {
        "order_id": 446228260,
        "quantity": 2,
        "created_at": 1264144993,
        "updated_at": 1264145152
      },
      "relationships": {
        "product": {
          "data": {
            "type": "product",
            "id": "6"
          }
        }
      }
    }
  ],
  "links": {
    "first": "http://api.dev/orders?page=1",
    "last": "http://api.dev/orders?page=330",
    "prev": "http://api.dev/orders?page=6",
    "next": "http://api.dev/orders?page=8"
  },
  "meta": {
    "current_page": 7,
    "from": 13,
    "last_page": 330,
    "path": "http://api.dev/orders",
    "per_page": "2",
    "to": 14,
    "total": 659
  },
  "included": [
    {
      "type": "product",
      "id": "6",
      "attributes": {
        "name": "Tommy Jersey",
        "created_at": 1502999372,
        "updated_at": 1502999372
      }
    }
  ]
}

How to write ResourceCollection classes in JSON API format

For endpoints that return a collection of resources, we can reuse the individual Resource classes like the one we wrote in the previous section and map each model to it. For including related resources, keep in mind the benefit of having them under the included offset instead of embedding them recursively is so the data isn’t duplicated over and over. For example, in the output above the product “Tommy Jersey” is duplicated in each order. To make sure you don’t have duplicates in the included offset, you can use the unique() method on collections. Here’s an example of what the OrderCollection class would look like:

class OrderCollection
{
   public function toArray($request)
   {
       return [
           'data' => $this->collection->map(function ($order) use ($request) {
               return (new OrderResource($order))->toArray($request);
           })
       ];
   }


   public function with($request)
   {
       return [
           'included' => $this->collection->pluck('product')->unique()->values()->map(function ($product) {
               return new ProductResource($product);
           })
       ];
   }
}

At this point we have responses for both individual resources and their collections which comply with the JSON API spec! You can find a fully working version of the code above in the feature/api-resources branch of an example API codebase here.

What JSON API Features Are Missing?

With these changes, you now have an API that outputs in valid JSON API format, but API Resources don’t automatically support some of the more advanced (optional) features such as giving clients control over inclusion of related resources using the “include” query param, or the ability for clients to reduce payload size by specifying to return only the fields they need using sparse fieldsets.

Prior to the release of API Resources in Laravel 5.5, Fractal was a popular PHP package which offered an alternative implementation of a transformation layer in APIs. It has support for outputting to JSON API format built-in by default. As well, Fractal includes the more advanced features we mentioned above like the “include” query param, and sparse fieldsets. In my next blog post I’ll explore if you can swap out Fractal for native Laravel API Resources, AND if you should.

Subscribe or follow me on twitter so you don’t miss the next one!

This allows you to go from this:

$this->validate($request, [
    'title' => 'required|unique:posts|max:255',
    'excerpt' => 'max:255',
    'body' => 'required',
    'category' => 'required',
    'tags' => 'array',
    'status' => 'required|in:draft,scheduled,published',
    'publish_at' => 'nullable|date',
]);

To just one line of code like this:

$this->validate($request, config('validation.post.create'));

How To Pull Validation From A Config File

Create /config/validation.php and add your rules:

<?php
return [ 
    'post' => [
        'create' => [
            'title' => 'required|unique:posts|max:255',
            'excerpt' => 'max:255',
            'body' => 'required',
            'category' => 'required',
            'tags' => 'array',
            'status' => 'required|in:draft,scheduled,published',
            'publish_at' => 'nullable|date',
        ]
    ]
];

Lumen: You’ll need to load the config file manually. Open /bootstrap/app.php and after the line $app->withEloquent(); add this: $app->configure('validation');.

Enjoy.

…

Wait, What about form request objects? They can be used to move validation bloat out of controllers too!

True, I’m a big fan of how form requests move validation and data transformation to a separate step before controller execution. However, I think you’ll find having all these different request objects (often just for the purpose of returning validation rules), can be overkill when you could just pull it from a config file. Not to mention, Lumen doesn’t support form requests, so this is a great alternative if you’re using Lumen.

Follow me on Twitter, or subscribe to Laravel/Programming for future posts.