arraypress / wp-storage-utils
The three storage operations WordPress lacks: cache-or-compute, delete-by-prefix, and reading a stored value as the type it is meant to be.
Requires
- php: >=8.3
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/storage(namespaceSugarCommerce\Storage, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
WordPress Storage Utilities
The three storage jobs WordPress leaves you to write: cache-or-compute, delete by prefix, and reading a stored value back as the type you wanted.
What it does
get_transient() returns false both when nothing is cached and when the
cached value is false, so the cache-or-compute pattern gets written by hand,
subtly wrong, in every plugin. remember() wraps the stored value so the two
are distinguishable.
Deleting your own transients when a plugin uninstalls has no API at all, so
everyone writes a DELETE ... LIKE — usually forgetting that the timeout rows
do not carry the prefix, and leaving half of them behind forever.
And anything out of the options table is a string, so it needs casting before it is useful.
Features
- Cache-or-compute that can store
false,nullor0without confusion - Delete every option, transient or meta row sharing a prefix, on uninstall
- Remove both halves of a transient, so nothing is orphaned in
wp_options - Cast a stored value to bool, int, float, a list, a list of ids or a list of strings
- Lists read back from an array, a JSON column or a comma-separated string alike
- Escapes
LIKEwildcards, so an underscore in your prefix stays literal
Installation
composer require arraypress/wp-storage-utils
Quick start
use ArrayPress\StorageUtils\Cache; use ArrayPress\StorageUtils\Cast; use ArrayPress\StorageUtils\Cleanup; // Computed once an hour, and it can legitimately return false. $is_eligible = Cache::remember( 'sc_eligible_' . $user_id, function () use ( $user_id ) { return expensive_eligibility_check( $user_id ); } ); // Options come back as strings. $limit = Cast::int( get_option( 'sc_download_limit' ), 5 ); // On uninstall, take everything with you. Cleanup::options( 'myplugin_' ); Cleanup::transients( 'myplugin_' ); Cleanup::meta( 'myplugin_', 'post' );
Reading lists back
A list can be stored three ways: as an array (meta and options serialise it),
as JSON in a custom table column, or as a comma-separated string somebody typed.
Cast::array(), Cast::ids() and Cast::strings() read all three alike, so the
code that reads a column and the code that reads a form post can share one line.
Cast::ids( '[5,"7",0,5]' ); // [5, 7] JSON column Cast::ids( array( 5, '7', '' ) ); // [5, 7] posted field Cast::ids( '5, 7' ); // [5, 7] typed text // Short labels: trimmed, blanks and duplicates dropped. Pass a cleaner to // sanitise each one; an entry that cleans away to nothing is dropped too. $features = Cast::strings( $row->features, 'sanitize_text_field' );
| Method | Keeps | Drops |
|---|---|---|
Cast::array( $value ) |
every entry, re-indexed | nothing (null, '' and false are an empty list) |
Cast::ids( $value ) |
positive integers (absint) |
zero, duplicates, nested arrays |
Cast::strings( $value, $clean = null ) |
trimmed, cleaned scalars | blanks, duplicates, nested arrays |
A string that opens with [ or { is read as JSON. If that JSON is broken the
list is empty rather than a comma split of the brackets.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later