Skip to content

WordPress, REST, and RegEx

Dear Reader,

I’m going to add this to “Using the WordPress REST API“, but I thought I would blog it here as well.

I have a tendency to over think things.

Today, I was working on a REST API endpoint for a client and it needed to have RegEx in it. I hate RegEx with a passion usually reserved for XML, but unlike XML, it’s a necessary evil, so I dove into it.

1
/item/(?P<itemId>\d+)

That’s an example.

For the uninitiated, when you are defining a custom WordPress REST endpoint, one of the things you can do is put in Regex into the route definition and WordPress will use that to pull out content and make it a parameter. The code above defines an endpoint for

https://example.com/wp-json/my-namespace/v1/item/4

When run, it will make a parameter named itemId whose value is the 4 from the URI. It’s incredibly handy. They are very easy to work with, especially if you are using numbers like 4, or even 294875.  Strings…well, strings get tricky.

The above example expect a number (so no alpha, just numeric) and numbers are contiguous.  You don’t have numbers with a space in them. Phrases however, have spaces. And what I needed to pull out was a phrase. So, I did what I always do, I pulled out Regex 101, and started figuring this out. This is where the overthinking part comes in.

I got it working in short order, then I started thinking. “What if…”

  • What if There’s a query string at the end
  • What if there’s more to the URI
  • What if there’s a slash at the end
  • …what if

This is where I got into trouble. I lost a good 2-3 hours designing a beautiful piece of RegEx that handled every situation I could think of. It was art, if I do say so myself. The only problem was that once I pasted it into my WordPress REST Controller, it did not work.

So I did what every developer does, I assumed the problem had to be in WordPress. I rolled up my sleeves and found out how WordPress matches routes.

What WordPress does

WordPress matches REST routes in WP_REST_Server::dispatch() (wp-includes/rest-api/class-wp-rest-server.php)

1
$match = preg_match( '@^' . $route . '$@i', $path, $matches );
$path is the URI. IN my case
https://example.com/wp-json/my-namespace/v1/item/this%20item%20name
$route was the route I defined in regex.
1
item/(?P<itemName>[w+].*)[?|/|\$]
(I’m working from memory but I think that was it.)
If – and only if – I could set some pattern modifiers I could make it work…but I couldn’t.
Then I began doing the other thing that PHP developers do a lot, I began throwing var_dump();die(); into WP_REST_Server. I thought I needed to see what was going on. Turns out, the answer was there in front of me all the time.
I was assuming that WordPress was applying my RegEx standalone from everything else. If you look at the line above though, you can see that is uses the route that I define in it’s entirety.
  • It puts a ‘@’ at the beginning of it. This tells PHP that ‘@’ is the regex delimiter, not ‘/’ like usual
  • It adds the caret ‘^’ to match the beginning of the line
  • It concatenates the route I defined
  • It adds the $ to match the end of the line
  • It puts the ‘@’ to signify that this is the end of the RegEx
  • It adds the ‘i’ pattern modifier (the things I needed to tinker with) to indicate that all matches should be case insensitive
WordPress doesn’t worry about the query string, or anything after that because it’s already stripped it off. I don’t have to overthink this thing with subgroups and special characters, WordPress has got my back.
My finished product ended up looking like this:
1
item/(?P<itemName>w+.*)
This gives me a parameter named itemNamethat includes everything past item/ to the end of the line.

Conclusion

Stop over-thinking things. Sometimes just let the framework do it’s job. :)

Did I meantion I hate Regex? :)

Until next time,
I <3 |<
=C=

p.s. the section in the book will be more coherant. I’ve spent the day with RegEx so I’m a bit scatterbrained now. :)

Community

Dear Reader,

At Sunshine PHP ’19, it was my privilege to make many new friends and re-connect with old ones. One of the new friends I made was Nara Kasbergen.

Nara did a great talk on Community – which of course made me nervous because, well, that’s MY shtick. Never the less Nara delivered a very good talk with some good points.

One of my takeaways was that you need to be an active part of several community. it’s not enough to be a part of your local PHP user group, you also need to be part of at least one conference community, (Sunshine, phptek, PHPBenlux, DPC, the list goes on)  and an easy win is to be part of an online community as well. (Whether that be Twitter, slack , Day Camp 4 Developers, or NomadPHP is up to you)

Take the time to get involved in the PHP community in the way that is best for you.

The connections you make will help you build a career.

The friends you make will help you build a life.

Until next time,
I <3 |<
=C=

Mautic Step 0 – Installing Mautic

Dear Reader,

Last time, in the post titled “My Journey into Mautic”, I explained that I was starting to play with the marketing automation package Mautic. Today’s post is about installing Mautic.

This post is not necessary for everyone. If you are using a hosted version of Mautic, it is probably safe to ignore this post. Even if you are hosting it with a provider like SiteGround or GoDaddy, the first part of these instructions won’t apply. You can skip the “Foundation” if you installed Mautic from a control panel and go straight to “Running the Mautic Installer”.

The Foundation

I use Digital Ocean as my hosting platform. For small businesses, Mautic WILL run on a $5/month droplet. However, I strongly suggest that if you are going this route to invest a little more and get at the minimum a $10/month droplet.

You will need to install:

  • Apache (or the web server of your choice)
  • PHP
  • MySQL/MariaDB

Additionally, Mautic makes this recommendation.

Mautic recommended configuration options.

You can also run Mautic in a sub-directory of your existing website. If you already have a website that is based on the LAMP stack then Mautic will either run without problems or it will tell you what the problem is and let you correct it before you install.

If you do not have a website, Mautic will not do you any good. Start with my friends over at SiteGround and get a WordPress installation up, running, and completely fleshed out before you even think the word Mautic.

Installing Mautic

Once you have your hosting platform up and ready to go, download and unzip Mautic into the proper directory. The proper directory will depend on how you decided to install it. If you decided to install it as a sub-domain, you will unzip Mautic into the root directory of the sub-domain. If you decided to install it in a sub-directory of your main domain, you will need to unzip it into that sub-directory.

Database

Before you begin, you will need a blank database for Mautic to use. Connect to your MySQL/MariaDB service with your favorite tool and create a database, and a user. Make sure you give the user access to the newly created database but ONLY access to that one database.

DO NOT us an existing database. Create a new database. if your hosting provider won’t let you create another database, get a better hosting provider. Start with a clean and empty database.

DO NOT user your root db or a root equivalent user account. Create a new account just for this database. Give it all the permissions except for GRANT.

If you are using a hosting provider with a tool like cPanel, you can use cPanel to create the database, and the user account.

Running the Mautic Installer

Installing Mautic is very straight forward. If you have your web server setup properly then you just point a browser to wherever you unzipped it and BOOM, it starts the install process.

Mautic install screen number one. This screen tells you if your platform is sane. it also makes optional recomendations.

This first screen tells you if your platform is sane. You can see from the green “Ready to Install” that Mautic likes my setup. However, the yellow section makes a few recommendations for how it could be better. Since I manage my own server, it was easy enough to fix the issues. If you are running on a platform where you do not have root access, it might not be as easy for you to fix them. In that case, I would recommend working with your hosting provider to see if they can resolve any or all of the recommendations.

Clicking “Next Step” takes you to the second screen.

This is the second Mautic install screen. This is where you enter all the information about your database.

On this screen, you enter all the information that Mautic needs to connect to your database server. If you have installed applications on a web server before (e.g. WordPress) then this will be familiar to you.

 

The only two things that might not ring a bell on this screen are:

  • Backup Existing Tables/Prefix for backup tables.
    This is set by default to YES. Since you are installing into a new database, it really makes no difference at all. I turn it to no as there should not be any existing tables. Either way, since no backup tables will be created, the prefix for the backup tables is irrelevant. It is safe to ignore this.
  • Database Table Prefix
    This is blank but I highly recommend you putting something here. three random letters and an underscore is plenty. This is a security feature. Anyone who reads the code for Mautic knows what the table names are. This gives an attacker a piece of information they can use in their favor. If you put a random prefix on the tables, it just makes it a little harder for an attacker to compromise your system. (Security s like an onion, it is made of of layers)

Clicking “Next Step” takes you to the screen where you will create the admin user for Mautic.

 

This screen will let you enter in the Mautic admin user name and password. Since this account will have God like powers in your application, do not simply reuse a long and password that you use for other websites. Make the user name something meaningful and use a password manager to create a strong password.

Once you have filled this form out, click “Next Step” to take you to the “Email Configuration” screen.

This is the Mautic email configuration screen. This is where you setup your Email Server provider information.

Enter your name and email address here. Don’t worry about the rest, we are going to properly configure all of this in a future post. Honestly, I’m not really sure why this information is asked for here. I’m sure there is a good reason though.

Success!

Mautic log in screen

If all goes well – and honestly, the installer is designed so well that if something is not going to go well, it won’t let you get to this point – then the next thing you see is the Mautic log in screen. Go ahead, enter your email address and password, you’ve earned it.

As you can see, even from scratch, Mautic is very easy to install. It rivals the WordPress “5 Minute Install” for ease of use and completeness.

Next, we will talk about Email Service Providers.

Until next time,
I <3 |<
=C=

Thank you Derick Rethans for 15 years of XDebug

Dear Reader,

There are a handful of tools that have actually changed how many of us code PHP. XDebug is one of those tools[1]. There is no doubt of the impact that XDebug has has on PHP developers and PHP projects.

Recently, XDebug turned 15. (If you don’t know what XDebug is, start with this SitePoint article about Xdebug) This means that the man responsible for XDebug, Derick Rethans, has been supporting XDebug for 15 years, for free. XDebug is open source. Derick maintains it, answers questions about it, spoke at conference about it, and generally done everything he can to help anyone who is having an issue with it.

FIFTEEN YEARS!

Thank about that. How much code do you have that has lasted fifteen years?

So on this the (close to) anniversary of this product, many of us in the PHP community decided to do something to show Derick how much we appreciate it. Those that know him know that Derick loves a good Scotch. So we decided to buy him some. Originally, I was just going to buy him the most expensive bottle I could find and be done with it. However, my friend James Titcumb stepped in. He knew the owner of the shop that Derick buys his Scotch. He contacted the owner and we gt a quick education in Scotch. tl;dr, expensive doesn’t always mean good. He picked out a selection of bottles that he knew met Derick’s high standards.

On April 26th, 2017, James met Derick at the retailer and here is the video.

Thank you!

  • First and foremost, thank you Derick.
  • Second, thank you James Titcumb for going above and beyond on this project. Y’all really have no idea what he did to make this happen.
  • Third, I gotta say it. Thank you to the lovely and talented Kathy. It is hard to describe how difficult it is to live with someone like me who randomly sit up and shouts “I HAVE AN IDEA”. Yes, sometimes, she buries her face in her hands and weeps. Most of the time though, she supports me, she encourages me, and she helps me. This time, she worked with James to get the Scotch paid for. (Moving that amount of money across the pond is not as easy as you might think it would be.)
  • Finally, but not nearly the least important, thank you to the entire PHP community. When I setup the GoFundMe, I never expected to actually hit the $5,000. I would have been happy with hitting $1,500. As of right now we have hit $5,100! (I’m trying to figure out how to close the GoFundMe!) :)

    Part of the deal I offered companies was that if anyone donated at least $100, I would list their logo and link in this blog post. Here are the people and companies that rose to that level.

    Make sure you say thank you to these individuals and companies.[2]

All told, 151 people donated to make this happen!

So that’s it. We had some fun, we raised some money, we said thank you to someone who has given so much to all of us. Once again, thanks Derick. :)

Until next time,
I <3 |<
=C=

p.s. I will provide a full accounting of all funds raised when I get home from traveling.

[1] The other two, IMHO, are PHPUnit and Composer.
[2] If you are on this list, you probably noticed there re no logos. This is my fault, not yours. Basically, I lost them in all my recent travels. PLEASE send to me again via email and I will update your entry.