PHPackages digital-nature/wordpress-utilities - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. digital-nature/wordpress-utilities ActiveLibrary[Utility & Helpers](/categories/utility) digital-nature/wordpress-utilities ================================== General utilities for use in WordPress websites v0.0.12(1y ago)013MITPHP Since Apr 8Pushed 1y ago1 watchersCompare [ Source](https://github.com/Digital-Nature-LTD/wordpress-utilities)[ Packagist](https://packagist.org/packages/digital-nature/wordpress-utilities)[ RSS](/packages/digital-nature-wordpress-utilities/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)DependenciesVersions (13)Used By (0) wordpress-utilities =================== [](#wordpress-utilities) General utilities for use in WordPress plugins User Roles and Capabilities =========================== [](#user-roles-and-capabilities) You can programmatically build up a user role and its capabilities by extending the classes in this section. BaseCapability -------------- [](#basecapability) Provides the interface for capabilities, simply requiring a name. BaseRole -------- [](#baserole) Provides the interface for a role, and the method to add that role. Roles should be built to contain their associated capabilities. ``` // The capability class MyNewCapability extends \DigitalNature\WordPressUtilities\Common\Users\Capabilities\BaseCapability { /** * @return string */ public static function get_capability_name(): string { return 'my_new_capability'; } } // The role class MyNewRole extends \DigitalNature\WordPressUtilities\Common\Users\Roles\BaseRole { /** * @return string */ public static function get_role_slug(): string { return 'my-new-role'; } /** * @return string */ public static function get_role_name(): string { return 'My New Role' } /** * @return string[] */ public static function get_capabilities(): array { return [ MyNewCapability::get_capability_name() ] } } // The code below shows example usage of the roles/capabilities // Include the role MyNewRole::add_role(); // Adding capability for an admin menu item add_submenu_page( 'parent_slug', 'Your Page Title', 'Your Menu Title', MyNewCapability::get_capability_name(), 'submenu_slug', 'your callback' ); // checking capability for the logged in user $canAccess = current_user_can( MyNewCapability::get_capability_name() ); ``` Config ====== [](#config) PluginConfiguration ------------------- [](#pluginconfiguration) The `PluginConfiguration` class gives quick access to a plugins name/dir/file/url for use in templates, adding assets etc. Helpers ======= [](#helpers) Settings -------- [](#settings) ### UserSettingHelper [](#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. ``` // Define the setting class class MySettingHelper extends \DigitalNature\WordPressUtilities\Helpers\Settings\UserSettingHelper { public static function get_meta_key(): string { return 'my_setting_metadata_key'; } } // switch the setting on/off MySettingHelper::enable($user); MySettingHelper::disable($user); // There are aliases, as some setting names lend themselves to a different terminology MySettingHelper::turn_on($user); MySettingHelper::turn_off($user); // You can check whether the setting is turned on (or not) for the given user MySettingHelper::is_enabled($user); MySettingHelper::is_turned_on($user); // There is a toggle method, should you need to simply switch the setting MySettingHelper::toggle($user); ``` ConfigHelper ------------ [](#confighelper) The `ConfigHelper` simply provides environmental checks, so that you can restrict functionality/integrations by environment. ``` // check if we're on the live site. This is dependent on WP_ENVIRONMENT_TYPE being defined and set to 'live' ConfigHelper::is_live_site() // check if we're running a script. This is dependent on DN_IS_SCRIPT being defined and set to true ConfigHelper::is_script(); ``` CustomPostTypeHelper -------------------- [](#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. ``` // Register your post type CustomPostTypeHelper::register_post_type(MyModel::class, $args); // Returns the correct model for the given post (providing we registered the post type using the helper) $myModel = ModelFactory::from_id(123); ``` DateHelper ---------- [](#datehelper) Provides some useful methods for manipulating dates, such as getting the start/end of the month. LogHelper --------- [](#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): ``` LogHelper::get_logs(); // all logs LogHelper::get_last_log(); // just the last thing logged ``` MessageHelper ------------- [](#messagehelper) A very simple error and exit message helper for when you need to bring the script to an abrupt end. ``` MessageHelper::error_and_exit("My message here"); ``` TemplateHelper -------------- [](#templatehelper) Allows template to be rendered, either immediately or returned in a variable. ``` TemplateHelper::render( 'plugin-name/my-template.php', [ 'arg' => $argument, 'arg2' => $anotherArgument ], trailingslashit('plugin-dir/templates'), $returnAsString // boolean ); ``` Models ====== [](#models) Model ----- [](#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 ``` // If we know the model class then we can directly pull through that $myModel = MyModel::from_id(123); // If we don't know the correct class, just the ID then we have a factory method to retrieve. // Note that the factory method will only work for custom post types we have registered using the `CustomPostTypeHelper` $myModel = ModelFactory::from_id(123); ``` 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: ``` $myModel->my_metadata = 'abc123'; ``` If you want to save the updated metadata values then you can do so either by saving the individual field or the entire model ``` $myModel->save_attribute('my_metadata'); // a single metadata value $myModel->save(); // all metadata values ``` ModelNote --------- [](#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 ======== [](#patterns) Singleton --------- [](#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 ===== [](#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) 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. ``` // Create a model note for $myModel, authored by $user ModelNoteRepository::create($myModel, 'The content of my new note', $user); ``` 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. ``` class MyModelRepository { public static function create(WP_User $owner): MyModel { // ... } public static function flush_caches(MyModel $myModel): void { // ... } } ``` ModelNotesRepository -------------------- [](#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) Stores are places for us to hold onto data for this request. CustomPostTypeStore ------------------- [](#customposttypestore) Allows us to look up Models for particular custom post types without needing to know the required model. InMemoryStore ------------- [](#inmemorystore) The base class that looks after the storage and retrieval of records. ModelStore ---------- [](#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 ====== [](#traits) CacheableModelTrait ------------------- [](#cacheablemodeltrait) This is where the caching logic lives for our models, the `Model` class uses this trait ### Health Score 25 — LowBetter than 37% of packages Maintenance47 Moderate activity, may be stable Popularity5 Limited adoption so far Community7 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 12 Last Release 397d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b6b41ce3e69067999d1379085fb6390cf35e5d61929aa49d72363d79e4890bb1?d=identicon)[gmidwood](/maintainers/gmidwood) --- Top Contributors [![garethmidwood](https://avatars.githubusercontent.com/u/4386083?v=4)](https://github.com/garethmidwood "garethmidwood (15 commits)") ### Embed Badge ![Health badge](/badges/digital-nature-wordpress-utilities/health.svg) ``` [![Health](https://phpackages.com/badges/digital-nature-wordpress-utilities/health.svg)](https://phpackages.com/packages/digital-nature-wordpress-utilities) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)