README

A backbone for utilizing the Wordpress Plugin API , using php@7.4 and OOP.

Getting started

Prerequisites

Php ^7.4.*
Composer ^2
WordPress >= 5.5.0

Installation

composer require jascha030/wp-plugin-lib

Usage

The easiest way to explain usage is with an example of the main plugin file.

The name of the package might be deceiving, Plugin refers to the WP Plugin API, which means that it can be used for either a plugin or a theme. In this example we pretend to be building a plugin, but for a theme we would just write our code in the theme's functions.php file instead of the main plugin file.

main-plugin-file.php

<?php
/**
 * Plugin jascha030/wp-plugin-lib
 *
 * @package   Jascha030
 * @author    Jascha van Aalst
 * @copyright 2021
 * @license   GPL-2.0+
 *
 * @wordpress-plugin
 *
 * Plugin Name: Package Tester
 * Plugin URI: https://github.com/jascha030/wp-plugin-lib
 * Description: Test plugin for package jascha030/wp-plugin-lib
 * Version: 1.0.0
 * Author: Jascha030
 * Author URI: https://github.com/jascha030.
 */

namespace Jascha030;

use Exception;
use Jascha030\PackageTest\Hookable\TestingAfterInitHookable;
use Jascha030\PackageTest\Hookable\TestingHookable;
use Jascha030\PackageTest\PackageTestPlugin;
use Jascha030\PluginLib\Container\Config\ConfigInterface;

use function Jascha030\PluginLib\Functions\buildPlugin;

/**
 * Check if WordPress' ABSPATH const is loaded
 */
if (! defined('ABSPATH')) {
    die('Forbidden');
}

/**
 * Get autoloader
 */
$autoloaderPath = __DIR__.'/vendor/autoload.php';

if (! is_readable($autoloaderPath)) {
    throw new \RuntimeException(sprintf('Could not find file \'%s\'. It is generated by Composer. Use \'install --prefer-source\' or \'update --prefer-source\' Composer commands to move forward.',
        $autoloaderPath));
}

include $autoloaderPath;

add_action('plugins_loaded', function () {
    // Set the hookable classes, ServiceProvider and PostTypes.
    $config = (new ConfigInterface('Package test plugin', __FILE__))->setHookables([
        TestingHookable::class,
        TestingAfterInitHookable::class
    ]);

    // The main plugin class extends PluginApiRegistryInterface, which implements FilterManagerInterface.
    $plugin = buildPlugin($config, PackageTestPlugin::class);
    // Injected dependencies will be hooked after calling the run() method.
    $plugin->run();
});

Hookables

The plugin revolves around classes implementing HookableInterface or one of it's extended interfaces. Hookables should only contain public methods that are hooked to WordPress' filters or actions.

I recommend using the LazyHookableInterface, classes implementing this will only be constructed upon the first call to a hook containing one of its methods.

Here's an example of a class Implementing LazyHookableInterface:

TestingHookable.php

<?php

namespace Jascha030\PackageTest\Hookable;

use Jascha030\PluginLib\Service\Hookable\LazyHookableInterface;

class TestingHookable implements LazyHookableInterface
{
    public static array $actions = [
        // 'hook' => ['method', priority, numberOfArguments]
        // If the prio and number are default you hook a method with call as `'hook' => 'method',`
        'init' => ['initMethod', 10, 1]
    ];

    public static array $filters = [];

    public static function getActions(): array
    {
        return static::$actions;
    }

    public static function getFilters(): array
    {
        return static::$filters;
    }

    final public function initMethod(): void
    {
        echo 'What\'s up, twitter world?';
        die();
    }
}

Providers

The standard container used is the Psr11 wrapper from the pimple/pimple package. Providers follow pimple's ServiceProviderInterface.

Testing

Included with the package are a set of Unit tests using phpunit/phpunit. For ease of use a composer script command is defined to run the tests.

composer run phpunit

A code coverage report is generated in the project's root as cov.xml. The cov.xml file is not ignored in the .gitignore by default. You are encouraged to commit the latest code coverage report, when deploying new features.

Code style & Formatting

A code style configuration for friendsofphp/php-cs-fixer is included, defined in .php-cs-fixer.dist.php.

To use php-cs-fixer without having it necessarily installed globally, a composer script command is also included to format php code using the provided config file and the vendor binary of php-cs-fixer.

composer run format

License

This composer package is an open-sourced software licensed under the MIT License

jascha030 / wp-plugin-lib

Maintainers

Details