WP Dev Life

A Journey through WordPress

Getting Started with Unit Tests

by

What is Unit Testing?

Unit Testing is the process of writing code to ensure that other code functions with its expected behavior.

Why should I write tests?

Writing tests for your code can help drive the development of your code. This is referred to as Test Driven Development (TDD). Recently I was working on a method that sanitizes the input of a form field, and I needed this function to perform different conditionals and formatting. Instead of dumping a variable out and refreshing the page, to see the output, I was able to write test cases with what I expect the output to be, and the actual output that was returned. This allowed me to speed up the development process, and easily iterate through each condition I needed to sanitize against, and it ensured that the code returned what we wanted it to return.

Let’s Get Started

I utilize a custom Docker environment for my local development that has a separate container for PHP, MySQL, NGINX, and I’ve got a few others in there to help mimic my production environment but those aren’t really needed. I’m able to open up an SSH connection into the containers that have my site mounted, and I have access to WP-CLI. The only real requirement here is that you’ve got WP-CLI, but this walk through assumes you’re using something similar, you’ve got access to /tmp, and WP-CLI. Additionally you will need Composer, a PHP package manager, installed as that is how we’ll be requiring our vendor dependencies like PHPUnit.

If you’ve already got a plugin or theme setup but no tests, WP-CLI has the scaffold command which has a few options to scaffold just tests for a plugin or theme. 

$ wp scaffold theme-tests <plugin-name>
OR
$ wp scaffold plugin-tests <theme-name>

The two above WP-CLI commands will scaffold all of the necessary files to begin writing tests, as well as providing a test-sample.php file.

This creates a phpunit.xml.dist file as well as the tests folder which contains the test-sample.php file.

WordPress REST API

by

What’s an API?

An API is an interface that allows applications to use, create or modify data from another application.

What’s the WordPress REST API?

The WordPress REST API takes information from the database and serves it in JSON format. This includes, posts, media, pages, and users and others. We’ll cover the Core endpoints further down.

The REST API can have two different structures depending on how permalinks are setup. On sites without pretty permalinks, the route is instead added to the URL as the rest_route parameter. For a site using the default permalink structure the REST API full URL would then be http://example.com/?rest_route=/wp/v2/posts/123

Plugins can extend this feature to generate their build their own API for use. A good example of this is the Woocommerce API, which we touch on below.

What is a route?

A route, in the context of the WordPress REST API, is a URI which can be mapped to different HTTP methods. The mapping of an individual HTTP method to a route is known as an “endpoint”. 

ResourceRoute
Posts/wp/v2/posts
Revisions/wp/v2/revisions
Categories/wp/v2/categories
Tags
/wp/v2/tags
Pages/wp/v2/pages
Comments/wp/v2/comments
Taxonomies/wp/v2/taxonomies
Media/wp/v2/media
Users/wp/v2/users
Post Types/wp/v2/types
Post Statuses/wp/v2/statuses
Settings/wp/v2/settings

HTTP Request Methods

Every time we go to a website, we’re making multiple HTTP requests. One to the server and then that sends a response which tells us we need to make more requests to get assets so that the browser renders the page properly. That is an example of a GET request. Whenever a slider changes, and triggers a request to admin-ajax.php, those are POST requests. Below is a table of different request methods availbab

GET Read data from an endpoint
POST Send data to an endpoint to create new data
PUTUsed for updating already existing data
DELETEDelete data from an endpoint
OPTIONS Used to determine which methods an endpoint accepts

Caching

GET requests will be cached per normal varnish rules.

POST requests will always be uncached.

Custom Routes

It is possible for plugins and themes to extend the WordPress REST API with their own routes. Woocommerce uses /wp-json/wc/v3 as their endpoint. They then have routes for products, orders, customers, coupons and more. Most of these requests will require authentication with a Woocommerce API key which can be generated in their Woocommerce settings page in their dashboard.

Responses

The WordPress REST API returns data in JSON format. This can then be consumed by other applications to process the data. When you load the REST API in your browser it will look similar to this:

[{"id":95,"date":"2019-05-31T15:40:16","date_gmt":"2019-05-31T15:40:16","guid":{"rendered":"http:\/\/wpdev.life\/?p=95"},"modified":"2019-05-31T15:40:16","modified_gmt":"2019-05-31T15:40:16","slug":"53w5","status":"publish","type":"post","link":"https:\/\/wpdev.life\/53w5\/","title":{"rendered":"53w5"},"content":{"rendered":"\n<p>weqtwetq<\/p>\n","protected":false},"excerpt":{"rendered":"<p>weqtwetq<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[1],"tags":[],"wpe_featured":["yes"],"_links":{"self":[{"href":"https:\/\/wpdev.life\/wp-json\/wp\/v2\/posts\/95"}],"collection":[{"href":"https:\/\/wpdev.life\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wpdev.life\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wpdev.life\/wp-json\/wp\/v2\/users\/1"}],"replies":........}]

You can make this look prettier using the JSONViewer Chrome Extension.

All of the information about a post or page can be obtained through the REST API. This is what allows customers to create phone applications, or run Headless WordPress sites, where the front end is a Node or React application powered by the WordPress REST API.

Authentication and the REST API

by

Why authenticate and how?

The WordPress RESTful API was a major addition to the core ecosystem when it launched with WordPress 4.7. Having these endpoints opened up a slew of possibilities to be able to power the future of digital experiences. By using the REST API, developers are able to create native mobile and web applications that are driven by the WordPress backend. This is what’s referred to as a Headless WordPress site.

By default, anyone can make a GET request to any of the API endpoints for posts, pages, users, media, etc to garner data about your site and its information. WordPress Core has  included a full list of REST API endpoints which can be found in the developer handbook here.. When it comes to creating posts or pages or adding information to your site via an API you don’t want any random person spamming your site with junk, and that is where authentication comes into play.

There’s a few options available for authentication. The easiest for development and testing purposes would be Basic Authentication, which requires that you send an appropriate username and password encoded in base64 with each request.  You may have set up an .htpasswd file in conjunction with your .htaccess file in the past if you use Apache as your backend web server, and this is pretty similar to that, however instead of storing information in a hidden file, WordPress uses usernames and passwords from your database to authenticate. You can install the Basic Auth plugin from https://github.com/WP-API/Basic-Auth. Since this requires sending a username and password with every single request, I do not recommend using this in a production environment.

Another way of authenticating with the WordPress REST API would be to utilize JWT Authentication, or JSON Web Tokens, which is an open industry standard for representing claims securely between two parties. There’s a multitude of JWT Authentication plugins out there, but I typically see either the WP-API teams jwt-auth plugin used, which is still experimental, or the JWT Authentication for WP REST API plugin . Additionally Jonathan Dejong has also created a Simple JWT Authentication plugin, but they all seem to function on the same basic premises. Once this plugin is installed and configured you’ll need to generate a token to be able to prove that your application has the required permissions to access specific endpoints, such as showing all posts with the status of draft. By sending a POST request to the plugin’s token endpoint, containing a username and password combination, you’ll get back a token which you can use in the headers of future requests for authentication.

Testing Authentication and the REST API

So we’ve got our WordPress instance running, an authentication plugin setup and configured so now how do we make sure it is working as intended? Postman is my go to application for testing REST API calls. It’s interface is great, it has support for a multitude of platforms, and is just all around excellent, because let’s be real, who wants to write out long curl commands, manually setting headers, running the request again because you didn’t get all the information you needed. Sure that’s fine for a few people, but Postman simplifies the process tremendously.

When we make GET request to the posts endpoint we get back a JSON array that contains all of the posts on our site.

But if we change that GET to a POST we get a 401 Not Authorized error back, and this is because we haven’t authenticated our requests yet.

Basic Authentication with Postman

Let’s say the Basic Auth plugin is installed on our site, and we want to try to create a post. We can use a POST request to create a post within Postman. If you send a default POST request to the /wp-json/wp/v2/posts endpoint you’ll receive a 401 error. Click on the Authorization tab within Postman, and in the dropdown choose Basic Auth. To the right of that fill in your username and password you use for logging into the Admin Dashboard, and click Send.

You’ll get back a 400 response because we didn’t send any other data to WordPress to create a post.

If we fill in the required information as form-data on the Body tab in Postman, which in this case is Content, title, and excerpt we can create a draft post.

If you were to change the username or password in the Basic Auth settings you would get back a response telling you to reset your password. Just as a reminder, we don’t recommend the use of Basic Auth in production requests due to constantly having to pass your username and password.

JWT Authentication with Postman

JWT Authentication uses the Bearer authorization header rather than the Basic authorization header. To be able to generate the token for the header though we first have to make a request to the Token endpoint of our respective JWT Auth plugin to get this token, except you only need to pass in the username and password in the body of the request to generate the token. Once you have the token, you can then just send that in the headers instead of having to pass your username and password on every request.

On the Authorization tab in Postman, set the dropdown to No Auth, and change the request url to your JWT Authentication Token endpoint. For the body, set your username and password entries and submit your POST request to get your token.

Once you have that token, change the endpoint you want to authenticate against. Go back to the Authorization tab, change the dropdown from No Auth to Bearer and copy and paste your token into the Token field. Then create another post similar to what we did with the Basic Auth one. For the Body, ensure you have Content, title, and excerpt values and send your POST request. If everything is configured right you should get back a 200 response and see your new post’s JSON data in the bottom of Postman.

Final Thoughts

As Gutenberg becomes more prevalent in use throughout the WordPress community, I believe that REST API knowledge is going to become absolutely necessary. With different plugins extending WordPress’ core API, like Woocommerce’s API, this ll paves the way for some extremely slick digital experiences powered by WordPress as we move into the future. If you see anything I missed, or may not be 100% accurate about feel free to drop me a mention on Twitter, @wpdevlife.

Migrating from Font Awesome 4 to 5

by

Today I was working with a custom genesis theme that a customer had created for one of his clients, but none of his icons were showing. There was only a square box. This was pretty perplexing to me. Everything in the code looked correct. Icons were being called properly, and the CSS files were properly enqueued, and showing in the browser. The issue turned out to be a change that Font Awesome made in version 5. 

Previously whenever utilizing an icon, the class would be something like class=”fa fa-instagram”. This is how the icons were being called in the theme code I was looking at and from everything I knew it was right. I checked the encoding of the database and created a new child theme. I even went so far as to not enqueue via WordPress and use the dirty @import statement. I downloaded the files locally and installed them on the site. Nothing I attempted was getting the icons to display. Only version 4 of Font Awesome worked. I was dead set on getting this resolved.

I decided to go to the WordPress.org plugin support forum  for the Better Font Awesome plugin to see if there were other reported issues for the latest font. The issue turned out to be related to the different styles of icons that Font Awesome now provides. 

Font Awesome allows for Solid, Regular, Light and Brand type of icons. Instead of using the fa class when loading the icons, you need to specify fas for solid, far for regular styling, and fal for light icons. If you’re going to be utilizing social media brands such as Instagram, Facebook, Youtube, etc. then you need to use the fab class. For example, if I wanted to load the Instagram icon, I would use <i class=”fab fa-instagram”></i>  to load the icon. Any non brand icons are able to utilize the other three icon styles. 

It is important to be aware of this change before updating any files that may be enqueuing Font Awesome version 4 to 5. At time of writing the latest version is 5.1.1. For a full list of icons, features, or to get Font Awesome Pro check out their website! 

Improve your Workflow with WP CLI

by

There exists within the WP CLI the scaffold command which allows you to easily create the base file and folder structure of some common WordPress features, like Plugins, post-types, or a theme based on Automattic’s _s. If you’re going experimenting with the new Gutenberg Editor slated for a Core Release in 5.0 there’s also the block generator. If you don’t currently utilize Boilerplates such as WPPB then using the scaffold feature of WP CLI can definitely help speed up your workflow

What does it do?

There’s multiple sub-commands for the scaffold command.

wp scaffold block – Generate the PHP, JS, and CSS files for creating your own Gutenberg block. I would definitely recommend this as a starting point for diving into creating custom blocks, especially since Gutenberg is slated for WordPress 5.0.

wp scaffold child-theme – If you use a framework such as Genesis, or Divi, or any other theme but need to get a child theme setup rapidly without manually copying/pasting files or creating them from scratch then this should shave some time off the initial setup.

wp scaffold plugin – Get a decent head start on developing a new plugin. I personally prefer using the WordPress Plugin Boilerplate because it gets setup for Object Orient Programming utilizing classes, so it gives you an even better headstart than scaffolding one.

wp scaffold plugin-tests – This will generate files for your plugin to run PHP Unit Testing on.

wp scaffold post-type – Whether you’re needing to get some post types added to your theme or for your plugin this command will generate all the necessary PHP code to register, and add a Custom Post Type to your plugin or theme, or just output the PHP code onto your Terminal for you to copy and paste it into a specific theme or plugin file.

wp scaffold taxonomy – Similar to the post-type command, this generates the PHP code necessary to setup custom taxonomies faster than having to manually type everything out, or saved somewhere as a template and then having to search and replace the necessary fields.

wp scaffold theme-test – Just like the plugin-tests this generates PHP Unit Test files around your theme.

wp scaffold _s – This works exactly like downloading a fresh file for Automattic’s Starter Theme Underscores or more simply put _s. You can pass all of the same arguments on the command line as you fill out on their website. It would be great to see WP CLI change the plugin scaffold command to use the WPPB setup that I’ve mentioned before, as their generator site works exactly the same as the _s website. If you need to create new themes and you prefer working with raw code starting from the bottom this is your best asset. I would like to see the addition of being able to choose some kind of CSS framework to add by default such as Bootstrap or Foundation as that could save additional time.

Wrapping it up.

For the full list of commands and more documentation I recommend reading over the Developer Handbook page.

Hopefully you find some usefulness to the scaffold command. Most local environments such as Wocker, or VVV will contain implementations of the WP CLI that are fully featured. Some web hosts that grant CLI access may turn off the scaffold command, but that’s due to developers scaffolding and programming locally before pushing things up with Git or another kind of development tool. WP CLI should be a part of any developer toolkit and can help speed up your workflow as you become more comfortable with it.