Forem: Josh Pollock

Parsing WordPress Block Data

Josh Pollock — Sat, 27 Feb 2021 16:31:04 +0000

Before WordPress 5.0, content for posts was stored as a string. It may or may not have contained HTML, line breaks and other formatting is meaningful, also shortcodes. WordPress 5.0 introduced a block based editor. It stores content as a string of HTML, with extra annotations as well as semantic HTML markup and attributes representing the data model. That HTML is parsed server-side -- removing extra annotations and replacing dynamic content -- before outputting HTML

Some developers would prefer that the block attributes, including content were stored in separate, queryable columns in the database or were presented as an object. Maybe that would have been better -- I disagree later in this post -- but it's not how it works. More importantly, you can parse the blocks into a structured object with PHP and JavaScript. That's best of both worlds, we get the interoperability of using HTML to represent HTML, and developers can work with content as an object to modify the content or how it is rendered as HTML.

I recently published a helpful tool for using the block parser in React apps. It helps when you want to replace WordPress' default block parsing with your own React components. In this article, I'll get to why I like WordPress, very imperfect approach and making it easier to modify with what I'm working on. I'll also look at how it compares to markdown-based content in Jamstack-style sites. I am a big fan of both approaches and this is not about debating one versus the other. Both are better, both maybe a better choice than the other, depending on the circumstances.

Shelob9 / block-content

Renders "raw" post content with WordPress block markup in it using React components, which you optionally provide.

Block Content Renderer

Renders "raw" post content with WordPress block markup in it using React components you optionally provide. Uses @wordpress/block-serialization-default-parser.

This works with the "raw" value returned by WordPress REST API for post title, content, excerpt, etc. You must request with ?context=edit which requires permission to edit the post.

BETA Probably don't use. An experiment by Josh Pollock.

Why / Status

WordPress parses block-based content to HTML before displaying it in a front-end theme. This HTML is also returned by the REST API and WPGraphQL. With a JavaScript front-end, in a headless site or what not, you may want to treat the block content as an object for several reasons.

Change the markup -- add classes to paragraphs, change element types, etc.
Sanitize content
Re-order or reformat content.

WordPress' block parser converts blocks to objects. These objects have block attributes and the inner HTML. This library will…

View on GitHub

Content Can Be An Object In A String

First, everything is a string in the database. A JSON column is a string with special annotations for translating it into an object. Relational databases like MySQL are great for putting it all back together. And if every block was its own row in a table, we could query for all blocks of a certain type. That and similar queries would make a GraphQL API for WordPress even cooler.

It is common when developing a Gatsby site to have a directory of markdown files stored in the same git repo as the code. When Gatsby generates the site, it parses the markdown in those files to an abstract syntax tree and then uses that tree to render HTML. Generally MDX is used to provide React components for each HTML element.

Gatsby provides APIs to hook in while that's happening so you can add business logic like "always add this class to paragraphs" or "make a fancy blockquote markup" or "insert an ad between sections."

I'm over generalizing a lot here. But the point is that minimal markup is stored with the content. The markup is generated at build-time, by treating the string of markup as an object.

Back To WordPress

When content is edited by the block editor, there is a lot of HTML markup in the_content field of the database. It's semantic HTML, making heavy use of comments and data attributes. The extra annotations, the Gutenberg grammar, are removed before sending the content to the browser in most settings.

The WordPress REST API returns an object for post content. It contains one or more properties. It should always return a "rendered" property. That is the same HTML as we get in the front-end. If you have permission to edit posts and append ?context=edit you will have a "raw" property in the content object.

That has the unparsed content. You can do the same thing WordPress does with it: use a PHP or JavaScript parser to convert it into an array of block objects and then walk that array to generate HTML.

This article covered parsing with JavaScript. Micah Wood wrote a good post on using the PHP parser and expose it on REST API endpoint. I also recommend this explanation of how dynamic block parsing works server-side by default. You may also want to look at Roy Sivan's Gutenberg Object Plugin which copies block data to a separate table, and exposes it on REST API endpoint.

Why This Matters

The rendered HTML returned by the REST API can be rendered with React, using dangerouslySetInnerHTML:



const PostContent = ({rendered}) => {
  function createMarkup() {
    return { __html: rendered };
  }
  return <div dangerouslySetInnerHTML={createMarkup()} />;
}

This is not the best solution, because you are opening yourself up to XSS attacks by letting React evaluate raw HTML like that. What if you have React components you want to use for rendering the content, for consistency with the rest of the site?

In these situations, using a block parser may be helpful. For example, you can parse out links and replace them with React components, for example Gatsby's Link component in place of links.

Customizing Block Rendering

As I said earlier, I'm working on a helper for working with the parser in React apps for headless WordPress sites. WordPress always returns post content with a "rendered" property, which contains the pre-parsed HTML, if you request a post with context=edit query param and have permission to edit, you also get back a "raw" property. That's what we're working with here.

WordPress' block parser works with that raw string, like this:



import {  parse } from "@wordpress/block-serialization-default-parser";
const blocks = parse( `<!-- wp:paragraph -->
<p>Hi Roy</p>
<!-- /wp:paragraph -->`);

That returns an object full of blocks, some of which have blocks inside them. I'm working on a utility that makes it easier to use this parser to render content using components supplied by the developer.

This library includes a component called BlockContent, which renders raw block content, by parsing the blocks, sanitizing the content and converting it to React elements. Remember, this request must be made by a user with permission to edit the post, and with the context query param set to edit.

Here's an example of a Post component that uses it:



import {BlockContent} from "@shelob9/block-content";
export const Post = ({post}) => {
  return (
    <article>
      <BlockContent rawContent={post.content.raw} />
    </article>
  )
}

That's cool, but it doesn't help customize what React components are used to render the block content or to add business logic to the rendering. To do that, you need to set up a provider and supply it with components.

Here is an example of the components you could use. In this example, all "a" elements in post content are replaced with Gatsby's link component and all "p" elements get a different class:



const components = {
  //replace links with Gatsby's link component.
  a:({children,className,href}) => (
    <Link className={className} to={href}>{children}</Link>
  ),
}

In this example, we add an additional class name to all paragraphs:



const components = {
   //Add a custom class to paragraphs
   p : ({children,className}) => (
    <p className={`${className} custom-class`}>{children}</p>
  ),
}

There is no need to supply all elements. If, for example, no component for p elements are provided, a generic one is generated.

These components are passed to the ThemeProvider component. That provider needs to go around all elements that use BlockContent:



import {ThemeProvider} from "@shelob9/block-content";
import {Link} from "gatsby";
import {Post} from "your/post/component";
import components form "your/components";

//Mock data
let raw = `<!-- wp:paragraph -->
<p>Hi Roy</p>
<!-- /wp:paragraph -->`;
let post = {
    content: {
        raw,
        rendered: '<p>Hi Roy</p>'
    }
};

//Wrap everything in the theme provider
const App = () => {
    return(
        <ThemeProvider components={components}>
            <Post post={post} />
        </ThemeProvider>
    )
}

Try It And Let Me Know What You Think

This is a new project. If you have a chance to use it, let me know what you think, in the comments or on Twitter. I will add more control over sanitizing content and attributes next, but would be super happy to know what you wish this could do.



yarn add @Shelob9/block-content

npm install @Shelob9/block-content

Shelob9 / block-content

Renders "raw" post content with WordPress block markup in it using React components, which you optionally provide.

Block Content Renderer

Renders "raw" post content with WordPress block markup in it using React components you optionally provide. Uses @wordpress/block-serialization-default-parser.

This works with the "raw" value returned by WordPress REST API for post title, content, excerpt, etc. You must request with ?context=edit which requires permission to edit the post.

BETA Probably don't use. An experiment by Josh Pollock.

Why / Status

Change the markup -- add classes to paragraphs, change element types, etc.
Sanitize content
Re-order or reformat content.

WordPress' block parser converts blocks to objects. These objects have block attributes and the inner HTML. This library will…

View on GitHub

I Think This Is Good

Yes, a table structure for block data would make it easier to do MySQL query based on blocks. I love to think about an alternate reality or possible future where blocks can be used as a graph database of some sort.

In the strange world we do live in, post content is a string and I think that's good. With a table based system, the content -- what site owners care about -- you would need MySQL and PHP to convert that to HTML.

Gutenberg markup in HTML makes parsing optional and can be done without PHP and MySQL. There are JS and PHP clients. Also, it's a spec you could implement in Go, because you're Chris Wiegman or whatever.

That's why I think this tradeoff makes sense. But, if querying against block attributes is a requirement, then those block attributes should be saved in post meta, so queries can be done based on those meta fields. I recommend this post by Helen Hou-Sandí wrote about working with meta fields in the block editor if you want to learn more about how to do that.

I know this may be a contrarian opinion, but using strings of HTML is not a bad way to represent content blocks. It is way more human readable and interoperable than JSON or storing in MySQL. With the parsers, available to use, when the rendered HTML doesn't fit our need, we can customize how the rendering works, to fit our needs.

Sane defaults and plenty of ways to modify core behavior. Yes, it's a little messy, but it works and is very extensible when it needs to be. That's the vibe that makes WordPress so useful, right?

Featured Image by Joeri Römer on Unsplash

Josh Update: 2021

Josh Pollock — Wed, 17 Feb 2021 00:55:14 +0000

Last week I shared some Josh news on twitter that it was my last week at Saturday Drive. To answer a common question: I work at 10up now.

Moving on From Saturday Drive

In 2019, we sold Caldera Forms to Saturday Drive, the developers of Ninja Forms. I joined Saturday Drive with several other members of our totally distributed team. We joined as Saturday Drive was transitioning to being mostly distributed.

I'm grateful to have been a part of the time and to have contributed to Ninja Forms, Caldera Forms, SendWP as well as internal applications. It's been a great opportunity and I've learned a ton about PHP, JavaScript, React, TypeScript and more while I've been there.

While I was at Saturday Drive I contributed to Ninja Forms, including new blocks, new architecture for add-ons, and I helped diagnose and fix a ton of bugs. I also worked on internal applications for Ninja Forms and oversaw a migration of NinjaForms.com in advance of Black Friday. While I wasn't able to continue the vision I had for Caldera Forms, I was able to complete Caldera Forms MailChimp 2.0, which was a complete rewrite and rewrote all of Caldera Forms' conditional logic editor in React to fix performance issues.

Ultimately, this wasn't the right fit, I know I made an impact, but it was time. Earlier this year everyone agreed it was time for me to find something new. I super appreciate the support of the Kevin, James, Jeremy and the whole Saturday Drive team during this transition.

I Work At 10up Now

Starting this week, my job title is "Lead Web Engineer" at 10up. 10up is a WordPress VIP partner, and works with top brands and some very high traffic sites. I've been working with the WordPress for awhile, but mainly on plugins and WordPress adjacent apps. While I've built sites, and dealt with scaling challenges for ecommerce sites, this is a bit different.

I'm really excited about a reset. It's a WordPress job, with a lot more WordPress development than my previous plugin development job. Moving to 10up is an opportunity to work on a team and use the skills I've developed over the last few years in new ways.

The process of interviewing was fairly quick and relatively low stress. I'm still onboarding, but I've been super impressed so far with the friendliness of the people and the quality of the documentation.

Also My Hair Got Long Again

I am super grateful that working with WordPress allows Alicia and I to stay home and stay safe during this pandemic. It has been great to spend more time together and we got a puppy. The puppy news isn't recent and if you have spoken to me or follow me on social media, you probably have seen this, but anyway here is a picture of Macy playing in the snow:

Oh shoot, this section was about me, not my dog. Sorry, that will happen. Anyway, my hair has gotten pretty long. It's been longer, but still I'm happy I had this opportunity to grow it out one last time before it's gone:

I'm going to keep growing it, but happy so far:

And here is another photo of Macy playing in the snow:

Long Distance Hugs And High Fives

Given everything, I'm doing pretty good right now. If you are friends, Roy or family enough that you just read a whole post about me, thank you for being awesome. I love you and hope to see you again soon. Hugs. Hi fives.

Using Docker For Local Development Of Headless WordPress Sites With NextJS

Josh Pollock — Wed, 13 Jan 2021 23:38:13 +0000

Back in 2016, I was talking about adding how the WordPress REST API was the first step in evolving WordPress to more of an application platform. Since then the WordPress post editor has been re-written in React. In addition to the WordPress REST API, there is now a GraphQL plugin for WordPress being developed with the goal of making it a part of WordPress core one day.

Back then, we were not sure how to integrate React or Vue with WordPress sites. Today, NextJS and Gatsby exist and come with WordPress presets. I am a huge fan of NextJS, which includes static site generation, making it perfect for static content sites. I also love the zero config routing for front-end pages and API routes.

NextJs's WordPress preset is everything you need to start a content site, with WPGraphQL. That's cool, but it could also be the start point for a WordPress-powered application.

Like most WordPress projects, the first step is choosing a local development environment for the WordPress site. There are a ton of options out there. I like to use Docker beacuse there is very little setup for WordPress, thanks to the @wordpress/wp-env package.

With a little configuration, we can automate all of the setup that is needed. This makes onboarding new developers and QA easier. In this article I am going to show you how to set that up. I will assume you are familiar with WordPress and NextJS.

Create The Application

First thing, we need a Next app. The WordPress preset is a great start point. It even includes Tailwind. Get started by generating the app using create-next-app:

yarn create next-app --example cms-wordpress cms-wordpress-app

That will create the application. Now we need a WordPress.

Adding A Local WordPress Site

The configuration for this site is going to very minimal. We need a site with a few plugins and we need to set one constant in wp-config.php of that site. @wordpress/wp-env can do all of that.

The WordPress site will need to have WPGraphQL installed. I like to add the Headless Mode plugin I made with some friends awhile ago. This will redirect all unauthenticated requests to the front-end of the WordPress site will be redirected to the client.

First install the package:

yarn add @wordpress/env

Then we will need to create a .wp-env.json config file for the local Docker site:

{
    "core": null,
    "plugins": [
        "https://downloads.wordpress.org/plugin/wp-graphql.zip",
        "https://downloads.wordpress.org/plugin/headless-mode.zip"
    ],
    "port": 4113,
    "config": {
        "HEADLESS_MODE_CLIENT_URL": "http://localhost:3000"
    }
}

The "plugins" section is being used to download the latest version of both of those plugins from WordPress.org. The "config" section sets one PHP constant. This is the URL for the redirect. You will need to set one constant in production to match your deployed URL for the client, as documented here.

To make my life easier, I added a "wordpress" command to the scripts section of package.json


{
        "scripts": {
        "dev": "next",
        "build": "next build",
        "start": "next start",
        "wordpress": "wp-env start"
    }
}

Making Them Work Toghether

Now, lets make sure the WordPress site is working. Try starting it:

yarn wordpress

If everything goes as expected that will download the plugins we need and start the site. When it says its done, if you go to the front-end of the WordPress site it should redirect you to port 3000, which isn't' running and that is fine. We are not there yet.

If you go to the WordPress login page you should see that like normal. If you can login with username "admin" and password "password", then everything is good.

Configuring NextJS To Work With WordPress

Before starting the next app, we need to tell it what URL to source content from.

Create a .env and add this:

WORDPRESS_API_URL=http://localhost:4113/graphql`

Now start the front-end

yarn && yarn dev

Now you should see the front-end at http://localhost:3000/.

Adding A Plugin

If you're going to add custom post types, or register new mutations or do anything else that requires custom PHP code, you will need to add a plugin or mu-plugin.

I like having a plugin for my custom code, so I can turn it on and off. I added a directory called "wordpress-plugin" and put a file in there called "wordpress-plugin". Then I updated the "plugins" section of .wp-config.json to map that directory as a plugin:

{
    "core": null,
    "plugins": [
        "./wordpress-plugin",
        "https://downloads.wordpress.org/plugin/wp-graphql.zip",
        "https://downloads.wordpress.org/plugin/headless-mode.zip"
    ],
    "port": 4113,
    "config": {
        "HEADLESS_MODE_CLIENT_URL": "http://localhost:3000"
    }
}

Check out this part of the documentation for more information on other ways to load plugins and mu-plugins.

Make Web Application Now

That's all you need to set up a NextJS app using a local WordPress site running in Docker containers. You can start developing the PHP and JavaScript for your project. What you do next is up to you. Figuring our deployment and authentication as well as coding the app will come next.

If you push the repo to Github, you can deploy the front-end with Vercel with their (super simpler importer](https://vercel.com/new). Make sure to set the WORDPRESS_API_URL environment variable to match the URL of the live WordPress site.

Feel free to fork the source for the example application to build your own thing. I hope you enjoy.

Featured image by Suresh Ramamoorthy on Unsplash

How To Use WordPress As An Authentication Provider For Laravel

Josh Pollock — Sun, 03 Jan 2021 21:02:39 +0000

Like a lot of PHP and JavaScript developers, I started web development by learning enough PHP and then jQuery to customize a WordPress theme and then got carried away from there. Along the way, I learned what WordPress is a good solution for and what it is not a great fit for. This has led to learning Angular, Vue, React and Laravel.

Overtime, more and more of my work has been building WordPress-adjacent apps in Laravel and/ or Node. This has led me to a variety of solutions for sharing data and user authentication between the two. This article shows how to allow users of an existing WordPress site to login to a Laravel site with the same username and password. I did this without data duplication -- besides the cache -- or storing passwords anywhere.

If your WordPress and Laravel applications are able to access the same database, there is an alternative solution, that I will discuss later. The solution I will share in this post, uses the WordPress REST API to check credentials and issue JWT tokens for users.

Setting Up The WordPress Site

This solution requires a WordPress site that has the JWT authentication plugin. This is a free plugin you can install through wp-admin.

Once that plugin is activated, make sure to set a long, random string in the constant JWT_AUTH_SECRET_KEY. Also, ensure that your server does not block the HTTP Authorization header.

This plugin does use username and password to issue the token. They are not stored, so this process is as relatively secure as long as it is run on HTTPS.

When this plugin is installed, you can make a POST request to the "/jwt-auth/v1/token" endpoint with username and password in the body to get a JWT token. That token can then be set in the Authorization header to authorize requests to the WordPress REST API. If we supply that header when making a GET request to "/wp/v2/users/me" we will get details of the current user.

WordPress 5.6 will add an "application password" feature. This is a basic authentication system that uses a different password then the one for login. In the future, that might be a better solution then JWT tokens.

I followed instructions on how to create a customer user provider. It takes the supplied username and password and attempts to get a JWT token from the WordPress site. If that works, a User model is created -- in memory and cache. The password is not saved. A standard Laravel session is created. That session will be maintained as long as the user remains in the cache or the user logs out.

In this post, I will show you how it works. I also put the source for the app I built to test this on the Githubs. Feel free to fork it. It's a basic Laravel 8 site with Breeze.

Creating An API Client

The first step in the Laravel app will be to create an API client. This client, which will make use of Laravel's HTTP facade will need to be able to make requests with and without the authentication token.

This client will need methods for GET and POST requests, that optionally add the header. I also added a method for exchanging username and password for the token:

<?php

namespace App\Http\Clients;


use Illuminate\Support\Facades\Http;

/**
 * API client for WordPress REST API
 *
 * Must have the JWT auth plugin
 * https://wordpress.org/plugins/jwt-auth/
 */
class WordPressApiClient
{

    public string $apiUrl;
    protected $token;

    protected array $options;

    public function __construct(string $apiUrl, ?string $token = null)
    {
        $this->apiUrl = $apiUrl;
        if ($token) {
            $this->token = $token;
        }
        //In production require TLS on both ends.
        //Else do not verify.
        $this->options = [
            'verify' => 'production' === app('ENV')
        ];

    }

    public function setToken(string $token) : WordPressApiClient
    {
        $this->token = $token;
        return $this;
    }

    public function hasToken(): bool
    {
        return isset($this->token) && is_string($this->token);
    }

    public function get(string $endpoint, array $query = [])
    {
        $url = $this->apiUrl . $endpoint;
        if( $this->hasToken() ){
            $request = Http::withToken($this->token)
                ->withOptions($this->options);
        }else{
            $request = Http::withOptions($this->options);
        }

        return $request
            ->get(
                $url,
                $query
            );

    }

    public function post(string $endpoint, array $body)
    {
        $url = $this->apiUrl . $endpoint;
        if( $this->hasToken() ){
            $request = Http::withToken($this->token)
                ->withOptions($this->options);
        }else{
            $request = Http::withOptions($this->options);

        }
        return $request
            ->post(
                $url,
                $body
            );

    }


    public function getToken(string $username, string $password)
    {
        return $this->post('/jwt-auth/v1/token', [
            'username' => $username,
            'password' => $password
        ]);

    }

}

Creating A User Provider

So far we have an HTTP client that could be used for a user provider. It could also be used to get or edit posts or other data from the WordPress site. For now, we'll look at the user provider.

The documentation for creating a custom user provider is pretty complete, and worth reading through.

The most important method here is retrieveById(). Returning a user model here sets the current logged in user. I wanted to avoid having to check the token against the WordPress REST API on every request.

To avoid this, I created a factory for User models that caches the results:

{
    protected function userFactory(array $data) : User
    {
       $user =  new User;
       Cache::put(
           $this->cacheKey(
               $user->getAuthIdentifier()
           ),
           $user->toArray(),
           9000
       );
       return  $user;
    }
}

Here is the method that finds users by id, which uses that factory:


    public function retrieveById($identifier)
    {
        //Has user in cache?
        $user = Cache::get(
            $this->cacheKey($identifier)
        );
        //Yes? Make a user model and return it
        if( $user ){
            return (new User())
                ->forceFill($user);
        }

        //No user? Do a login.
        //Could trigger a redirect to wp-logint that comes back with a JWT...
    }

This function, may not return a user model. This happens when there is no no logged in user. IF that happens, thes enext two methods will be called, in the order you see here. If the token check throws an exception, which the API client will do if it's invalid, that will trigger a login error:

public function retrieveByCredentials(array $credentials)
    {
        $r = $this->wordpressClient
            ->getToken(
                $credentials['email'], $credentials['password']
            );
        return $this
            ->userFactory($r);
    }

    public function validateCredentials(Authenticatable $user, array $credentials)
    {
        Auth::setUser($user);
        return $this
            ->retrieveById(
                $user->id
            );
    }

I did modify the User model to simplify it, and make it work for my needs. You don't have to use the User model, you can use any model. That might be useful if you wanted to have users in the Laravel database and users in the WordPress database. Here is my user model:

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use HasFactory, Notifiable;

    /**
     * The attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'name',
        'email',
        'password',
        'token'
    ];

}

I also deleted the user migration. In my test site I used sqlite for the session and cache table. If I deployed this with Vapor, I would use DynamoDB and/ or Redis instead. That means that the Laravel application may not need a MySQL database, which would be great for scaling and cost-control.

Here is the full user provider:

<?php

namespace App\Providers;

use App\DTO\UserResponse;
use App\Http\Clients\WordPressApiClient;
use App\Models\User;
use Illuminate\Contracts\Auth\Authenticatable;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Cache;

class WordPressUserProvider  implements  UserProvider
{

    protected WordPressApiClient $wordpressClient;

    public function __construct()
    {
        $this->wordpressClient = new WordPressApiClient(
            env('WP_API_URL')
        );
    }

    public function getModel()
    {
        return User::class;
    }

    protected function cacheKey($identifier):string {
        return __CLASS__ . $identifier;
    }

    public function retrieveById($identifier)
    {
        //Has user in cache?
        $user = Cache::get(
            $this->cacheKey($identifier)
        );
        //Yes? Make a user model and return it
        if( $user ){
            return (new User())
                ->forceFill($user);
        }

        //If nothing is returned here, login redirect will be triggered
        //That is normal for unauthorized users.
    }

    public function retrieveByToken($identifier, $token)
    {
        //Try to find by id
        $user = $this
            ->retrieveById($identifier);

        //Not found? Exchange token for user details again.
        if( ! $user ){
            $r = $this
                ->wordpressClient
                ->get('/wp-json/wp/v2/me');
            return $this
                ->userFactory($r);
        }
        return $user;
    }

    public function updateRememberToken(Authenticatable $user, $token)
    {
        //Not actually needed
    }

    /**
     * @param array $credentials
     * @return User|Authenticatable|null
     */
    public function retrieveByCredentials(array $credentials)
    {
        $r = $this->wordpressClient
            ->getToken(
                $credentials['email'], $credentials['password']
            );
        return $this
            ->userFactory($r);
    }

    public function validateCredentials(Authenticatable $user, array $credentials)
    {
        //Recheck token?
        //Auth::setUser($user);
       return $this
           ->retrieveById(
               $user->id
           );
    }

    protected function userFactory(array $data) : User
    {
        $user =  ( new UserResponse(
            Arr::only($data,[
                'token',
                'ID',
                'user_email'
            ])
        ) )
            ->toModel();
       Cache::put(
           $this->cacheKey(
               $user->getAuthIdentifier()
           ),
           $user->toArray(),
           9000
       );
       return  $user;
    }

}

{
    protected function userFactory(array $data) : User
    {
        $user =  new User;
        $user->forceFill(
          [
              'id' => $data['ID'],
              'name' => $data['user_email'],
              'token' => $data['token']
          ]
        );

        Cache::put(
            $this->cacheKey(
                $user->getAuthIdentifier()
            ),
            $user->toArray(),
            9000
        );
        return  $user;
    }
}

Configuring Everything

That's basically it. The last step is to wire things up. These steps are straight out of the documentation.

First in the AuthProvider service provider, register the user provider:

 Auth::provider('wordpress', function ($app, array $config) {
            return new WordPressUserProvider();
        });

Once that is done, you can tell Laravel to use that provider by modifying config/auth.php.

'providers' => [
    'users' => [
        'driver' => 'wordpress',
    ],
],

In the user provider, I used the env varibale WP_API_URL for the URL of the site's REST API. You would put something like WP_API_URL=https://hiroy.club/wp-json in your .env file.

Conclusion

As an alternative to the approach I showed in this post, you may want to look at this package. That package requires access to WordPress' MySQL database. That's not required by the approach I showed here.

My organization's goal is to decouple our big WordPress site from our other internal applications, so co-location didn't make sense. Also, I want to use managed WordPress hosting providers for WordPress and Vapor for Laravel. Mixing them on the same server feels like a regression.

I hope you found this useful. Please feel free to copy the example application that is on Github. I am curious to see if anyone finds this useful and if you have better solutions. I know one thing I'm considering is using a redirect to the WordPress login screen.

I Love Writing JavaScript, But Livewire Is A Great Way To Avoid Writing JavaScript For Stupid Reasons

Josh Pollock — Fri, 01 Jan 2021 00:38:41 +0000

I suppose it is tempting, if the only tool you have is a React, to treat everything as if it were JSX.

Roy Sivan

So, I really love writing JavaScript. React plus TypeScript is some of my favorite code to write. One of the things I've done a lot of is build drag and drop user interface builders, React is amazing for that.

A lot of the development I do right now for my job is internal applications to help development and support of Ninja Forms. I am mainly working with Laravel. The complexity in these projects is scaling databases and processing a ton of data. On the other hand, the UI requirements are very basic -- mainly HTML tables and some graphs.

Initially, I was using Laravel as a headless API and for scheduled task processing. The user interface was a decoupled NextJS front-end. Starting a project with Next and Tailwind is a great way for me to get started. Also, it was totally overkill, and I had to figure out CORS and authentication. Sure, that is worth it in some cases, but I was building a UI for like 3 people to use.

So this was a perfect opportunity to try out LiveWire. I was able to build dynamic components that switch between tables and graphs as well as handle pagination and live search. All with out page re-loads.

Web Applications Are Difficult

One of the problems I run into with my job, is I'm good at figuring things out. In general this is a good thing, but it also means I can get stuck in a rabbit hole making something stupid work.

Livewire got me out of the "everything has to be an app" mindset. AJAX for pagination? That improves UX when searching. A full page refresh between screens that are for totally different data? Chill, it's fine.

Like, do you ever think about the amount of work we do to show people a loading spinner while we reset the entire state of the web page, just to avoid reloading the web page? Chill.

With Livewire I can create an SPA-like interface. For something basic, that we may or may not ever expand on, not having a lot of code, I think is a benefit.

For this app, I created one Livewire component per page. This was a little awkward, as it meant in addition to the PHP class for the component, I had a blade file with the layout for the page, with a livewire component tag and I had a blade file for the component.

The Laravel router returns a view that calls a blade file like this:

@extends('layouts.app')

@section('content')
    <div class="flex items-center">
        <div class="md:w-10/12 sm:w-full md:mx-auto">

            @if (session('status'))
                <div class="text-sm border border-t-8 rounded text-green-700 border-green-600 bg-green-100 px-3 py-4 mb-4" role="alert">
                    {{ session('status') }}
                </div>
            @endif

            <div class="flex flex-col break-words bg-white border border-2 rounded shadow-md">

                <div class="font-semibold bg-gray-200 text-gray-700 py-3 px-6 mb-0">
                    <h1>Page Title</h1>
                    <a
                        class="md:float-right"
                        href="/">Back
                    </a>
                </div>

                <div class="w-full p-6">
                    <p class="text-gray-700">
                        <livewire:component-name :id="$id">
                    </p>
                </div>
            </div>
        </div>
    </div>
@endsection

This is too many files for me, but it does mean that only part of the page is a Livewire component. What's neat about it is that the rest of the page is just a normal blade file. There could be other Livewire components. Or other JavaScript can be used for other parts of the page.

This blade file has to "wire" bindings, that's where the magic happens. The first on the input is wire:model="url". This binds the value of the property of the component PHP class to this input. I just needed to add a public property called URL to make it work:

<?php

namespace App\Http\Livewire;

use App\Models\Team;
use Illuminate\Support\Facades\Auth;
use Livewire\Component;

class NewSite extends Component
{

    public string $url;

    public function mount(){
        $this->url = '';
    }
    public function render()
    {
        return view('livewire.new-site');
    }

    public function create()
    {
       //Don't worry about this yet.
    }
}

I used a typed property to force the value to string. That can cause issues with using the value server-side, for example, in the create callback of this method. If the input is never changed, the value of $this->url will be null, which is not a string, and therefore there is an error.

My solution is to set it the property to an empty string using the mount() method of the class. That method, gets called before render, which renders the blade template on the server and sets up whatever magic keeps the client in sync with the server.

If the variable does not need to be dynamically addressed in the client, you can also pass it to the view directly:

    public function render()
    {
        return view('livewire.new-site', ['site' => 'https://hiroy.club']);
    }

I really like that there isn't a special view function for Livewire. It's the same old view(). There is some special syntax in the Livewire blade templates, but for the most part, it is just blade.

Another use for the mount() method I mentioned before, is to get URL parameters. For example, if this component was for the route /sites/{id} I could get the site ID from the mount() function:

{

    public $siteId;

    public function mount($id){
        $this->siteId = $id;
    }

}

Anyway, back to the component for creating a site. We were discussing bindings and magic. The second binding is wire:click="create". This binds the click event of the button to the PHP class method create.

That method has the value of the input, set in the property $url, thanks to the first binding. I was able to use that to create the site, and associate it with the current user's team, like this:


    public function create()
    {
        /** @var Team $team */
        $team = Auth::user()->getCurrentTeam();
        $site = $team->sites()->create([
            'url' => $this->url
        ]);
        return $this->redirect(sprintf('/sites/%s', $site->id));
    }

Full Page Livewire

As I mentioned earlier, in the first project I used Livewire on, I did not use full page components. This approach allows for composing the page out of HTML, one or more Livewire components, and could include other frameworks.

That project started as a Laravel 7 app, and was upgraded to version 8, and I never got full page components to work. When I started a second project, using Jetstream they worked as expected.

That way there is only one blade file per page. Binding the component to the route, in web.php, is like binding an invokable controller:

Router::get( '/sites/{id}', \App\Http\Livewire\Site::class);

This is an example of a full page component blade file, which would work with the same PHP class I showed in the previous section:

<x-slot name="header">
    <h2 class="font-semibold text-xl text-gray-800 leading-tight">
        {{ __('New Site') }}
    </h2>
</x-slot>

<div class="py-12">
    <div class="max-w-7xl mx-auto sm:px-6 lg:px-8">
        <div class="bg-white overflow-hidden shadow-xl sm:rounded-lg">
                <label for="url">
                    URL
                </label>
                <input type="url" id="url" required wire:model="url" />
                <button wire:click="create">Save</button>
        </div>
    </div>
</div>

The first part is the equivalent of a VueJS slot. I like how Jetstream breaks the page up into sections like this. I will likely add a sidebar and footer slot next.

LiveWire FTW!

Not every website needs to be a complete single page web application. Working with Livewire has reminded me that a traditional page navigation isn't such a bad thing. That page refresh prepares the user for a change, and it wipes out the unrelated state.

Livewire, especially with Jetstream is a great tool for building Laravel UI quickly. That makes it a great fast prototyping tool that should force you to ask the question -- do I need to replace this with a full SPA? Probably not, Livewire is very good.

This post is a brief intro to Livewire and why I think it is good. That said, I think I covered most of the important things you need to know. The docuemntation is quite good. If you sponsor the creator of the framework, Caleb Porzio on Github, you will get access to screencasts about using Livewire.

Unit Testing Classes That Call Functions From WordPress Core

Josh Pollock — Mon, 30 Nov 2020 15:59:04 +0000

In general, I make the distinction between unit and integration testing based on dependencies. A unit test should test one "unit" of code only, just one class or function, with no external dependencies -- WordPress or MySQL.

Unit testing with mocks can be very useful. It can also create false confidence beacuse it assures your code works when the dependencies work as you assume they will. So don't forget to use integration tests.

One way to make your code more testable is to inject dependent functionality into a class. Then you can mock those classes with a different class implementing the same interface, or use a mocking library such as Mockery.

That's not always possible, or not practical, if the functionality you need to mock out is a function from WordPress core. In those cases, monkey patching is a better solution. "Monkey patching" is the process of swapping the definition of a plugin at runtime, this case during testing.

Instead of testing with the actual function -- that would be an integration test -- we replace it. When we use a monkey patching library or a mocking library we can ensure that the code being tested calls the dependency, calls it with the right value and does the right things with the return values.

There is a WordPress-specific tool called Brain Monkey, that can do this for us. In this post, I will show you how to do that. Both Mockery and Brain Monkey will be setup if you choose to add unit tests, when creating a WordPress plugin with Plugin Machine.

If you need a good way to try these tests out, that's good place to start. Alternatively, you can copy my example tests into your plugin.

You just need to install Brain Monkey first:

composer require brain/monkey:2.* --dev

Unit Testing That WordPress Hook Callbacks

I often get asked how to test a class that calls add_action() and add_filter() in the constructor and then has callback functions in the same class. The best advice I can give you is don't do that.

Instead, write classes, or even better functions for your callbacks that are totally de-coupled from the WordPress plugins API.

For example, imagine a plugin that adds a call to action to every post. If I create a class that can be used as a callback for the the_content filter.

<?php

class ContentFilters{

    protected  $cta;
    public function __construct($cta)
    {
        $this->cta = $cta;
    }

    public  function callback($content){
        return $content . sprintf( '<p>%s</p>', $this->cta );
    }
}

This is a super basic example, but if the callback function for an action or filter does something, you should be able to test it by passing the arguments to the function and testing the side effects or return values. If there are a lot of side effects, that's probably better suited to an integration test.

Because this is a class with one responsibility, I can test it's business logic without worrying about the integration with the WordPress plugins API.

class ContentFiltersTest{

    public function testAddCta(){
        $adder = new ContentFilters('Hi Roy');
        $this->assertSame('Before<p>Hi Roy</p>',$adder->callback('Before');
    }
}

Unit Testing WordPress Functions Called By Hooks

In general structuring your code for easy testing, for example decoupling hooks from hook callbacks is a good practice. So that's an advantage of testing, it makes path of least resistance -- code that's easy to test -- the good path.

But what about a function that sets up enqueuing scripts? That's a good example of something I test, just to prevent big mistakes that break everything. Here is an example of that kind of function:

add_action('wp_enqueue_scripts', 'callback_for_registering_scripts');
function callback_for_registering_scripts()
{
    wp_register_script(
    //...
    );
    wp_localize_script(
    //...
    );
}

I can use Brain Monkey's expect() function to ensure the functions in my callback get called:

public function testRegisterAndEnqueue()
{
    callback_for_registering_scripts();
    \Brain\Monkey\Functions\expect('wp_register_script')->once();
    \Brain\Monkey\Functions\expect('wp_localize_script')->once();
}

You could also use expect to make sure that add_action() is called. But that would be a different test, which you could write with expect. There is also a specialized library for mocking WordPress hooks.

Unit Testing Interactions With WordPress Core Functions

So far, we've just tested that functions are called. That's nice, but often times we have logic following a core function call. That's what we need to test: our business logic. For example, let's say you have a class that creates a post:


class Storage {

    public function save(string $title){
        $id = wp_insert_post(
            ['post_title' => $title]
        );
        if( ! is_numeric($id)){
            throw new \Exception('Could not create');
        }
        return $id;
    }
}

If you were to unit test this, without monkey-patching wp_insert_post(), you'd get an error. Our goal isn't to test wp_insert_post. Our goal is to test the unique business logic of the plugin. In this case, that is the conditional and whether or not it throws an exception.

We can do that with the when() function. When we call when(), we can chose what to return. I will test once where it returns an integer, which is what happens when a post is saved. I will test again and this time have it return an object. That test expects an exception to be thrown.

These two tests cover what happens if things go right and what happens if they go wrong. As long as I've made accurate assumptions about what right and wrong are, this is good.

use Brain\Monkey\Functions;
class TestWhatever extends YourTestCase {

    public function testInsert(){
        //A fake wp_insert_post() that always returns 1
        Functions\when('wp_insert_post' )->justReturn(1);
        $this->assertIsNumeric(
            (new Storage() )->save('Hello Royvan')
        );
    }

    public function testInsertThrows(){
        Functions\when('wp_insert_post' )
            ->justReturn( new \stdClass() );
        $this->expectException(\Exception::class);
        (new Storage() )->save('Make Errors!');
    }

}

These Tests May Not Be Enough

In this post, I've shown how to fake WordPress core functions during unit testing. Don't forget that these tests rely on assumptions. Make sure to confirm your assumptions with integration or acceptance tests.

If you want to get more comfortable with this type of testing, I would suggest making a new plugin from my template, adding a new class that calls functions you may commonly use, like get_post() orupdate_option() and write unit tests for them. As you do that, keep in mind what assumptions you're making. If any of them make you uncomfortable, write integration tests instead :)

Cover image: Photo by Benjamin Voros on Unsplash

I Made An App With Userbase And Have Written A Blog Post About It

Josh Pollock — Sun, 22 Nov 2020 02:02:16 +0000

This blog post is about Userbase. It's not a tutorial. I made one app with Userbase, these are some initial reactions. I'm impressed with how quickly I was able to get going once I figured out the very small API.

The documentation for Userbase is very complete. The docs include an excellent tutorial that explains how it works by showing how to build a user login screen and some other things.

I recommend reading through that and then making a NextJS, with Tailwind and Userbase:

yarn create next-app --example hi-roy next-userbase-app

The file-based routing in Next makes it my favorite React framework for building apps quickly. Not having to think through the router is one less thing to worry about when trying out a new thing.

The starter I used included Tailwind, which made me happy. I can make things look sort of good with Tailwind.

Anyway, this post is about Userbase. I was curious if it fit that pattern of easy to set up, work with like the other tools I mentioned.

No Setup Database, End To End Encrypted? Nice.

Userbase is a product I'd been meaning to try for a bit. I built an app earlier this year to try out blockstack.js, which also offers end-to-end decryption and a no set up database.

Some things that are super neato about both Usersbase and Blockstack are that you get a database backend with basically no set up. The database is very easy to get started with and is encrypted. This is great for privacy-first applications.

That's a cool benefit.

Userbase is more centralized than Blockstack. There is a paid service, which runs on AWS, or you can run your own instance, on AWS. Blockstack uses a blockchain and various cloud providers, and has a decentralized file system, as well as a wallet-based authentication. Having to set up a crypto wallet to login to an app isn't ideal, so I was interested in trying Userbase.

While signing up for a Userbase is very typical. You provide your email address and a password. The big catch with Userbase is there is no way to do a password reset. To be honest, that does me a concern.

Blue Boxes

I love graph paper. When I got stuck going to school, beacuse I was a child, one of my favorite things was the blue boxes on the graph paper. It's simple, and you can use it to make graphs or patterns. I also like to use graph paper for writing sometimes.

Anyway, it's November 2020 and the sun is getting dark earlier now, and I've been trying to channel my anxiety with JavaScript, and I saw this Visa tweet:

// Detect dark theme var iframe = document.getElementById('tweet-1329093575649370113-432'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1329093575649370113&theme=dark" }

This was a nice way to stop doom scrolling, so I built the graph paper generator after work the other day. I like the idea of putting notes or links to tweets in boxes, so this felt like a good way to test out Userbase as a data store for this type of app.

I'm starting to enjoy these puzzles to make a surface that is X by Y and has different things in each box. I used two loops, one for rows and one for adding boxes to the row. Here is the code for the generator. This isn't a tutorial, but it's probably helpful to know what the data looks like. Here are the TypeScript interfaces for the graph object:

export interface IBox {
    boxId: string;
    rowId: string;
    content?: string;
    link?: string;
    open: boolean;
}

export interface IBoxes {
    [key: string]: IBox;
}
export interface IRow {
    boxes: IBoxes;
    rowId: string;
}

export interface IRows {
    [key: string]: IRow;
}
export interface IGraph {
    graphId: string;
    rows: IRows;
}

It was my original intent to store the entire object for a graph, with an array of rows, each one with an array of boxes in one "item" in the Userbase database.

I got a helpful error telling me that the max size of any item in the database is 10kb. It does say that in the documentation. I missed that, I was tired and it's been a week, but I think we'll be OK and that the data in productivity and wellness apps should be private.

The solution that worked for me was to create one database, identified by the graph's ID, per graph. All of the records in the database are boxes. The boxes know what row they are in, and there order in the row, so the graph can be re-assembled.

Saving Boxes

I kept the database name in a memo-ized value:

let databaseName = useMemo(() => `graph-${graphId}`, [graphId]);

Then I was able to create a function for saving individual boxes:

       const saveBox = async (box: IBox) => {
        const { boxId } = box;
        return await userbase
            .updateItem({
                databaseName,
                item: box,
                itemId: boxId,
            })
            .then(() => {
                return { boxId };
            })
            .catch((e) => console.error(e));
    };

Given that I never created that database with a CLI or back-end or waited for it to provision and the code is that little, I'm super duper impressed.

Creating Boxes

Originally I had a similar function to create one box. Then I looped through each row and created each box. I ended up getting rate-limited doing that. Which felt fair, also userbase supports bulk operations.

You are able to create, update or delete up to ten records at a time. I broke the boxes up into chunks of ten when they are created.

Userbase Is Very Cool

I am not going to go on about how I built the application. You can read the source here.

Clearly, I think Userbase is very neato. There is a lot of promise here and they are working on SQL. I will keep my eye on Userbase.

The big concern is that if a user looses there password, they can't reset it. That's a concern. Still, this is a great way to build an app quickly.

Oh Yah, The Blue Boxes

I do not identify as someone who can make a user interface, web blog or web application look good. I enjoy building user interface for other reasons, and assume someone with different skills will make it look right.

So, I was pretty proud of myself that I made the blue boxes. The graph is an HTML table. The table, table body, table rows and table cells have the class graph. The table cells, the blocks, also have the class graph-box. This little bit of Tailwind CSS made it look right:

.graph {
    @apply border-2 border-blue-500 border-opacity-50;
}

.graph-box {
    width: 20px;
    min-width: 20px;
    height: 20px;
    min-height: 20px;
}

Here is an image of the result:

Graphs Are Fun

This is the end of the blog post. If you have not yet, check out Userbase. This is a very promising framework. I used it for user authentication and data storage. There is also built-in file uploads, data sharing and payments.

You can check out the source code for the app I built or try the app. The graph paper interface is fun, I'll probably build something else with it, feel free to put it to use in your own thing.

Have fun. The blog post is now over.

Cover Photo by Gabriel Santiago on Unsplash

How To Use Docker For WordPress Development

Josh Pollock — Thu, 07 May 2020 22:04:27 +0000

When developing WordPress sites, apps, plugins and themes, it's always a good idea to work with a local test environment. When I started WordPressing seriously in 2014, the options were XAMP -- DesktopServer, MAMP, WAMP, etc. and Vagrant -- VVV, Homestead, etc. Later on Docker-based solutions appeared. For example, Local by Flywheel.

This post is an introduction to using Docker for local WordPress development. It's not going to teach anything about using Docker in production or make you a Docker expert. My goal is to understand what Docker does and how to quickly get a local development envioronment up and running with the tools for this provided by the WordPress open source project.

Why Docker

XAMP like solutions install and configure PHP, MySQL and a web server -- apache, nGnix, etc -- on your computer to work as WordPress site. On the other hand, Docker creates and runs a complete web server stack -- including the operating system and all tooling -- in a completley isolated "container" that runs the same whether your computer is Linux, Windows, or Mac.

For teams of any size, the "works on my machine" problem will always be present. Using Docker allows us to explictily say "this is what the machine we develop with is." With Docker, everyone can choose there own computer, or possibly a cloud-hosted IDE and not worry about getting all of the parts of a web server set up the same way as there team mates every time.

Docker is used to "containerized" our applications. A container is one application, totally encapsulated into one immutable entity. We simplify the creation of containers with pre-defiend templates called images. For example, if we want to use PHP in our app, we could use our Dockerfile to install PHP, and extensions and configure it. Or we may use a PHP image, or a PHP-fpm 7.4 image.

This is a good article comparing Docker and Vagrant from Delicious Brains.

Basic Introduction To Docker

If you've ever followed a tutorial on setting up a server, you may recall beign given a set of instructions to follow, in the correct order to install all of the software via the command line. This always makes me nervous -- I'm worried about skipping a step or remembering to do it the same way every time.

Docker files normally start with a "FROM" directive, which tells us what "image" -- a template defined in a different Dockerfile -- to start from. This is like starting with a fresh VPS with Ubuntu installed.

# Start with Ubuntu installed
FROM ubuntu

The Dockerfile describes exactly how to make the server. The commands are similar. If we had a VPS, we might SSH in, and use apt-get to install some software, such as git. We use the RUN directive to do the same thing in our Dockerfile:

# Start with Ubuntu installed
FROM ubuntu

# install git
RUN apt-get update \
    apt-get upgrade \
    apt-get install git

A Few Key Docker Concepts

Docker is a technology that gets a lot of attention, beacuse it can do so much. It's a large ecosystem, I want to start with a few concepts that you should know. The goal here is to show what's important, and what can be ignored.

Docker is a software that manages containers. Container is a general term, not specific to Docker. Containers are not run by the operating system directly, instead they use the operating system's kernal directly and run there own OS. This makes containers, effectively different computers running on the same processor.

Docker, provides and API and CLI for creating and running containers both in production and on your computer, via a desktop app. You should install the Docker desktop app for Mac, Windows or Linux.

Intermodal shipping containers come in a variety of standard sizes. They can be stacked in warehouses, on ships, placed on trains, or pulled behind a truck. What is in the container doesn't matter. A ship is built to carry X containers of size Y, what's inside those containers doesn't matter, as long as the dimensions, max weight and door specifications match.

You can think of Docker, the software as the crane that moves the containers around. We can do this from the command line, but that doesn't scale well past a single container. We need php, MySQL, etc for our apps. The docker ecosystem has various container orchestration tools that you can think of as telling the crane how to assemble stacks of containers.

There are several solutions we could use for orchestration. The simplest is docker-compose, which is optimized for local development. While docker-compose could be used in production, generally something like Kubernetes is a better choice in production.

With docker-compose, we can define a collection of services that work toghether into one container, with a single yaml file.

Options For WordPress Local Development With Docker

Until recently, to use docker-compose with WordPress, we needed to write and maintain a docker-compose.yml file. The documentation includes a great guide, with examples of how to write a docker-compose file for WordPress.

WordPress now has two node packages that use docker-compose, and remove the need to write that file. These packages do what I have spent a lot of time doing for my projects -- scripting installation, package.json commands, etc. But I don't have to maintain it and the open source project has done a better job than I ever did.

The rest of this post focuses on those options. Using your own docker-compose file is totally fine as well. I have also used Lando and Local By Flywheel, both of which work well.

Options For Docker-based Local Development From WordPress Core

The WordPress open-source project has published two tools to simplify docker-based local development. Both of them use nodejs to abstract away most of the complexity of using docker-compose for WordPress development.

The first option @wordpress/env is the simplest option. It is useful for spinning up a quick test site with, some options. These options include installing plugins and switching WordPress versions.

The other option is the env sub command of @wordpress/scripts. This command is similar to @wordpress/env. It can also has a phpunit test runner that runs WordPress integration tests, making it more useful.

Using @wordpress-scripts for Local WordPress Development With Docker

You may wish to review this sample plugin I created while working through this section.

This section assumes you are already using @wordpress/scripts in your plugin for compiling JavaScript and CSS. If not install it first:

yarn add @wordpress/scripts

Update Your package.json

WordPress env requires you add a "wp-env" key to your package.json and define at least two values. These required options are plugin name and directory. Assuming your plugin's name is Catus

{
  "wp-env": {
    "plugin-dir": "cactus",
    "plugin-name": "Cactus"
  }
}

You also need to add an "env" or similar command to your plugin's scripts:

{
  "scripts": {
    "env": "wp-scripts env"
  },
}

Using The Env Command

To start and install the local docker-based development environemnt:

yarn env start

The first time this runs, the environment will be installed and started. In the furture it will re-start. You should see WordPress in your browser when you go to http://localhost:8889

To stop this environment, go to

yarn env stop

Featured image by Dorothea OLDANI on Unsplash

Developing WordPress Blocks Without WordPress

Josh Pollock — Tue, 03 Mar 2020 22:23:42 +0000

Now that WordPress has React-powered editor with code decoupled from WordPress, we do not need WordPress as a dependency when developing block plugins. This can speed up block development. In this article, I will show you how to use Codesandbox to develop blocks.

The proposed block block library should allow for WordPress plugins with only JavaScript, CSS and a block.json file. The structure of this template is only 1 PHP file -- the assets.php file generated by wordpress-scripts -- away from being a complete plugin.

Quick Steps To Start Block Development

I created a CodeSandbox template to start block development. You can use this template to start developing your blocks. I started by cut and pasting the code in the "playground" story of the Gutenberg repo's Storybook.. This minimal implimentation of Gutenberg has the setting sidebar and the main editor area. You can insert the block from this sandbox and the core blocks. The sidebar is on the top, I didn't add extra CSS for that. It's a little odd at first, but I think it will help me focus on settings and block seperately. I might change that.

This is now my two step process for starting development of a block:

Click the "New Sandbox" option and then choose to create from a template.
Search templates for "WordPress Block" and choose my template.

You can then open the src/block directory and start working on your block there. I added an block.json file, which sets block attributes, index.js that collects the object of settings you would pass to registerBlockType in your plugin and a componet for the Edit callback, as well as it's tests.

The block is registered for you in the Editor component.

In the Editor component, I commented out this code, beacuse it can make things run very slow if you add a lot of blocks:

  useEffect(() => {
    let previewHtml = serialize(blocks);
    console.log(previewHtml);
  }, [blocks]);

What that does is, every time blocks are updated, it converts them to HTML and echos it. That's cool and useful for testing. Also you could build a live preview with it. Have fun.

Then What

Codesandbox projects can be linked to a git repository. At some point you should start making commits. Once a block is ready, you can add a main plugin file and use the build command of wordpress-scripts. You have a WordPress plugin now!

Have Fun

Follow Me On DEV and Twitter.

Use this button to start your own blocks:

Typed Properties In PHP Are Neato

Josh Pollock — Sat, 01 Feb 2020 23:17:15 +0000

Until recently, for a PHP and JavaScript developer, avoiding bugs caused by variables being the wrong type was difficult, beacuse the langues are not strongly-typed. Thanks to PHP7 and TypeScript, we can opt-in to more type safety, which I like.

PHP7 added scalar type hinting to function parameters, as well as return types. This makes the getter and setter pattern very useful. By protecting a property and a protected property, we can prevent a property from being set to the wrong type -- from outside of the object's scope. This pattern looks like this:

class User {
    /** @var string */
    protected $firstName;

    public function getFirstName(): string {
        return $this->firstName;
    }
    public function setFirstName(string $firstName) : string
    {
        $this->firstName;
        return $this;
    }
}

That's cool, and while it's a lot less boilerplate than it would be in PHP5, it's still a pretty complex way to implement a string property on an object. This class has two public methods that need test coverage, which adds up.

Having a property that acts public, but also is constrained by type, is nice. I think the popularity of Laravel backs up this opinion. And yes, I can use magic methods to make something like a Laravel model.

Also, PHP 7.4 has typed properties and they are neato.

Refactoring PHP With Typed Properties

So, I can now rewrite that class, with no methods:

class User {
    public string $firstName;
}

In addition to being less code, I don't need to write a test for this. However this class gets used in integration tests by other classes, my IDE and a static analysis tool all prevent it from being used wrong.

In the first example, nothing stopped me from setting $firstName to an array from another method of this class. Now the program will not let me make that mistake. Machines are better at remembering stuff than me, so that's great.

But Wait. There Is A Catch!

One catch though, Ok, technically, it's a potential error that you can catch...

You can not read a property before it is set for the first time:

//This works
$user = new User();
$user->firstName = 'Roy';
echo $user->firstName;

//This throws an error
$user = new User();
echo $user->firstName;

This problem is also present in the older method. In both cases, a default value of the property could be set. Or I could just not use the property before setting. Depends on how the program is run. I don't like the possibility of the code being used wrong, beacuse lots of people I don't know run code I write.

One solution is to hardcode the default value:

class User {
    public string $firstName = 'Roy';
}

That keeps the code minimal, which is nice. I do think writing the class so that the property HAS to be set on initialization is a good option as well:

class User {
    public string $firstName;

    public function __construct(string $firstName)
    {
        $this->firstName = $firstName;
    }
}

How To Immutably Update An Array In TypeScript

Josh Pollock — Fri, 31 Jan 2020 22:58:15 +0000

Using an array to collect objects is useful. But, it presents some challenges with searching and updating the data. In React, updating an object in an array will not cause re-renders, adding more complication.

This article does not aim to provide a great explanation of what immutability means in this context. This recent post from CSS tricks explains the concept of immutability in JavaScript quite well.

The Problem

An array is an object, and objects are React's state management tracks objects by reference.


const items = [
  { id: 1, label: 'One' },
  { id: 2, label: 'Two' },
  { id: 3, label: 'Three' },
];

return (
<div>
    <button onClick={() => items.push({id:5})}>Add Item</button>
    {items.map( item => <Item key={item.id} {...item} />)}
</div>

To make this work, we need a new array, not an updated array. Instead of updating the array -- a mutation -- we need to return a new array.

The Solution

I want to avoid clever abstractions on top of array searches and updates that I have. Sorting and searching large collections of objects can become a performance issue. Avoiding an abstraction or dependency helps a bit. So, basically I keep cutting and pasting the same code, so I figured if I put it on dev.to, I could find it via internet search. I'm glad that you may find it useful as well.

These examples work with a collection of objects that use this type:

type field = {
  id: string;
  label: string;
};

You can use whatever type you want. The searches are based off of the id property.

Immutably Adding Or Adding An Item To An Array

This function makes use of Array.findIndex() to locate the index of the field being updated in the collection. If it's not present, the item is added to the array. If the item does is found, the existing items in the array are sliced into two -- the items before and the items after -- with the updated item placed in between:

export const addOrUpdateField = (
  field: field,
  fields: Array<field>
): Array<field> => {
  const index = fields.findIndex((f: field) => field.id === f.id);
  //Not found, add on end.
  if (-1 === index) {
    return [...fields, field];
  }
  //found, so return:
  //Clone of items before item being update.
  //updated item
  //Clone of items after item being updated.
  return [...fields.slice(0, index), field, ...fields.slice(index + 1)];
};

Notice that instead of Array.push(), I'm returning a new array, with the existing items spread in. I can prove that this is returning a different object, with this test:


it('Adds fields immutably', () => {
    const intitalFields = addOrUpdateField({ id: '2', label: 'Two' }, []);
    const fields = addOrUpdateField({ id: '3', label: 'Three' }, intitalFields);
    expect(fields).not.toBe(intitalFields);
  });

It is important to me that adding and removing items maintains order, which is why I used Array.slice(). These tests prove adding and removing works, and maintains the order:

 it('Removes field, maintaining order', () => {
  const intitalFields = addOrUpdateField({ id: '3', label: 'Three' }, [
    { id: '1', label: 'One' },
    { id: '2', label: 'Two' },
  ]);
  expect(intitalFields.length).toBe(3);
  const fields = removeField('2', intitalFields);
  expect(fields.length).toBe(2);
  expect(fields[0].id).toBe('1');
  expect(fields[1].id).toBe('3');
});

it('Adds a field', () => {
  let fields = addOrUpdateField({ id: '3', label: 'Three' }, []);
  expect(fields[0].id).toBe('3');
});

it('Adds a second field', () => {
  const intitalFields = addOrUpdateField({ id: '2', label: 'Two' }, []);
  expect(intitalFields[0].id).toBe('2');
  const fields = addOrUpdateField({ id: '3', label: 'Three' }, intitalFields);
  expect(fields[0].id).toBe('2');
  expect(fields[1].id).toBe('3');
});

Immutably Removing An Item From An Array

Ok, one more thing while I'm here, though this could be it's own post: immutably removing item.

This function also relies on Array.findIndex(). If no item is found, the field collection is returned unmodified. If it is found, I use Array.slice() to cut the array in two again: items before and items after. This time only those two pieces are returned:


export const removeField = (
  fieldId: string,
  fields: Array<field>
): Array<field> => {
  const index = fields.findIndex((f: field) => fieldId === f.id);
  //Not found, return same reference.
  if (-1 === index) {
    return fields;
  }
  //Return clone of items before and clone of items after.
  return [...fields.slice(0, index), ...fields.slice(index + 1)];
};

I can prove that fields are removed, and order is maintained, with this test:

 it('Removes field, maintaining order', () => {
    const intitalFields = addOrUpdateField({ id: '3', label: 'Three' }, [
      { id: '1', label: 'One' },
      { id: '2', label: 'Two' },
    ]);
    expect(intitalFields.length).toBe(3);
    const fields = removeField('2', intitalFields);
    expect(fields.length).toBe(2);
    expect(fields[0].id).toBe('1');
    expect(fields[1].id).toBe('3');
  });

BTW I'm using the addOrUpdateField function, which does make this an integration test, not a unit test. Also, I don't care. I like this kind of functional programming with arrays.

I care that it works the way I want it to. So I care that it updates immutably when used how I'm actually going to use it:

 it('Removes field immutably', () => {
    const intitalFields = addOrUpdateField({ id: '3', label: 'Three' }, [
      { id: '1', label: 'One' },
      { id: '2', label: 'Two' },
    ]);
    const fields = removeField('2', intitalFields);
    expect(fields).not.toBe(intitalFields);
  });

Testing Node's Event Emitter

Josh Pollock — Fri, 24 Jan 2020 21:41:23 +0000

Today at work, I implemented a basic event system using Node's EventEmitter class. I am developing a state management system to aid in migrating a part of a WordPress plugin's admin interface from jQuery and Handlebars to React.

Our immediate goal is to fix some performance issues related to storing state in the DOM. I'm developing this API decoupled from the main Git repo for the plugin so I can work faster. This repo has unit tests, and the main git repo for the plugin will have acceptance tests proving that the system works in the plugin.

One type of test I'd never written before was to cover the events emitted with that event emitter. My logic is that if we're supposed to test our application like it is used, then we should test developer APIs like they are used. Use the comments to tell me any better approaches you may have.

Testing The Event Emitter

The plugin this is for is a form builder plugin. The code being tested manages the state of the forms in the form editor. In the test code below,

it('Emits remove field event', () => {
    // Mock the event callback to see that:
    const callback = jest.fn();

    // This is a factory function
    const state = fieldState([field]);

    //Bind jest's mock function to the event.
    state.feildEvents.on('removeField', fieldId => callback(fieldId));

    //Do the thing that triggers the event
    state.removeField(field.id);

    //Did callback get called once?  
    expect(callback).toBeCalledTimes(1);
    //Did callback get called with the right data?
    expect(callback).toBeCalledWith(field);
});

What I'm doing here is, instantiating my state management system, pretty much how it will actually get used, and then doing the thing that triggers the event and making sure the callback gets the right data.

It Could Be More Isolated

So, yes, this is more of an integration test than a unit test. I could have invoked the event directly. But, I didn't add that event emitter so I'd have something cute to write about on the internet. I needed to do something with the data the callback passes.

The test I wrote looks more like the actual code that is bound to the event I'm testing, than any unit test would look like. I don't care that an instance of EventEmitter emits events, I care that it emits the right event, with the right data at the right time.

I added the event emitter beacuse updating the field list wasn't updating the generated list of "magic tags" -- merge tags based on field values and other settings. So, really the most important tests here were showing that adding and removing fields change the total list of magic tags:

it('Adds field magic tag when adding a field', () => {
    // Start with 1 field
    const state = cfEditorState({
      intialFields: [
        {
         //...
        },
      ],
    });
    // Has one magic tag
    expect(state.getAllMagicTags().length).toBe(1);

    //Add a field
    state.addField({
      //...
    });

     // Has two magic tags
    expect(state.getAllMagicTags().length).toBe(2);
  });

This test covers that the event was fired, with the right data, and had the right effect. I have tests with less scope than that, which were helpful to have on the journey to getting this test to pass. But, this one final test makes sure everything works together.

Typing Events

This passed in my tests, but made compilation fail. The error I had was I was not extending the base event emitter. So when I exported the events object, TypeScript's compiler was not happy. A little googling later and I learned you can't export an internal in TypeScript.

And like, whatever, I found a solution on Github called tsee and it let's me type my events. That's really cool.

The one thing I don't like about event-based architecture is if the code emitting the event changes, the callback can break. This can happen accidently, beacuse it's not always obvious what is bound to an event. Typeing the events should help.

Before I made the change I had:

import EventEmitter from 'events';

I updated that to:

import { EventEmitter } from 'tsee';

Then I was able to type the event emitter:

const fieldEvents = new EventEmitter<{
    addField: (fieldId: fieldId) => void;
    updateField: (args: { fieldId: fieldId; beforeUpdate: field }) => void;
    removeField: (field: field) => void;
  }>();

A Fun Event

Event-based architecture is useful. Instead of piling more responsiblities into a function or file, sometimes it's better to open it to modification from the outside world. But, it also means the function has side effects.

Testing side effects is always difficult, in this post, I've shown one way to test that the data supplied to the callbacks is consistent. In this post you also learned how to use TypeScript to make it harder to make the kinds of mistakes this test prevents. Adding tests, and typing the events does not mean that they can't be consumed incorrectly, but it's a step in the right direction.

Featured image by Anthony Cantin on Unsplash