studiometa/wp-toolkit

WordPress utilities for Studio Meta.

2.2.2 2024-04-19 12:59 UTC

Requires

• php: ^8.1
• monolog/monolog: ^2.9|^3.0
• psr/log: ^1.1|^2.0|^3.0
• sentry/sentry: ^4.6
• studiometa/webpack-config: ^5.0|^6.0
• symfony/http-foundation: ^6.4|^7.0
• symfony/yaml: ^6.4|^7.0
• timber/timber: ^1.0|^2.0
• wecodemore/wordpress-early-hook: ^1.2

Requires (Dev)

• dealerdirect/phpcodesniffer-composer-installer: ^0.7.0
• php-stubs/wordpress-stubs: ^5.5
• phpunit/phpunit: ^9.0
• squizlabs/php_codesniffer: ^3.4
• szepeviktor/phpstan-wordpress: ^1.1
• wp-phpunit/wp-phpunit: ^6.4
• yoast/phpunit-polyfills: ^2.0

MIT

README

A PHP toolkit to boost your WordPress development! 🚀

Installation

Install the package via Composer:

composer require studiometa/wp-toolkit

Requirements

• PHP >=7.3

Usage

// Create Custom Post Type
use Studiometa\WPToolkit\Builders\PostTypeBuilder;

$cpt = new PostTypeBuilder( 'product' );
$cpt->set_labels( 'Product', 'Products' )
  ->set_has_archive( true )
  ->register();

// Create Custom Taxonomy
use Studiometa\WPToolkit\Builders\TaxonomyBuilder;

$tax = new TaxonomyBuilder( 'product-cat' );
$tax->set_post_types( 'product' )
  ->set_labels( 'Product Category', 'Product Categories' )
  ->register();

// Create a manager
use Studiometa\WPToolkit\Managers\ManagerInterface;

class CustomManager implements ManagerInterface {
  run() {
    add_action( 'init', array( $this, 'some_action' ) );
  }

  some_action() {
    // do something on init
  }
}

// Init all managers
use Studiometa\WPToolkit\Managers\ManagerFactory;
use Studiometa\WPToolkit\Managers\AssetsManager;
use Studiometa\WPToolkit\Managers\CleanupManager;

ManagerFactory::init(
  array(
    new AssetsManager(),
    new CleanupManager(),
    new CustomManager()
  )
);

AssetsManager

The AssetsManager manager does the heavy lifting of registering and enqueuing assets for you. It works with a configuration file in YAML with the following format:

<template-name-or-all>:
  css:
    <asset-id>: <asset-path-in-theme>
  js:
    <asset-id>: <asset-path-in-theme>

If used with our Webpack configuration package, you can also specify entrypoints and all their dependencies to be registered and enqueued.

all:
  entries:
    - css/app.scss
    - js/app.js

new AssetsManager(
  get_template_directory() . '/config/assets.yml',
  get_template_directory() . '/dist/assets-manifest.json',
);

Parameters

• $configuration_filepath (string): path to the config.yml file, defaults to config/assets.yml in your theme.
• $webpack_manifest_filepath (string), path to the Webpack assets manifest file, defaults to dist/assets-manifest.json in your theme.

Helpers

Functions to interact with WordPress behaviour.

Plugin helper

use Studiometa\WPToolkit\Helpers\PluginHelper;
// Check if a specified plugin is enable.
use Studiometa\WPToolkit\Helpers\PluginHelper;
PluginHelper::is_plugin_enabled( 'my-plugin/my-plugin.php' );

Transient Cleaner

Usage

Important Transients keys must be prefixed with transient cleaner prefix (TransientCleaner::PREFIX) to be tracked.

use Studiometa\WPToolkit\TransientCleaner;

// 1. Set a transient with transient cleaner prefix.
if ( $my_condition ) {
  set_transient(
    TransientCleaner::PREFIX . 'transient_key',
    'example'
  );
}

// 2. Initialize transient cleaner.
$transient_cleaner = TransientCleaner::get_instance(
  array(
    'post'   => array(
      'all'           => array(
        TransientCleaner::PREFIX . 'transient_key',
      ),
      'post_type_key' => array(
        TransientCleaner::PREFIX . 'transient_key',
        TransientCleaner::PREFIX . 'transient_key_1',
      )
    ),
    'term'   => array(
      'all'                    => array(),
      'your_taxonomy_type_key' => array(),
      'category'               => array(),
    ),
    'option' => array(
      'all'             => array(),
      'option_key'      => array(),
      'blogdescription' => array(),
    ),
  )
);

// Update config if needed.
$transient_cleaner->set_config(array());

// 3. Insert/Update post/term/option to see your transients deleted based on your config.

Contribute

Run tests

PHPUnit

# WP-tests must be installed before run PHPUnit (required a test MySQL database).
./bin/install-wp-tests.sh [dbname] [dbuser] [dbpasswd] [dbhost] [test_version]
composer run-script phpunit

Tests can be run in ddev which preconfigures the WordPress environment when starting:

ddev start
ddev exec phpunit

To test against different PHP version, you can edit the .ddev/config.yaml file and change the php_version property.