Download the PHP package digital-nature/wordpress-utilities without Composer

wordpress-utilities

General utilities for use in WordPress plugins

User Roles and Capabilities

You can programmatically build up a user role and its capabilities by extending the classes in this section.

BaseCapability

Provides the interface for capabilities, simply requiring a name.

BaseRole

Provides the interface for a role, and the method to add that role.

Roles should be built to contain their associated capabilities.

Config

PluginConfiguration

The PluginConfiguration class gives quick access to a plugins name/dir/file/url for use in templates, adding assets etc.

Helpers

Settings

UserSettingHelper

This abstract class provides the interface for user settings, stored in metadata.

By extending this class you gain the ability to turn settings on and off programatically using the setting helper class.

ConfigHelper

The ConfigHelper simply provides environmental checks, so that you can restrict functionality/integrations by environment.

CustomPostTypeHelper

Provides an alternative way to register custom post types.

The benefit here is that we can automatically load the correct model for a custom post type if we have used the CustomPostTypeHelper to register it.

DateHelper

Provides some useful methods for manipulating dates, such as getting the start/end of the month.

LogHelper

As the name suggests, this logs messages!

For local environments (where WP_ENVIRONMENT is 'local', 'dev' or 'development') it will output to a local debug file wp-uploads/local-debug.log

When running scripts (see ConfigHelper) the LogHelper will output to screen rather than file.

For other environments it will output to the php error log.

Should you need them, you can retrieve previously logged messages (from this request only):

MessageHelper

A very simple error and exit message helper for when you need to bring the script to an abrupt end.

TemplateHelper

Allows template to be rendered, either immediately or returned in a variable.

Models

Model

Models are based on WordPress post types, offering the opportunity to create a model per post type.

The biggest advantage of models is encapsulation, having a single class to store and manipulate the data for a post (including its metadata).

A model can be loaded in numerous ways, but the simplest is by ID

Loading models uses the ModelStore, saving resources by ensuring that we only load each model once.

You can define your own methods on your models, or simply define your metadata maps and manipulate the metadata directly. For example if we have a metadata key of 'my_metadata' we can update like so:

If you want to save the updated metadata values then you can do so either by saving the individual field or the entire model

ModelNote

Notes can be created for each model, to give a history of changes, audit log etc.

You can retrieve or create notes for any model using the ModelNoteRepository

Patterns

Singleton

The Singleton pattern ensures that there is only one instance of the extending class.

This allows more efficient memory management, ensuring we don't need to load the same resources multiple times.

It also allows a central store of messages - for example log messages in LogHelper - that can be retrieved from anywhere in the codebase.

Query

Queries are used to retrieve posts by their metadata attributes.

Queries are used by repositories, their results are cached for 5 minutes by default.

Repositories

Repositories are used for database interactions relating to models.

Where we need to create a model, a repository should be used. The parameters for the create method will be specific to the type of model you are creating.

The benefit to creating models using repositories is that we can more closely manage the caching of model queries. For example if we create a new instance of MyModel we know that we can clear the cache for MyModel::all() as it has been invalidated.

You may wish to create a repository for your own model classes with create/delete/retrieve/flush caches methods.

ModelNotesRepository

The ModelNotesRepository provides methods to create, delete and retrieve model notes. It also provides a cache flushing method that is automatically triggered when a note is deleted.

Stores

Stores are places for us to hold onto data for this request.

CustomPostTypeStore

Allows us to look up Models for particular custom post types without needing to know the required model.

InMemoryStore

The base class that looks after the storage and retrieval of records.

ModelStore

Holds the models we have loaded and returns references to them, ensuring we don't need to look up models and their metadata multiple times.

Traits

CacheableModelTrait

This is where the caching logic lives for our models, the Model class uses this trait