Aaron Arney's RSS Feed

Critical Path Rendering

Fri, 14 Aug 2020 14:49:31 GMT

Critical Rendering Path

CRP or Critical Rendering Path is an algorithm of sorts that browsers use to display a webpage. When you use your browser to navigate to a webpage, a series of steps have to occur before you will see anything populate the screen. You can think of CRP as a linear top-down process in which the browser reads HTML one line at a time and forms the webpage as it goes.

The CRP process has several phases;

DOM (Document Object Model)
CSSOM (Cascading Style Sheet Object Model)
Render Tree
Layout

In each of these phases a different set of steps occur. Let's go over them individually.

Document Object Model (DOM)

The Document Object Model is a tree structure that represents the HTML on a webpage, by converting each HTML entity into a node object. When each HTML entity is encountered a startTag is generated. The parser then moves to the next token to see if there are any children of the entity. If there is a new node and startTag is generated, and so on and so forth until the end of the entity is found. At that point an endTag is created and that node is closed. These series of startTags and endTags form the tree that makes up the DOM.

As a simplified example, it may help to visualize it.

<div>
    <div>
        <a href="#">
            Some Link
        </a>
    </div>
</div>

Could convert to something like the following. Note that this is a JavaScript flavor and probably not the best way or most accurate way to represent this information.

startTag('div')
  .startTag('div')
    .startTag('a')
      .attribute('href', '#')
      .content('Some Link')
    .endTag('a')
  .endTag('div')
.endTag('div')

The more HTML on a page the longer this step takes. However, don't be fooled into thinking that reducing your HTML by a few or even dozens of elements will make a difference! Browsers are really fast and performance gains from such optimizations are likely to not result in anything significant.

CSS Object Model (CSSOM)

The CSS object model works similar to the DOM except this time CSS is parsed and applied to nodes. When each CSS rule is encountered, the browser performs a lookup on the DOM to make a match to an element.

Both HTML and CSS are render blocking resources. However, using through the use of media queries you can achieve non-render blocking CSS. This is because the CSS is ignored if the viewport size doesn't match the media query, essentially deferring the application of the CSS.

Render Tree

The Render Tree is the phase in which the DOM and CSSOM are combined. Each node in the DOM has it's position and size computed. This phase is when the layout is created. Therefore, any time you modify the DOM such as adding or removing nodes, this phase gets re-triggered.

Here are some common properties that trigger layout.


width	height
padding	margin
display	border-width
border	top
position	font-size
float	text-align
overflow-y	font-weight
overflow	left
font-family	line-height
vertical-align	right
clear	white-space
bottom	min-height

Painting

Finally at the end of the pipeline, the painting phase is when the render tree elements are converted into pixels on the screen.

The complete layout is generated and painted. Then for each node, lays out the elements on the page with their given dimensions and positions. Lastly it applies the remaining CSS to the element.

Just like with the layout there are CSS properties that can re-trigger paint.

The common properties that trigger a re-paint.


color	border-style
visibility	background
text-decoration	background-image
background-position	background-repeat
outline-color	outline
outline-style	border-radius
outline-width	box-shadow
background-size

As a sidenote, this is why with CSS animations it's fairly important you stick to the rules of only animating four things; position, scale, rotation and opacity. These operations allow the animation to run on the GPU instead of the browsers software rasterizer. For a more in-depth explanation of how this works, read the excellent post "High Performance Animations."

Conclusion

This is a nutshell version of the Critical Rendering Path. It is worth diving into how to optimize the CRP but I will save that for another post.

Node Concurrency

Wed, 01 Jul 2020 20:51:01 GMT

Node.js in of itself is a single-threaded application (if you want to call it that). However through the use of libuv and the underlying operating system, we can enjoy asynchronous capabilities. The question I'm going to hopefully answer, is how does this work?

Node.js Event Loop

First, we need to have an understanding of how the event loop works in Node. The event loop is essentially an infinite while loop that waits for an instruction, executes it, and returns to waiting unless there are no more tasks in which case Node will gracefully shut-down.

There are a group of queue's which are called phases in Node nomenclature, each with a specific job.

Timers - Executes callbacks scheduled by setTimeout and setInterval.
Pending Callbacks - Executes I/O callbacks that have been deferred to the next loop iteration.
Idle, Prepare - Used internally by Node.
Poll - Get new I/O events and execute I/O callbacks
Check - Executes callbacks registered with setImmediate
Close Callbacks - Close certain callbacks such as socket.on('close', ...).

I'm not going to go into detail about each of these phases in this post, but perhaps in the future I will. Until then you can read about each phase in-depth over at the Node docs.

Each phase is an array/queue with a FIFO (first in, first out) list of callbacks. When Node enters a phase it will cycle through each queue and execute each callback until either the maximum number of callbacks is reached, or the queue length is zero.

An important detail to realize is that during any of these phases, additional callbacks can be registered and in some cases those callbacks won't get executed until the next loop iteration. You can use setImmediate to register a callback that gets executed, well, immediately. However you need to know what you're doing as you can cause the application to hang indefinitely in a scenario where setImmediate gets called recursively.

Concurrency

The first thing to understand with Node.js and threads is that, as mentioned, Nod.js is single-threaded. It runs on one and only one thread for the duration of its lifetime. Write an infinite loop and you'll lock up your whole application. But concurrency or multi-threading does exist in this architecture.

As explained earlier I noted that Node.js defers I/O operations to the operating system. Take the https module for example.

const https = require('https');
https.request('https://aaronarney.dev').then((response) => {});

If you are familiar with jQuery's $.ajax function, JavaScripts xmlhttprequest or fetch then you might think you know how this snippet is executed. However recall that Node.js uses V8 as essentially a type translator not as the underlying engine itself. When Node.js uses https requests, that request is passed to libuv and then libuv defers it to the operating systems networking libraries.

Once that request hits the OS layer, Node.js knows that it will get notified when the OS returns some data so it decides to free up it's thread and work on something else until that happens, giving us asynchronicity.

When the OS returns the data, Node.js gets notified that it's ready to get back to work processing the https request and pushes that task into poll queue. When a thread becomes available to process the request the original callback assigned to https.request gets executed with the data returned from the OS.

Note that by default, libuv uses 4 threads which can be increased using the process.env.UV_THREADPOOL_SIZE.

But the question we should be asking ourselves at this point is which parts of Node.js use this thread pool? The answer isn't easy because different OS's might decide to do different things. However it is somewhat safe to assume any intense operation such as reading and writing files, working with databases or networking will utilize the thread pool.

I never know how to end blog posts so I'll just leave it at that.

Brief Overview of Node Internals

Thu, 18 Jun 2020 00:00:00 GMT

Node.js is an architecture that wraps several APIs into one consistent interface. There are several libraries which are encapsulated within Node.js and I want to provide a brief overview of what they are and how they are used.

In order to access the filesystem (I/O operations), asynchronous TCP/UDP sockets, child processes etc, Node.js utilizes the libuv library. It was originally developed to be used for Node.js but has since been adopted by several other platforms. This library is exposed through multiple modules such as the fs or path module. The libuv library is written in C/C++, this is important since it needs to be fast and cross-platform.

Complementing libuv is the V8 engine, Google's JavaScript implementation that is used in Chrome, Edge, and other browsers. V8 implements both ECMAScript and WebAssembly, but does not have a DOM as that functionality is provided by a browser. V8 is mostly written in C++ with some JavaScript mixed in at some places.

There are a few more dependencies that Node.js has such as llhttp. This library extracts http message data such as:

Headers
Content-Length
Methods
Status Codes
Request URLs
Message body

If you've ever inspected a http request in your browsers networking debug tools, you've likely encountered this kind of data. Since Node.js's bread and butter is acting as a some sort of web server, it's easy to see why this library would be so important.

Next is c-ares which is a C library that Node.js utilizes to parse DNS requests asynchronously.

OpenSSL is another dependency that is used mostly for cryptographic functions and modules in Node.js. This library is exposed primarily through the crypto module in Node.js.

Lastly is zlib a really fast compression/decompression library. If you've worked on websites before you understand the value in gzip, well that's what zlib provides. Gzip compresses data that is sent to a client so that no unnecessary bandwidth is eaten up by serving assets in their raw form. This helps both performance and speed.

C++ Bindings

Node.js exposes these underlying libraries through its own JavaScript API. When one API written in one language, ties into another API written in another language, it is often done so through what is known as a binding. If we take a look at the Node.js source code, there are two specific directories that I want to point out - src and lib.

The lib directory is where the JavaScript API is contained. This is where methods such as fs.readFileSync are contained. Bindings are bound through the process.binding() method.

The src directory is the C++ bindings that the lib modules call into. This is where most of the magic happens.

Conclusion

That is a very brief overview of the internals of Node.js but there is so much more to get into. I only wanted to talk about how the libraries work and come together to make Node function the way it does.

The JavaScript Event Loop

Thu, 11 Jun 2020 00:00:00 GMT

JavaScript is an interesting language and part of that interestingness comes from it's event driven architecture. Everytime we need some code to execute we have to hook into an event of some sort. Whether it's when the page loads, a button is clicked or a message is broadcast.

Think about how click handlers work. Typically you write something like this..

document.getElementById("button").addEventListener("click", callback);

Here "click" is an ID of an event that get's emitted by the JavaScript engine any time a button in the DOM is clicked or tapped. Using the addEventListner let's us hook into that event so we can do something interesting. This is event driven JavaScript.

The Event Loop

JavaScript utilizes what is known as The Event Loop™. If you have ever written a video game or used the Observer/Pub-sub design patter it is likely you already are familiar with the event loop concept.

while (queue.waitForMessage()) {
    queue.processNextMessage();
}

You might think that when we add an event listener, like the "click" one above, that it get's pushed into this queue. This is in a way true, but not really.

When a button is found in the DOM, all click events are handled by the browser automatically. It knows what all events an element supports and dispatches messages when those events are triggered.

I'm getting a little sidetracked here, but this is what a basic observer would look like in JavaScript.

const Observer = {

    /**
     * A list of registered observers. The intent is to store essentially key->value pairs
     * so that events like "click", "change", "submit" etc are stored as keys with an 
     * array of callbacks as their values.
     */
    observers: new Map(),

    /**
     * Register a callback with a given event. If an event already has been initialized
     * with an array we use the spread operator to merge the existing array with the 
     * new observer.
     */
    addEventListener: function (eventID, callback) {
        const queue = [callback];

        if (this.observers.get(eventID).isArray) {
            queue.push(...this.observers.get(eventID));
        }

        this.observers.set(eventID, queue);
    },

    /**
     * Dispatch a message to all registered observers for a given event name.
     */
    notifyListeners: function (eventID, event) {
        this.observers.get(eventID).forEach((observer) => {
            observer(event);
        });
    }
};

Now imagine that this is the implementation the browser uses (narrator: it isn't). When click events occur, the browser would then execute the notifyListeners passing click as the eventID and an object containing all of the event data we've come to expect as the event argument.

With an understanding of events/messages, there are three new terms we need to understand here.

The Stack
The Queue
The Heap

The Stack

The stack is a list of function calls that create a stack of frames. The frames are generated when the engine encounters a new function call. That frame contains all of the variables and arguments of the function. Frames are generated until there are no more function calls being made. Then as each frame returns some value either implecitely or explicitely, frames are popped off the stack until there are no more frames.

The absolute easiest way to understand the stack is realizing this is the exact same stack you see when debugging or encountering errors in the console. The stack trace is a human readable form of this stack.

The Queue

A queue a linear wait-list. Harking back to our event listeners, when a button is clicked a new item is pushed into this queue to process that button click. Then if event listeners are found to be observing this click, additional messages are pushed into this queue. The queue works by processing messages in a FIFO (first in first out) manner.

The Heap

The heap is just a section in memory where the engine has reserved for use. When items in the stack have variables for instance, those values are stored in the heap.

   STACK                                 HEAP
-----------
-  Frame  -
-----------                 [] Object
-----------        [] Object
-  Frame  -
-----------
-----------                         [] Object
-  Frame  -
-----------
-----------------------------------------------------
- Message -- Message -- Message -- Message --       - QUEUE
-----------------------------------------------------

This is how JavaScript does what it does. Wait, process, execute rinse and repeat over and over until the end of time.

Named Routes in Flutter

Sat, 21 Dec 2019 00:00:00 GMT

Flutter provides built-in functionality for routing in apps. You can use either pass the MaterialApp a Widget, or a named route.

There are two ways of going about named routes, you can either:

Use URL style routes /main or /login etc.
Use an arbitrary string loginscreen, mainscreen etc.

When using URL style identifiers, you must provide a default route of / or the app will crash. Personally, I don’t like this style at the moment, but in the future when Flutter web support is stable this may make more sense to me.

The issue with using strings as ID’s is that static code analysis won’t catch typos. Meaning if you have a loginscreen route but then attempt to use that route later in your app, but accidentally type lognscreen, the IDE won’t catch that.

Instead, in each of your screen widgets, I think it’s a good idea to add a static id to the class, so that you can reference it wherever you need without having to worry about getting the string correct every time.

class LoginScreen extends StatefulWidget {
  static const String id = 'login_screen';

  @override
  _LoginScreenState createState() => _LoginScreenState();
}

When you create your named routes Map, pass the id’s as the key.

routes: {
  LoginScreen.id: (context) => LoginScreen(),
},

Then whenever you want to navigate to that screen, you simply access that static id.

Navigator.pushNamed(context, LoginScreen.id);

That’s it.

WordPress Transients

Fri, 29 Nov 2019 00:00:00 GMT

WordPress has several great API’s for caching and retrieving data, transients being one of them.

Transients are best used in situations that you need to persist data through several request-response transactions. They can have either a set expiration time or default to “indefinite.”

If you’ve used a custom WP_Query at any point in your theme or plugin, you might already have a great use-case for implementing the transient API.

The best part of transients is just how ridiculously simple they are to use. There are only two functions you need, gettransient and settransient.

set_transient( 'name_of_key', array( 'some' => 'values' ), 60 * MINUTE_IN_SECONDS );

This code snippet stores an array of data with an expiration time of 60 minutes. Note that this is not guaranteed by WordPress to remain viable for 60 minutes. The expiration time is simply the maximum time that the transient should potentially be present. Because of this you should always ensure that there is a fallback routine to refresh the data set should the cache not be there!

if ( ! get_transient( 'key' ) ) {
	$data = new WP_Query( array( 'post_type' => 'cpt' ) );
	set_transient( 'key', $data, 60 * MINUTE_IN_SECONDS );
}

Something else you will need to consider is cache priming. Let’s say you have a transient that is storing an array of possible values for a custom select dropdown element on a page. This data is being populated through all the titles in a custom post type you’ve created.

Now, imagine that a visitor hits your site and triggers a new transient cache. This transient is set to expire in 60 minutes, but only a few minutes later one of your editors adds a new post. This new post will not be present in the transient for possibly an hour!

The way to account for this is to prime your cache by adding an action that triggers when your custom post types are modified. This way you can clear any transients and ensure that your data is as fresh as possible.

function prime_my_cache() : void {
	delete_transient( 'key' );

	$data = new WP_Query( array( 'post_type' => 'cpt' ) );

	set_transient( 'key', $data, 60 * MINUTE_IN_SECONDS );
}
add_action( 'edit_post_custom_post_type', 'prime_my_cache' );

Very cool and very easy.

Resources

WordPress Transients API

Azure Devops Pipeline Build with Shopify

Thu, 11 Apr 2019 00:00:00 GMT

At Leap, we utilize Microsoft's Team Foundation for all of our version control efforts. Included in this platform is Azure DevOps, a service that allows users to set up continuous improvement, continuous delivery, and continuous deployment, for repositories.

A client of ours, Kern's Kitchen, is a Shopify hosted website that requires deployments from the command line in order to update theme code. I decided to set up an Azure Pipeline to automate this deployment, but ran into an issue. Shopify developed a node package called Slate that allows a dev to generate, develop, and deploy themes. This package also includes a very annoying "feature" that stopped my automated deployments dead in their tracks.

The Issue

Before I jump into the issue, I want to provide my pipeline and give a bit of context. I'm not going to go over on how to build a pipeline out in Azure, but it's worth noting the tasks I needed to be accomplished for deployments.

Install Node v9.10.1
Run npm install
Run npm run-script gulp
Run npm run-script deploy

In my package.json, my scripts look something like the following.

{
    "scripts": {
        "gulp": "gulp build",
        "deploy": "slate-tools build && slate-tools deploy --skipPrompts"
    }
}

All of my tasks would execute right up until it hit step number 4, my deploy command. The "error" I received from Azure was as helpful as...well...something. Disclaimer, this isn't verbatim as I'm writing this from memory at the moment.

Error: Exited with error code 130

When I inspected the logs, there was no error to be found, just that the script halted execution as soon as slate-tools initialized. At this point I started brainstorming and attempting different fixes, among them...

Changed the Agent Pool to a mac, then ubuntu, and VS2017...thinking maybe the script was choking when it hit the && operator in my script for some reason.
Changed the node version.
Wrote a bash script that executed all the commands instead of using individual tasks.
Upgraded slate-tools to the latest beta version.
Many others..

Then it hit me like a ton of bricks. The reason I couldn't reproduce this error locally, was that I have used slate-tools a ton. When you first build a theme with the slate-tools, Shopify asks if they can collect data from you using a prompt. Once you answer that question, a .slaterc file generates and stored on the root of your OS. Since this file was present, I was never asked again - even though I cleared all global packages from my system, did yarn cache clean, among other things.

Now it all made sense. Since a new container's spun up to run my scripts, it will never save a .slaterc file locally. Thus, the question will always be asked "can we fucking collect analytics from you," with the task runner never being able to answer. Instead, it aborts the script and fails, even with the --skipPrompts flag!

Solution

The solution was simple. Create a .slaterc file in the root of any Shopify project, copy the contents of the one on my local machine, and commit that to the repo. I also had to set a configuration value in the slate.config.js file that tells Slate to look for this rc file in the root of my project, as opposed to OS.

What happens? Spoiler alert, it fucking deploys with no problems.

In Conclusion

Maybe there is a super easy way to combat these types of issues in packages during CI/CD builds. I'm fairly new to using these automated systems, but after searching around I couldn't find a simple answer.

I think the take away here is that, in my humble opinion, you should not create these kinds of prompts without a more clear way of circumventing them. As of this writing, Shopify decided the Slate tool was not worth maintaining or improving, so it might die soon anyway, who knows.

Fathom Analytics

Mon, 04 Feb 2019 00:00:00 GMT

The following is not entirely a step-by-step tutorial on how to get up and running with Fathom. Instead, this is an overview of my setup and how I went about getting a Fathom server up and capturing data.

Fathom

Fathom is an privacy focused data collection system that replaces the need for using intrusive and overreaching platforms like Google or Adobe analytics. Of course companies or individuals that require a great deal of data filtering, conversions, filters, etc, will probably not be able to replace their platforms of choice with Fathom. The greatest "weakness" of Fathom is also its greatest strength, simplicity. Instead of tracking tons of data that you really will never use, much less how to use, Fathom just gives you the data you're really looking for - visitors and top pages.

It took me a few hours to get the Fathom server up and running using an Amazon Web Services EC2 instance. This is mostly due to my inexperience with managing servers on AWS and less to do with Fathom as an application. I first attempted to run the Fathom docker image using Amazon's ECS platform, but those efforts proved futile. In the end I decided to say fuck it and just boot up an Ubuntu image and install Fathom manually.

This is how I went about it.

Launching EC2 Instance

Create an EC2 instance, with Ubuntu
Create an Elastic IP and associate it with the EC2 instance
SSH into the instance
Run the following commands

# Download the release
curl -o fathom.tar.gz -L https://github.com/usefathom/fathom/releases/download/v1.2.1/fathom_1.2.1_linux_amd64.tar.gz

# Extract it
sudo tar -C /usr/local/bin -xzf fathom.tar.gz

# Change the permissions
sudo chmod +x /usr/local/bin/fathom

# Check that it installed correctly
fathom --version

Configuring Fathom

Create an .env file with the following

FATHOM_SERVER_ADDR=8080
FATHOM_GZIP=true
FATHOM_DEBUG=true
FATHOM_DATABASE_DRIVER="sqlite3"
FATHOM_DATABASE_NAME="fathom.db"
FATHOM_SECRET="random-secret-string-change-this"

Create a service file

sudo touch /etc/systemd/system/fathom.service

Add the following to the file

[Unit]
Description=Starts the fathom server
Requires=network.target
After=network.target

[Service]
Type=simple
User=ubuntu
Restart=always
RestartSec=3
WorkingDirectory=/home/ubuntu
ExecStart=/usr/local/bin/fathom server

[Install]
WantedBy=multi-user.target

Reload the daemon, enable fathom, and start it.

sudo systemctl daemon-reload
sudo systemctl enable fathom
sudo systemctl start fathom

Configuring a Custom Domain

Create a new Hosted Zone in AWS Route 53
Supply your domain name and leave the type as Public Hosted Zone
Once created, make two new Record Set by clicking on the Create Record Set button
Add A type with a blank Name. Paste the address of your Elastic IP as the value
Add A type with a name of www. Paste the Public DNS of the EC2 as the value
SSH back into the EC2 instance
Enable mod_proxy via the commands

sudo a2enmod proxy
sudo a2enmod proxy_balancer
sudo a2enmod proxy_http

Edit the Apache2.conf

sudo vim /etc/apache2/apache2.conf

# Add the following to the file
ProxyPass "/" "http://keytar.co:8080/"
ProxyPassReverse "/" "http://keytar.co:8080/"

Restart Apache sudo systemctl restart apache2

Now the requests to http://keytar.co should route to http://keytar.co:8080 behind the scenes. That way users don't have to know to use the :8080 port and makes passing the URL as a configuration much easier.

Content Security Policy

Fathom uses embedded data in images as a way of capturing data instead of ajax. Because of this, my content security policy was preventing the images from being created, as it sets the source of the image to be my tracking url for Fathom, in my case https://keytar.co (a domain I had sitting around doing nothing).

Modifying the CSP header in my gatsby-config.js was easy enough. I just had to pass https://keytar.co as an additional value.

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' https://keytar.co; connect-src 'self'; img-src https://*.ocular-rhythm.io https://keytar.co data:; style-src 'self' 'unsafe-inline';

The last step is to throw the tracking code Fathom gives you when you create a new site.

Bye.

Importance of Perception

Fri, 01 Feb 2019 00:00:00 GMT

During my most recent performance review at work, my boss and I began discussing communication. For almost my entire life, I have had an weakness when it comes to communicating with my co-workers. I can articulate my thoughts well, and enjoy documenting code and processes, but there is a recurring perception that I "don't care" about my job - but this couldn't be farther from the truth.

It was brought up that I have excellent work ethic and my boss believes I am one of the hardest workers at my company. Yet, due to several reasons such as my sarcastic nature, the fact I don't often smile, and have a very even and flat emotional level, it's perceived to others that I lack drive and ambition. This is nothing new to me, I've had this recurring problem everywhere I've gone, including the Army.

In a strange twist of fate, I so happened to be reading a book entitled "Release It!: Design and Deploy Production-Ready Software" a few days ago. In it the author was describing a situation in which the airline company he worked for had a major outage. Part of the post-mortem, the author flew to another location to talk to the team them and assess what he could salvage from the server information. The reason for this was not for solving the problem itself, but also for managing the perception that his team was looking for answers. His direct quote:

"...managing perception after a major incident can be as important as managing the incident itself." - Michael T. Nygard

I'm taking the quote a bit out of context here, but the lesson is roughly the same. Even though I do care about my job a great deal and do a lot behind the scenes, people don't see that. They only know what I "give" them in the form of enthusiasm, reaction, micro-interactions, etc..in other words - the perception.

My Plan

The goal is to manage this perception using a combination of factors.

Maintain eye contact with the person I am talking to.
Don't isolate myself and be more social at work through small talk.
Reduce the sarcasm when appropriate. If others are concerned or stressed out, don't try to cut the tension with a joke. Things are serious to my co-workers, so I need to act like they are serious even if I find them insignificant.
Reduce or cut passive aggressiveness. We all suffer from this affliction.
Be an advocate for my accomplishments. If I do something cool, share it with people. Don't assume anyone cares.

That at least starts me out with giving me a good leg up on trying to improve my soft skills. It will be difficult for me to quantity or measure the results of my efforts, I will be able to tell a difference based on the attitudes afforded to me.

Writing the Ferret Plugin

Fri, 11 Jan 2019 00:00:00 GMT

Recently I decided to begin leveraging the Sentry service for some of the WordPress sites I manage. I wanted to use this on several sites, and I noticed that Sentry has a PHP library but not an officially supported plugin for WordPress.

There was one other plugin in the directory, but it essentially only acted as an entry point in which to interface with Sentrys SDK. I was looking for a solution where I could upload the plugin, set my API key (or DSN in Sentry nomenclature) and just catch any and all errors with no configuration. I decided to just quickly write my own plugin.

The Boilerplate

Usually, when I write a new plugin, I tend to head straight for the WordPress plugin boilerplate generator to quickly create the plugin files.

I made a snap decision to just name the plugin Ferret because:

a) I love ferrets (used to own two!)
b) Due to trademarks, I can't really use my original idea of WordPress Sentry since both of those (I believe) are trademarked

The SDK

The next step was to take a look at the integration documentation on Sentry's website. Luckily enough, they have a library for just about every language and framework you could realistically want in 2019. The PHP library is part of composer, so including that in the project was very simple.

composer require "sentry/sentry"

Next, I had to ensure the composer autoloader.php is called in my plugin. This would work perfect in the plugins entry point file - ferret/ferret.php.

...
require_once __DIR__ . '/vendor/autoload.php';
...

Now was the time to initialize the Sentry client, which happens to be a class named Raven_Client. I put this logic in the base plugin class located in the includes directory - ferret/includes/class-ferret.php.

To follow the practice of single responsibility and to keep my functions small, I created a new function to initialize Sentry. Note that to keep my DSN and Project ID secret, I'm just using dummy text in their place.

public function init_sentry() {
    $client = new Raven_Client( 'https://abc123@sentry.io/123' );
    $error_handler = new Raven_ErrorHandler( $client );
    $error_handler->registerExceptionHandler();
    $error_handler->registerErrorHandler();
    $error_handler->registerShutdownFunction();
}

The $error_handler here hooks into all errors that occur in PHP. This is desirable because I am wanting to just "set and forget" the client.

The last thing to do was call this function. The best place is to just call it during the construction of the class, so I added it to the __constructor.

...
$this->init_sentry();
...

Plugin Options

Writing code to handle options has gotten better than it used to be (I think), but it's still a somewhat confusing process. The way I've been accomplishing it lately is by creating a helper class to encapsulate my getters and setters for the native WordPress get_option function. Then passing an instance of that class to constructors of other classes, so they have a single access point for everything. This has reduced the need to arbitrarily pass around key strings and reduces the cognitive load.

Since quite a bit is going on to create these options, I don't want to write everything I did in this post, but it was essentially what I just outlined above. If you want to take a look and dissect my approach, you may find the following files of interest...

Submission to Directory

I had never submitted a plugin to the WordPress plugin directory before, so this was all new to me. Luckily, WordPress has some fairly thorough resources for the process and what I should be cognizant of when submitting a new plugin.

Since this was a very simple plugin, there wasn't too much to be worried about. There were only a few things I had to go "out of my way" to prepare for submission...

Localization - I had never generated this before but it was simple. I used the recommended app Poedit to generate my english .pot file. For the uninitiated, you need to wrap all of your plain text that is visible to users with the native WordPress __() or _e() functions. This lets WordPress know that the strings are translatable.
README.txt - The readme is very important. This is where all of the critical information is placed, such as compatible versions, author data, descriptions, etc.
SVN - Once the plugin is approved, you are required to commit your code into an svn repository. This is a bummer but not the end of the world. SVN is truly awful in my opinion, but most of that opinion stems from lack of extensive use and understanding. The "svn way" is quite different than the "git way". When all was said and done, I think I had to publish around 7 versions just to rename a file.

Success!

My plugin was approved in just a day, which is surprising as they claim it can take up to two weeks for that to happen.

Next, I hope to extend the plugin to allow a user to easily set up custom filters and events much like how Unity works when setting up event handlers in the UI.

Thanks for reading!

Resources

Initial Thoughts on Flutter

Wed, 19 Dec 2018 00:00:00 GMT

While building an app in React Native, I accidentally stumbled on Flutter. I had heard of, but never used the Dart language and was surprised to learn that Flutter existed as a React Native alternative. Glancing the docs got me excited to try it out, so I wrapped up as much as I could to make my other app "complete" and immediately moved into rebuilding it in Flutter.

I decided to run through a Udemy course (which I highly recommend) called "The Complete Flutter App Development Course" before I started hacking together an app on my own, just to make sure I was building it the "Flutter" way. After getting far enough through that course I started porting over the app. I'm around 35% of the way through and decided to put together a sort of pros and cons list of my findings so far.

Pros:

Simple to start a new app.
Very simple to debug with additional tools built into Android Studio (inspectors, performance, etc).
Dart is basically TypeScript, so the adoption and learning process is smooth if you have experience with it.
Testing framework is built-in an easy to get started. No installing additional dependencies and configurations.
Laying out and styling the UI is substantially easier. Once you understand how to compose your Widgets, that is.
The API documentation for both Dart and Flutter is fantastic.
Google introduces a new architecture design pattern called BLoC which seems well suited to Flutter and apps in general.

Cons:

Not a lot of worldwide adoption so the ecosystem is much smaller than React Native.
While the API docs are great, I found there to be lacking real-world examples here and there.
The Dart linter takes direction from a remote server so can be difficult to configure. There was limited documentation on how to customize these lint rules. Other times I encountered errors which said one thing but meant another. Overall this was a very limited and tame issue.
Could be a harder "sell" to development teams since it not only requires learning a new framework, but a new language as well. If teams are already using React Native and other JavaScript frameworks, I could see this being an uphill battle.

As a fan of React, it almost disappoints me to say that I found Flutter to be a much better tech stack to build apps with. The amount of configuring and third-party libraries and tools you need to get started in React Native and debugging, is just maddening. I absolutely love just having everything work and tie-in out of the box. Debugging apps on a mac with React Native Debugger sucks!

Testing WordPress Plugins with PHPUnit and WP Mock

Thu, 06 Dec 2018 00:00:00 GMT

Part 1: Up & Running

Assumptions This article assumes a basic understanding of WordPress Plugins and the PHP language. I'll also be using the OSX/Linux flavor in terminal examples. If you are on Windows, you will need to use your own respective commands.

Testing code is important. It's the only way to know for certain that something you've changed in your code behaves exactly as how you intended. Without automated testing there is a need to constantly run your code and check for every condition manually after every single change you make. This is far from ideal and a huge waste of your time. Granted tests do not make your code bug free, but it certainly is a start to a healthy and maintainable codebase.

As you begin writing tests you may find that your idea of "simple" and "elegant" code, may be turned upside down. For example, I discovered that even having several if statements in one function can be somewhat difficult to test every condition for which means that my function was too complicated. This is what testing code gifts us.

The downside of tests are that they can be quite difficult to get started with and slow your development time substantially. That's not even factoring in the added complexity of integrating unit tests with WordPress, but that's something I hope to help remedy by the time you finish this article.

For those who are new to testing, there are quite a few different types of tests you can write. For the sake of brevity, we're only going to cover two:

Unit Tests
Integration Tests

Unit Tests

Unit tests are ones that only test a single part, or unit, of your code. Consider the following class...

class Math {

    public function add( int a, int b ) : int {
        return a + b;
    }

    public function divide( int a, int b ) : int {
        return a / b;
    }

    public function multiply( int a, int b ) : int {
        return a * b;
    }
}

With unit tests, we would write separate tests for each individual method, add, divide, and multiply.

Integration Tests

On the other hand, integration tests are those that test an entire system or object. For example, if we had written a class that uses dependency injection to load another class in its constructor; with integration tests we would test that the classes work together appropriately.

class FirstClass {

    protected $secondClass;

    public function __constructor( SecondClass $instance ) {
        $this->secondClass = $instance;
    }
}

You may be wondering why we wouldn't just test the constructor with a unit test in the following way:

$actual = new FirstClass( new SecondClass() );

The reason is that when we write our unit test for the constructor, we'll be passing what is known as a stub instead of an actual SecondClass object. We'll get into that later on, but for now just know that unit tests should always be done in isolation, meaning to have no external dependencies or reliance on code outside of its own body.

Get Dependencies

In order to even use WP Mock, you will need to have PHP v^7.0 installed in your environment. You'll also need the plugin you are going to test installed into WordPress.

Lastly, you'll need composer installed. If you don't know what composer is or how to use it, take a pause here and go read through the getting started guide on composers website.

Installing

Start by installing PHPUnit and WP Mock into your plugin. Open up a terminal and navigate to your plugins root directory and run the following.

composer require --dev 10up/wp_mock:0.3.0

As a side note, an issue I've run into is that I have to use a downgraded version of PHPUnit in order for the tests to pass. At the time of this writing, there is a solution that can be found here.

To mitigate, require PHPUnit version 6.5.8:

composer require --dev phpunit/phpunit:6.5.8

Configuration

Next, a configuration file can optionally be created, though I highly recommend doing so. This configuration file accomplishes things such as telling PHPUnit where to look for tests, what directories to exclude, and if code coverage reports should be created.

This file should be named phpunit.xml.dist and placed in your project root. To start, I'll specify..

Test directory as ./tests/
Test file names all start with test-
File extensions with .php

<?xml version="1.0"?>
<phpunit>
    <testsuites>
        <testsuite>
            <directory prefix="test-" suffix=".php">./tests/</directory>
        </testsuite>
    </testsuites>
</phpunit>

I like to see my code coverage so I have a clear picture of exactly what code is getting hit throughout my tests, so I'll set that up as well. Code coverage reports are great visual helpers that allow you to quickly see and understand what classes and methods are lacking tests.

This section gets added just beneath the </testsuites> closing element.

<logging>
    <log type="coverage-html"
         target="tests/coverage"
         showUncoveredFiles="true"
         charset="UTF-8"
         highlight="true"
         lowUpperBound="35"
         highLowerBound="70" />
</logging>

I'm telling PHPUnit that I want:

The report to be output as HTML
To output the report files into the tests/coverage directory
To display files in the report that do not have associated tests (so we know where we should create tests)
Highlight the coverage in either red (for uncovered) or green (for covered)
Low upper bound is a percentage. This indicates of how uncovered a file can be before it is considered to be ”lowly" covered.
The high upper bound is just the opposite. How covered a file is before its considered "highly" covered.

Lastly, we need to add a section that specifies directories to exclude from being parsed. This is required for the code coverage to function. It wouldn't make sense to allow PHPUnit to crawl all files in the vendor directory since that isn't our code, and therefore shouldn't be our responsibility to unit test.

Add this section directly under the </logging> section, replacing the ./your-source-files with the directory your plugin code is contained in.

<filter>
    <whitelist processUncoveredFilesFromWhitelist="true">
        <directory suffix=".php">./your-source-files</directory>
        <exclude>
            <directory suffix=".php">/tests/</directory>
            <directory suffix=".php">/vendor/</directory>
        </exclude>
    </whitelist>
</filter>

The Bootstrap File

Next we need to write the bootstrap.php file which acts as the entry point into the tests. First create the file inside of your tests directory...

touch tests/bootstrap.php

In order for PHPUnit to use this file, it will need to be defined in your phpunit.dist.xml file...

<?xml version="1.0"?>
<phpunit bootstrap="tests/bootstrap.php">
    ...
</phpunit>

The contents of this file will be fairly simple. We will need to define just a few things:

Require the composer autoloader file so your dependencies can be loaded
Your plugin entry file
Any other dependencies you create (such as factories)
Invoking the 1WP_Mock::bootstrap() static method

Your file may end up looking something like this (replace plugin-name with your plugin entry file).

require_once dirname( dirname( __FILE__ ) ) . '/vendor/autoload.php';
require_once dirname( dirname( __FILE__ ) ) . '/plugin-name.php';
WP_Mock::bootstrap();

Save that file, and let's move on.

Writing a Test

Now is the time to write a simple passing test so you can ensure everything is wired up correctly.

In your tests directory, create a directory called unit. Create a test file inside of that directory called test-example.php.

cd tests && mkdir unit
touch unit/test-example.php

Begin by defining your class and extending the WP_Mock test case class. In order for WPMock to work, you will have to implement the setUp and tearDown methods in every class that you use WPMock on. These methods let you define logic that should be executed as the test is about to run, and then directly after. You would put things such as instantiating stubs or mock objects.

<?php

class TestExample extends WP_Mock\Tools\TestCase {

   public function setUp() {
        WP_Mock::setUp();
   }

   public function tearDown() {
        WP_Mock::tearDown();
   }
}

Next, add a method that just has a single assertion. Just to make things easy, let's assert that true === true since we know it will evaluate to, well, true...

public function test_arbitrary_value() {
    $this->assertTrue( true );
}

Open up your terminal and run the tests...

./vendor/bin/phpunit

If all is well, you should see something to the following output...

Time: 1 seconds, Memory: 1.00MB

OK (1 tests, 1 assertions)

If for some reason you have any errors or failures use the output and error messages to debug and problem solve.

Hopefully that gives you a taste of how to set up tests with your WordPress plugin, but there's still plenty more to cover and learn. Stay tuned for part 2.

Making the Switch to TypeScript

Mon, 05 Nov 2018 00:00:00 GMT

If you've been living under a rock, you might have not yet heard about Microsoft's TypeScript - "a typed superset of JavaScript that compiles to JavaScript." A typed superset in this context just means it combines plain old JavaScript syntax with a few new extras.

It can often be overwhelming learning a new set of syntax and if you are new to JavaScript it may feel even more so. Luckily, learning TypeScript doesn't mean adopting it in its entirety. You can use as much or as little as you like, which makes getting started relatively painless.

What is TypeScript For?

To answer this question, it is first helpful to understand how JavaScript works. Since JavaScript is a loosely typed language, that means that we don't have to explicitly declare our types, instead the JavaScript JIT (just in type) compiler that is built into our web browsers, simply infer the type at run time.

That makes situations like this possible:

let a = "string";
a = 1;
a = false;

In strictly typed languages such as C# or C++, the above example would throw errors for several reasons.

This is what TypeScript helps to mimic and achieve, a way to declare and enforce types in your JavaScript files. This helps to reduce bugs and increase collaboration. Not to mention it can reduce the sizes of your functions since you no longer must dedicate the first few lines performing the manual interrogation of your function arguments.

Getting Started

The first thing you need to do is install TypeScript. You can do these one of two ways:

NPM - npm install -g typescript
Yarn - yarn add global typescript

To ensure its installed correctly, run this command in your terminal/console to print the package version:

tsc - v;

Your output should be something along the lines of Version 2.7.1. If you see something similar command not found: tsc, then it means TypeScript wasn't installed. Try installing it again and then restarting your terminal/console.

Now, create an empty file with the extension .ts - that stands for TypeScript. Inside we'll just create a simple function that represents a Vector2 to ensure our compiler works.

function Vector2(x, y) {
    return { x, y };
}

Go back to your command line and run tsc name-of-file.ts and wait. If all goes well you will see no errors on the command line, but a new file will have been created with the same name as your TypeScript file - except with a .js extension. This is the compiled file TypeScript generated with your code. If you look, you'll notice it's the same, because we haven't written any TypeScript yet.

Writing Type Annotations

The next step is to use TypeScript. We're going to dive into type annotations, which essentially tell the TypeScript compiler what kind of variable a function should accept.

In example, it should be easy enough to reason about that the function expects a number value for both x and y. However, since mistakes happen and to err is to human, we want to make sure that the compiler will throw a temper tantrum if either of the arguments are not numbers. This is where the type annotation comes into play.

To write a type annotation, you simply follow the variable with : followed by the type. In our example, the outcome would be:

function Vector2(x: number, y: number) {
    return { x, y };
}

// Let's invoke the function with numbers
Vector2(12, 49);

Now, compile the file and you should see no errors. Open your file back up and change one of your numbers to a string.

Vector2("fail", 22);

If you run the compiler now, TypeScript is going to give you an error:

thing.ts(5,9): error TS2345: Argument of type '"fail"' is not assignable to parameter of type 'number'.

That's the beauty of TypeScript. Now you can always ensure that your functions are being called with the correct type. The best part of it is though is that this error is caught at compile time, not run time. Meaning it's not going to pop up as a surprise to you or your users.

Return Type

Not only can we set the type of arguments, we can also set the type that gets returned from the function. This is wonderful because anyone interacting with our code, knows without certainty that a function will always return something we expect, without side effects. Writing the return type is the same as before, except the “:” comes after the closing function parenthesis.

function Vector2(x: number, y: number): object {
    return { x, y };
}

Now, how can we test this with the tsc compiler? Let's create a variable to store the result of the function.

let result: number = Vector2(2, 40);

Run the compiler and wait for the error. You should have gotten this message (or something like it):

thing.ts(4,5): error TS2322: Type 'object' is not assignable to type 'number'.

Since you're smart you've already guessed that we need to change the variables type from number to object. Go ahead and do so, then recompile.

I am confident that this time, you ran into no issues.

Conclusion

There is a lot more to TypeScript than just type annotations, but this was meant to be a "toe dipper" into the library and not an extensive deep dive. Hopefully you have found that TypeScript is not as overwhelming and scary as you may have perceived it to be.

TypeScript can be a very helpful development tool that can reduce the number of bugs in your code. It is not a magic wand however, and care should always be taken to write clean and maintainable code above all else.

Managing Levels in Phaser 2

Mon, 10 Sep 2018 00:00:00 GMT

When I first began to use Phaser 2, I had trouble wrapping my head around the way that "levels", stages", or "scenes" (like in Unity) were created and accessed. I was looking in the documentation for some kind of Level Manager or methods that would allow me to load said scenes but came up short.

The reason I was getting tripped up, is due to the official tutorials way of creating the Phaser.Game object.

When the game configuration object is created, another object is passed into it containing three methods, the preload, create, and update methods. These are essentially Phasers "life cycle" methods that tell the engine what should happen during each of these phases.

In order to use more than one scene, just simply omit this object and instead add your scenes using the game state add method.

For example, if we want to have a start screen state, main game state, and end scene state, we would add these three states like so:

// Some comment
const game = new Phaser.Game(config);
game.state.add("gameState", gameState);
game.state.add("endState", endState);
game.state.add("titleState", titleState);

Each state will have its own respective preload, create, and update methods that will get executed automatically. Note that the order in which these states are added does seem to matter. In order for you to change from the start state to the game state for example, you will need to add the game state first or else Phaser won't know that it exists.

To specify which state will start when the game is loaded, simply call the state.start method, passing the state you want to load as the only argument.

game.state.start("titleState");

Lastly, when you want to load a new state you simply call the same method. For example if I want the game state to load after the user presses the spacebar key on the title screen, I would add this logic into the titleScene update method.

function update() {
    const { game } = this;

    if (game.input.keyboard.isDown(Phaser.keyCode.SPACEBAR)) {
        game.state.start("gameState");
    }
}

There you have it, a simple explanation of how Phaser 2 handles game states.