Forem: Leonardo Losoviz

🙅‍♀️ Why GraphQL should not be in WordPress core

Leonardo Losoviz — Fri, 27 Aug 2021 14:01:56 +0000

This post originally appeared on graphql-api.com/blog/why-graphql-should-not-be-in-wordpress-core.

Yep, you read that title correctly. Even though I am myself the creator of a GraphQL server for WordPress, I've changed my mind concerning if WordPress should ship with GraphQL or not.

Until not long ago, I believed that GraphQL should be in WordPress core. The logic was that contributors were spending time and effort on implementing functionality for the WP REST API (batch operations) which is native to GraphQL.

However, I have lately learnt some new information which made me think again, and now I believe WordPress should not ship with GraphQL, because of the added risks.

These are my reasons.

1. It doesn't satisfy the 80/20 rule

Historically, a certain functionality is added to WordPress core only if it satisfies the 80/20 rule, meaning that 80% or more of the users will use it.

Would that be the case with GraphQL? I think the answer is "no", based on the precedent from the introduction of the WP REST API to WordPress 4.7.

In his talk WordPress as Data, 5 Years In, K. Adam White (main lead of the initial development and release of the WP REST API) described that the contributors expected the REST API to be widely used once it was released with core. But that didn't happen: developers kept creating WordPress sites the same way as before, paying little attention to "headless" or the REST API.

Fortunes changed only later, with the introduction of the Gutenberg editor in WordPress 5.0, which was based on the REST API. Could Gutenberg then justify the addition of GraphQL to WordPress core?

2. Headless is already satisfied via the REST API

The WordPress editor can be enhanced with a native GraphQL server, allowing block developers to use GraphQL (in addition to the existing REST API) to fetch data for their blocks. In addition, themes and plugins could make use of GraphQL to power their own internal functionality. These are strong reasons to add GraphQL to WordPress core.

However, WordPress already has the REST API, and whatever you can do with GraphQL can also be done with REST. Introducing GraphQL in addition to REST is akin to buying a BMW when you're already driving a Toyota. You will reach your destination faster, and the driving experience will be more appealing. But both cars will take you to where you want to go.

Because GraphQL will not provide a previously-unavailable functionality, then its inclusion in core is not fully justified. GraphQL would certainly enhance the experience of interacting with the API, but this could be perfectly considered plugin-land.

3. WordPress themes and plugins can use `webonyx/graphql-php`

Public plugins cannot require a website to install either WPGraphQL or the GraphQL API for WP in order to use the plugin, since that will diminish their potential reach. As such, public plugins cannot rely on GraphQL, and that's a real pity.

I thought hard about this issue, and I came up with a potential solution: the GraphQL API Private, a self-contained GraphQL engine that plugins can embed for their own use, distributed as a Composer package. (I haven't started working on this project yet.)

But then, a few weeks ago, a GraphQL-powered WordPress plugin was released. I wondered how the author did it: would it be using WPGraphQL or the GraphQL API for WP under the hood? So I checked its source code and, as it turns out, it's directly using webonyx/graphql-php!

This is an interesting solution, which demonstrates that, with a bit of effort, developers currently do have access to GraphQL for their themes and plugins.

This plugin uses GraphQL to fetch its own data entities, and not those of WordPress (posts, users, comments, etc). Then, it doesn't need to recreate the GraphQL schema containing the WordPress data model, as done by WPGraphQL and the GraphQL API for WP (and eventually the GraphQL API Private). As such, relying on webonyx/graphql-php makes sense.

4. GraphQL presents additional risks

All three issues above suggest that GraphQL would enhance WordPress, even though it's not extremely compelling. In this light, we could still add GraphQL to WordPress core, and either benefit from it or nothing happens.

But this 4th issue suggests that, if GraphQL will not add much value to WordPress, then it should not be added, because of its added risks.

GraphQL is susceptible to the following attack vectors (among others):

The single endpoint provides access to all information from the website, so we could have private data unintentionally exposed.
The queries can be very complex and may overwhelm the web and database servers.
The same mutation can be executed multiple times in a single query, and multiple queries can be executed together in a single request, allowing attackers to attempt gaining access to the back-end by providing many combinations of user/passwords.

These attacks can be really damaging. In his presentation Damn GraphQL - Defending and Attacking APIs, the cybersecurity researcher Dolev Farhi managed to bring down a WordPress site in less than 30 seconds, by attacking the WPGraphQL endpoint with a batch of complex queries.

The WPGraphQL team fixed the issue immediately. But how can we be sure that no other exploit can take place? (I mean not only WPGraphQL, but the GraphQL API for WP too.)

These attacks can happen with GraphQL, and not with REST, because GraphQL is more powerful than REST. While in REST the query is defined in advance and stored in the server, in GraphQL it is provided on runtime by the client (unless using persisted queries).

If website admins are sloppy configuring who can access the endpoint, or which data gets exposed, then bad things can happen. And due to the popularity of WordPress, which is used by millions of people who are not tech-savvy, then bad things will most likely happen.

Wrapping up

Just to be sure: I am not advocating to not use GraphQL in WordPress (of course I am not!), but to use GraphQL responsibly. GraphQL is powerful, which means it is dangerous. When using GraphQL, we need to be sure we know what we are doing.

Shipping GraphQL in WordPress core would put it in the hands a lot of people, many of which will not be aware of its risks, and not take appropriate measures. It's a recipe for potential disaster. And as such, it is now my opinion, it should be avoided.

Version 0.8 of the GraphQL API for WordPress is now available 🚀

Leonardo Losoviz — Sat, 31 Jul 2021 09:46:03 +0000

Version 0.8 of the GraphQL API for WordPress is now available for download 🎉

This release focuses on three areas:

Refactoring the codebase to enable extensions
Further satisfying the GraphQL specification
Completing the GraphQL schema

Release notes: https://graphql-api.com/blog/released-graphql-api-v08/

👨🏻‍💻 Demoing the GraphQL API for WordPress

Leonardo Losoviz — Thu, 22 Apr 2021 14:25:39 +0000

Several weeks ago I talked about GraphQL on WordPress, for WordCamp India 2021. I explored these topics:

👉🏽 What is GraphQL?
👉🏽 How is it different from REST?
👉🏽 How do we use it with WordPress?

Alongside, I did a demo of the GraphQL API for WordPress plugin. It's all me showing how to use the plugin in the wp-admin, for some 30 min.

Here is the video:

The following features were covered:

✅ The GraphiQL and Voyager clients
✅ Persisted queries
✅ Passing parameters by URL to the persisted query
✅ HTTP caching
✅ Access control
✅ Making the API public and private

We also had a Q&A session, which lasted 15 min. Here is the video:

The Q&A include the following questions, and at what time they appear:

❓ Will the hosting provider support GraphQL, or do we need to manage it on our own? (1:25)
❓ How extensible is it, compared to the WP REST API? (1:55)
❓ Is multilingual search supported in GraphQL? (answer is not clear, connection problems) (2:39)
❓ How do we secure the GraphQL API? (3:48)
❓ Why is the GraphQL API for WordPress plugin not officially available in the WordPress plugin repository? (6:48)
❓ What is the limit for GraphQL? (8:08)
❓ If somebody wants to dive into GraphQL, what's your advice for them? (10:21)
❓ What can we expect from you should you present a new talk about GraphQL in another WordCamp? (12:08)

As I mentioned at the end of the Q&A, if you like what you see, and you'd like to learn more, or get your hands dirty using it and need help, send me an email or DM on Twitter. I'm generally available, and always thrilled to work on the combination of WordPress and GraphQL 🙏

I hope you enjoy the demo 😀

👶🏻 Rejuvenating WordPress through GraphQL

Leonardo Losoviz — Thu, 15 Apr 2021 12:52:58 +0000

WordPress is a legacy CMS: having been invented over 17 years ago, it's filled with PHP code that, given a new chance, it would be coded in a different way.

GraphQL is a modern interface to access data. Please notice the word "interface": it doesn't care how the underlying data system is implemented, but only how to expose the data.

What happens when we put these two together? How should we design the GraphQL interface to access data from WordPress?

There are a couple of obvious strategies that we can put in place:

Respect tradition, and provide a mapping that keeps the WordPress data model as is, including the technical debt it accumulated during the years
Fix the technical debt, providing an interface exposing data in an abstract, not-necessarily-fixed-to-WordPress way

Both approaches have benefits and drawbacks, and there is no right or wrong. It's just opinionatedness, prioritizing some behavior over another.

For plugin GraphQL API for WordPress I have chosen the latter approach, attempting to create a GraphQL schema that, even though it is based on WordPress and works for WordPress, it is not tied to WordPress (for instance, by removing inconsistent names and relationships).

The result is that GraphQL rejuvenates WordPress: while we still have WordPress as our underlying CMS, with its legacy PHP code, its data layer can be created anew, based on common sense, not tradition. The data layer goes back from being an adolescent, to become a toddler again.

The result is this GraphQL schema, representing the WordPress data model, and also supporting nested mutations.

Let's check out it was carried out.

The WordPress data model

WordPress has the following entities:

posts
pages
custom posts
media elements
users
user roles
tags
categories
comments
blocks
meta properties
others (options, plugins, themes, etc)

These entities can have a hierarchy. For instance, post, page and media elements are both custom post types, and tags and categories are both taxonomies.

This is the WordPress database diagram, showing how data for all entities is stored:

Is the mapping an exact replica of the DB diagram?

When mapping the WordPress database into a GraphQL schema, is the same diagrame above respected 1 to 1?

No, it is not. While the database diagram is an actual implementation, GraphQL is an interface to access the data from the client. These two are related, but they can be different. GraphQL doesn't care about the database: it doesn't think in SQL commands, or know there are database tables called wp_posts and wp_users.

So we don't need to worry too much about the database diagram when creating the GraphQL schema for WordPress. That means that we can produce a GraphQL schema that fixes some of the technical debt from the WordPress data model.

Mapping the WordPress data model as a GraphQL schema

Let's do the mapping. First, we map the original entities as types, as much as possible. From the list of entities in the WordPress data model, we produce the following types for the GraphQL schema:

Post
Page
Media
User
UserRole
PostTag
PostCategory
Comment

Then, we add all the expected fields to every type. To represent the schema, we can use the SDL, or Schema Definition Language. (This is used for documentation purposes only; the plugin itself does not use SDL to codify the schema: it's all PHP code).

These are the fields (among many others) for a Post:

type Post {
  id: ID!
  title: String
  content: String
  excerpt: String
  date: Date!
}

These are the fields (among many others) for a User:

type User {
  id: ID!
  name: String
  email: String!
}

We also create the corresponding connections, which are fields that return another entity (instead of a scalar, such as a number or a string). For instance, we represent a post having an author, and a user owning posts:

type Post {
  author: User!
}

type User {
  posts: [Post]
}

Fields and connections can also accept arguments. For instance, we enable Post.date to be formatted, and User.posts to search entries and limit their number:

type Post {
  date(format: String): Date!
}

type User {
  posts(limit: Int, search: String): [Post]
}

We keep doing this for all entities in the WordPress data model. Once we are done, we'll arrive at the GraphQL schema for WordPress, as visible using the Voyager client (available as "Interactive Schema" on the plugin's menu):

This schema has similarities to the WordPress database diagram, but also many differences. Let's analyse them.

Operations without entity are mapped as Root fields

In the WordPress database diagram represents how data is stored, so there is no "beginning". GraphQL, though, is an interface to retrieve data, hence there must be an initial stage from which to execute the query.

This initial stage is the Root type, or, to be more precise, the QueryRoot and MutationRoot types (to deal with queries and mutations, respectively).

In these two types, we map all operations that do not depend on an entity, such as when executing get_posts(), get_users() or wp_signon():

type QueryRoot {
  posts: [Post]!
  users: [User]!
}

type MutationRoot {
  logUserIn(username: String, password: String): User
}

The fields do not need to have the same name or signature as the operation they represent. For instance, calling field logUserIn can be considered more suitable than signOn.

All mutations go under MutationRoot

There are operations which do depend on an entity, such as wp_update_post(), which is applied on some post. The corresponding mutation on the GraphQL schema must be added to the MutationRoot type, because that's how GraphQL works.

Then, this operation is mapped like this:

type MutationRoot {
  updatePost(postID: ID!, newTitle: String, newContent: String): Post
}

This plugin also supports nested mutations, which are offered as an opt-in feature (because this is not standad GraphQL behavior). Then, mutations can also be added under any type, not just MutationRoot. In this case, we obtain:

type Post {
  update(newTitle: String, newContent: String): Post!
}

Dealing with custom posts

There is no type inheritance in GraphQL. Hence, we can't have a type CustomPost, and declare that Post and Page extend it.

GraphQL offers two resources to compensate for this lack: interfaces and union types.

For the first one, we create an interface IsCustomPost for the schema, declaring all the fields expected from a custom post, and we define types Post and Page to implement the interface:

interface IsCustomPost {
  title: String
  content: String
  excerpt: String
  date(format: String): Date!
}

type Post implements IsCustomPost {
  title: String
  content: String
  excerpt: String
  date(format: String): Date!
}

type Page implements IsCustomPost {
  title: String
  content: String
  excerpt: String
  date(format: String): Date!
}

For the second one, we create a CustomPostUnion type for the schema returning all the custom post types:

union CustomPostUnion = Post | Page

And have fields return this type whenever appropriate:

type QueryRoot {
  customPost(id: ID): CustomPostUnion
  customPosts: [CustomPostUnion]!
}

type User {
  customPosts: [CustomPostUnion]
}

type Comment {
  customPost: CustomPostUnion!
}

As it can be observed, in the GraphQL schema we need to explicitly assert when we are dealing with posts, and when with custom posts, since they are not the same! Calling these two interchangeably is technical debt from WordPress, which we can fix.

For this reason, a custom post is always called CustomPost and not Post, a field dealing with custom posts is always called customPosts and not posts, and a field argument receiving the ID for a custom post is called customPostID and not postID (even though that's how it's called in the mapped WordPress function).

Then, the expectation is always clear:

field User.customPosts can return a list of any custom post, including posts and pages, and User.posts only returns posts
field Root.setFeaturedImageOnCustomPost can add a featured image to any custom post, that's why it's not called setFeaturedImageOnPost

Not grouping tags (and categories) under a single type

Why is type PostTag (and same for PostCategory) called like that, instead of just Tag?

Because, when executing this query (where a product is a CPT), the results from field tags for posts and products will always be different, non-overlapping:

query {
  posts {
    tags {
      id
      name
    }
  }
  products {
    tags {
      id
      name
    }
  }
}

Tags added to posts will not show up when retrieving tags for products, and the other way around (unless a product also uses the post_tag taxonomy, but then it can also be represented with the PostTag type). This does not represent a big deal in WordPress, since these items can be considered different rows from the same database table. But it does matter for GraphQL, which is strongly typed.

Then, it's a good design decision to keep these entities separate, under their own types, and have tags for posts returned under the PostTag type and, if a custom plugin implements its own product CPT, it must use the ProductTag type for its tags.

Giving media items their own identity

Media entities in WordPress are custom post types, only because it was convenient from an implementation point of view. However, the GraphQL schema can avoid this technical debt, and model media elements as a distinct entity, not as custom posts.

This implies the following decisions for the GraphQL schema:

When querying field customPosts, it will not fetch media elements
The Media type does not implement the IsCustomPost interface, and won't be part of the CustomPostUnion type
The Media type doesn't have many fields expected from a custom post type, such as excerpt, date and status. Instead, it only has those fields expected from a media element:

type Media {
  id: ID!
  src: String!
  width: Int
  height: Int
}

Identifying and mapping enums

In some situations, WordPress uses fixed values from a given set. For instance, the status of a post can only be "publish", "draft", "pending" or "trash".

In GraphQL, we can treat these as enums (instead of strings), and create a corresponding enumeration type. Following the GraphQL standard, enums should be written in uppercase, like this:

enum CUSTOM_POST_STATUS {
  PUBLISH
  DRAFT
  PENDING
  TRASH
}

However, then the query can't be directly used to interact with WordPress, since executing get_posts( [ "post_status" => "PUBLISH" ] ) doesn't work.

So, as a compromise, we keep these enum values in lowercase:

enum CUSTOM_POST_STATUS {
  publish
  draft
  pending
  trash
}

Mapping additional types

Blocks are not directly visible in the WordPress database diagram, since they are stored in wp_posts (there is no table wp_blocks), but nevertheless thay are a distinct entity.

Hence, we introduce the type Block to map them:

type Post {
  blocks: [Block]
}

type Block {
  type: String!
  attributes: JSONObject
}

🍾 GraphQL API for WordPress is now scoped, thanks to PHP-Scoper!

Leonardo Losoviz — Wed, 31 Mar 2021 13:08:38 +0000

This post was originally published in graphql-api.com

Plugin GraphQL API for WordPress is now scoped. This means the plugin can be finally uploaded to the WordPress plugin directory.

To do it, I'm using the wonderful PHP-Scoper. Using this library with WordPress does not go without its challenges, so I'll explain in this blog post how I managed to pull it out.

Sections:

Taking the decision to scope
Checking out the options
Trying out Mozart, and failing
Checking PHP-Scoper, and coming out in panic
Coming back to PHP-Scoper, this time for good
PHP-Scoper, the easy way 😎 👈🏽 Here starts my solution
Show me the real stuff
Testing
Check out the results

Taking the decision to scope

A few weeks ago, Matt Mullenweg announced he'll be keeping an eye on "the GraphQL plugin", obviously referring to WPGraphQL. His expression demonstrates that he believes there is only one GraphQL plugin, when in fact there are two (the one left out is, well, mine). That made me realize how little visibility my plugin has, and I felt bad about it.

Matt didn't know my plugin existed. Nor does most of the WordPress community, for that matter. Clearly I'm not publicizing it well enough. I know that I suck in marketing and social media; I'm just OK with technical stuff (or so I believe). So I decided to do something about it, at least within my capabilities.

So this is what I'm working on:

I just finished coding this same website, graphql-api.com, and launched it 2 weeks ago (yay! 🥳 Btw, how do you like it? Be welcome to give me feedback, via DM or email)
3 days ago, I finally started scoping the plugin, and finished this task yesterday! (At 3 am, but it was worth it 😅)
And finally, I'm already working on the upcoming version 0.8, which will be the first one available in the plugin repository

Scoping the plugin is mandatory to upload it to the repository, because otherwise it could conflict with a different plugin, which requires the same dependency as my plugin, but with a different version. Having done it is a really big milestone; no other development is as important. For instance, I must still complete the GraphQL schema to fully match the WordPress data model, but that will be done steadily on each new release.

So in a few weeks from now, the plugin will show up when searching for "GraphQL", and the people who are actually needing to implement a GraphQL API will get to know of my plugin's existence.

Indeed, I do want my plugin to be seriously considered for the future of WordPress. I've been working on it for several years now. The repo was started back in August 2016; that is even before WPGraphQL existed, and at the beginning of GraphQL. But I didn't know that the project would become a GraphQL server; it took that direction only around 1.5 years ago.

(The project is actually a framework to build applications using server-side components, and a GraphQL server could perfectly be built using this architecture. So then I just built it).

WPGraphQL is an established plugin, and rightly so: it was started a few years ago, and a community was built around it. The work by Jason Bahl (who was until recently employed by Gatsby) and the contributors to his project has been outstanding: integrating WordPress into the Jamstack is now easier than ever.

But one thing is Gatsby and the Jamstack, and another thing is WordPress. WordPress is 40% of the web, not just an input to a static site generator.

So now, we can consider if WPGraphQL is the right option, without having this decision taken for us out of lack of alternatives. We can now analyze both plugins to see whose goals are more aligned to what's important for WordPress.

The GraphQL API for WordPress can also work with the Jamstack. But its main objectives are, I believe, more splendid: To "democratize data publishing", so that editing an API becomes as easy as editing a post (something everyone can do), and to make WordPress become the OS of the web.

Once the plugin is available on the repository, I hope more people will try it out and say "Hey, this is so friking awesome! How comes I didn't know about this stuff before?".

And then, the choice of "the GraphQL plugin" is not pre-determined, and the WordPress community can consider both WPGraphQL and the GraphQL API for WordPress based on their own merits.

Now that my motivations are out of the way, let's talk technical stuff 🤓.

Checking out the options

Scoping a plugin involves running some tooling, that takes the plugin code as input, and spits out the scoped plugin. No big deal, right? How hard can that be?

Well, depending on the codebase, just executing the scope command alone won't be enough. After that, we need to check for errors in the console, fix them, test the application thoroughly, identify errors and why they happen, fix them, and iterate. To get it completely right, it might require some time.

There are 2 libraries for scoping, which have different goals:

Mozart, for WordPress code
PHP-Scoper, for any PHP code, particularly when producing PHARs

Because I have a WordPress plugin, I tried out Mozart first. Let's see how it fared.

Trying out Mozart, and failing

I tried Mozart around 1 year ago. For what it says in the documentation, "the mozart compose command does all the magic". So I expected it all to be very quick and simple, and go enjoy a daiquiri for the rest of the day.

Alas, Mozart never worked for my codebase. It kept running into issues, so the scoping never materialized. And I couldn't get the required assistance: I submitted a PR, but it was not considered for merging, and I was not even notified about it, so I kept waiting until I naturally lost interest in this project.

I believe that Mozart couldn't handle some of the dependencies in my plugin. I'm making use of several of Symfony's components, including DependencyInjection, Cache and Dotenv, with everything managed through Composer.

Scoping PHP is not just about PHP, so the scoper will have many hurdles to avoid and challenges to solve. For instance, Symfony DependencyInjection uses YAML files to set-up configuration, and these must be scoped too. And the composer.json file contains the configuration for PSR-4 autoloading, and this must be scoped too. And, I believe, Mozart couldn't handle these complexities properly.

But I'm sure that my experience is not the only one, and that there are many happy users our there. Also, my failed attempt happened 1 year ago, so I wonder if the tool has been improved since then. And then, don't forget the saying: "All scoped plugins are alike; each unscoped plugin is unscoped in its own way", so possibly it fails just for me.

If your WordPress plugin is simple, with self-contained logic, and scoping must be performed within PHP code only, then chances are that Mozart will work. You just gotta find out.

Checking PHP-Scoper, and coming out in panic

So I headed for PHP-Scoper. However, I never even tried to try it, because I got frightened immediately by it.

To start with, this tool does not naturally support WordPress. And to continue, they recommend to take a look at their own Makefile, which looks like this:

# See https://tech.davis-hansson.com/p/make/
MAKEFLAGS += --warn-undefined-variables
MAKEFLAGS += --no-builtin-rules

.DEFAULT_GOAL := help

PHPBIN=php
PHPNOGC=php -d zend.enable_gc=0
IS_PHP8=$(shell php -r "echo version_compare(PHP_VERSION, '8.0.0', '>=') ? 'true' : 'false';")

SRC_FILES=$(shell find bin/ src/ -type f)

.PHONY: help
help:
    @echo "\033[33mUsage:\033[0m\n  make TARGET\n\n\033[32m#\n# Commands\n#---------------------------------------------------------------------------\033[0m\n"
    @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//' | awk 'BEGIN {FS = ":"}; {printf "\033[33m%s:\033[0m%s\n", $$1, $$2}'


#
# Build
#---------------------------------------------------------------------------

.PHONY: clean
clean:   ## Clean all created artifacts
clean:
    git clean --exclude=.idea/ -ffdx

update-root-version: ## Check the lastest GitHub release and update COMPOSER_ROOT_VERSION accordingly
update-root-version:
    rm .composer-root-version || true
    $(MAKE) .composer-root-version

And 600 more lines, all like this. It looks like a riddle. Believing that I needed to understand that code just to scope my plugin, made me flee unceremoniously.

(Well, understanding that code is their recommendation to test the scoped application, but it is not required. We can also just run the command php-scoper add-prefix, let it do all the magic, and go drink our daiquiris.)

Coming back to PHP-Scoper, this time for good

So, 3 days ago, I took a decision to implement scoping, somehow. I had to make it happen.

I came back to PHP-Scoper, to try it out in earnest. I knew that WordPress could be scoped with it from reading PHP Scoper: How to Avoid Namespace Issues in your Composer Dependencies (by the brilliant folks from Delicious Brains). It was just a matter of attitude, and perseverence.

I explored some of the existing solutions, including:

This one by Lucas Bustamante
This one by Yoast
This one by Google Site Kit
This one by Google Web Stories

But they all look not fully satisfying to me: either the code seems hacky, or fragile and waiting to break at some time or another.

For instance, the Google Web Stories plugin scopes the code, and then reverts back each one of the conflicts:

return [
  'patchers'                   => [
        function ( $file_path, $prefix, $contents ) {
            /*
             * There is currently no easy way to simply whitelist all global WordPress functions.
             *
             * This list here is a manual attempt after scanning through the AMP plugin, which means
             * it needs to be maintained and kept in sync with any changes to the dependency.
             *
             * As long as there's no built-in solution in PHP-Scoper for this, an alternative could be
             * to generate a list based on php-stubs/wordpress-stubs. devowlio/wp-react-starter/ seems
             * to be doing just this successfully.
             *
             * @see https://github.com/humbug/php-scoper/issues/303
             * @see https://github.com/php-stubs/wordpress-stubs
             * @see https://github.com/devowlio/wp-react-starter/
             */
            $contents = str_replace( "\\$prefix\\_doing_it_wrong", '\\_doing_it_wrong', $contents );
            $contents = str_replace( "\\$prefix\\__", '\\__', $contents );
            $contents = str_replace( "\\$prefix\\esc_html_e", '\\esc_html_e', $contents );
            $contents = str_replace( "\\$prefix\\esc_html", '\\esc_html', $contents );
            $contents = str_replace( "\\$prefix\\esc_attr", '\\esc_attr', $contents );
            $contents = str_replace( "\\$prefix\\esc_url", '\\esc_url', $contents );
      $contents = str_replace( "\\$prefix\\do_action", '\\do_action', $contents );
      // ...
    }
  ]
]

I understand why they do it, but I don't like it. Whenever a new WordPress function gets referenced, they need to make sure it also makes it to this list. It's too manual, too fragile.

So this was my challenge: Isn't there a simpler way to scope a plugin, and relying on code that we can present to our friends and colleagues without blushing?

PHP-Scoper, the easy way 😎

It actually turned out to be easier than I thought! In just a few hours, I had it all working.

Now, when I say "easy" and "hours", I actually mean: It all worked immediately, but only after spending 2 months creating the proper structure for the codebase (I'll explain better later on).

But the important thing is: If you have the right set-up for the project, scoping it can be accomplished in no time.

The problem with scoping WordPress code is, well, WordPress code. The issue is explained here, but it boils down to all WordPress functions and classes being namespaced too. So if we reference WP_Query or call get_posts in our code, these will be transformed to MyPrefixedNamespace\WP_Query and MyPrefixedNamespace\get_posts, producing an epic fail on runtime. And that cannot be avoided in PHP-Scoper without hacks.

So, what is the solution to this? Easy peasy: don't reference WP_Query, or call get_posts, or use any WordPress code in the codebase that will be scoped.

No, I'm not crazy, and I'm sure you're not either. And yeah, I know that we're building a WordPress plugin... Let me explain.

How can we not include WordPress code? By splitting the codebase into 2 sets of packages:

Those containing WordPress code, without referencing code from any external library
Those containing business logic, without containing any WordPress code, and including all required dependencies and references to their code

This way, instead of having a single codebase, we have multiple codebases (or packages), where some of them will get scoped and some not, and they all form the plugin, tied together via Composer.

Then, we do not scope the package containing WordPress code, avoiding the conflict. This works because it doesn't reference any code belonging to any external dependency. All references are internal, such as MyNamespace\MyPlugin\MyClass. But these need not be scoped, because we can safely assume that there will be only 1 version of the plugin installed in the WordPress site, and we can whitelist our namespace MyNamespace\*.

Moreover, if our plugin can be extended, then whitelisting our own namespace is mandatory. For instance, a field resolver for the GraphQL API for WordPress is implemented by extending from class PoP\ComponentModel\FieldResolvers\AbstractFieldResolver. If I scoped it, developers would be forced to reference PoP\ComponentModel\FieldResolvers\AbstractFieldResolver for development, and PrefixedByPoP\PoP\ComponentModel\FieldResolvers\AbstractFieldResolver for production. That's a no go.

Then, we only scope the business-logic packages, which contain references to all external libraries but no WordPress code.

In summary, we are switching this strategy:

"Have a single codebase, scope it, and then painfully and with plenty of patience undo the damage, while praying that no conflict goes unnoticed and it 💣 booms in production"

To this one:

"Split up the codebase into 2 groups, scope only the one containing the references to the external dependencies and no WordPress code, and go have your well-earned daiquiri 🍹".

Show me the real stuff

It's time open up the sausage and see if it has real meat inside 🌭.

4 days ago, I had the following code in my plugin:

namespace GraphQLAPI\GraphQLAPI\ContentProcessors;

use Parsedown;

class MarkdownContentParser
{
  protected function getHTMLContent(string $fileContent): string
  {
    return (new Parsedown())->text($markdownContent);
  }
}

Class Parsedown comes from the external dependency erusev/parsedown, as defined in the plugin's composer.json:

{
  "require": {
    "erusev/parsedown": "^1.7"
  }
}

Hence, my plugin contained references to an external library, so I needed to scope it, to transform Parsedown into PrefixedByPoP\Parsedown. But doing so would also scope all WordPress code in the plugin, causing the conflicts.

So I extracted the code into a separate package, called graphql-api/markdown-convertor, and replaced the 3rd-party dependency in composer.json with my own dependency:

{
  "require": {
    "graphql-api/markdown-convertor": "^0.8"
  }
}

Now, the plugin avoids referencing the external library; instead, it references the service MarkdownConvertorInterface from the new package:

namespace GraphQLAPI\GraphQLAPI\ContentProcessors;

use GraphQLAPI\MarkdownConvertor\MarkdownConvertorInterface;

class MarkdownContentParser extends AbstractContentParser
{
    protected MarkdownConvertorInterface $markdownConvertorInterface;

    function __construct(MarkdownConvertorInterface $markdownConvertorInterface)
    {
        $this->markdownConvertorInterface = $markdownConvertorInterface;
    }

    protected function getHTMLContent(string $fileContent): string
    {
        return $this->markdownConvertorInterface->convertMarkdownToHTML($fileContent);
    }
}

Referencing the 3rd-party dependency is done in the new package:

namespace GraphQLAPI\MarkdownConvertor;

use Parsedown;

class MarkdownConvertor implements MarkdownConvertorInterface
{
  public function convertMarkdownToHTML(string $markdownContent): string
  {
    return (new Parsedown())->text($markdownContent);
  }
}

Finally, we must:

Scope dependency graphql-api/markdown-convertor
Skip scoping the plugin code
Whitelist namespace GraphQLAPI\*, to avoid my own classes from being scoped

This is pretty much the strategy. From now on, it will be a repetition of this same idea, to remove all external dependencies from the code, until voilà, the plugin can be scoped.

The dependencies to extract are only those from the require section on your composer.json file; for require-dev you can keep any dependency, external or not, since we don't need to scope dependencies used for development; only those ones to create and ship the plugin, for production, need be scoped.

At the end, the composer.json from your plugin should not contain any external dependency. For my plugin, it looks like this:

{
  "require": {
    "php": "^7.4|^8.0",
    "getpop/engine-wp": "^0.8",
    "graphql-api/markdown-convertor": "^0.8",
    "graphql-by-pop/graphql-clients-for-wp": "^0.8",
    "graphql-by-pop/graphql-endpoint-for-wp": "^0.8",
    "graphql-by-pop/graphql-server": "^0.8",
    "pop-schema/basic-directives": "^0.8",
    "pop-schema/comment-mutations-wp": "^0.8",
    "pop-schema/commentmeta-wp": "^0.8",
    "pop-schema/comments-wp": "^0.8",
    "pop-schema/custompost-mutations-wp": "^0.8",
    "pop-schema/custompostmedia-mutations-wp": "^0.8",
    "pop-schema/custompostmedia-wp": "^0.8",
    "pop-schema/custompostmeta-wp": "^0.8",
    "pop-schema/generic-customposts": "^0.8",
    "pop-schema/media-wp": "^0.8",
    "pop-schema/pages-wp": "^0.8",
    "pop-schema/post-mutations": "^0.8",
    "pop-schema/post-tags-wp": "^0.8",
    "pop-schema/posts-wp": "^0.8",
    "pop-schema/taxonomymeta-wp": "^0.8",
    "pop-schema/taxonomyquery-wp": "^0.8",
    "pop-schema/user-roles-access-control": "^0.8",
    "pop-schema/user-roles-wp": "^0.8",
    "pop-schema/user-state-mutations-wp": "^0.8",
    "pop-schema/user-state-wp": "^0.8",
    "pop-schema/usermeta-wp": "^0.8",
    "pop-schema/users-wp": "^0.8"
  }
}

All those packages, with namespaces getpop, graphql-api, graphql-by-pop, and pop-schema, are all mine: dependencies containing the whole code for the plugin. They are distributed into different namespaces to better manage the code, but you don't need to: using a single namespace works well.

Now, as the number of packages in your application grows, you'll need to have them all hosted in a monorepo, or you'll go bunkers creating pull requests involving more than one package (believe me, I've been there). In my case, all my packages are hosted in the leoloso/PoP monorepo, and I keep them in sync via the wonderful Monorepo Builder (I need to write an article about this tool, it's such a life saver!).

The namespaces for these packages are PoP, GraphQLAPI, GraphQLByPoP and PoPSchema. Since they are mine, I know they will appear only once in the application, and so I can avoid scoping them.

To do that, I whitelist them in scoper.inc.php:

return [
  'whitelist' => [
    // Own namespaces
    'PoPSchema\*',
    'PoP\*',
    'GraphQLByPoP\*',
    'GraphQLAPI\*',
    // Own container cache
    'PoPContainer\*',
  ],
];

The last entry corresponds to the dependency injection container, which also needs be scoped. By default, this container is assigned name ProjectServiceContainer, directly in the global namespace. But PHP-Scoper doesn't support whitelisting specific classes from the global namespace. Hence, I added the artificial namespace PoPContainer to the whitelist, and assigned this namespace when dumping the container to disk:

$dumper = new PhpDumper($containerBuilder);
file_put_contents(
  self::$cacheFile,
  $dumper->dump(
    // Save under own namespace to avoid conflicts
    array('namespace' => 'PoPContainer')
  )
);

You may notice that, concerning the packages, some of them end with -wp (like pop-schema/users-wp) while some don't (like graphql-by-pop/graphql-server). Yep, you guessed it right: the former ones contain WordPress code and no references to external libraries, and the latter ones can contain references to external libraries, but no WordPress code whatsoever.

Then, I skip scoping the WordPress packages:

return [
  'finders' => [
    // Scope packages under vendor/, excluding local WordPress packages
    Finder::create()
      ->files()
      ->notPath([
        // Exclude libraries ending in "-wp"
        '#getpop/[a-zA-Z0-9_-]*-wp/#',
        '#pop-schema/[a-zA-Z0-9_-]*-wp/#',
        '#graphql-by-pop/[a-zA-Z0-9_-]*-wp/#',
      ])
      ->in('vendor')
  ]
];

What happens if some WordPress package needs to reference an external library, and this cannot be extracted into another package? For instance, my package getpop/routing-wp depends on brain/cortex, and this is unavoidable.

I can't scope the whole package, since getpop/routing-wp contains WordPress code. Instead, what I do is to identify the files where those references are done, and make sure that they do not contain any WordPress code. Then I can scope those files only.

In this case, the reference to Cortex/Brain is done in 2 files, including layers/Engine/packages/routing-wp/src/Hooks/SetupCortexHookSet.php:

namespace PoP\RoutingWP\Hooks;

use PoP\Hooks\AbstractHookSet;
use Brain\Cortex\Route\RouteCollectionInterface;
use Brain\Cortex\Route\RouteInterface;
use Brain\Cortex\Route\QueryRoute;
use PoP\RoutingWP\WPQueries;
use PoP\Routing\Facades\RoutingManagerFacade;

class SetupCortexHookSet extends AbstractHookSet
{
  protected function init()
  {
    $this->hooksAPI->addAction(
      'cortex.routes',
      [$this, 'setupCortex'],
      1
    );
  }

  /**
   * @param RouteCollectionInterface<RouteInterface> $routes
   */
  public function setupCortex(RouteCollectionInterface $routes): void
  {
    $routingManager = RoutingManagerFacade::getInstance();
    foreach ($routingManager->getRoutes() as $route) {
      $routes->addRoute(new QueryRoute(
        $route,
        function (array $matches) {
          return WPQueries::STANDARD_NATURE;
        }
      ));
    }
  }
}

Can you notice the oddity here? This is an implementation of a hook, but no add_action is called, since I can't have any WordPress code here. Instead, it calls function addAction from service HooksAPIInterface, and this service is implemented by class HooksAPI in package getpop/hooks-wp, where we can have WordPress code:

namespace PoP\HooksWP;

use PoP\Hooks\HooksAPIInterface;

class HooksAPI implements HooksAPIInterface
{
  public function addAction(string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1): void
  {
    add_action($tag, $function_to_add, $priority, $accepted_args);
  }
}

Now that the code is cleanly split, we can scope those 2 files referencing external dependencies:

return [
  'finders' => [
    Finder::create()->append([
      'vendor/getpop/routing-wp/src/Component.php',
      'vendor/getpop/routing-wp/src/Hooks/SetupCortexHookSet.php',
    ])
  ]
];

Earlier on I mentioned that setting-up the scoping took a few hours, but only after 2 months of work. Well, this example demonstrates what I meant: The actual work lies in dividing the codebase cleanly into the 2 sets.

In my case, the work took 2 months because the level of detail was extreme: The plugin became a composition of 125 packages! But this is an exceptional case, with the goal to have GraphQL by PoP (the underlying server for the plugin) be CMS-agnostic, as to support an implementation for other CMSs/frameworks just by reimplementing the corresponding -wp packages.

(I wrote in detail about this strategy, in article Abstracting WordPress Code To Reuse With Other CMSs: Concepts and Implementation.)

It's certainly quite some work, but the improved cleanliness of the code makes it worth it. And not just for scoping the plugin, which came as a total surprise to me, and I'm still gidding in my unexpected happiness. For instance, I run PHPStan and PHPUnit separately on WordPress and non-WordPress code, avoiding me many headaches.

Once the codebase is tidied-up, the world suddenly becomes such a better place.

Testing

So, how do we test this beast?

The solution I came up with is to rely on Rector, the same tool I use for downgrading code from PHP 7.4, for development, to 7.1, for production.

The idea is the following:

Scope the plugin
Analyze it with Rector, applying any rule (it doesn't matter which one)

If something went wrong when scoping, then Rector won't be able to load some class, and it will throw an error. For instance, if class Brain\Cortex was scoped as PrefixedByPoP\Brain\Cortex, but some reference to it was left as Brain\Cortex, then autoloading this class will fail.

This is my GitHub Action for testing (working-directory is being used, because I'm operating from the root of the monorepo, but the scoping happens on the plugin folder):

name: Scope GraphQL API for WP tests
on:
  push:
    branches:
      - master
  pull_request: null

env:
  COMPOSER_ROOT_VERSION: "dev-master"

jobs:
  main:
    defaults:
      run:
        working-directory: layers/GraphQLAPIForWP/plugins/graphql-api-for-wp

    name: Scope the plugin code via PHP-Scoper, and execute tests

    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set-up PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 7.4
          coverage: none
        env:
          COMPOSER_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Install root dependencies
        uses: "ramsey/composer-install@v1"

      - name: Install plugin dependencies for PROD
        run: composer install --no-dev --no-progress --no-interaction --ansi

      - name: Install PHP-Scoper
        run: |
          composer global config minimum-stability dev
          composer global config prefer-stable true
          composer global require humbug/php-scoper

      # The scoped results correspond to vendor/, so must generate them in such folder
      - name: Scope plugin into separate folder
        run: php-scoper add-prefix --output-dir ../../../../build-prefixed/vendor --ansi

      - name: Copy scoped code back into plugin
        run: rsync -av build-prefixed/ layers/GraphQLAPIForWP/plugins/graphql-api-for-wp/ --quiet
        working-directory: .

      - name: Regenerate autoloader
        run: composer dumpautoload --optimize --classmap-authoritative --ansi

      - name: Run Rector on the scoped code
        run: vendor/bin/rector process --config=layers/GraphQLAPIForWP/plugins/graphql-api-for-wp/rector-test-scoping.php --ansi
        working-directory: .

And this is my Rector configuration:

use Rector\CodeQuality\Rector\LogicalAnd\AndAssignsToSeparateLinesRector;
use Rector\Core\Configuration\Option;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $containerConfigurator): void {
  $services = $containerConfigurator->services();
  $services->set(AndAssignsToSeparateLinesRector::class);
  $parameters->set(Option::AUTO_IMPORT_NAMES, true);

  $parameters->set(Option::AUTOLOAD_PATHS, [
    __DIR__ . '/vendor/scoper-autoload.php',
    __DIR__ . '/vendor/erusev/parsedown/Parsedown.php',
    __DIR__ . '/vendor/jrfnl/php-cast-to-type/cast-to-type.php',
    __DIR__ . '/vendor/jrfnl/php-cast-to-type/class.cast-to-type.php',
  ]);

  // files to rector
  $parameters->set(Option::PATHS, [
    __DIR__ . '/vendor',
  ]);

  // files to skip
  $parameters->set(Option::SKIP, [
    // Exclude tests
    '*/tests/*',
    __DIR__ . '/vendor/nikic/fast-route/test/*',
    __DIR__ . '/vendor/psr/log/Psr/Log/Test/*',
    __DIR__ . '/vendor/symfony/service-contracts/Test/*',
  ]);
};

You can notice that some dependency files, such as erusev/parsedown/Parsedown.php' need to be added to Option::AUTOLOAD_PATHS. That's because scoping the package's composer.json is not 100% reliable, and then their autoloading may fail.

Whenever that happens, Rector will complain that some class failed autoloading. From there, we identify the corresponding file, and manually add it to the autoloading paths.

Check out the results

This is the plugin's source code, and this is its scoped (and downgraded to PHP 7.1) version.

Find the 7 differences 😁. (I give you a hint: search for PrefixedByPoP.)

And this is the final graphql-api.zip plugin file, ready to be installed on your site.

That's all. I hope this has been useful 😃💪🚀

👷🏽‍♂️ Building the GraphQL API in the Open #1 (March '21)

Leonardo Losoviz — Fri, 19 Mar 2021 13:34:25 +0000

This post has been originally published in graphql-api.com.

Welcome to the very first "Building in the Open"!

This is a channel to share news concerning the development of the GraphQL API for WordPress with the community, sent the first week of each month.

Through this space, we will learn everything that happened during the last month, including:

✅ What we've been working on, what new features we released
✅ What we will be working on the upcoming month
✅ Amount of traffic we got on the site
✅ How did the plugin do: Number of downloads, newsletter subscriptions, GitHub stars
✅ Progress on achieving financial sustainability
✅ Newly published guides
✅ Summary of our recently published blog posts
✅ Reaching out / Plugin mentions
✅ General news

If you enjoy this newsletter, please invite your friends to subscribe.

Let's start!

Heads up: This newsletter is a two-way communication channel. If there's anything you'd like to say, be welcome to add a comment.

What we've been coding on

If you notice the Guides, section "Extending the GraphQL API" is still pretty empty:

My priority is to complete these guides. But before I do that, I want the plugin's code to be as simple as possible. The simpler it is, the less documentation is required, and the more anyone and everyone is able to understand it.

With this in mind, I've decided to refactor the code, to have it be fully based on Symfony's DependencyInjection Component.

The idea is that any extension to the plugin (such as a custom TypeResolver, FieldResolver or DirectiveResolver) is simply defined as a service in the container, and the service is automatically configured via Compiler passes.

Fully relying on Symfony's dependency injection has several advantages:

✅ There is a single, consistent way to create extensions
✅ Just creating a PHP class implementing some interface does the whole job, and the developer needs not be aware of the nitty-gritty details
✅ Symfony's documentation is very extensive. By pointing developers to it, that is documentation that I do not need to write

Interested in the code? Check out my latest merged PRs (#453, #452, #449 and several others).

I will keep working on this code for the upcoming weeks, until the migration is 100% complete, and I get to write the missing guides.

Traffic to graphql-api.com

Let me be clear on something: I care about how many people visit the plugin's website, as a proxy to know how many people know about the plugin.

I don't have deep pockets to publicize my plugin. And even if I did, I wouldn't spend my money on promoting it, since that goes against the spirit of open source. (This would be different if open source were just a channel to sell some product or service, but that's not my case.)

That means that I rely fully on word of mouth to promote it. For that, I've been devoting plenty of effort in writing high-quality content for the plugin's blog, hoping this content would get shared around, reaching people who would otherwise not know about the plugin.

And so far, I'm pretty happy with the results.

During the past month, I've had 4.5k visitors, with 6k page views:

Let's break down these stats.

Most of my visitors come from Hacker News, where I managed to pull a few "Show HN" front pages, and Reddit, mostly from /r/PHP and /r/graphql (where I always share my articles).

I managed to rank #1 on Google when searching "wordpress core graphql", and that brought plenty of traffic. Unfortunately, it was a one time-off: after 24hs it went away as suddenly as it arrived. Otherwise, on a typical day I get between 3 and 10 visitors from Google.

Twitter and Facebook bring a sizable amount of traffic, but I don't know from who (not from me, since I am extremely bad at social media). I do share my articles on Twitter, but they seldom get retweeted. And I do not use 👎🏾 Facebook.

(Btw, for those of you who share my articles on social media, thanks ❤️)

I get some modest but consistent traffic from the listing of GraphQL servers in PHP on graphql.org, and from an article I've published on dev.to, which ranks #1 when googling "graphql execute multiple queries".

Finally, my articles consistently appear in WordPress' main newsletters (including WP Owls, wpMail.me, Post Status, WP Builds, and The WP Weekly). I don't know exactly how much traffic each of them brings, since the referrer will appear as Gmail and similar others. However, when taken together, these newsletters produce a sizable number of visitors.

My blog posts are by far my most popular content, with the last three (this one, this one and this one) bringing over 1k visitors each.

These numbers look pretty good, more since I barely launched the website less than 2 months ago. However, not everything looks good: At 88%, the bounce rate is quite high. I need to work on that.

Metrics

Traffic to the site is only a decorative metric, to estimate awareness of the plugin. But far more important to ask is: How many people started using the plugin during the past month?

During the past month, the plugin fared like this:

🎯 Number of plugin downloads: 170
⭐️ GitHub stars: 27

The number of downloads can be retrieved from the GitHub API, passing param per_page=3 to include only the 3 releases created during the last month:

curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/leoloso/PoP/releases?per_page=3 | grep "download_count"

I am neither happy nor unhappy about these numbers. They are not great (and I wish they were better), but they are a good start.

Concerning downloads, it is said that getting the first user is the most difficult task. Only after a few people start using the plugin, and start talking about it, that its use will become more widespread. I am still within this initial stage of finding the first batch of commited users.

Concerning GitHub stars, I must say it looks pretty flat: around 1 star per day on average. This is certainly nothing great. If you like what I'm building with the GraphQL API for WordPress, and you don't mind showing some ❤️ love, then please consider giving it a ⭐️ star on GitHub.

Financial Sustainability

This one is the tough issue: the project must be financially sustainable. It either generates a bit of money, or it won't make it for long.

If I am able to make an income for myself, then I can keep working on it, for as long as needed. That's all I need: an income. Not investors knocking on my door looking for millions. Just a couple thousands per month, to pay for the roof above my head.

My goal is to keep the plugin fully open source. For that, I'm currently reaching out to a couple of potential sponsors, asking if they'd like to help fund the development of the plugin. It will be a win-win situation.

Why am I resorting to some "big guns" sponsors, instead of relying on regular sponsorship, by anyone from the community?

Yes, I've been trying that too: I am on GitHub Sponsors. However, it doesn't really work, unless you already have thousands of users, followers, or people subscribed to your mailing list, to whom you can reach out to, expecting many of them to fund you.

For instance, asking for a standard u$d 5 or 10 per month, I'd need several hundred funders for this approach to fund my work. And I'm nowhere near that stage.

But even more, who can really succeed with this approach? I know that Caleb Porzio (creator of Livewire) has made it, and has now reached over 1350 sponsors! But that's more the exception than the norm.

Take Composer, for instance. Composer has fundamentally changed how we develop PHP applications, yet they barely have 90 sponsors. How could I ever expect to get more sponsors than Composer?

That's why my current approach is to create a win-win situation for my project and the few companies willing to sponsor it. Let's hope it will work out, and the GraphQL API is free for everyone, for all the features, and I don't need to lock the good stuff behind a paywall.

(If you'd like to find out how it's a win-win, please send me an email or DM. Maybe your company may be interested too?)

I'll give this approach a few months, hopefully I will make it happen. If I don't succeed, only then I will need to consider building a PRO version of the plugin, and restricting some of the features for the paid version. (Yeah, that would suck, so I hope I can avoid that stage.)

In the upcoming newsletters, I will keep you updated if I managed to get sponsors or not.

Blog posts

The blog posts have been my absolute pride and joy.

Heads up: Did you know there's an RSS feed on the site? You can subscribe to receiving all my blog posts, read them on your favorite reader.

During the past month, I've managed to publish a high-quality blog post every week:

🛠 Should WordPress have a GraphQL API in core? makes the case that WordPress could benefit from GraphQL, since the WP REST API was given a new functionality in WordPress 5.6 (batch operations), that a GraphQL API can deliver natively.

🥊 GraphQL API vs WPGraphQL: the fight! compares my plugin with WPGraphQL, on a clash to be remembered for ages to come, and which will keep boxing fans asking for more.

👶🏻 Rejuvenating WordPress through GraphQL demonstrates how a headless WordPress can be decoupled from the WordPress codebase, providing an opportunity to fix (or, at least, bypass) the accumulated technical debt.

🍾 GraphQL API for WordPress is now scoped, thanks to PHP-Scoper! describes a strategy to scope a WordPress plugin using PHP-Scoper, as to avoid conflicts with other plugins.

Reaching out / Plugin mentions

I'm delighted that the plugin has been featured in a few places.

✅ I have given talk "Intro to the GraphQL API for WordPress" in WordCamp India 2021, doing a demo of the plugin, and (surprisingly from doing a demo) it all came out perfectly! Check out the Youtube video.

✅ Joe Howard has interviewed me for the WPMRR podcast. The recording will come out soon.

✅ Chris Coyier featured my plugin in the CSS-Tricks newsletter #239!

A bit of everything

Some general news, about anything taking place during the last month.

Jason Bahl goes to WP Engine

Congrats to Jason for joining WP Engine! I hope he'll keep rocking, as he's been doing so far for WPGraphQL.

Btw, the fact that we're competitors (well, I'm the one competing with him, he's way far ahead) doesn't mean that we can't be friends, or collaborate to improve each other's projects. Indeed, we both share the same goal: to bring GraphQL to WordPress (even though we have different ideas on how that should happen).

But I believe that competition is good, and it will benefit everyone.

WP Engine launches Atlas, and claims to know everything about headless (do they?)

I also congratulate WP Engine for launching Atlas, their new headless WordPress solution.

Unfortunately, they state some inaccurate information:

Companies that use an entirely headless solution will typically host a separate JavaScript application for the front end, which pulls specific WordPress data via APIs—the WordPress REST API or the WPGraphQL plugin.

Yeah, the GraphQL API for WordPress does not exist, right?

I would normally not be troubled about this, since I don't expect everyone to know about my plugin. But I do believe that they know about my project, and they seem to be wilfully ignoring it.

After they launched developers.wpengine.com (the "one-stop hub for best practices, tutorials, blogs, and documentation for headless WordPress"), I did reach out to them:

Matt Landers, Developer Relations at WP Engine for Headless WordPress, on Twitter
Their development team, on their headless framework GitHub repo
Somebody from Torque (the magazine owned by WP Engine), via DMs with @TheTorqueMag.

I guess they haven't taken my project seriously. Or well, maybe they just didn't care about it, since they are fully invested in WPGraphQL.

Now, I'm OK if they don't want to mention my plugin. However, stating that the WP REST API and WPGraphQL are the only two options is very misleading. As a consequence, my plugin gets harmed, and the community of developers gets confused.

So then yeah, I must admit I'm annoyed. This is not cool at all. I hope they will rectify their inaccurate information (I sent them an email already).

Wrapping up

So this is the end of the first ever "Building the GraphQL API in the open".

How did you like it? Be welcome to share your thoughts in the comments.

If you did like it, I will appreciate if you can share the newsletter with your friends (or, even better, invite them to subscribe).

See you next month!

🎉 Released v0.7 of the GraphQL API for WordPress , with support for mutations, and nested mutations!

Leonardo Losoviz — Fri, 22 Jan 2021 16:07:48 +0000

Version 0.7 of the GraphQL API for WordPress, supporting mutations, and nested mutations, has been released! 🎉

Read the account of what's new here:

https://graphql-api.com/blog/released-graphql-api-v07-with-mutations-and-nested-mutations/

💪 WordPress + GraphQL

Leonardo Losoviz — Wed, 20 Jan 2021 15:09:59 +0000

I created a WordPress plugin to install a GraphQL server, and launched its new site:

https://graphql-api.com

It also has a REST-like behavior: it supports persisted queries, which are normal GraphQL queries, but published and accessed under their own URL, and these endpoints are even cacheable on the server-side.

Check it out! 😁

For a bit more info, I wrote on CSS-Tricks about the goals and philosophy of this plugin (that is, how it brings the WordPress philosophy to GraphQL).

Enjoy!

🚀 Coding in PHP 7.4 and deploying to 7.1 via Rector and GitHub Actions

Leonardo Losoviz — Wed, 25 Nov 2020 15:31:56 +0000

This post has been originally published in my blog leoloso.com

I've written a step-by-step guide about transpiling PHP code, from PHP 7.4 to 7.1, when creating a WordPress plugin:

Coding in PHP 7.4 and deploying to 7.1 via Rector and GitHub Actions

It explains all the hows and whys:

Why the target is PHP 7.1 and not 5.6
Which are the PHP features from each PHP version that our code can support
How to find out which 3rd party dependencies must be transpiled
How to make Rector work specifically for WordPress
Testing the downgrade through Travis
Creating the WordPress plugin via GitHub Actions

Enjoy!

🧱 Reusing code in WordPress plugins with blocks

Leonardo Losoviz — Tue, 17 Nov 2020 12:45:50 +0000

This post was originally published in my blog leoloso.com

I've written a new article about Gutenberg (the WordPress editor), exploring:

👉 What is the most effective way to reuse code, within a (single or multi-block) WordPress plugin?

The answer is here:

Reusing Functionality for WordPress Plugins with Blocks

Enjoy!

🙅🏻‍♀️ How the Jamstack is failing at comments

Leonardo Losoviz — Fri, 06 Nov 2020 15:23:13 +0000

This post was originally published on my blog leoloso.com

This content is from a comment I added in WPTavern, on an article where WordPress founder's Matt Mullenweg clarifies his earlier remarks that the Jamstack is "a regression for the vast majority of the people adopting it".

I think Matt’s brutal honesty is welcome, because most information out there about the Jamstack praises it. However, it also comes from developers using these modern new tools, evaluating their own convenience and satisfaction. As Matt points out, that doesn’t mean it makes it easier for the end user to use the software, which is what WordPress is good at.

I actually like the Jamstack, but because of how complex it is, it’s rather limiting, even to support some otherwise basic functionality.

The definitive example is comments, which should be at the core websites building communities. WordPress is extremely good at supporting comments in the site. The Jamstack is sooooo bad at it. In all these many years, nobody has been able to solve comments for the Jamstack, which for me evidences that it is inherently unsuitable to support this feature.

All attempts so far have been workarounds, not solutions. Eg:

Netlify forms: no hierarchy, so can post a comment but not a response (unless adding some meta to the comment body? how ugly is that?)
Storing comments in a GitHub repo: it takes a long time to merge the PR with the comment

Also, all these solutions are overtly complicated. Do I need to set-up a webhook to trigger a new build just to add a comment? And then, maybe cache the new comment in the client’s LocalStorage for if the user refreshes the page immediately, before the new build is finished? Seriously?

And then, they don’t provide the killer feature: to send notifications of the new comment to all parties involved in the discussion. That’s how communities get built, and websites become successful. Speed is a factor. But more important than speed, it is dynamic functionality to support communities. The website may look fancy, but it may well become a ghost town.

(Btw, as an exercise, you can research which websites started as WordPress and then migrated to the Jamstack, and check how many comments they had then vs now… the numbers will, most likely, be waaaaaaay down)

Another way is to not pre-render the comments, but render them dynamically after fetching it with an API. Yes, this solution works, but then you still have WordPress (or some other CMS) in the back-end to store the comments :P

The final option is to use 3rd parties such as Disqus to handle this functionality for you. Then, I will be sharing my users’ data with the 3rd party, and they may use it who knows how, and for the benefit of who (most likely, not my users’). Since I care about privacy, that’s a big no for me.

As a result, my own blog, which is a Jamstack site, doesn’t support comments! What do I do if I want feedback on a blog post? I add a link to a corresponding tweet, asking to add a comment there. I myself feel ashamed at this compromise, but given my site’s stack, I don’t see how I can solve it.

I still like my blog as a Jamstack, though, because it’s fast, it’s free, and I create all the blog posts in Markdown using VSCode. But I can’t create a community! So, as Matt says, there are things the Jamstack can handle. But certainly not everything. And possibly, not the one(s) that enable your your website to become successful.

🎉 I got my 1st big sponsor for the GraphQL API for WordPress

Leonardo Losoviz — Mon, 02 Nov 2020 12:51:57 +0000

This post was originally published on my blog leoloso.com

My plugin GraphQL API for WordPress just got a new sponsor!

This is the second sponsor that I get, and the first one at the u$d 1400/m tier (the other was is at u$d 70/m).

This is a huge step forward, since it gives me the economic certainty as to keep developing the plugin (at least for the short/medium term... I still need a few more sponsors for it to become a living wage and long-term economic reliability).

I'll describe how it happened.

The road to sponsorship

Several weeks ago, there was a proposal to introduce a fixed schedule to WordPress to bump the minimum required PHP version. Among the comments, one of them struck me:

So effectively this means that we cannot use PHP 8 syntax in themes/plugins if we want to support all WordPress versions until December 2023, 3 years after it has been released. This is very disappointing.

I work with WordPress. My plugin is for WordPress. Not being able to use the latest PHP features in 3 more years feels very disempowering.

So I decided to look for some solution, and I discovered Rector, a tool to reconstruct PHP code based on rules. It is like Babel, but for PHP. I asked if I could use Rector to transpile code from PHP 7.4 to 7.1, and they said yes, it could be done, but the rules to do it had not been created yet.

So I created them.

I contributed to this open source project full time for some 2 weeks, and produced some 15 rules to downgrade code, which I have applied to my plugin: Now I can code it using features from PHP 7.4 (and even from PHP 8.0), and release it to run on PHP 7.1, so it can still target most of the WordPress user base (only users running PHP 5.6 and 7.0 are out). That's a huge win!

After implementing those 15 rules, I documented the remaining rules to downgrade PHP code, and called it a day. I didn't mind working on them, but I didn't have the time to do it. Nevertheless, I also created this task as a sponsorable feature for my plugin; if anyone sponsored my time to work on it, I could then attempt to finish the task.

Well, Tomáš Votruba, creator of Rector, liked my contributions so he decided to become my sponsor.

Yay! 🍾 🎉 🎊 🥳 🍻 🥂

In exchange, I'll work on the downgrade rules, and even attempt to have Rector itself run on PHP 7.1.

Nature of the sponsorship

Now, let's be clear: Tomáš is sponsoring me to work on Rector, not on GraphQL API for WordPress. That's why the sponsoring tier is u$d 1400/m, since it involves me working on the sponsor's repo.

While I get to increase the price for the tier, it makes no difference to me if the code is in my repo or my sponsor's: when I first worked those 2 weeks, it was for the benefit of my own plugin anyway, even if the code does not belong to my project.

Ultimately, where the code lives is not really important. What is important is that my project (and, for that matter, any project based on PHP) will be able to benefit from it.

In addition, anyone from the PHP community who starts using Rector because of my work on it, may learn that it was the GraphQL API for WP that made it possible, so I gain face and recognition.

So I think this is a win-win-win for all parties involved:

Tomáš gets Rector expanded, supporting a broader set of use cases
I get the sponsorship money, and the associated badge of recognition from having a big sponsor
My plugin GraphQL API for WordPress can use the new rules to use new PHP features (which was my objective all along)
The WordPress community can implement this same strategy for their own themes and plugins
Other PHP-based projects can also use it

Takeaways

Some personal takeaways from this experience:

Contributing to open source projects may pay off
Looking for synergies may pay off. Rector and my plugin can benefit from each other. Contributing to Rector is contributing to the GraphQL API for WP
Getting sponsors is tough, mainly at the beginning. They may not come to you. So you need to (directly or indirectly) go to them
I'm working on my plugin for the long run, and its being successful depends on many small victories, like this one

Coming next

My next step is to share my work on Rector with the broader WordPress and PHP communities: I've just published an intro to downgrading from PHP 8.0 to 7.x, and in a few weeks I'll publish a step-by-step guide on transpiling code for a WordPress plugin, using my repo as the example.

Hopefully, along the way I'll be able to get new sponsors, and eventually achieve long-term economic certainty with my plugin 😀

Forem: Leonardo Losoviz

🙅‍♀️ Why GraphQL should not be in WordPress core

1. It doesn't satisfy the 80/20 rule

2. Headless is already satisfied via the REST API

3. WordPress themes and plugins can use webonyx/graphql-php

4. GraphQL presents additional risks

Wrapping up

Version 0.8 of the GraphQL API for WordPress is now available 🚀

👨🏻‍💻 Demoing the GraphQL API for WordPress

👶🏻 Rejuvenating WordPress through GraphQL

The WordPress data model

Is the mapping an exact replica of the DB diagram?

Mapping the WordPress data model as a GraphQL schema

Operations without entity are mapped as Root fields

All mutations go under MutationRoot

Dealing with custom posts

Not grouping tags (and categories) under a single type

Giving media items their own identity

Identifying and mapping enums

Mapping additional types

🍾 GraphQL API for WordPress is now scoped, thanks to PHP-Scoper!

Taking the decision to scope

Checking out the options

Trying out Mozart, and failing

Checking PHP-Scoper, and coming out in panic

Coming back to PHP-Scoper, this time for good

PHP-Scoper, the easy way 😎

Show me the real stuff

Testing

Check out the results

👷🏽‍♂️ Building the GraphQL API in the Open #1 (March '21)

What we've been coding on

Traffic to graphql-api.com

Metrics

Financial Sustainability

Blog posts

Reaching out / Plugin mentions

A bit of everything

Jason Bahl goes to WP Engine

WP Engine launches Atlas, and claims to know everything about headless (do they?)

Wrapping up

🎉 Released v0.7 of the GraphQL API for WordPress , with support for mutations, and nested mutations!

💪 WordPress + GraphQL

🚀 Coding in PHP 7.4 and deploying to 7.1 via Rector and GitHub Actions

🧱 Reusing code in WordPress plugins with blocks

🙅🏻‍♀️ How the Jamstack is failing at comments

🎉 I got my 1st big sponsor for the GraphQL API for WordPress

The road to sponsorship

Nature of the sponsorship

Takeaways

Coming next

3. WordPress themes and plugins can use `webonyx/graphql-php`