WPRun – WordPress development in OOP

WPRun simplifies WordPress development in OOP with just ONE simple base class!

Why WPRun?

Simplify creating your own WP components. WPRun provides a simple base class that makes it easy to develop in WordPress with OOP, like:

  • adding action and filter methods
  • setting callback methods
  • using templates

Extending WPRun will help you to structure your classes in a consistent way:

  • only singleton objects
  • use create() to instantiate object
  • implement init() for initial code
  • auto-set action and filter callbacks by prefixing method names with action_ or filter_
  • use template files for presentation

And with only ONE tiny base class!

OOP

WPRun was built to make OOP development in WordPress easier. It’s a pragmatic OO approach and stays close to the WordPress way of developing. For example it uses the WP code conventions instead of the PHP PSR-2 code conventions.

KISS

Just ONE base class that will help you simplify WP development. Like Einstein said:

“Everything should be made as simple as possible (but not simpler)”

Create Component

Extend Class

Make your own component by extending the WPRun Base Class, f.e.:

final class My_Component extends WPRun_Base_1x0x0
{

}

Return to top

Create Instance

Create an instance of your component by using the static create() method:

My_Component::create();

Return to top

Initialize

Implement the init() method to add code to initialize the component (run right after instantiation):

final class My_Component extends WPRun_Base_1x0x0
{

    protected function init()
    {
        // some code...
    }

}

Return to top

Pass Arguments

To pass arguments to a WPRun subclass can be done by passing them to the create() method:

My_Component::create( $param1, $param2 );

Those arguments will be passed on to the init() method:

final class My_Component extends WPRun_Base_1x0x0
{

    protected function init( $param1, $param2 )
    {
        // some code...
    }

}

Another way to get those arguments witin the class is to use the get_argument() method:

$param1 = $this->get_argument( 0 ); // get first argument
$param2 = $this->get_argument( 1 ); // get second argument

Return to top

Singleton

Subclasses of the WPRun Base Class are always singletons and cannot have more than one instance.

There are two ways to get the instance:

  1. The return value of the create() method ($my_component = My_Component::create();)
  2. Use the static get_instance() method on a particular class (f.e. My_Component::get_instance()). Only works if object was created, else it will trigger an error.

Return to top

WordPress Actions and Filters

Auto-set

Methods prefixed with action_ and filter_ will be automatically added to the WP hooks. For example if you want to add an action for plugins_loaded then create the method action_plugins_loaded:

final class Some_Example extends WPRun_Base_1x0x0
{

    protected function action_plugins_loaded()
    {
        // some code...
    }

}

Create a method called filter_the_content to add a WP filter for the_content:

final class Other_Example extends WPRun_Base_1x0x0
{

    protected function filter_the_content( $content )
    {
        // some code...

        return $content;
    }

}

A filter always has one argument containing the content and needs to return the new content.

Return to top

Priority

Set the priority to action and filter methods by adding an underscore followed by the priority number to the end of the method name:

final class Priority_Example extends WPRun_Base_1x0x0
{

    protected function action_plugins_loaded_100()
    {
        // this action has the priority 100
    }

}

Return to top

Accepted Arguments

The WP functions add_action and add_filter also have a param for accepted arguments. This will automatically set by WPRun with the amount of parameters defined in the callback method.

Return to top

Page Only

When creating components for the admin section, like an admin options page. Actions and filters within the class should only be applied when loading that page. This can be done by setting the property $page_hook.

Return to top

Properties

$action_prefix

Set prefix for WP action methods (default: "action_").

$filter_prefix

Set prefix for WP filter methods (default: "filter_").

$page_hook

Set the page hook when action and filter methods within the class only needs to be added when a particular admin page is loaded (default: null).

$autoset_hook_methods

Set to false if you don’t want action and filter methods to be set automatically (default: true).

Return to top

Change Property Values

WPRun contains a few protected properties which can be changed by subclasses.

Method 1:

final class General_Help_Tab extends WPRun_Base_1x0x0
{

    protected $action_prefix = 'a_';

}

Or method 2 within init():

final class General_Help_Tab extends WPRun_Base_1x0x0
{

    protected function init()
    {
        $this->action_prefix = 'a_';
    }

}

Callback Methods

Use get_callback() to get a callable of the given method. This callable can be passed on as a callback:

$callback = $this->get_callback( 'show_help' );

In the following example the show_help() method will be passed on as a callback. Normally such a callback needs to bepublic, but when using get_callback() the callback method can also be implemented as protected. Just like in this example:

final class General_Help_Tab extends WPRun_Base_1x0x0
{

    protected function action_admin_head()
    {
        $screen = get_current_screen();

        $screen->add_help_tab( array(
            'id'        => 'wprun-help-intro',
            'title'     => __( 'WPRun Intro', 'demo-wprun' ),
            'callback'  => $this->get_callback( 'show_help' ),  // set "show_help" as callback
        ) );
    }

    protected function show_help()
    {
        $this->show_template( PLUGIN_DIR .'/templates/general-help-tab.php' );
    }

}

Return to top

Templates

WPRun encourages to use templates to separate presentation from your main code. This results in clean PHP classes withoutecho‘s and HTML code. This makes your application better structured and more readable.

Here is an example on how to show a template:

$this->show_template( PLUGIN_DIR .'/templates/demo-page.php' );

Return to top

Template Variables

The second arguments is optional and can be used to pass an array of variables which can be used inside the template.

$this->show_template( '/templates/demo-page.php', array(
    'title'    => __( 'Some title', 'demo-wprun' ),
    'content'  => __( 'Lorum ipsum', 'demo-wprun' ),
) );

Within a template the array of template vars are accessible with $vars:

<h1><?php echo $vars[ 'title' ]; ?></h1>
<?php echo $vars[ 'content' ]; ?>

NOTE: By using the extract() method of PHP you can create separate variables of each item in $vars, like:

<?php extract( $vars ); ?>
<h1><?php echo $title; ?></h1>
<?php echo $content; ?>

Return to top

Render Template

This method will render the given template and returns the content. It doesn’t show the output like show_template() does.

$help_content = $this->render_template( PLUGIN_DIR .'/templates/demo-help.php' );

Return to top

The autoloader takes care of loading class files. To make it work you should create an instance and add at least one path to it.

// include autoloader
if ( ! class_exists( 'WPRun_Autoloader_1x0x0' ) ) {
    require_once __DIR__ . '/includes/libs/wprun/class-wprun-autoloader.php';
}

// create instance
$autoloader = new WPRun_Autoloader_1x0x0();

// add folder
$autoloader->add_path( __DIR__ . '/includes/' );

If you also want to include all subfolders, then pass “true” as second argument.

// add folder (and subfolders)
$autoloader->add_path( __DIR__ . '/includes/', true );

Return to top

Multiple Versions

The autoloader supports version postfixes in class names, f.e. FWP_HTML_Fields_1x0x0.

This solves a practical problem when you have more plugins using the same class(es), like libraries, but different versions. This would cause naming conflicts, because both versions share the same class name. When adding the version as a postfix the class names become unique.

You could also use these postfixes for your own library classes. The version postfix has the following format_{major}x{minor}x{patch}. So when you have a class MyClass and you want a versionized name:

  • version 1.0.0 becomes MyClass_1x0x0
  • version 2.4.11 becomes MyClass_2x4x11

Return to top

A real plugin that uses WPRun is WP External Links. Check the code to see how you can use WPRun to create your own plugin.

WPRun needs:

  • PHP version 5.3 or up
  • WordPress version 3.6 or up

Dual licensed under the MIT and GPLv2+ licenses.

This project hasĀ a repository on Github:

Leave a Reply