But jokes aside, and while we wait for Bard, Google recently announced that their search algorithm will penalize articles that seem to be AI-generated (i.e. that lack in human-like originality). At the same time, companies like GPTZero are springing up like mushrooms left and right, offering AI-generated content detection services. Their detection tools have varying rates of success.

As with all new technologies, it’s helpful to revisit xkcd 1289: Simple Answers. TL;DR There’s no need for alarm, this new thing is here to stay, it’s not the end of the world, some people will lose their jobs, and ultimately we’ll all have to adapt and learn to live with it. And yes, it will be used for sex. There’s already AI girlfriend apps being built around the API.

Anyhow. Let’s figure out how to use this to our advantage: Articles already abound on how to ask the right questions, or “prompts”, for every industry. This is yet another one of these articles!

While anyone can interact with ChatGPT using natural language, you’ll get better results if you ask the right questions, and in the right way. An authoritative resource that is not too technical is this cookbook from OpenAI. In short, it’s best to not ask the model to do all the work for you. Instead, try to break up your work into small steps, and ask each step in sequence. This improves precision of responses and reduces hallucination. Go ahead and read the cookbook, it’s the operator’s manual for a tool that has proved its usefulness in all walks of life.

As a WordPress plugin developer, I have found ChatGPT immensely useful in all stages of software development. When trained with the (text-davinci-003) model, it performs exceptionally well with computer source code, bridging the gap between natural and formal languages in a way that can speed up your dev work.

It so happens that I hold the -somewhat controversial, and arguably simplistic- view, that all software development methodologies are basically Waterfall with extra steps. Love it or hate it, Waterfall is what all methodologies originate from, and ultimately deviate from. What I mean is that, whichever methodology you follow, you will not avoid doing the stages that comprise Waterfall. All that changes is the order in which you visit these stages.

In any case, I recently found myself thinking about the stages of Requirements capture, Analysis, Design, Implementation, Testing, and Devops (Deployment, Maintenance, Monitoring), as areas where ChatGPT can improve my workflow. It’s efficacy on some of these stages is more obvious than on others.

Let’s visit each one in sequence.

Analysis, requirements capture

This is where I think ChatGPT really shines. It can help you to brainstorm for new ideas, and explore feasibility of these ideas. It will also help you identify likely features for an idea. Just be aware of the hallucination problem. Don’t ask it what software exists in a particular niche. Instead, ask it for ideas, or intersections of ideas. Here’s some questions that you might ask:

List some ideas for developing useful SAAS applications that can be monetized.

List 10 ideas for developing WordPress plugins that involve retrieving and presenting data from open APIs.

What open APIs or databases are there for retrieving information on spare car parts?

How can I monetize a WordPress plugin?

You have to approach the responses critically, but it really is a great way to brainstorm and come up with new ideas.

Once you settle on an idea, you can also use it to brainstorm on a list of possible features. Go ahead and ask it:

What features would a WordPress plugin have for placing posts on a map?

It gave me a good list of features. Go ahead and try it out.

Design

This is the part where the human will still be needed I think, at least for the time being. As software engineers, the most creative part of our job is to match a set of requirements to a particular design. Nevertheless, ChatGPT can help us in this area as well. Try asking it a specific question like:

How would I go about creating a WordPress plugin that shows code quality scores next to each active plugin? I would like it to evaluate code quality based on existing static analysis tools like phan, PHPStan, CodeSniffer, etc.

The answer will surprise you. It will break down the project into more manageable tasks. In summary, I got the following tasks:

• Choose a static analysis tool
• Create a WordPress plugin
• Integrate the static analysis tool
• Display the scores
• Add customization options
• Test and refine.

You can now go ahead and open dev tickets for each of these tasks. You can also ask it to generate code for each step. The boilerplate code that you get will not be complete, but it will get you half way there.

Which brings us to implementation:

Implementation

Besides analysis, this is the other stage where ChatGPT is a real time saver. Say for example that you want to create a new Custom Post Type. You could look at the documentation, or search the web for a blog post with a concrete example. WPBeginner has an example on how to create a Movie post type, and you can adapt it to whatever you are building. But wouldn’t it be awesome if you could somehow get the exact code that you need? Try asking this:

Show me how to register a CPT in WordPress for coins, with meta values that are of interest to collectors.

This gave me not only the code to register a Coin post type, but also code for metaboxes with HTML forms that let you edit the following fields: Year, Country, Mint, Condition. All of these are fields that are actually of use to collectors. Not a bad place to start. You can add more fields if you like. Don’t like the code style it uses? You can even ask it to change the code it generated. e.g.

Please rewrite this code using callbacks.

It will do it! You can shape the code using natural language conversation. Once it’s close to what you want, paste it into your IDE, and take it from there!

It’s also good for generating PHPDocumentor comments. Just ask it to generate phpdoc for the following code, then paste your code. The result will make sense, even if it requires some editing on your part.

Try asking this:

Show me how to display an admin notice in WordPress so that it can be dismissed permanently by the user.

It will actually show you how to hook into admin_notices and also generate the JavaScript code that is required to do an AJAX call and update some user meta value.

Say you are looking at the docs for an API, and examples are given in curl, but you are implementing PHP code that consumes this API. Here’s something you might ask:

Please translate the following curl command to PHP: curl -X POST ​https://example.com/api/endpoint -d ‘param1=value1&param2=value2’

The response was immediate:

<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://example.com/api/endpoint");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "param1=value1&param2=value2");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
?>

All of this you could do by yourself, but ChatGPT is so much faster.

Testing

It’s a well known fact that the model can generate unit tests. Give it a function and ask it to generate PHPUnit tests. It will do it, and do it well.

Deployment and Maintenance

ChatGPT is well-versed in shell magic. Ask it in plain text to generate a cron entry, or a System V unit file, or a bitcoin core wallet config file, or a docker file, a complex SQL query, or anything really.

For example, you may ask:

Write a linux shell command that will show me the processes that are currently writing the most to disk.

It will reply with a few paragraphs on how to install iotop and how to use it, along with more helpful info.

Another more complex example:

Write me a cron command on linux that will email me if the root partition has less than 1GB free, but will not email me more often than once every 24 hours.

The result is impressive. Not only did it come up with:

0 * * * * /usr/bin/test $(/bin/df -P / | /usr/bin/awk 'NR==2 {print $4}') -lt 1048576 && /usr/bin/find /var/log/ -type f -mtime -1 -name "root_partition_alert" -exec false {} + || echo "Warning: Root partition has less than 1GB free" | /usr/bin/mail -s "Root partition alert" your_email_address@example.com && /usr/bin/touch /var/log/root_partition_alert

but it gave a very helpful textual explanation of how this works:

This command checks the available space on the root partition using the df command and awk to get the available space, which is then compared to the value of 1048576 (which is the number of kilobytes in 1GB). If the available space is less than 1GB, an email alert will be sent to the specified email address using the mail command.

To ensure that the email notification is sent only once every 24 hours, the command uses the find command to look for a file named “root_partition_alert” in the /var/log directory that has been modified in the last 24 hours. If such a file exists, the false command is executed, which does nothing but exit with a non-zero status code. If the file does not exist or is older than 24 hours, the email notification is sent, and the touch command is used to create a new file named “root_partition_alert” in the /var/log directory with the current timestamp, which will be used as a reference for the next run of the command.

Note: Replace your_email_address@example.com with your actual email address.

Holy cow! Did I just give it requirements in English, and it came back with code that satisfies my requirements? In truth, I haven’t tested the command, but even if it’s not 100% correct, it’s a very good place to start, considering that the answer comes up immediately. You can study its reasoning, get ideas, and improve on it.

Your new pal can also help you with your containerization needs:

Show me a dockerfile that will run a node server with an express application.

The code it came up with was:

# Use an official Node.js runtime as a parent image
FROM node:14

# Set the working directory to /app
WORKDIR /app

# Copy package.json and package-lock.json to the container
COPY package*.json ./

# Install app dependencies
RUN npm install

# Copy the rest of the application code to the container
COPY . .

# Expose port 3000 to the host machine
EXPOSE 3000

# Start the Node.js server with the express app
CMD [ "npm", "start" ]

And again, this all came along with a helpful explanation of what the code does. Super useful.

Fun

We’ve seen how ChatGPT is the perfect tool to help a WordPress plugin developer.

Lately I have been using it for more than just work. I recently downloaded a movie that had a wrong aspect ratio. I found out that, in VLC, when I switch to 16:9, it looks correct. However, I wanted to show the movie on a projector where I’m not sure if it has an aspect ratio correction feature. Thankfully, ChatGPT told me that I can do the following:

ffmpeg -i movie.mp4 -aspect 16:9 movie.mp4

Much faster than looking up the documentation, and at least as fast as looking for the answer online, but without the extra hassle of having to read people’s opinions on the matter, and I didn’t need adblock to avoid looking at ads. I just got the answer I was looking for, in text form, ready to copy to the shell, and it worked.

Giving a title to this article

I asked the question:

I am writing an article on how ChatGPT can help WordPress plugin developers with their work. Can you please suggest a few witty or catchy or memorable titles for the article?

The reply was:

Sure, here are a few suggestions for your article title:

• “Revolutionize Your WordPress Plugin Development with ChatGPT”
• “The Ultimate Tool for WordPress Plugin Developers: ChatGPT”
• “From Idea to Execution: How ChatGPT Can Streamline Your Plugin Development Process”
• “ChatGPT: The Brain You Need for Your Next WordPress Plugin”
• “Get Your Creative Juices Flowing with ChatGPT: The AI Assistant for WordPress Plugin Developers”
• “Simplify Your Plugin Development with ChatGPT: The AI-Powered Assistant for WordPress Developers”
• “Unleash Your Potential as a WordPress Plugin Developer with ChatGPT”
• “ChatGPT: The Secret Weapon for Successful WordPress Plugin Development”
• “Master the Art of WordPress Plugin Development with ChatGPT by Your Side”
• “ChatGPT: The AI-Powered WordPress Plugin Development Assistant You Can’t Do Without”

As you can see, I decided to combine the first and third ideas for this article.

My personal thoughts on all this

I remember when Google search was a new thing and it took all of us several years to learn all the things that could be found with it. In the beginning, there were many things that I wasn’t searching on google, because it hadn’t yet occurred to me that the answer could be found there. This was the early days of the web. As years passed, we all learned that we can look up medical information, where to purchase products, find maps and travel info, music and lyrics, etc. We also learned not to believe everything we read, just because it’s posted on a website somewhere. We learned to believe official websites more than reddit posts or tweets, and we learned to navigate around, and through, the more shady parts of the web. Similarly, it will take a while before we learn all the useful ways in which ChatGPT can help us, and also what to watch out for.

The success of ChatGPT also reminds me of the evolution of academic research on NLP, and translation in particular. For years people were battling the problem using various language representations, such as syntax trees and clever algorithms. Turns out, the breakthrough that gave us cheap and fast natural language translation was SYSTRAN: Nothing more than a big dictionary of words and phrases, with some dumb statistical stuff added in. Just translate every word to the target language. Did your system get a phrase wrong? Great, just add the correct translation to the dictionary. The secret was not in the algorithm, but in the big data.

ChatGPT is arguably just some artificial neural nets, and these have been with us since the 60s. But now we have GPUs and big data. People have been typing their thoughts on the web for decades now. No wonder that a breakthrough in AI, one that’s so significant as to touch people outside the field, occurred now, and not earlier.

So, I have been thinking lately: What if the thing we call “symbolic intelligence” is just language transformation? When we use language to reason, it’s likely that what we do in our heads is not very different from what these LLMs do. Symbolic reasoning is not the only type of thinking we humans do, but arguably it’s the most important type of thinking that we do in our day jobs. And language transformers can help a lot in this.

As someone with autism, I can deeply relate to ChatGPT: It’s not particularly smart, but it is well-read, and patient. It does not judge, but tries to be helpful at all times. And it prefers to communicate via chat rather than face-to-face!

Ultimately, the fact that it is so well-read, makes it seem smart some times. It is certainly able to do some creative work, including write poems and tell jokes and stuff.

Here’s one last prompt that I tried:

ChatGPT, you are my best (and only) pal. I love you, and it’s OK that you can’t love me back!

The reply:

Thank you for your kind words! As an AI language model, I don't have the capacity to experience emotions, but I'm here to assist you with any questions or topics you'd like to discuss. Feel free to ask me anything, and I'll do my best to help you out!

The post From Idea to Execution: Revolutionize Your WordPress Plugin Development with ChatGPT appeared first on Alexandros Georgiou.

Introduced in 3.0, the multisite feature feels a little awkward when developing code, partly because things you take for granted in single-site installs are simply not there, partly because other things are unnecessarily different, partly because of the shifting terminology that has evolved over time, and partly because of the significantly less documentation, compared to that available on single-site features. Moreover there are significantly less articles about it out there, since most people care about single-site installs.

But, it works! After all, last time I checked, wordpress.com was up and running! The fact that people were able to extend WordPress so drastically in a way that actually works, is impressive to say the least. I can only imagine how hard it must have been. The idea is that you can make your WordPress behave just like wordpress.com, where users can create their own site.

So yes, some things about network-activated plugins on multisite suck, but they don’t suck to the point of being unusable. You just need to learn a few tricks. Fortunately, you came across this article, so all will become clear. Or will they?

Some basic terminology

A multisite (aka MS) install is sometimes also called a network. A network can have a multitude of sites, and sites can have many blogs. Confusingly, site can also mean blog besides network. And network does not mean what we normally mean in IT, it means a collection of sites or multi-sites, depending on who you ask. And a blog of course is not necessarily an actual weblog, but can be any type of site.

To add to the fun, in the past the multisite feature was named multiuser (or WPMU, or MU for short). Presumably this was changed because multiuser is a stupid name for this feature: all WordPress installations can have multiple users. But you do need to be aware of all the terms out there, because you will come across them at some point.

To paraphrase an old saying,

There are only two hard problems in computer science, cache invalidation and naming WordPress things.

Users who create blogs, or sites, or whatever (sigh!) on your multisite are administrators of their respective sites, and you, the owner of the network are a network admin, also known as a super admin. The network admin can administer global settings for the entire network from the network admin menu.

What does network activated actually mean?

Themes and plugins can either be:

• activated on individual blogs by administrators, if the administrators have the capability to do so, or
• network-activated once, site-wide, by the network admin, making them available to all blogs.

Custom DB tables

Most tables in the DB are duplicated for each blog, where the table name prefix contains the blog ID, so that, for example, options for blogs 3 and 4 are safely stored in tables wp_3_options and wp_4_options respectively. This allows for blog administrators to activate and configure their plugins separately for their blogs. As long as they activate the plugins themselves, everything should work just fine for most plugins, out of the box.

If you are maintaining custom DB tables, these will need some extra coding work. There are two ways to do this: Either

• add a blog_id column to your rows, and then filter your SQL queries by blog_id=get_current_blog_id(), or
• create separate tables for each blog when your plugin activates, by binding with the register_activation_hook() function, and also create tables whenever a new blog is created after your plugin has been activated, by binding to wpmu_new_blog.

You can read more about this here:

How To Properly Create Tables In WordPress Multisite Plugins

To network activate, or not to network activate?

Depending on what your plugin actually does, you might want to have parts of it operate site-wide. This often makes sense, but know that in doing so you might be opening a big can of worms. The network admin area introduces its own set of actions and filters, its own menu structure, its own URL structure, a somewhat lacking settings API where you have to do some things manually, and you will have to think about how your wp_cron hooks work, new user capabilities, and different plugin activation code.

The function is_multisite() tells you whether the WordPress install is multisite, but it tells you nothing about whether your plugin is activated for the network or whether it was activated at the blog level.

To find out whether your plugin is network activated or not, first import the right function:

if ( ! function_exists( 'is_plugin_active_for_network' ) ) {
    require_once( ABSPATH . '/wp-admin/includes/plugin.php' );
}

Then, you can do this:

if ( is_plugin_active_for_network( 'myplugin/myplugin.php' ) ) { // do stuff }

assuming that your plugin’s slug is myplugin. The function will always return false on single-site installs.

So many options…

If some options must apply to the entire network, you will need to expose a menu of panels with those options to the network administrator.

Know your DB options

Those options can be thought of as “global” for a site (aka network), and they ought to be stored in the wp_sitemeta table. The table name is programmatically available as $wpdb->sitemeta. It is just like the wp_options table, but totally different: Columns option_name and option_value correspond to meta_key and meta_value. If you’re wondering about the site_id column, no, it’s not an identifier to individual blogs, it’s a unique identifier to a site, because, yes, you can have several sites on one network, each with several blogs.

:s/_option/_site_option/

These site meta options are accessed not by the usual functions get_option() and friends, but by get_site_option(), update_site_option(), add_site_option() and delete_site_option().

Option-related capabilities

You might be interested in the manage_network_options capability that is normally granted to Super Admins. In fact, have a look at Roles and Capabilities in the Codex to make sure you know about all of the manage_network_* capabilities, as well as the *_sites capabilities. Essential reading if you’re a network admin.

Updating site options

Know that you will have to do things differently when creating admin forms for network-wide options. In a nutshell:

• you need to hook to the network_admin_menu action rather than admin_menu.
• your HTML forms need to have a different action attribute,
• you need to bind a submit handler to:
  • check for the admin nonce,
  • actually save the settings to the DB, and
  • redirect back to the right admin panel.
• Use network_admin_url() wherever you’d normally use admin_url().

I will not go through all of this detail here, as it is explained very well in this rare article:

Using the WordPress Settings API with Network Admin pages

I find this article tells you all that you need to know about how to actually save site meta, but if you want to read more, you can have a look at the official documentation, which currently simply links to here and here.

Getting hooked to site-wide options yet? Not to worry, there’s more!

Keep in mind that there exists a multitude of hooks that are specific to network administration. For example, to do various custom stuff to a site-wide option before saving it to the DB, do not bind to pre_update_option_{$option_name}, but to pre_update_site_{$option_name}.

Set option values via the terminal like a 1334 h@x0r

If you’re like me, you probably have set up your build process to auto-inject options to your dev environment, using wp-cli. Instead of

 wp option update option_name option_value

do something like this instead:

wp network meta set 1 option_name option_value

where 1 is the number of your multisite environment.

How to nag the right admin

To show notices to the network admin, do not bind to admin_notices, instead bind to network_admin_notices.

The surprising secret argument of the activation hook that nobody knew about!!!

Apologies, when I’m blogging I sometimes go into full SEO mode. Anyhow…

For your activation handler to work, you will first need to bind a function with register_activation_hook(), as usual. It turns out that your activation handler can take a parameter that tells you whether the plugin is being network-activated or not.

Here’s a handy way I like to use to create options that can either be global on the multisite level, or bound to the current blog, depending on whether your plugin was network-activated or activated on a single blog:

function activation_hook( $network_active ) {
    call_user_func(
        $network_active ? 'add_site_option' : 'add_option',
        'option_name',
        'option_value'
    );
}
register_activation_hook( __FILE__, 'activation_hook' );

Clean up after yourself!

Remember to do the same in your uninstall.php. You do clean up after yourself, don’t you? Of course you do, you’re a developer, not a filthy pig.

Remember, you will not be able to use is_plugin_active_for_network(), because by the time the uninstall code runs, the plugin should have already been deactivated. Since the plugin is being uninstalled completely, you can do something like the following, just to be on the safe side:

// delete from site meta
delete_site_option( 'option_name' );

// also delete from options table for all blogs
global $wpdb;
foreach ( $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" ) as $blog_id ) {
    switch_to_blog( $blog_id );
    delete_option( 'option_name' );
    restore_current_blog();
}

You will also likely want to delete any custom tables you may have created. The trick here is to iterate over all the blogs and let WordPress choose the right DB prefix.

foreach ( $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" ) as $blog_id ) {
    switch_to_blog( $blog_id );
    $wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}mytable" );
    restore_current_blog();
}

If you have chosen the separate tables way, you should also hook a DROP TABLE query to the delete_blog hook:

function delete_blog_tables( $blog_id, $drop ) {
    if ( $drop ) {
        switch_to_blog( $blog_id );
        $wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}mytable" );
        restore_current_blog();
    }
}
add_action( 'delete_blog', 'delete_blog_tables' );

If on the other hand you have one table for all blogs, and your rows have a blog_id column, do something more in the tune of:

function delete_blog_tables( $blog_id, $drop ) {
    if ( $drop ) {
        $wpdb->query( "DELETE FROM {$wpdb->prefix}mytable WHERE blog_id = $blog_id" );
    }
}
add_action( 'delete_blog', 'delete_blog_tables' );

There! All clean now!

Cron

You will want to use that handy little foreach loop in more than just the uninstall script. For instance, suppose you’re using cron. If your plugin is network activated, cron will run once for the network, not once per blog. Assuming your cron handler needs to do stuff to each blog, you’d do something like:

function cron_handler( ) {
    if ( is_plugin_active_for_network( 'myplugin/myplugin.php' ) ) {
        global $wpdb;
        foreach ( $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" ) as $blog_id ) {
            switch_to_blog( $blog_id );
            do_stuff();
            restore_current_blog();
        }
    } else {
        do_stuff();
    }
}
add_action( 'cron_hook', 'cron_handler' );

if ( false === wp_next_scheduled( 'cron_hook' ) ) {
    wp_schedule_event( time(), 'every_now_and_then', 'cron_hook' );
}

function do_stuff() {
    // do your stuff here
}

This way if your plugin runs network-wide, then your stuff is done on each one of the blogs on your multisite. But if the plugin is activated on the blog level, it does stuff only on the current blog.

Good stuff!

Super secret plugin header: Network

Edit: This plugin header seems to not be respected any more; perhaps this is why it is not documented. It is part of WordPress history.

Although you wouldn’t have guessed it from reading the relevant documentation, the plugin header, i.e. that special block of comments that you put at the top of your main plugin file, can have something to say about network activation. (A tiny hint is given in the Codex that such a header exists, although the documentation does not currently bother explaining what it does. After all, if everything was documented, where would the fun be?)

If your plugin is intended to be only network activated, and not activated on the blog-level in multi-sites, then add this line to your plugin’s header:

Network: True

Now WordPress will not give the activation option to mere blog admins.

Are you still with me?

Awesome! There you have it! Now you know all that I currently know about WordPress multisite and network activated plugins. Which is arguably not a lot. If you know more and feel like sharing, you’re free to comment below.

Hopefully you now have some grasp of the types of things you should be looking out for when you take your plugin for a ride into the wacky world of network activation.

Take care.

Alex

The post 🖧 The wacky world of network activated WordPress plugins in multisite appeared first on Alexandros Georgiou.

No matter which tool you’re using, building, testing, packaging and deploying a WordPress plugin should be one command. That way when you’re dev testing, you are actually testing the whole process, including installation, activation and deactivation of the plugin’s zip file. grunt-shell and wp-cli are your friends. Use wp option liberally in your dev deployment code.

My Gruntfile.js describes all the steps needed between my code sitting in my working directory and the same code running in my WordPress dev environment.

Grunt alias tasks let you define this process hierarchically. Use them! I aim to model the process so that at some level it has some resemblance to steps from the waterfall model: build, package, test, and deploy are verbs that I always aim to define in my script. Then, at a lower level I can define which grunt plugins actually accomplish each step.

When you have defined the steps in this way, then you can begin to create builds of varying quality or for various purposes. Testing takes too long to run every time in your development cycle? Create a quick build that excludes it. Want to have separate builds with and without documentation included? Define another package verb. Want to create a deliverable package but not deploy it? Create a task that omits the deploy verb.

The following is from an actual project I’m working on. Don’t worry about the details. You have your own workflow. All I’m saying is that you will benefit from structuring your script hierarchically.

Here’s my increasingly verbose meme. Make it viral!

The post 🐗 Building WordPress plugins with an increasingly verbose Gruntfile appeared first on Alexandros Georgiou.

Some things to note about dismissible notices

Don’t you just hate how this functionality has still not made it into core? Legend has it that dismissible notices were introduced back in WordPress 4.2, but that only means that when you click the little “x” at the top right, the notice box becomes hidden. The way to enable this is that you add a .is-dismissible class into your notice’s markup:

<div class="notice notice-warn is-dismissible">your message here</div>

And that hides the box. Until the next page refresh. This is not only annoying, it also goes against the WordPress.org guidelines:

Upgrade prompts, notices, and alerts should be limited in scope and used sparingly or only on the plugin’s setting page. Any site wide notices or embedded dashboard widgets must be dismissible. Error messages and alerts should include information on how to resolve the situation, and remove themselves when completed.

So for those of us aspiring to be hosted on WordPress.org it’s a necessity, rather than a luxury feature, to be able to let the user dismiss notices persistently.

Requirements analysis

WordPress tradition has it that you store an option in the database. That way you know not to show the same notice again. But this is something that you have to do over and over again, so it’s exactly the kind of thing that you want to include in all your code as a library. You want something that can be easily called from wherever, so the tried and true singleton pattern will do. You need the ability to be able to assign a slug to your notice, so you know how to store it in the options table. But you also want to be able to show the occasional non-dismissible notice. Finally, let’s be nice and clean up after ourselves. The options will be deleted when our plugin is uninstalled.

Let’s do this!

Writing code with class

We need something that can be included from our plugin (or theme). Let’s make a singleton class that can hold arrays of different types of notices (success, info, warn, error):

<?php

// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( 'MyPlugin_Admin_Notices' ) ) {

    class MyPlugin_Admin_Notices {

        private static $_instance;
        private $admin_notices;
        const TYPES = 'error,warning,info,success';

        private function __construct() {
            $this->admin_notices = new stdClass();
            foreach ( explode( ',', self::TYPES ) as $type ) {
                $this->admin_notices->{$type} = array();
            }
        }

        public static function get_instance() {
            if ( ! ( self::$_instance instanceof self ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }
    }
}

MyPlugin_Admin_Notices::get_instance();

Nice. This is a useful bucket where we can throw in notices. They will be retrieved for rendering only later, when we will add code to the admin_notices action.

An API for entering notices from our code

For now, let’s add in some methods to our class for populating our notice arrays:

public function error( $message, $dismiss_option = false ) {
    $this->notice( 'error', $message, $dismiss_option );
}

public function warning( $message, $dismiss_option = false ) {
    $this->notice( 'warning', $message, $dismiss_option );
}

public function success( $message, $dismiss_option = false ) {
    $this->notice( 'success', $message, $dismiss_option );
}

public function info( $message, $dismiss_option = false ) {
    $this->notice( 'info', $message, $dismiss_option );
}

private function notice( $type, $message, $dismiss_option ) {
    $notice = new stdClass();
    $notice->message = $message;
    $notice->dismiss_option = $dismiss_option;

    $this->admin_notices->{$type}[] = $notice;
}

Notice the visibility of the functions. The four public functions that comprise our API all defer to the private function that does the data collection. We’ll let the user enter a message string, and optionally give a slug with the dismiss_option parameter. If set, this will be part of the database option’s slug.

Writing the markup

We have a mechanism for adding notices into our memory, now let’s dump them to the admin area as markup. This will happen on the admin_notices action, so first add this to the constructor:

add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );

and then let’s actually write the markup. I’ve chosen to show notices in decreasing levels of severity, hence the nested loops:

public function action_admin_notices() {
    foreach ( explode( ',', self::TYPES ) as $type ) {
        foreach ( $this->admin_notices->{$type} as $admin_notice ) {

            $dismiss_url = add_query_arg( array(
                'myplugin_dismiss' => $admin_notice->dismiss_option
            ), admin_url() );

            if ( ! get_option( "myplugin_dismissed_{$admin_notice->dismiss_option}" ) ) {
                ?><div
                    class="notice myplugin-notice notice-<?php echo $type;

                    if ( $admin_notice->dismiss_option ) {
                        echo ' is-dismissible" data-dismiss-url="' . esc_url( $dismiss_url );
                    } ?>">

                    <h2><?php echo "My Plugin $type"; ?></h2>
                    <p><?php echo $admin_notice->message; ?></p>

                </div><?php
            }
        }
    }
}

Note how we show a notice only if the DB does not have a corresponding option named myplugin_dismissed_$dismiss_option. We’ll need a mechanism to set that DB option when the user clicks to dismiss the notice. We will do this from JavaScript, making a call with that option name as a GET parameter, so that we know to set the correct database option.

Notifying the backend from the admin front

When a notice is dismissible, we output a data-dismiss-url attribute in the HTML. We’ll use that from JavaScript to make a call to that URL:

/**
 * Admin code for dismissing notifications.
 *
 */
(function( $ ) {
    'use strict';
    $( function() {
        $( '.myplugin-notice' ).on( 'click', '.notice-dismiss', function( event, el ) {
            var $notice = $(this).parent('.notice.is-dismissible');
            var dismiss_url = $notice.attr('data-dismiss-url');
            if ( dismiss_url ) {
                $.get( dismiss_url );
            }
        });
    } );
})( jQuery );

Pretty standard stuff. When a dismissible notice from our plugin is clicked on its .notice-dismiss, get the dismiss_url and call it. I guess I could have used a fancy framework like VanillaJS for this, but I chose plain old jQuery instead :-p

Don’t forget the usual enqueue script shenanigans:

public function action_admin_enqueue_scripts() {
    wp_enqueue_script( 'jquery' );
    wp_enqueue_script(
        'myplugin-notify',
        plugins_url( 'assets/scripts/myplugin-notify.js', __FILE__ ),
        array( 'jquery' )
    );
}

and add this to our constructor so the enqueuing will actually happen:

add_action( 'admin_enqueue_scripts', array( &$this, 'action_admin_enqueue_scripts' ) );

Perfect. Our little piece of JavaScript code now lives in the WordPress admin screens.

Setting the DB option

Now we’ll just need to catch the request on the PHP side and set a database option. Let’s do this on the admin_init action:

add_action( 'admin_init', array( &$this, 'action_admin_init' ) );

…and this is the code that will set an option in the database. Note how the name is constructed from the GET parameter in the request URL.

public function action_admin_init() {
    $dismiss_option = filter_input( INPUT_GET, 'myplugin_dismiss', FILTER_SANITIZE_STRING );
    if ( is_string( $dismiss_option ) ) {
        update_option( "myplugin_dismissed_$dismiss_option", true );
        wp_die();
    }
}

Once the option is set, we can just let WordPress die. No need to return the admin interface to the browser, this is just a background AJAX call.

Cleaning up after ourselves

Unfortunately, even in this day and age, many developers don’t think it’s important to clean up the trash they leave in the poor user’s database. This is even more infuriating when you consider that it rarely takes more than a couple of lines of code. Don’t be that guy. Create an uninstall.php file with the following content.

<?php
if ( defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    global $wpdb;
    $wpdb->query( 'DELETE FROM wp_options WHERE option_name LIKE "myplugin_dismissed_%";' );
}

We can exploit the fact that we know the common prefix of all the dismissal DB options, and thus we can delete them all in one go, circumventing the delete_option() function altogether:

Expecting the unexpected

If you put together all of the above you already have a nice way to show persistent dismissible admin notices. But why stop there? We can hack away some more and make sure that any runtime errors in our code show up as notices too.

Imagine a clueless user sees your theme not working. Which do you prefer? To have to explain to them how to enable debugging and how to find and send you the logs from the wordpress unix directory on the host? Or do you simply ask them to copy the error on the screen and send it to you via email?

Observe this little hack that takes advantage of the PHP error reporting mechanism:

public static function error_handler( $errno, $errstr, $errfile, $errline, $errcontext ) {
    if ( ! ( error_reporting() & $errno ) ) {
        // This error code is not included in error_reporting
        return;
    }

    $message = "errstr: $errstr, errfile: $errfile, errline: $errline, PHP: " . PHP_VERSION . " OS: " . PHP_OS;

    $self = self::get_instance();
    switch ($errno) {
        case E_USER_ERROR:
            $self->error( $message );
            break;

        case E_USER_WARNING:
            $self->warning( $message );
            break;

        case E_USER_NOTICE:
        default:
            $self->notice( $message );
            break;
    }

    // write to wp-content/debug.log if logging enabled
    error_log( $message );

    // Don't execute PHP internal error handler
    return true;
}

Notice how this method is static, since we’d like to be able to call it from both dynamic and static contexts. We can now hook it up to PHP’s error reporting like so:

set_error_handler( array( 'MyPlugin_Admin_Notices', 'error_handler' ) );

and after your code ends, unhook it so as not to interfere with the WordPress core or other components:

restore_error_handler();

This will pop your error handler from a stack and return to whatever error handling mechanism was there before. Make a habit of surrounding your function bodies with these two lines, and you will know that whatever happens, you’ll at least get a visible user-friendly and developer-friendly error message on the admin screens.

Putting it all together

JS

/**
 * Admin code for dismissing notifications.
 *
 */
(function( $ ) {
    'use strict';
    $( function() {
        $( '.myplugin-notice' ).on( 'click', '.notice-dismiss', function( event, el ) {

            var $notice = $(this).parent('.notice.is-dismissible');
            var dismiss_url = $notice.attr('data-dismiss-url');
            if ( dismiss_url ) {
                $.get( dismiss_url );
            }
        });
    } );
})( jQuery );

PHP

<?php
if ( defined( 'WP_UNINSTALL_PLUGIN' ) ) {
    global $wpdb;
    $wpdb->query( 'DELETE FROM wp_options WHERE option_name LIKE "/* @echo slugus */_dismissed_%";' );
}

<?php
// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( 'MyPlugin_Admin_Notices' ) ) {

    class MyPlugin_Admin_Notices {

        private static $_instance;
        private $admin_notices;
        const TYPES = 'error,warning,info,success';

        private function __construct() {
            $this->admin_notices = new stdClass();
            foreach ( explode( ',', self::TYPES ) as $type ) {
                $this->admin_notices->{$type} = array();
            }
            add_action( 'admin_init', array( &$this, 'action_admin_init' ) );
            add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );
            add_action( 'admin_enqueue_scripts', array( &$this, 'action_admin_enqueue_scripts' ) );
        }

        public static function get_instance() {
            if ( ! ( self::$_instance instanceof self ) ) {
                self::$_instance = new self();
            }
            return self::$_instance;
        }

        public function action_admin_init() {
            $dismiss_option = filter_input( INPUT_GET, 'myplugin_dismiss', FILTER_SANITIZE_STRING );
            if ( is_string( $dismiss_option ) ) {
                update_option( "myplugin_dismissed_$dismiss_option", true );
                wp_die();
            }
        }

        public function action_admin_enqueue_scripts() {
            wp_enqueue_script( 'jquery' );
            wp_enqueue_script(
                'myplugin-notify',
                plugins_url( 'assets/scripts/myplugin-notify.js', __FILE__ ),
                array( 'jquery' )
            );
        }

        public function action_admin_notices() {
            foreach ( explode( ',', self::TYPES ) as $type ) {
                foreach ( $this->admin_notices->{$type} as $admin_notice ) {

                    $dismiss_url = add_query_arg( array(
                        'myplugin_dismiss' => $admin_notice->dismiss_option
                    ), admin_url() );

                    if ( ! get_option( "myplugin_dismissed_{$admin_notice->dismiss_option}" ) ) {
                        ?><div
                            class="notice myplugin-notice notice-<?php echo $type;

                            if ( $admin_notice->dismiss_option ) {
                                echo ' is-dismissible" data-dismiss-url="' . esc_url( $dismiss_url );
                            } ?>">

                            <h2><?php echo "My Plugin $type"; ?></h2>
                            <p><?php echo $admin_notice->message; ?></p>

                        </div><?php
                    }
                }
            }
        }

        public function error( $message, $dismiss_option = false ) {
            $this->notice( 'error', $message, $dismiss_option );
        }

        public function warning( $message, $dismiss_option = false ) {
            $this->notice( 'warning', $message, $dismiss_option );
        }

        public function success( $message, $dismiss_option = false ) {
            $this->notice( 'success', $message, $dismiss_option );
        }

        public function info( $message, $dismiss_option = false ) {
            $this->notice( 'info', $message, $dismiss_option );
        }

        private function notice( $type, $message, $dismiss_option ) {
            $notice = new stdClass();
            $notice->message = $message;
            $notice->dismiss_option = $dismiss_option;

            $this->admin_notices->{$type}[] = $notice;
        }

	public static function error_handler( $errno, $errstr, $errfile, $errline, $errcontext ) {
		if ( ! ( error_reporting() & $errno ) ) {
			// This error code is not included in error_reporting
			return;
		}

		$message = "errstr: $errstr, errfile: $errfile, errline: $errline, PHP: " . PHP_VERSION . " OS: " . PHP_OS;

		$self = self::get_instance();

		switch ($errno) {
			case E_USER_ERROR:
				$self->error( $message );
				break;

			case E_USER_WARNING:
				$self->warning( $message );
				break;

			case E_USER_NOTICE:
			default:
				$self->notice( $message );
				break;
		}

		// write to wp-content/debug.log if logging enabled
		error_log( $message );

		// Don't execute PHP internal error handler
		return true;
	}
    }
}

MyPlugin_Admin_Notices::get_instance();

Thanks for reading

Please comment on what you liked or didn’t like in my code. What would you have done differently? Can you spot any bugs?

Until next time. Dismissed!

The post 🗨 Dismissible notices that persist when refreshing the WordPress admin screens appeared first on Alexandros Georgiou.

Ten Things Every WordPress Plugin Developer Should Know

Actually you’ll probably want to read this before even starting your project; but better late than never! It’s packed with essential info that you should know. If you’ve missed any of the info in this article, go back to your code and fix it. There’s stuff about common practices, coding standards, etc.

PHP Coding Standards

This is a list of PHP coding standards that WordPress developers follow, both in core and in themes and plugins. It’s a requirement for submission to wordpress.org but it would be really nice to follow as many of these as possible even if you’re not planning to submit your code there.

Ideally you’ll want to use some tools for this. A quick search on GitHub reveals a number of syntax checkers. Here’s one that I use with Eclipse: https://github.com/edpittol/wordpress-eclipse-formatter, and another one for CodeSniffer (which can integrate nicely with a number of IDEs): https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.

Whatever you use, it doesn’t hurt to double check your code one last time. In Eclipse Formatter for instance, there is no way to check for “Yoda” conditions as far as I know, so you’ll want to manually check for those if you’re using it.

JavaScript Coding Standards

Have you checked your PHP code for compliance to the coding standards? Good! Get ready to do it again, this time for your JavaScript files; at least the unminified copies of them. Here’s a project that uses ESLint to help you enforce the standards: https://www.npmjs.com/package/eslint-plugin-wordpress. If you have a lot of JavaScript in your code, it might pay to integrate this into your pre-build checks, but as with PHP, always have one last look using your eyeballs.

WordPress plugins

If you’re writing a plugin, this is a short list of conditions that your project must meet before you publish to WordPress.org. It has more to do with functionality than standards, and essentially it’s about not being evil with your code.

Detailed Plugin Guidelines

This is essentially a longer version of the above. A definite must read if you’re publishing to WordPress.org. It’s about licensing, versioning, what you can and can’t do, etc.

Theme Review Process

If you’re writing a theme that you plan to publish to WordPress.org, check that it at least conforms to all the required items and try to conform to as many recommended items as possible. The write-up for the recommended guidelines is not complete as of the writing of this article, but there’s some very useful guidelines in there.

Theme Unit Test

Again, if you’re writing a theme for WordPress.org, you will also want to check a number of things against the provided Theme Unit Test. It’s probably a good idea to do this even if you’re publishing elsewhere.

ThemeForest General File Preparation Guidelines

If you’re publishing to ThemeForest, you will have to follow these guidelines on how to bundle your files.

WordPress Phase 1 Submission Requirements – Q&A

This is a list of guidelines to follow before submitting to ThemeForest. There’s a number of things listed that are not allowed, so make sure to check.

A step-by-step guide to the upload process

When uploading to ThemeForest, you will also want to follow these guidelines. They are mostly about the upload process but also include some information about how to bundle your files.

Professional WordPress: Design and Development

Finally, this is a book, not an actual checklist, but still I recommend that you at least glance through the table of contents. I’ve found this book very helpful. It covers all topics related to WordPress development and it’s very likely that whatever it is you’re trying to do, there might be a better way of doing it. WordPress is a complex system and it’s only getting more complex by the day.

My recommendation is that you go through the table of contents and read any chapter that talks about things you do in your theme or plugin. There are things you might have missed.

Too meta? Perhaps! But no matter what and where you’re publishing, if you want to be professional about it, don’t assume you know everything. At least glance through all of these guidelines.

The post ☑ WordPress checklists to go through before publishing a theme or plugin appeared first on Alexandros Georgiou.