Download the PHP package pfaciana/wp-routines without Composer

WP Routines

WP Routines is an in-browser console for WordPress that displays a command line style output for executed code.

It brings a command line like interaction to the browser, but instead of the input being a text command, the input comes from the HTTP request. The purpose is to provide live real-time updates of code executing on the server. Often times this is used for admin tasks or cron jobs. Code that may take more than a few seconds to execute, and where real-time updates would be beneficial for progress and logging purposes. In additoin, it can also be interactive since it is simply a html output, that can have clickable events.

WP Routines can overlap similar use cases as the WP CLI, with two major differences. One, you don't need to learn or write CLI specific code. Second, more importantly, you may not always have access to the CLI on a particular server. However, it these two concerns are relevant to your use case, the WP CLI would typically be a better option.

Getting Started

Install as a composer package

NOTE: This also comes bundled in WP Debug Bar, which is another composer package.

If you are already using WP Debug Bar, or would like to, then you don't need to install WP Routines via composer.

How to Use

Concepts

There are three main concepts: a Stream, a Task and a Page, and the Routines singleton manages all of these.

Simply put, Routines is a collection of Pages. A Page is a collection of Tasks. A Task can be any registered function that accepts a Stream argument. A Stream instance is what allows the developer to send content to the browser.

Documentation Links

• Routines - A collection of Pages
• Page - A collection of task groups or Tasks
• Tasks - This is an abstract class. When extended represents a group of Tasks on a Page
• Task - A class that contains a callback method to be executed on a Page
• Stream - The layer that communicates with the ajax call to stream data

See the Wiki for the full documentation.

In its simplest form...

That's it! This will automatically create a WordPress admin page called Routines Console (the default name). On that page, the console html and a header of available task groups will display across the top. In this example, there will be just one task, called My Task Title. When the user clicks on My Task Title, an ajax call will be made to server and the response back will be a stream of data that will print out Hello World! to the console in real time. Now, WP Routines is much more powerful than that, but this is the most basic concept.

Additional Examples

Creating a Task

A note about default values

• Default title is 'Task #1', where the number is incremented as additional tasks are added
  
• Default group is 'Main'
  
• Default page is an auto-generated 'Routines Console' admin page
  
• Default priority is 10

Creating a Page

By default, you don't need to create a page, an admin page called 'Routines Console' will be created for you. However, you can override this, or create additional pages with the Page class.

Adding a Task or Tasks to a Page

Adding a Task or Tasks to a Page is identical to adding it to the $routines manager as shown above. This only difference is since you're adding it to an existing page, that will be used instead of the default or defined page from the config.

Defining a $page in the Task or Tasks object and registering them through the $routines manager is the same as not defining a $page in the Task or Tasks, but registering them through the $page itself. Both ways work and do the same thing.

Creating Tasks

See the Tasks Documentation for full set of $config options, but here are a couple of things to be aware of.

$this->taskPrefix - is the prefix a method should have to be registered as a task. Default: 'wpajax'. All methods that begin with this string (and are public methods) will automatically become a Task

$this->crons - is an array[] of methods to be registered as cron events. The first level keys are cron schedule ids registered to WordPress. If you want to use a custom cron schedule, you must create it first by hooking into the cron_schedules filter hook (See cron_schedules hooks docs). You can do this in the optional $this->preInit() method (See below for example). At the secondary level, the crons array uses the key as the name of the method and the value is the priority to run the cron action for that method. If the priority values is an array, then it will schedule multiple cron actions to match those priorities. You may want that for a cleanup method that runs before AND after other code has run.

Anonymous Classes

You can also use anonymous classes to build a Page, Tasks or Task. They can be placed anywhere in your code as long as it's after the composer autoload file has loaded and before the admin_menu has been created. Here are examples very minimal setup to get started. Everything else from above and in the documentation still apply.

For a Page you need a $this->config['menu_slug'] and $this->config['autoload'] = TRUE

For a Tasks you need at least one public method that starts with $this->taskPrefix

For a Task you need a public method named render

The Stream class

A new instance of the Stream class (see Stream documentation) gets created and sent to the active task from the Page that it's on.

NOTE: There are a set of handy filter hooks that allow you to customize the functionality of the Stream (See hooks documentation).

There are a small handful of methods available, but we'll go over the most important ones here.

Stream MAGIC chars

There currently are two arbitrary characters that manipulate the buffer output in a particular way.

Those chars are \a and \b. If you send those to the buffer, the browser console will interpret those as an instruction. This is similar to how \n is a new line. \a tells the console position to go to the beginning of the previous line, deleting everything that was on current line and on the one before. \b tells the console position to go to the end of the previous line, deleting anything on the current line. Oftentimes the current line is empty, so \b usually doesn't delete any output, just moves the last position back one spot.

Example

Outputs...

NOTE: Another way to do the same thing would be to combine the 4th and 5th send with $stream->send( "\a\aNew Line 2!" ); However, I wanted to break out steps into their individual parts for the explanation.

Example 2 - A spinning asterisk

Outputs...

Example 3 - A text progress bar

Outputs...

Example 4 - A HTML progress bar

Outputs...

Flexibility

I put a lot of effort to provide many different ways to do the same thing, depending on your coding preference and specific situation to make development as fast as possible. You can use the $routines singleton manager and build everything off that, you can create individual instances of classes and autoload them into the $routines manager, or create anonymous classes.

I also allow for shorthand version of most things. You can reference a Page, Tasks or Task by a string, config array or by a specific instance. The code will determine how to get what it needs. For a Page a string representation is the $this->config['menu_slug'], for a Tasks its the $this->group and for a Task its $this->title.