Tutorial: Add Custom Functionality To WPCD, Part 2

In our prior article in this series we showed how easy it is for a developer to add new functionality to the WPCD dashboard. However, “easy” comes with a limitation – the commands MUST run within the PHP script execution time limit. So that could mean 30 seconds to 600 seconds or more depending on how WordPress and PHP is configured on the WPCD site.

Still, that might not be the only limit – something like the free version of CloudFlare enforces an arbitrary limit of 100 seconds (or something similar) on all requests. So for all practical purposes, when using Cloudflare, the command must run within that time even if the PHP script execution time is higher.

And your NGINX or APACHE server might have limits on execution times as well.

As you might expect, we do have a method for handling longer running transactions. Its a tad bit more complicated but still easy to get started when using our sample plugin template.

While there are a lot of moving parts, if all you need to do is to fire off a single command without asking the user for attributes, then it’s not that big a deal.

So, in this article we’ll take a look at how that process works.

The Sample Plugin Again

In the sample add-on, which you can download from Github, there is an option for Export Database. This option has been setup as a long-running task.

When the Export Database button is clicked, it pops up a pseduo terminal window – I am sure you’re familiar with it if you’ve been using WPCD for a while.

If you want to understand what’s going on in the background to facilitate long-running transactions, take a look at the 3rd section in this document (“Async Execution Type 2”).

Sending A Command To The Server

As with the first article, the command(s) being sent to the server is centralized. But it’s placed in a DIFFERENT file – a text file.

The reason for this is because the command is longer – we need quite a few to make sure that when the command is completed, we get a call-back that announces it.

So, lets take a look at that file first. Navigate to the includes/scripts/ folder and pull up exportdb.txt file.

The line that contains the critical command is line . This command:

  1. Uses SUDO to switch to a restricted user (which has the same name as the domain)
  2. Run the wp db export command to place the file in the domain folder (which is writable for the user) and
  3. Outputs the results to a log file.

If you want to get your own command up and running fast, this is the line that needs to be changed.

Replace the area in red with your own command. You can replace it with something as simple as sudo -E ls ~ which simply lists out the home folder of the root/sudo user. The new command will look like this:

Now, when you click on the EXPORT DATABASE button you will notice two things:

  1. This simple command still takes a 60+ seconds to execute and
  2. The output shown in the “terminal” window is different:

When sending a command using the “long running” method, the minimum execution time is going to be 60 seconds. Thus, any command you need executed that is expected to take less time should be sent using the method we explained in the first article – it’s far more efficient that way.

Making Your Own Command

Now that you know where the critical commands are located, you might want to create your own button and link it to a file that contains a full set of your own commands. To do that we need to:

  1. Create a new command file – we’ll do this by just copying the existing exportdb.txt file.
  2. Create a new button on the screen and
  3. Link the command to the button which involves:
    1. Creating a new action function and
    2. Modifying a couple of existing utility functions to let them know about about the new command file and what’s in it.

Let’s get started on this!

Create A New Command File

Copy the exportdb.txt to a new file – lets call it article02.txt. It should be placed in the same scripts folder as exportdb.txt.

Modify the file to create a new command sequence.

echo "done" && {
sudo -E tar -vczf /var/www/##DOMAIN##/html/backupfiles.gz /var/www/##DOMAIN##/html/ >> ##SCRIPT_LOGS##.log.intermed 2>&1 ;
sudo -E mv ##SCRIPT_LOGS##.log.intermed ##SCRIPT_LOGS##.log.done ;
sudo -E wget -q ##CALLBACK_URL##;
} > /dev/null 2>&1 &

This new command simply creates an archive of all the files in the domain root.

Create A New Button

Now, lets create a new button with the title Compress Files.

The existing code is in a function named get_server_fields_sample. It’s located in the includes/wpapp-tabs-sample.php file. The current button code looks like this (you can find it by searching for $actions[‘sample-action-c’])

So let’s just duplicate that entire code block. Then, change the following:

  • Modify $actions[‘sample-action-c’] to $actions[‘sample-action-d’]. This is important. This is the name of the action and is how we’ll hook up the front-end click to the php execution code.
  • Change the label that says “Export Database” to “Compress Files” or something similar.
  • Change the description to something relevant.
  • Change the confirmation prompt.
  • Change the console message.

The image above shows the new code. Now, when you go to the tab you’ll see a button that reflects what the action is about to do. Clicking on it will give you a nice confirmation message and the terminal will tell you what’s about to happen.

Of course, nothing will actually happen because we haven’t hooked up button to new PHP code nor have we hooked up the PHP code to the new action file.

Link the New Button To PHP Code

To link the button to PHP code, we need to modify two sections in the current sample code:

  • Find the function tab_action_sample.
  • Add a new “case” statement to reflect the new button’s name (sample-action-d).

So, the new code looks as follows (new code is shown in the red box):

Now, of course, we need to create a new function named sample_action_d. You can do this by duplicating the sample_action_c function. Do NOT duplicate sample_action_b or sample_action_a since those are not handling a long-running command.

After duplicating the sample_action_c function, rename it to sample_action_d.

That’s it. The two functions are exactly the same. We could have re-used the sample_action_c function but, by using a new function we’ve ensured you can experiment with sample_action_d after completing this tutorial.

We will need to hook up the PHP code to the new command file though.

Connect PHP Code To The New Command File

We have to modify two filter functions to let the PHP code know about our new command file.

The first function is called, appropriately enough wpcd_script_file_name. In there modify the “if” statement that is checking for file names to also check for our new file name. The new function looks like this (modifications in the red box):

The second filter function that needs to be modified is called wpcd_wpapp_replace_script_tokens. In there, just copy the only “if” block that exists and then change the file name that is being checked.

We could, of course, reuse the existing code with just a minor change to the “if” condition. But, by doing it this way, you can pass different parameters to the command script later. The revised function looks like this:

Testing Your Work

With all these changes, the sample add-on tab now sports a slightly new look!

You can see the new button and description are all there, looking nice and professional. When you click on it, you get a nice contextual popup:

And that’s it, you’re done. Everything has been wired up and that button should be compressing all the files in the domain. The final compressed file should be at the root of the domain. You should log into your server to verify that’s the case!

Wrap Up

Whew! That seemed like a lot.

If all you want is to add a single button to the screen you can just modify the existing command files – that’s nice and simple.

If you want to add multiple buttons to the screen you need to do more work – that’s what the entire latter part of this article covered.

But, overall, for most experienced developers, this should all be relatively simple and straight forward.

We can’t wait to see what you do with these new capabilities!

View all articles in this series.

Was This Article Useful? Or do you have questions or comments about it (or our products & services)? We'd love to hear from you!

Please enter your name.
Please enter a message.
You must accept the Terms and Conditions.
Please check the captcha to verify you are not a robot.

Automatic Notification Of New Articles

Sign up to get automatic notifications of new articles.  This is a different list than our standard list - you only get new articles once a week (usually on Mondays).  No other emails will be sent unless you sign up for our general list as well.

Posted in ,