Forem: Chris Arter

How to Comment Your Code Like a Boss

Chris Arter — Thu, 03 Dec 2020 12:18:44 +0000

Comments are like garlic.

They can push a dish over the top. Or, they can relegate it to the polite pile of leftovers that your guests appreciate but didn't enjoy.

Comments in your code are much the same. Good, clear, and necessary comments can help keep an otherwise convoluted narrative of code become a clear, easy-to-follow story.

The two main ideas that have helped me when deciding if a section of code needs comments, or if I should leave it bare are these:

💡 Code should explain what is happening.

A true gem from Uncle Bob's Clean Code is the chapter on naming. Explicit and clear naming will help make your code be clear and easy to follow.

Instead of this:

// get the length of an array
const gl = a => a.length

We write this:

const getArrayLength = a => a.length

This allows us to write code that is expressive. The code itself tells you what is happening. In the simple example above, the name of the function tells you what it does. There is no need to parrot this in a comment above. Each time you write a comment, you add to the mental overhead of trying to parse not only the code, but the comments as well. This is why comments should be limited & meaningful.

💡 Comments should explain why.

Let's say we have a user base that is split between two databases. A client or product has users from an old system, a new system, and our application needs to manage both while we transition the code base to a new platform.

import oldsdk from 'old-sdk';
import newsdk from 'new-sdk';

const getUserByEmail = async email => {

    // we switched identity providers
    // and not all users are migrated yet.
    const oldUserData = await oldsdk.getUserByEmail(email);
    const newUserData = await newsdk.getUserByEmail(email);
    return newUserData || oldUserData;
}

In this example, we are fetching a user from some API using a new SDK, and an old SDK. Stuff like this happens all the time. For someone reading this code, while the variable names are descriptive, we don't know why this is happening. The comments in this code explains the purpose of this code. The what is still clear.

Conclusion

Like many things, this is not a hard and fast rule. In fact, it's not even a rule, but more like a tool. It's a generalized guidepost that has been helpful for me in my career as a barometer for writing good comments. There are plenty of situations where you would want or need to approach things differently, but this tip can be a great starting point when getting a feel for writing comments.

Happy coding!

How to easily test REST endpoints in Laravel with minimal syntax.

Chris Arter — Sat, 09 May 2020 12:46:59 +0000

When I write unit tests for APIs, I try to write tests that are as flexible and durable as possible. I try my best to avoid brittle tests that may break if some implementation in my code base should change.

Ideally, tests should not care at all about the implementation, and only care that with X input, we get Y output. Some of your endpoints may return Laravel API Resources. I've seen some developers write tests that ensure that the resource is returned compared to a given shape / array. But, we don't really care about that, do we? We may change our API Resource class, but we want our test to stay resilient.

In the example image above, we'll say we only really care that the title and content of a post is included in the API response. Other fields may change in our resource, but this test ensures that those two fields are always contained in the response.

This is best achieved by using assertJsonFragment. You may have used assertJson() before, but since we are interested in creating as durable tests as possible, assertJsonFragment ensures the tests won't fail if the shape of our returned response changes.

A no-fuss Laravel + Docker starter repo

Chris Arter — Thu, 26 Sep 2019 10:48:19 +0000

This starter repo was born out of frustration of getting docker working with Laravel. Hopefully this will save you some headache!

First, clone the repo here: https://github.com/christopherarter/Quick-Laravel-Docker-Starter

Prerequisites:

PHP 7.1 (minimum)
Composer install guide
Docker install guide
Docker Compose install guide

Get started

Clone this repo and navigate to the repo folder. Run composer create-project --prefer-dist laravel/laravel my-app
Run mv my-app/* my-app/.* ./ && rm -rf my-app
Change the values in your .env to the values below:

DB_CONNECTION=mysql
DB_HOST=laravel_db
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel_user
DB_PASSWORD=myStrongPassword1234

The last step, run docker-compose up

When you run docker ps, you should see your service running locally at http://localhost:9000

To run migrations and commands that interact with the database you need to be inside the laravel web app container.

Run docker ps and get the id of the laravel web container. Next, run docker exec -it <container-id> /bin/bash and you should be at /var/www/app. You may now run artisan commands to interact with the database.

Connecting to your database with a database tool

To connect with this database using tools like MySQL Workbench, DB Beaver or TablePlus, you can access it with the 3305 port, username and password you specified in your .env file.

Middleware for Wordpress

Chris Arter — Mon, 15 Jul 2019 02:36:06 +0000

When I originally began doing significant development around the Wordpress REST API, I was excited to finally get hands-on with it.

Then, it came to write "middleware". If you are unfamiliar with middleware in web development, it is simply a series of checks between the inbound request and your controller actions.

This is the way you can perform middleware checks according to the current WP Codex:

<?php
add_action( 'rest_api_init', function () {
  register_rest_route( 'myplugin/v1', '/author/(?P<id>\d+)', array(
    'methods' => 'GET',
    'callback' => 'my_awesome_func',
    'args' => array(
      'id' => array(
        'validate_callback' => 'is_numeric'
      ),
    ),
    'permission_callback' => function () {
      return current_user_can( 'edit_others_posts' );
    }
  ) );
} );

All we're left with is permission_callback to pass in a function string, or closure as seen in the documentation.

I decided to dig into the source code and see if I could create a more familiar looking middleware.

WP Middleware

That's when I created a middleware() helper.

This helper simply takes the WP_REST_Request from the rest_pre_dispatch filter and injects it as a parameter into the callback in the rest_pre_dispatch hook.

This allows you to write simple checks, with all of the objects you need all in one place:


middleware()->get('/wp/v2/posts', ['check_foo', 'check_bar']);

// callback check
function check_foo($request) {
    if( $request->get_param('foo') != 'foo' ){
        return reject();
    }
}

// callback check
function check_bar($request) {
    if( $request->get_param('bar') != 'bar' ){
        return reject();
    }
}

Simply return the reject() function to reject the request and return a 401. You can also pass custom rejection messages and response code.

return reject("foo doesn't equal bar!", 400);

Authorization

This also opens the door to allow for certain API operations based on external sources, e.g. using user tokens from Cognito, or approving or denying requests based on other token data in the request, like Stripe.

middleware()->post('/wp/v2/stripe-webhook', ['stripe_check']);

function stripe_check($request){
    // verify the webhook came from stripe
}

Middleware Stacks

This also allows you to create pre-described middleware stacks that allow for portable, consolidated check logic across your application.

$middlewareStack = ['check_foo', 'check_bar'];

middleware()->guard([
    '/wp/v2/posts',
    '/wp/v2/users' ], 
    $middlewareStack);

Getting Started

For documentation, see the ReadMe.

To install this middleware as a plugin, use GitHub

To install via composer:
composer require christopherarter/wp-middleware