DEV Community: Matt Moore

Abstracting Laravel Dependencies

Matt Moore — Mon, 16 Dec 2019 15:56:45 +0000

Over the course of building a Laravel application, most developers utilize numerous composer packages to implement common functionality. It's important to think about future-proofing these 3rd-party dependencies or you may find yourself battling considerable technical debt in the future.
One way to do this is to apply the DRY principle to your dependencies. Keep them in one place, so that if you ever need to change, upgrade, or replace a 3rd-party package, you can do it with minimal headache. I'll explore a couple strategies for doing this in the rest of the article.

Note: This is by no means exclusively applicable to Laravel or even PHP, but I'll be focusing on Laravel for examples and specific scenarios for this article.

#1: Create an Interface and a Wrapper Implementation

I was once working on a codebase that used Guzzle in several places in the application. When Guzzle released a breaking upgrade, it was a lot of extra work hunting down all the places it was called to make the upgrade.

To prevent us from having to spend the same amount of time if the scenario came up again (it did, and always will), I first created a HttpClient interface that described all the functionality we wanted to use from the new version of Guzzle. Then, I created a GuzzleWrapper class that wraps Guzzle's Client class and adheres to the interface.

Once I added a binding in Laravel's IoC container, I replaced every place that Guzzle was called with the new Interface instead. This ensures that the next time I had to do an upgrade, I only had to do it in that one class.

One day, a new Http package might come out that performs better, or has better security, or shiny new features. All I would have to do is create a new implementation using that new package, swap out the binding, and it is good to go.

Example: Guzzle

Here is a real-world example of how you could create a wrapper for the popular Http package Guzzle. Since Guzzle uses PSR-7, we can use the ResponseInterface included in the psr/http-message package. The wrapper implementation is incomplete, but demonstrates the concepts that can be used to create a wrapper for a 3rd-party package.

Note: Examples are written with features that are new in PHP 7.4 such as class property type declarations.

<?php 

namespace Acme\Core\Http;

use Psr\Http\Message\ResponseInterface;

interface HttpClient
{
    public function get(string $uri, array $options = []): ResponseInterface;
    public function post(string $uri, array $options = []): ResponseInterface;
}

<?php 

namespace Acme\Core\Http;

use GuzzleHttp\Client;
use Psr\Http\Message\ResponseInterface;

class GuzzleWrapper implements HttpClient
{
    private Client $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public function get(string $uri, array $options = []): ResponseInterface
    {
        return $this->client->get($uri, $options);
    }

    public function post(string $uri, array $options = []): ResponseInterface
    {
        return $this->client->post($uri, $options);
    }
}

You can add the interface and concrete implementation to a $bindings property in one of your app's service providers.

<?php 

namespace Acme\Core\Providers;

use Acme\Core\Http\GuzzleWrapper;
use Acme\Core\Http\HttpClient;
use Illuminate\Support\ServiceProvider;

class CoreServiceProvider extends ServiceProvider
{
    public array $bindings = [
        HttpClient::class => GuzzleWrapper::class
    ];
}

?>

Now you can resolve the class out of the service container anywhere you need it! Just make sure to inject the HttpClient interface, and not the GuzzleWrapper class directly.

<?php 

namespace Acme\Feature;

use Acme\Core\Http\HttpClient;

class ApiIntegration
{
    private HttpClient $httpClient;

    public function __construct(HttpClient $httpClient)
    {
        $this->httpClient = $httpClient;
    }
}

?>

You should avoice creating Leaky Abstractions to the best of your ability. In our example, we are returning a typehint of a PSR-7 compliant ResponseInterface rather than the Guzzle Response implementation that actually gets in the hands of the caller. That way, if you change the wrapped class, as long as they are PSR-7 compliant, nothing will break. If it's not PSR-7 complaint, you can simply write a PSR-7 compliant adapter of whatever it does return.

If whatever class you are wrapping does not have a PSR standard, you can create your own wrapper class based on current behavior for its return or input classes to prevent your abstractions from leaking. The end-goal is to make sure whatever classes call your wrapper don't know the details of the 3rd-party implementation.

#2: Create a standalone wrapper class

A quicker and dirtier method would be to create a wrapper class without an interface. Almost identical to the first method, but you instead call your wrapper class as a dependency directly. This makes it harder to test, harder to change, and makes it impossible to run multiple implementations simultaneously, so I would recommend avoiding this method.

#3: Confine dependency to one class.

If your application only uses a package in one place, and will for the foreseeable future, you may not need to abstract it. The whole point is easing upgrades or changes, so if it truly will only ever live in one place like a service or job class then you gain little benefit from abstraction. Doing this can definitely be a slippery slope, as you may think it only needs to be in one place, to find that it was needed elsewhere, and you or somewhere else simply injected the 3rd-party class directly elsewhere. To be safe, I would avoid this method as well.

Considerations

Write Everything Twice

It's important to protected against premature optimizations. This article shares some good ideas regarding when exactly is a good time to abstract something and apply the DRY principle.

https://dev.to/wuz/stop-trying-to-be-so-dry-instead-write-everything-twice-wet-5g33

Avoid Laravel Facades

While Facades are technically okay since they resolve out of the IoC container, I still prefer to inject the dependencies into the constructor. It makes it a bit easier to tell exactly what dependencies a class has, and helps improve testability in certain scenarios.

Wrap Laravel Helper Methods

While I don't think it's beneficial to wrap all the Laravel dependencies you use unless you suspect you'll one day migrate out of Laravel, which in some cases might be something worth considering, I would consider wrapping Laravel's helper methods if you plan to use them. When the str*() methods got deprecated in favor of Str::*(), I had to spend an hour or two between all my codebases making sure that I swapped all of them out.

I should have created a wrapper class for them so that I can always rely on only changing them in one place should they ever change again.

Conclusion

Creating abstractions for 3rd-party dependencies is a bit of a time investment to get setup, but it provides a lot of benefits and saves time and headache in the future. As always, thanks for reading, and leave your comments and questions in the section below.

The post Abstracting Laravel Dependencies appeared first on Matt Does Code.

6 Laravel Tips

Matt Moore — Sun, 20 Oct 2019 21:55:03 +0000

I've put together a small list of tips that I've found useful while working with Laravel.

1. onDelete('set null')

You probably know about, and have used onDelete('cascade'); on foreign keys in Laravel migrations, but did you know about 'set null'? This allows you to preserve models when their related model is deleted. An example of this would be if you have comments that have a user, if the user gets deleted, and you want to preserve their comments, you can use onDelete('set null'). This will set your user_id column to null automatically if the user gets deleted, and you can handle this in your data presentation layer to show ‘User Deleted’ as the author, or something similar.

$table->foreign('user_id')
          ->references('id')->on('users')
          ->onDelete('set null');

2. dropForeign([]);

For the longest time, I thought you had to use the full key name when rolling back a foreign key constraint in a migration. I was also confused when rolling back multiple foreign keys using array syntax didn't work.

// doesn't work
$table->dropForeign('user_id');

// works
$table->dropForeign('posts_user_id_foreign');

// doesn't work
$table->dropForeign([
    'posts_user_id_foreign',
    'posts_type_id_foreign'
]);

When I read the documentation to figure out what was going on, I realized that the array syntax on dropForeign is for dropping a foreign key using a shorthand column name.

$table->dropForeign(['user_id'])

Super handy! But why array syntax? What happens if you put multiple strings in there? I looked at the source code to find out since it wasn't obvious to me from the documentation.

Here is drop foreign:

/**
* Indicate that the given foreign key should be dropped.
*
* @param  string|array  $index
* @return \Illuminate\Support\Fluent
*/
public function dropForeign($index)
{
    return $this->dropIndexCommand('dropForeign', 'foreign', $index);
}

Simply an abstracted call to dropIndexCommand which looks like this:

/**
* Create a new drop index command on the blueprint.
*
* @param  string  $command
* @param  string  $type
* @param  string|array  $index
* @return \Illuminate\Support\Fluent
*/
protected function dropIndexCommand($command, $type, $index)
{
    $columns = [];

    // If the given "index" is actually an array of columns, the developer means
    // to drop an index merely by specifying the columns involved without the
    // conventional name, so we will build the index name from the columns.
    if (is_array($index)) {
        $index = $this->createIndexName($type, $columns = $index);
    }

    return $this->indexCommand($command, $columns, $index);
}

So, when we call dropForeign with an array, it builds an index name using the involved columns. So if we had a composite key index, we could drop it using the array syntax and simply pass in the column names, rather than passing in the entire index name just like we do with the foreign key constraint.

3. Model Validation

There are lots of different ways to perform user input validation in Laravel. You can use Request objects, middleware, or even validate right in your controllers. Recently, I've been defining validation rules in Eloquent Models. You can then hook into those rules wherever you need to, like in a Request object. This approach was inspried by the Elixir framework, Phoenix.

<?php

namespace Acme;

use Illuminate\Database\Eloquent\Model;

class Contact extends Model
{
    /**
     * Fillable attributes.
     *
     * @var array
     */
    protected $fillable = [
        'name',
        'phone_number',
        'user_id'
    ];

    /**
     * Validation rules for creation
     *
     * @var array
     */
    public static $createRules = [
        'name' => 'required|string',
        'phone_number' => 'string',
        'user_id' => 'integer'
    ];
}

<?php

namespace Acme\Http\Requests;

use Acme\Contact;
use Illuminate\Foundation\Http\FormRequest;

class CreateContact extends FormRequest
{
    public function rules(): array
    {
        return Contact::$createRules;
    }
}

You can use multiple rulesets if create and update validation differs. For instance, if your front-end only sends values that have changes for updating, you don't want all fields marked as required.

<?php

namespace Acme;

use Illuminate\Database\Eloquent\Model;

class Contact extends Model
{
    /**
     * Fillable attributes.
     *
     * @var array
     */
    protected $fillable = [
        'name',
        'phone_number',
        'user_id'
    ];

    /**
     * Validation rules for creation
     *
     * @var array
     */
    public static $createRules = [
        'name' => 'required|string',
        'phone_number' => 'string',
        'user_id' => 'integer'
    ];

    /**
     * Validation rules for update
     *
     * @var array
     */
    public static $updateRules = [
        'name' => 'string',
        'phone_number' => 'string',
        'user_id' => 'integer'
    ];
}

4. Data Migrations

Sometimes you want to put static information in the database for reference throughout your application. Permissions, country or state names, default settings, the list goes on an on. If the data needs to be able to change or needs to be versioned, you can use migrations instead of seeders. I've tried two approaches and they both work well.

Approach #1 is to simply run queries inserting, updating, or deleting data in a migration. In this scenario I'm backfilling a new setting with a default value.

<?php

use Acme\Reports\Utilities\ReportEmailDefaults;
use Acme\Team\Team;
use Acme\Settings\Setting;
use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class FillEmailsSetting extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        // get all teams
        $teams = Team::all();

        foreach($teams as $team) {
            // add new default emails setting for each team
            $setting = new Setting();
            $setting->key = 'emails';

            // get values from constants to avoid magic strings
            $values = [
                'report_subject' => ReportEmailDefaults::SUBJECT,
                'report_body' => ReportEmailDefaults::BODY
            ];

            $setting->value = json_encode($values);

            $team->settings()->save($setting);
        }
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Setting::where('key', 'emails')
            ->where('settingable_type', 'team')
            ->delete();
    }
}

Approach #2 is to extend the migration class to make it easier to add/remove data. I have used this approach when managing permissions using migrations. That might look something like this.

<?php
namespace Acme\Core\Application;

use Acme\Authentication\Permissions\Permission;
use \Illuminate\Database\Migrations\Migration;

abstract class PermissionMigration extends Migration {

    protected $permissions;

    public function getPermissions(): array
    {
        return $this->permissions;
    }

    final public function up(): void
    {
        $permissions = $this->getPermissions();

        foreach($permissions as $permission)
        {
            Permission::create($permission);
        }

    }

    final public function down(): void
    {
        Permission::whereIn('key', $this->getPermissions())->delete();
    }
}

Whenever you want to add permissions you just need to create a new migration that extends the permission migration and define an array of permission keys to be added.

<?php

use Acme\Authentication\Permissions\CreatePost;
use Acme\Core\Application\PermissionMigration;

class AddCreatePostPermission extends PermissionMigration
{
    protected $permissions = [
        CreatePost::$key
    ];
}

This is an incomplete example, you'd want to build ways to update and remove permissions, but I hope you get the idea.

5. Adding attributes to the request

You can add attributes to Laravel's request object using middleware. One scenario in which this is handy, is in mulit-tenant applications where you want to fetch a given team or organization and make sure the requesting user has access to it, as well as passing along the entity so you don't have to look it up multiple times.

Here is what the middleware might look like. If you are copying this at home, be aware that the $user->cannot() method is a custom helper method
I usually add to my User model. I also use a role-based permission system, but you can use Laravel Gate's and other built-in authorization
methods.

<?php

namespace Acme\Core\Http\Middleware;

use Closure;
use Acme\Authentication\Permissions\Team\ViewTeam;
use Acme\Team\Repositories\TeamRepository;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Cache;

class LookupTeam
{
    private $teamRepository;

    public function __construct(TeamRepository $teamRepository)
    {
        $this->teamRepository = $teamRepository;
    }

    public function handle($request, Closure $next, ?string $guard = null): Closure
    {
        // Fetch the requesting user
        /* @var $user \Acme\Authentication\User */
        $user = Auth::guard('api')->user();

        $slug = $request->teamSlug;

        // Fetch the requested team
        $team = $this->teamRepository->find($slug, 'slug');

        // If no team is found, return a 404
        if ( ! $team) {
            abort(404);
        }

        // Make sure user has access
        if($user->cannot(ViewTeam::key(), $team)) {
            return response('Unauthorized', 401);
        }

        // Finally, add the team to the request
        $request->attributes->add(['team' => $team]);

        return $next($request);
    }
}

Make sure to add the middleware to the route middleware group in your Kernel.php file, then you can attach the middleware to your route groups

Route::prefix('/team/{teamSlug}')->middleware('team-lookup')->group(function () {
    Route::get('/tasks', [TaskController:class, 'get']);
});

And in the controller method, you can retrieve the Team from the request object.


public function get(Request $request): TaskResource
{
    $team = $request->attributes->get('team');

    $tasks = dispatch_now(new GetTeamTasks($team));

    return TaskResource::collection($tasks);
}

6. Ordering models by distant many-to-many related items

Let's say you're building a system that tracks and manages production chains. When assigning products to machines, you want
to get a list of available machines ordered by what products they support, with the most compatible at the top of the list.

You might have a Machine entity that belongs to a Machine Type. The Machine Type entity has a Many-to-Many relationship with
Products.

So you need to do a count and order based on a many-to-many relationship with the assigned Machine Type. You can use withCount with constraints
to order the machine results based on whether or not the machine's type relationship has the assigned products you're looking for.

$machines = $machines->withCount(['type' => function($query) use($product) {
    $query->whereHas('products', function($query) use($product) {
        $query->where('products.id', $product->id);
    });
}])->orderBy('type_count', 'desc');

Whether or not the assigned type has the assigned products will set the type_count to a 0 or a 1, which you can then order the results by.

Summary

I hope you found some of these tips useful. Feel free to add your thoughts, comments, criticisms, or ideas below!

The post 6 Laravel Tips appeared first on Matt Does Code.

API Specifications and Laravel

Matt Moore — Wed, 14 Nov 2018 16:09:35 +0000

One of the most important parts of building an API, or any codebase for that matter, is making sure it is well-documented. How can users know how to use your API, or what it even does if there’s no documentation? How can your team members (or yourself 6 months from now) know how to extend and test your endpoints if there’s nothing describing how they’re supposed to behave?

The biggest hurdle with documentation in my experience is maintaining them. What happens when someone is in a rush to build a feature and they forget to add it to the docs? Or when business rules change and certain inputs and outputs change? Poorly maintained documentation quickly becomes useless as users and developers no longer trust them, and suddenly it’s as if there are no docs at all, leaving them to guess at contracts. See: The Broken Window Theory for why this happens.

This is where specifications come in.

API Specification vs API Documentation

What is an API Specification and how does it differ from documentation? Nordic APIs has a great article that goes into the differences in detail

Simply put, documentation explains how to use the API, while a specification describes how the API behaves. I’ve seen specifications described as blueprints for your API and I think that analogy is accurate. Indeed you can derive many things from a well-built specification including documentation, validation rules, front-end API clients, contract tests, and more.

There are a whole host of specs to choose from, but I’m focusing on OpenAPI Version 2 (I will explain why later) and JSON Schema.

OpenAPI

Remember that we will be using Open API Version 2 for the remainder of this article.

Generating the specification

Open API is an API specification developed by SmartBear and can be written (or generated) as YAML or JSON files. You may also notice that when using Laravel or PHP, you can use libraries such as L5-Swagger to use annotations for generating your spec. Despite my instincts telling me this is a horrible idea I decided to give it a try. My instincts were right, it’s a horrible idea, for a number of reasons.

The most readily apparent reason, though superficial, is that writing and maintaining these annotations is a chore. There’s no IDE plugins to help with formatting so you end up fiddling with asterisks, white spaces, and curly brace and comma alignment for far too long just to keep them looking nice.

Aside from that, once you’re done writing the annotations, you’ll notice that they now take up the majority of your source files,add unnecessary cognitive overhead, and can become difficult to find when needed.

What would be a better approach to this madness? We still need our spec to be scalable, so it can’t exist as one file. We want it to be easily navigable and editable, and we want generation of docs, tests, etc, to be straightforward.

I chose to maintain my spec separately from my code in a folder labeled spec in the root of my Laravel app using YAML files. Though I’m by no means a fan of YAML, I prefer writing it by hand over JSON.

Example

Let’s pretend we are building a simple REST API for a blog with a few endpoints for managing articles. The endpoints might look something like this:

GET /
GET /articles
POST /articles
GET /articles/{slug}
PUT /articles/{slug}
DELETE /articles/{slug}

Setting up the Application

If you want to follow along, create a dev environment however you’d like to (straight on your dev machine, or using a tool like Vagrant or Docker), and install a fresh copy of Laravel.

Setting up the build tools

We want to first setup all the tools and scripts necessary for building our spec. The tools I’m using are: json-refs, path-loader, js-yaml, and swagger-cli. Make sure NPM is installed and grab these packages with

npm install --save-dev json-refs path-loader js-yaml swagger-cli

Create a scripts directory in your application root and place the following script in a file called build-spec.js

var JsonRefs = require('json-refs');
var PathLoader = require('path-loader');
var YAML = require('js-yaml');
var fs = require('fs');

var root = YAML.load(fs.readFileSync('../spec/api.yaml').toString());

var options = {
 loaderOptions: {
     processContent: function (res, callback) {
         callback(YAML.safeLoad(res.text));
     }
 },
 location: '../spec/api.yaml'
};

JsonRefs.resolveRefs(root, options).then(function (results) {
   var dir = '../spec/dist';
   if (!fs.existsSync(dir)){
       fs.mkdirSync(dir);
   }

   fs.writeFileSync('../spec/dist/api.yaml', YAML.dump(results.resolved), function(err) {
       if(err) {
           return console.log(err);
       }

       console.log('Specification compiled successfully.');
   });
}, function(err) {
 console.log(err);
});

This script converts the YAML files to JSON and resolves all of our external references.

Finally, add the following line to the scripts section of the package.json file.

"build-spec": "cd scripts && node build-spec.js && swagger-cli validate ../spec/dist/api.yaml"

Creating the spec object

Now that we have our build tools setup, create the spec folder in the root of the application with a file called api.yaml. According to the spec, there are three required fields. The swagger field, which specifies the version of Open API that we are using (it’s called openapi in version 3), the info field, which contains basic information about our API like it’s name and version, and the paths field, which contains our endpoint definitions. Put together, a basic spec might look something like this:

swagger: '2.0'
info:
 version: '1.0'
 title: Blog API

host: 'api.blog.test'
schemes: [http]
consumes: [application/json]
produces: [application/json]

paths:
 $ref: ./paths.yaml

And in paths.yaml, let’s create a simple endpoint to display our API version

/:
 get:
   summary: 'Return the API's version'
   responses:
     200:
       description: 'API version successfully returned.'

You can now run the build script to resolve the external references, validate the spec, and output the final product by running:

npm run build-spec

Adding the endpoint

Let’s add the post index endpoint to our spec. I like to split out our spec into modules, following the application structure as outlined in Scaling Laravel Architecture.

Create an articles directory, a paths subdirectory, and a YAML file called article-index.yaml. Your directory structure should look like this:

spec
├── dist
│   └── api.yaml
├── articles
│   └── paths
│       └── article-index.yaml
├── api.yaml
└── paths.yaml

Let’s write our post index endpoint spec!

summary: 'Return a list of articles.'
tags:
 - Articles
parameters:
 - name: page
   in: query
   required: false
   type: integer
 - name: limit
   in: query
   required: false
   type: integer
responses:
 200:
   description: 'Articles returned successfully.'
   schema:
     type: object
     properties:
       meta:
         type: object
         properties:
           page:
             type: integer
           total:
             type: integer
           last_page:
             type: integer
           limit:
             type: integer
       data:
         type: array
         items:
           type: object
           properties:
             title:
               type: string
             published_at:
               type: string
               format: date
             author:
               type: object
               properties:
                 name:
                   type: string
             body:
               type: string

And then in our paths.yaml file:

/articles:
 get:
   $ref: ./articles/paths/article-index.yaml

In the example above we have defined a summary of the endpoint, the available parameters, and the output schema. Path operations also inherit the consumes and produces field that we defined at our root level spec. We can also override them here if we’d like.

Extracting reusable components

We can, and should, clean this up. You’ll notice there are some structures here that would be useful to abstract and make reusable such as pagination query parameters, metadata pagination output, and the article entity output. Extracting these structures into a reusable structure not only saves time, but allows us to maintain them in one place, rather than in every instance that they occur.

OpenAPI makes defining reusable parameters easy. Add a file called parameters.yaml to the root spec directory.

pageParam:
 name: page
 in: query
 required: false
 type: integer

limitParam:
 name: limit
 in: query
 required: false
 type: integer

Then link it api.yaml like paths.

parameters:
 $ref: ./parameters.yaml

To reference the objects defined here, you can reference them like so:

 - $ref: '#/parameters/pageParam'

So the parameters section of article-index.yaml now looks like this:

parameters:
 - $ref: '#/parameters/pageParam'
 - $ref: '#/parameters/limitParam'

We start the ref with a # to denote it is an internal reference. Since the files resolve external references first, all of our definitions will be in the same file as our paths, so we can reference them internally.

Now we need to extract our Post definition into its own schema file. According to the Open API Specification Version 2: “Models are described using the Schema Object which is a subset of JSON Schema Draft 4.”

Models may be a subset of JSON Schema, but as far as I can tell, you cannot directly work with JSON Schema objects in Open API v2. I wanted to use JSON Schema to define a single source of truth for our models, and import them into our Open API spec, but the current tools do not allow it with version 2. The awesome people over at WeWork have built Speccy to work with this type of setup with Open API v3, but unfortunately we are not using version 3 (We’ll get into the reasoning behind this later).

So for now, we will simply use the Open API spec to define our models. I’d love to come back to this and explore JSON Schema more when there’s a viable route to do so.

Create a file called article.yaml in spec/articles/schemas

type: object
properties:
 id:
   type: integer
 title:
   type: string
 published_at:
   type: string
   format: date
 body:
   type: string
 author:
   $ref: '#/definitions/Author'

Now a file called author.yaml in the same folder.

type: object
properties:
 id:
   type: integer
 name:
   type: integer
required:
 - id
 - name

Now create a file called definitions.yaml in the spec/ directory.

Article:
 $ref: ./articles/schemas/article.yaml
Author:
 $ref: ./articles/schemas/author.yaml

And link the definitions file in your root spec like we did with the paths and parameters files.

definitions:
 $ref: ./definitions.yaml

Now we can reference the models in our path operation like so:

responses:
 200:
   description: 'Articles returned successfully.'
   schema:
     type: object
     properties:
       meta:
         type: object
         properties:
           page:
             type: integer
           total:
             type: integer
           last_page:
             type: integer
           limit:
             type: integer
       data:
         type: array
         items:
           $ref: '#/definitions/Article'

We could extract the meta object in the same way. Create a shared/ module in the root spec and add a schemas folder with a file called pagination.yaml

type: object
properties:
 page:
   type: integer
 total:
   type: integer
 last_page:
   type: integer
 limit:
   type: integer

And the final path operation looks like this:

summary: 'Return a list of articles.'
tags:
 - Articles
parameters:
 - $ref: '#/parameters/pageParam'
 - $ref: '#/parameters/limitParam'
responses:
 200:
   description: 'Articles returned successfully.'
   schema:
     type: object
     properties:
       meta:
         $ref: '#/definitions/Pagination'
       data:
         type: array
         items:
           $ref: '#/definitions/Article'

Much cleaner! There are definitely aspects to this flow that could be improved, but I believe this is a good pattern for building a scalable and maintainable API spec.

Documentation with ReDoc

Now that we have our basic spec, let’s generate some documentation! Using ReDoc, we can turn our spec into clean, easy to read docs. First, grab redoc-cli by running

npm install -g redoc-cli

Then add the following to the scripts section in the package.json

"serve-docs": "redoc-cli serve spec/dist/api.yaml --watch"

You can now serve up your docs by running

npm run docs

Navigate to http://127.0.0.1:8080 and you should see something like this:

Easy

Testing your spec

To me, being able to test your spec against your API, and integrate that process into your CI/CD is one of the biggest benefits to having a spec in the first place. The only tool I’ve seen that does this is Dredd, and it is the reason I suggested using Open API v2.

Dredd does not yet have Open API v3 support, and a ticket has been open to add it for over a year. I’m not sure when to expect it, and given that there are tools to help convert from Open API v2 to v3, I think sticking with v2 to gain the benefit of Dredd is worth it.

Setup

Install Dredd using NPM

npm install -g dredd

Initialize Dredd by running

dredd init

? Location of the API description document (apiary.apib) spec/dist/api.yaml
? Command to start the API server under test (npm start) 
? Host of the API under test (http://127.0.0.1:3000) http://api.blog.test
? Do you want to use hooks to customize Dredd's behavior? (Y/n) Y
  Go 
  JavaScript 
  Perl 
❯ PHP 
  Python 
  Ruby 
  Rust 
? Do you want to report your tests to the Apiary inspector? (Y/n) n
? Dredd is best served with Continuous Integration. Do you want to create CI configuration? (Y/n) N

Make sure you’ve configured your app to be served at http://api.blog.test, or replace this with the location of your Laravel app. Next, go ahead and install the Dredd PHP hooks with

composer require ddelnano/dredd-hooks-php --dev

We can use these hooks to configure our application for test mode when Dredd runs. For now though, let’s see what happens when we run Dredd:

info: Configuration './dredd.yml' found, ignoring other arguments.
info: Beginning Dredd testing...
fail: GET (200) / duration: 248ms
fail: GET (200) /articles duration: 36ms

I’ve truncated the rest of the output due to length, but as you will see, all of our tests are failing! With each failure you get the request, the expected output, and the actual output, Since we haven’t changed anything in our actual application, it doesn’t reflect what we have specced out! Let’s fix this with mocked responses.

Our first path

The first path we added to our spec was the root endpoint to display our application version. It produces JSON and should output a version number. Let’s look at what Dredd tells us about this path:

request: 
method: GET
uri: /
headers: 
    Content-Type: application/json
    Accept: application/json
    User-Agent: Dredd/5.2.0 (Linux 4.15.0-38-generic; x64)

body: 

expected: 
headers: 
    Content-Type: application/json

statusCode: 200


actual: 
statusCode: 200
content-type: text/html; charset=UTF-8

Again, I’ve truncated this as there’s tons of output, but you can see it expects a 200 response with the application/json mime-type, but it actually received a 200 response with text/html. We can quickly fix this by replacing the welcome view in the route with a JSON response like so:

Route::get('/', function () {
   return response()->json([
       'name' => 'Blog API',
       'version' => '1.0'
   ]);
});

If we re-run our tests we see that it now passes!

The articles endpoint

If we look at our next test we will see that it is also failing.

fail: GET (200) /articles duration: 38ms
fail: statusCode: Status code is '404' instead of '200'

The route doesn’t exist, so let’s add it by adding an entry to our routes file.

Note: We would not want to put any of this directly in our routes file, it's just easier to demonstrate this way.

Route::get('/articles', function () {
});

If we re-run Dredd, we get the following output

fail: GET (200) /articles duration: 74ms
fail: headers: Header 'content-type' has value 'text/html; charset=UTF-8' instead of 'application/json'

We get a 200 now, but the content-type is invalid. Let’s return a JSON response and see what happens.

Route::get('/articles', function () {
   return response()->json([]);
});

And now Dredd tells us…

fail: GET (200) /articles duration: 71ms
fail: body: At '' Invalid type: array (expected object)

We are returning the correct status code and content-type, but the actual response is being marked as invalid by Dredd. Let’s look at documentation to see what Dredd is expecting:

We can see that our response should be an object with a meta and data properties. Meta should contain a Pagination object as we defined in our schema, and the data property should be an array containing Article objects. Dredd validates that our API is returning the correct data structure, so let’s mock what one would look like:

Route::get('/articles', function () {
   return response()->json([
       'meta' => [
           'page' => 1,
           'total' => 1,
           'last_page' => 1,
           'limit' => 10 
       ],
       'data' => [
       [
           'id' => 1,
           'title' => 'My Article Title',
           'published_at' => '2018-11-13',
           'body' => 'My article body',
           'author' => [
               'id' => 1,
               'name' => 'Test'
           ]
       ]]
   ]);
});

If we run Dredd, we can see all of our tests now pass!

info: Configuration './dredd.yml' found, ignoring other arguments.
info: Beginning Dredd testing...
pass: GET (200) / duration: 174ms
pass: GET (200) /articles duration: 22ms
complete: 2 passing, 0 failing, 0 errors, 0 skipped, 2 total
complete: Tests took 198ms

This is the ultimate safeguard from documentation rot! You can, and should, set up measures to prevent deployments unless your spec matches your actual API. This kind of protection around your spec is invaluable.

Other tools

ReDoc and Dredd are only the beginning in terms of what you can do with your new specification. There are tools that let you generate validation rules, client libraries, mock servers, and more!

Summary

This article ran a bit longer than I meant it to, and I didn’t even touch on everything I wanted, so I may be writing a follow-up sometime in the future. In the meantime, please feel free to share any questions, comments, or suggestions in the section below! Thanks for reading!

The post API Specifications and Laravel appeared first on Matt Does Code.

Scaling Laravel Architecture

Matt Moore — Fri, 09 Nov 2018 23:08:22 +0000

Laravel ships with a great starting directory structure, one which may support your entire project, depending on the size. If, however, you notice it’s getting harder and harder to find code that you want to work on, you may want to step back and rethink your app’s architecture.

The most popular patterns I’ve seen in the Laravel world are Domain Driven Design and Hexagonal Architecture. While I’m by no means a DDD expert, I have found it works well within Laravel’s patterns, given you don’t try to follow it exactly.

For instance, as this blog post points out, Eloquent substantially breaks DDD principles. I think the mistake here is trying to implement “pure” DDD rather than using it as a guideline.

Eloquent is an Active Record ORM, and therefore is inherently incompatible with DDD. This is not a bad thing! I prefer leaning into this rather than fighting it and embracing the power Eloquent gives you alongside the benefits of DDD.

I find that these Laravel components map to the following Domain-Driven Design layers quite nicely.

Controllers/Console Command Classes - Presentation
Jobs - Application
Repositories - Infrastructure
Models - Domain

Presentation

Controllers are responsible for the presentation layer of DDD. Whether you are building an API or an application that returns HTML views, your controllers are responsible for presenting this content to the user. Custom Artisan command classes can also be considered part of the presentation layer.

Application

The application layer of a domain-driven codebase is responsible for orchestrating the Domain and Infrastructure layers to perform high-level tasks in your application.

I like to use Laravel’s Command Bus for this layer. I adopted the idea from PyroCMS, and haven’t looked back since. I have also seen the Application layer represented using Gateways, which is outlined in this post, but I think encapsulating features into a single job class is cleaner.

A big benefit of using Jobs is that you can dispatch them from any presentation layer. Just make sure you use dispatch_now() function so it doesn’t get queued.

$result = dispatch_now(new CreatePost($request));

Infrastructure

The infrastructure layer deals with anything that interacts with code or services outside of the application. This includes things like emails, API calls, and,most commonly, database interactions. I am a huge fan of the repository pattern for interacting with the database in a Laravel application. Encapsulating query logic and model retrieval is a sure way to reduce bugs and promote code reuse for database interactions.

Domain

The domain layer contains all business logic and is the heart of your application. This is the layer that can get muddy when using Eloquent since your domain models know about your database. If we ignore this aspect, and only use repositories to interact with the database, I believe we can satisfy the requirement of separating these concerns sufficiently.

I’ve seen hacks in Eloquent to disable database calls but I believe this is unnecessary. I find that baking these standards into the project at the documentation/code review level is sufficient.

An alternative to Eloquent is using Laravel Doctrine. This gives you everything you need to create a true Domain layer using Entities and a data-mapper for the infrastructure layer. There are a number of benefits to this approach when working on a truly large application, but it might be overkill for smaller applications.

I typically enjoy Eloquent, especially for the speed it provides when you’re hacking together a prototype or proof of concept, and believe it can even work fine for large applications. I have, however, experienced some of its shortcomings first hand, and think that in certain situations, an alternative such as Data Mapper is a completely valid choice. It’s important that you always weigh your options and pick the right tool for the job.

Here is a fantastic article that takes an honest look at both patterns and their tradeoffs

Okay, so what does this actually look like in a Laravel application? Let’s go through the steps I typically take when starting a new project following this architecture.

Set-up

Let’s say we want to build a personal site with a blog and a projects section. Let’s call it our Portfolio.

Note: A site this small would work fine with the default directory structure and basic Laravel architecture, but ignore that for now.

Download a fresh copy of Laravel using either composer create-project or the laravel CLI as outlined in the documentation.

Namespace your app using

php artisan app:name Portfolio

Moving the core code.

Your initial app directory structure should look something like this:

├── Console
│   └── Kernel.php
├── Exceptions
│   └── Handler.php
├── Http
│   ├── Controllers
│   │   ├── Auth
│   │   │   ├── ForgotPasswordController.php
│   │   │   ├── LoginController.php
│   │   │   ├── RegisterController.php
│   │   │   ├── ResetPasswordController.php
│   │   │   └── VerificationController.php
│   │   └── Controller.php
│   ├── Kernel.php
│   └── Middleware
│       ├── Authenticate.php
│       ├── CheckForMaintenanceMode.php
│       ├── EncryptCookies.php
│       ├── RedirectIfAuthenticated.php
│       ├── TrimStrings.php
│       ├── TrustProxies.php
│       └── VerifyCsrfToken.php
├── Providers
│   ├── AppServiceProvider.php
│   ├── AuthServiceProvider.php
│   ├── BroadcastServiceProvider.php
│   ├── EventServiceProvider.php
│   └── RouteServiceProvider.php
└── User.php

I first like to move all the core code into a Core\ namespace. This contains all the laravel specific setup code such as the main service provider, kernel, etc.

To do this, create a Core folder in the app/ directory and move everything into it except the User model. Either using an IDE, or by hand, you must now adjust the namespaces of all the classes within these directories. Simply add the Core namespace after Portfolio\ like so:

namespace Portfolio\Core\Providers;

Once namespaces are adjusted, we have to fix a few references.

bootstrap/app.php
Fix the singleton bindings for the HTTP and Console Kernels, as well as the Exception handler.
config/app.php
Fix the references to your application service providers.
app/Core/Http/Kernel.php
Fix the middleware references for the CheckForMaintenaceMode, TrimStrings, TrustProxies, EncryptCookies, VerifyCsrfToken middlewares, as well as the Authenticate and RedirectIfAuthenticated route middlewares. These references can be simplified by simply prepending the middleware class with the Middleware\ namespace e.g. Middleware\CheckForMaintenanceMode::class
app/Core/Providers/RouteServiceProvider.php
Fix the $namespace attribute to allow for multiple controller directories. I prefer to shorten this to just the route namespace, in this case Portfolio
app/Core/Console/Kernel.php
Remove the call to load() (line 38) as commands will be declared in numerous places. I prefer to declare commands explicitly using the $commands attribute, or you can use the newer console route file.

You now have a clean slate to build your first feature module. Your app/ directory structure should now look like this.

Core
    ├── Console
    ├── Exceptions
    ├── Http
    │   ├── Controllers
    │   │   └── Auth
    │   └── Middleware
    └── Providers

The Blog Module

Let’s start the Blog module. Every module requires some of the same components. Controllers (presentation), Jobs (application), Models (domain), and Repositories (infrastructure). I like to loosely follow the default Laravel structure inside each Module like so:

Blog
├── Http
│   ├── Controllers
│   │   └── PostController.php
│   ├── Requests
│   │   ├── CreateOrUpdatePost.php
│   │   └── DeletePost.php
│   └── Transformers
│       └── PostTransformer.php
├── Jobs
│   ├── EditPost.php
│   ├── RemovePost.php
│   └── WritePost.php
├── Repositories
│   ├── EloquentPostRepository.php
│   └── PostRepository.php
├── Author.php
├── Comment.php
└── Post.php

The presentation layer lives in Http/ and Console/. This is where you will find your controllers, form requests and transformers (I recommend Fractal).

The bulk of the application layer can be found in in the Jobs directory. The only thing your Jobs should do is delegate to lower layers such as Repositories and Service classes. No business logic should live here.

The repositories directory seems self-explanatory, this is where your repositories live.

Models are in the root of the module. I prefer this structure because it’s where most of the business logic should live, which should be the most visible and readily available part of any module. Any other service classes could live here as well, or you might opt to put them in a Service or Utilities namespace.

While this is a very basic module, I believe it demonstrates the idea of how you can shape a Laravel application with principles from DD. You can freely implement any other Laravel component in the same way, for instance Events or Listeners would become directories in the root of the module, as would Notifications or Mail classes.

If your module starts to become too large you can split it out into submodules, but I recommend doing everything you can to keep your directory tree as flat as possible. Only nest when it is the cleanest solution! Having 5 submodules with 1 model each is probably overkill.

The Project Module

Our “Projects” module will look very similar in structure.

Projects
├── Http
│   ├── Controllers
│   │   └── ProjectController.php
│   ├── Requests
│   │   ├── CreateOrUpdateProject.php
│   │   └── DeleteProject.php
│   └── Transformers
│       └── ProjectTransformer.php
├── Jobs
│   └── CreateProject.php
├── Repositories
│   ├── EloquentProjectRepository.php
│   └── ProjectRepository.php
└── Project.php

Extracting Comments into its own module

Let’s imagine that we want to enable comments in our Project module. Currently the comment code lives in the Blog module, so we must refactor it into a shared module.

Shared modules can either live inside the Core namespace or a top-level module of its own. Or you might want to create a Shared module with utility classes, traits, or sub-modules. Any of these are perfectly valid and will depend on a multitude of factors.

Let’s create a top-level Comments module for both the Blog and Project modules to consume.

Comments
├── Jobs
│   ├── CreateComment.php
│   ├── RemoveComment.php
│   └── UpdateComment.php
├── CommentController.php
├── Comment.php
├── CommentRepository.php
└── EloquentCommentRepository.php

Notice how the model, controller, and repository live in the root module directory. This is just personal preference. If there is only one type of a component, I will not put it in its own directory as it only makes it harder to get to the file. I only start to split things into their own directories when a directory gets too big to easily grok. It might not be the best architecture pattern but it has worked well for me so far. Do what feels best for you, but the important thing is to remain consistent! Don’t go by feel alone, create rules for organizing files so that other people who work on the project can replicate your organization.

Summary

In the future I want to dig deeper into what this architecture pattern looks like at the code-level but I hope I’ve shed some light on how you can organize a growing project using Laravel effectively.

I’m currently reading Domain Driven Design and recommend it to anyone looking to learn more about DDD. I’m by no means an expert on this topic and it is something I’m constantly striving to improve at. If you have any suggestions or want to point out any flaws in anything I’ve demonstrated, please feel free to do so in the comments. Thanks for reading!

The post Scaling Laravel Architecture appeared first on Matt Does Code.

Angular, Accessibility, and You

Matt Moore — Thu, 25 Oct 2018 20:44:39 +0000

The motivation behind this post is that technical resources for implementing accessibility techniques, especially with modern Javascript frameworks like Angular, are very sparse. There also seems to be a misconception that modern Javascript frameworks impede your ability to make your web application accessible. While there are some accessibility pitfalls involved in using frameworks like Angular, there are also many benefits, and I want to go over some of the lessons I’ve learned while building an Angular powered platform that strives to be as accessible as possible.

I also want to point out that there are many aspects to web accessibility, but this article focuses on keyboard and screen reader optimizations.

SPA Considerations
1. Route changes
2. Form validation
3. Lazily-loaded content
4. Notifications
5. Page title
UI Package Pitfalls
1. Data table
2. Bootstrap
3. Tree Components
4. Toggle Switches
Recipes
1. Skip Link
2. Focus management
3. Page titles
Testing
Resources

SPA Considerations

It doesn’t matter what technology you use, if you’re building a Single-Page Application (SPA), there are some extra considerations you must make to ensure that it is accessible. In this section, we’ll briefly cover some of these areas. Later, in the Recipes section, we’ll get into the details of how to solve these concerns using Angular.

1. Route Changes

The biggest difference between a traditional web application and an SPA is dealing with navigation. In a traditional web application, on each page change and on most user interactions such as form submissions, the web page reloads, focus gets reset, and the page title changes (if you are using proper page titles). If your user is using a screen reader, it will announce the new page title, and it will make them aware that the new page has loaded. In an SPA, you must manage this manually.

I’ve seen a few ways to accomplish this, but the easiest way to do it is to set focus to each page’s H1 element when it comes on screen. I will go over how to do this with Angular later on.

Another option is to have a div with specific wording to show a new page has loaded, which only appears on screen readers. Something like “The contact page is now on-screen”, and set focus to that div on each route change.

You could also set focus to the skip link or header on each route change to emulate how a traditional web application behaves. These are all valid options, but best practice will depend on your specific use-case.

2. Form Validation

Form validation is another important area to consider when building an accessible SPA. Similar to route changes, focus management is key here. To ensure a good user experience, make sure that focus gets set to any error messages after submission. Useful error messages are clearly linked to a specific input field, with clear directions for fixing it.

Another common issue I’ve noticed with SPA forms is that the submit button is disabled until the form is valid. Don’t do this! Your user should be able to submit your forms in any state, and if the form is invalid, it should provide clear direction on how to fix it. This will greatly improve usability for screen reader and non screen reader users alike.

Here is a great post about implementing accessible forms using Angular: https://simplyaccessible.com/article/accessible-forms-angular/

3. Lazily-loaded content

This is a big one, and one you don’t usually have to even think about for traditional web apps. There are a wide range of solutions for solving this issue, and it’s one that I’m still refining on Dinolytics.

Lazy-loading all your content is a very popular method for SPA’s as it dramatically improves the initial page load. If you have lots of different content areas, you can split a giant API call into several smaller ones. The problem is that this content will not get presented to screen reader users. If they’re on a slower connection, they may have explored the page before the content gets loaded and concluded that it’s an empty page.

The best solution I’ve found involves using aria-live regions. You can use an aria-live region as a way to notify screen reader users when certain content has loaded. Do not, however, just throw all your content into an aria live region, this will cause your entire page to be read when it gets loaded in. Stick with short descriptive messages such as “content loading” and “content is now on-screen”. If in doubt, test with a screen reader!

If you’d like to read more about aria-live regions and the available options, check out this article: http://juicystudio.com/article/wai-aria_live-regions_updated.php

4. Notifications

There are 2 main ways to handle app-wide notifications such as toast notifications for keyboard and screen reader users.

The first is to use an aria-live region. You can give the aria-live attribute to your toasts container and any notifications get presented to screen readers users.

The other option is to use focus. You can set focus to the notification when it appears and it will get presented to screen reader users as well. You may want to have your notification remains on-screen until it is no longer receiving focus, this will prevent the notification from being unexpectedly dismissed.

5. Page title

Page titles are important for accessibility for a few reasons. Generally, it’s the first thing that gets read by screen readers when the page loads and it should give the user an idea about what’s going to be on the page.

In a round-trip website or application, the page title is determined before the browser loads the page since the content is being served by the backend. If you’re building a SPA, however, you must set the page title dynamically based on the route on the front-end.

In addition, a screen reader will not read the page title on subsequent page changes since the page doesn’t actually change, Javascript just swaps out the content on the same page.

It is still important to manage the title, as it will be read if the user switches to a different tab and comes back, if they move to a different window, and on the first page load.

If you’ve taken care of managing the page title, you will also see benefits if you switch to server-side rendering for SEO purposes since the page title will be properly set.

UI Package Pitfalls

UI packages have their own section because they were, by far, my most problematic issue during my first accessibility audit on Dinolytics. In the MVP stages I was in a rapid prototype mode and I just grabbed any package that looked good and did what I needed. This included datatables, tree components, switch toggles, comboboxes and Angular bootstrap packages. At best, some of these packages had minor accessibility issues, and at worst they were completely inaccessible. Testing the accessibility of any 3rd-party package that you bring into your project is important.

One options for mitigating future issues is to wrap all your 3rd-party components in your own component and use that throughout the app. This way if you ever have to switch components for any reason at all, accessibility or otherwise, you just have to change the internals of your wrapper component and the changes will be made app-wide for free. In my opinion, this is one of the biggest benefits of using something like Angular.

1. Datatables

This is by far the biggest problem area when it comes to inaccessible Angular packages. I may be missing some packages and if I am, please let me know in the Twitter thread, but out of the few times I went searching, I only found 1 package that met all of our requirements and was even remotely accessible. There are still a few minor accessibility and responsive issues with this package, and I’ve forked it to make some improvements. The fork is not on NPM yet but I am planning on publishing it soon. In the meantime, you can check out the original package as it’s by far the best Angular Datatable package in terms of accessibility.

Original: https://github.com/brunano21/angular-4-data-table#readme

Fork: https://github.com/pope-tech/ngx-table

2. Bootstrap

Dinolytics uses Bootstrap which has great accessibility support, but there are multiple Angular packages that implement the Javascript based components such as toggletips and modals. I didn’t notice until I already implemented most of the components that the one I chose was completely inaccessible. Luckily, there is an alternative that has great accessibility support built-in.

https://ng-bootstrap.github.io/#/home

3. Tree Components

Dinolytics presents a tree component to help you manage your group hierarchy. There are a few tree components for Angular out there, but I only found one that supports keyboard navigation. This is a great example of why you should employ multiple forms of accessibility testing.

I thought the fact that the tree was keyboard-navigable was enough to consider it accessible. It turns out there was no way to navigate to the tree by keyboard only, which I should have caught during testing. In addition, it wasn’t presenting any content to screen readers even after being focused. It was completely inaccessible and I wasn’t even aware until I tested with a screen reader.

Since there wasn’t any other package (even the Angular Material tree component is completely inaccessible!), I decided to fork this package and add aria support. This forked version is what we’re currently using on Dinolytics, and while it’s not yet perfect, it’s at least usable. I am planning on submitting a PR to make these changes available to everyone in the near future.

https://github.com/500tech/angular-tree-component

4. Toggle switches

I am a fan of using toggle switches rather than checkboxes. I think that they look better and are easily understood by the user. That being said, all the toggle switch packages for Angular that I could find are inaccessible. While you can accomplish the same look and feel using CSS and Javascript, which we might do in the future, I decided to change all the toggle switches to checkboxes. Sometimes just using native HTML elements is the best option for remediating some of the issues you run into when you override native browser behavior.

Recipes

Let’s dive into some code. I want to go over some common accessibility techniques and how you can implement them in Angular.

1. Skip Link

WebAIM has a great article on skip links so I won’t explain the benefits here. I initially thought you could implement this using Angular’s routerLink and fragment directives like so:

<a [routerLink]="['./']" fragment="main-content">Skip to content</a>

This doesn’t work! If you activate that link, nothing happens. I tried a lot of combinations using native attributes but nothing worked. The thing that finally got it working was the following code:

<div id="skip-link">
    <a [href]="skipLinkPath">Skip to content</a>
</div>


<main id="main-content" class="content">
    <!--Main content goes here-->
</main>

// in constructor or ngOnInit()
router.events.pipe(filter(event => event instanceof NavigationEnd)).subscribe(() => {
   if( ! this.router.url.endsWith('#main-content')) {
       this.skipLinkPath = `${this.router.url}#main-content`;
   }
});

I also found a blog post with an alternate method. I personally prefer the method above since it’s as close to a native skip link as possible, but the following, which uses a button and calling the focus method on the HTML element itself, works as well.

http://markleblog.com/tl-dr/

2. Focus Management

Focus management is a huge piece of web accessibility, especially when it comes to SPA’s. There are many interactions which change what’s on screen, and you need to make sure your app focuses on those elements appropriately. There are a few techniques you can employ using Angular to manage focus.

Scenario 1:

Let’s say you have a content or form section that is initially hidden, and comes into view when the user presses a button.

Take for instance, the website widget on the group screen in Dinolytics. The initial view is showing the websites list.

When the user activates the “Add Website” button, the screen changes to the website form. When interactions like this happen, you need to make sure you are setting focus to the appropriate element, in this case the first and only field in the form.

You can accomplish this in Angular in the following way:

<div>
   <button type="button" (click)="toggleForm()">
       <ng-container *ngIf=" ! showForm">Show form</ng-container>
       <ng-container *ngIf="showForm">Back</ng-container>
   </button>

   <ng-container *ngIf=" ! showForm">
       <table id="mytable"></table>
   </ng-container>

   <ng-container *ngIf="showForm">
       <form>
           <label>Website</label>
           <input type="text" id="website" name="website" />
       </form>
   </ng-container>

</div>


public toggleForm() {
   this.showForm = ! this.showForm;

   let focus = this.showForm ? 'website' : 'mytable';

   setTimeout(() => {
       document.getElementById(focus).focus();
   });
}

A few things are going on here. First, if you don’t know about ng-container, go check it out! It provides a convenient way to use structural directives without adding unnecessary divs and spans.

Second, you may have noticed that the focus() call is wrapped in a setTimeout() function. This is because the browser needs to perform an update before calling the focus method or else the element you’re trying to focus on won’t be on-screen and it will fail.

Scenario 2:

You are using dynamic form inputs where the user can add or remove inputs by activating a button. Take the external email addresses field on the reports screen in Dinolytics for instance.

The interface starts with the “Send to external email addresses” button. When you activate that button it adds a new text input for an e-mail address.

When a new field gets added it should receive focus.

When a field is removed, the previous field should receive focus, and when all fields are removed, the “Send to external email addresses” button should receive focus. You can accomplish a large part of this with a custom directive on your dynamic input field.

<input focus-input formControlName="address" id="emails-{{ ii }}" class="form-control" type="email" name="emails[]" />

import { AfterViewInit, Directive, ElementRef } from "@angular/core";

@Directive({
   selector: '[focus-input]'
})
export class FocusInput implements AfterViewInit {

   constructor(public elem: ElementRef) {}

   ngAfterViewInit() {
       this.elem.nativeElement.focus();
   }
}

This takes care of setting focus to the input when it is added. Now we have to make sure that focus is returned to the previous element when an input is removed. We can just grab the index of the input being removed, subtract one, and focus to that id. Now add a call to focus on the main button when all emails get removed and you’re done!

public deleteEmail(index) {

   // remove email field

   // set focus
   document.getElementById('emails-' + (index - 1)).focus();
}

public removeAllExternalEmails() {

   // remove all emails and hide container

   // set focus
   document.getElementById('show-external-emails').focus();
}

Scenario 3:

The route changes and you want to focus on the H1 tag. We can hook into the router events again to make sure this happens on every route change automatically.

Make sure your H1’s are focusable by setting tabindex=”-1″ and then subscribe to the router events.

constructor(private router: Router) {
    router.events.pipe(filter(event => event instanceof NavigationEnd)).subscribe(() => {
        document.getElementsByTagName('h1')[0].focus();
    });
}

Scenario 4:

You want to set focus to an Angular component but can’t use a tag name, id, or class. I ran into this when I tried to focus on a combobox component using the ng-select package. We can accomplish using Angular’s View Child decorator. I suggest only using this method when a more native approach like using document.getElementById is not available.


<ng-select #websiteSelect
          [items]="selectWebsites$ | async"
          formControlName="website"
          placeholder="Select a website"
          bindLabel="name"
          labelForId="website">
</ng-select>

@ViewChild('websiteSelect') websiteSelect;

public toggleForm() {
   setTimeout(() => {
       this.mySelect.focus();
   });
}

You can pass a component class or string identifier into ViewChild which is defined by declaring it on the component prepended by a ‘#’ like the example above. You can then access that component directly. Note that the setTimeout() call is only needed if the component was not on screen before the toggle call.

3. Page Titles

Angular comes with a class to help you manage your page title. I hooked into the route definition so that it was automatically defined based on the route.

You can define the page title on the route, and then subscribe to navigation change events through the router.

constructor(private router: Router,
                   private route: ActivatedRoute
                   private titleService: Title) {

   router.events.pipe(filter(event => event instanceof NavigationEnd)).subscribe(() => {
       let title = this.getTitleFromRoute(route.root) + ' - Dinolytics';
       this.titleService.setTitle(title);
   });
}

private getTitleFromRoute(route) {
   if (route.snapshot.data.hasOwnProperty('title')) {
       return route.snapshot.data.title;
   }

   let children: ActivatedRoute[] = route.children;

   // iterate over route children
   for (let child of children) {
       // verify that we have the correct router outlet
       if (child.outlet !== PRIMARY_OUTLET) {
           continue;
       }

       if ( ! child.snapshot.data.hasOwnProperty('title')) {
           return this.getTitleFromRoute(child);
       }

       return child.snapshot.data.title;
   }

   return false;
}

export const routes = [{
   path: ':id',
   component: GroupsEditComponent,
   data: {
       title: 'Edit Group'
   },
}]

Since routes can be nested, we must recursively iterate over the routes to find the title. Once we have it we can use Angular’s TitleService to set the correct title.

Testing

Now that you know a few tips and tricks to help make your Angular app more accessible, you need to know how to test them.

WAVE

The first and easiest method to use is the WAVE browser extension.

WAVE Chrome Extension

WAVE Firefox Extension

You can locally evaluate each page using this extension to quickly find points of failure and remediate them. You will not find all the issues with your application using this method but it will get you started.

Axe

Axe also has free browser extensions to get you started with initial accessibility assessments.

Axe Chrome Extension

Axe Firefox Extension

Keyboard Testing

The next method is to test your application using your keyboard only. WebAIM has an awesome article to help get you started with this technique. If you cannot effectively use your app without a mouse, it’s not accessible! Make sure you use proper focus management and indicators to help improve keyboard navigation.

Screen Reader Testing

The final method I will recommend is screen reader testing. Again, WebAIM has great resources for helping you with this. Once you’re familiar with how the screen reader works, turn off your monitor and try to use your application. You will quickly find which areas need work.

Windows

Windows users can use NVDA and Firefox, Chrome, or IE with very little setup.

Mac

Mac has VoiceOver already installed and ready to go.

Linux

If you are a Linux user like myself, there are a few options available to you.

Chromevox

Link to Chromevox in the Google app store. I don’t recommend this option as there seem to be a lot of issues with ChromeVox and it doesn’t have very high adoption as of now.

Linux screen reader such as Orca

I haven’t tested any of these out yet but they are on my list to check out.

NVDA using VirtualBox

Finally, the method I use employs a Windows VirtualBox image running Firefox, Chrome, and NVDA. I will briefly walk you through setting this up as there are a few gotchas.

Head over to https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/ and get a Windows 10 image by selecting the “MSEdge on Win10” machine on the VirtualBox platform.
If you don’t already have VirtualBox, go to https://www.virtualbox.org/ and download the appropriate package for your machine and install it.
Once your image has finished downloading and you have VirtualBox installed, extract the windows image .zip and import the .ova into VirtualBox by double clicking on it and boot it up.
If your Angular app talks to an external API that is hosted locally, be sure to add the appropriate hostfile entries in C:\Windows\System32\drivers\etc\hosts
If you’re using the Angular CLI, make sure you add a host option onto your ng serve command so that VirtualBox can talk to it. Either your internal host IP or 0.0.0.0 will work.
You may not need to do anything else other than install NVDA and Firefox but if your sound is disabled like mine was, go into the machine settings and find the “Audio” section.

You may have to play with the settings as I’m under the impression it is hardware specific, but here are the settings I had to use to get mine working correctly.

Host Audio Driver: PulseAudio

Audio Controller: Intel HD Audio

Enable Audio Output: Checked

Save and reboot your machine and you should be good to go! Take a snapshot once everything is setup so that you can always come back to this point if something breaks (or the 90 day Windows limit is reached).

Automated tests

Testing accessibility with front-end testing tools such as Jasmine and Karma is something I have yet to check out, but I really really like the idea. I think integrated accessibility checks into your test suite is a valuable practice and will protect against regressions. Here are a few resources if you’d like to dive into the topic.

Accessibility Testing with Angular

Automating accessibility testing with Selenium Webdrive and AxeCore

Test for accessibility and help millions of people

Conclusion

I’ve only scratched the surface of Web Accessibility in this post and there’s a ton I didn’t cover. I have included a small list of additional resources that are Angular-specific if you want to dive a bit deeper into the topic. Join the conversation on Twitter if you have any suggestions for additional topics to cover, if you have questions, or if you just want to say hi! Thanks for reading.

Resources

Angular 2 Training Book

Angular Accessibility Tips and Tricks

Accessibility with Angular

Angular CDK Accessibility

The post Angular, Accessibility, and You appeared first on Dinolytics Blog.

DEV Community: Matt Moore

Abstracting Laravel Dependencies

#1: Create an Interface and a Wrapper Implementation

Example: Guzzle

#2: Create a standalone wrapper class

#3: Confine dependency to one class.

Considerations

Write Everything Twice

Avoid Laravel Facades

Wrap Laravel Helper Methods

Conclusion

6 Laravel Tips

1. onDelete('set null')

2. dropForeign([]);

3. Model Validation

4. Data Migrations

5. Adding attributes to the request

6. Ordering models by distant many-to-many related items

Summary

API Specifications and Laravel

API Specification vs API Documentation

OpenAPI

Generating the specification

Example

Setting up the Application

Setting up the build tools

Creating the spec object

Adding the endpoint

Extracting reusable components

Documentation with ReDoc

Testing your spec

Setup

Our first path

The articles endpoint

Other tools

Summary

Scaling Laravel Architecture

Presentation

Application

Infrastructure

Domain

Set-up

Moving the core code.

The Blog Module

The Project Module

Extracting Comments into its own module

Summary

Angular, Accessibility, and You

Table of Contents

SPA Considerations

1. Route Changes

2. Form Validation

3. Lazily-loaded content

4. Notifications

5. Page title

UI Package Pitfalls

1. Datatables

2. Bootstrap

3. Tree Components

4. Toggle switches

Recipes

1. Skip Link

2. Focus Management

Scenario 1:

Scenario 2:

Scenario 3:

Scenario 4:

3. Page Titles

Testing

WAVE

Axe

Keyboard Testing

Screen Reader Testing

Windows

Mac

Linux

Chromevox

Linux screen reader such as Orca

NVDA using VirtualBox

Automated tests