PHPackages                             italystrap/storage - 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. [Caching](/categories/caching)
4. /
5. italystrap/storage

ActiveLibrary[Caching](/categories/caching)

italystrap/storage
==================

A storage library for ItalyStrap

1.0.2(1y ago)22.2k2MITPHPPHP >=7.4

Since Apr 23Pushed 1y ago1 watchersCompare

[ Source](https://github.com/ItalyStrap/storage)[ Packagist](https://packagist.org/packages/italystrap/storage)[ RSS](/packages/italystrap-storage/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (3)Dependencies (20)Versions (4)Used By (2)

ItalyStrap Storage API
======================

[](#italystrap-storage-api)

[![Test Application](https://github.com/ItalyStrap/storage/actions/workflows/test.yml/badge.svg)](https://github.com/ItalyStrap/storage/actions/workflows/test.yml)[![Latest Stable Version](https://camo.githubusercontent.com/369b4bcb9217b7be5dabc359dc0a0b76e5484008c0b6f14597ab7d828b9fcd21/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6974616c7973747261702f73746f726167652e737667)](https://packagist.org/packages/italystrap/storage)[![Total Downloads](https://camo.githubusercontent.com/bd0dd504a414278111c44b2957f86f9166f446dcce788628879591c660ce58d8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6974616c7973747261702f73746f726167652e737667)](https://packagist.org/packages/italystrap/storage)[![Latest Unstable Version](https://camo.githubusercontent.com/3617af27c1762206fc408cbbb0b360d334f1889c2a8fe55f41ab75a11cb7c3ec/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f767072652f6974616c7973747261702f73746f726167652e737667)](https://packagist.org/packages/italystrap/storage)[![License](https://camo.githubusercontent.com/0f929ba76daf05f70c1bccd914dc45c1b3d5c303cfecc60ca1282b259edafd64/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6974616c7973747261702f73746f726167652e737667)](https://packagist.org/packages/italystrap/storage)[![PHP from Packagist](https://camo.githubusercontent.com/e08c319b37e7700016ca91245a783d79fc1b85847da702af7f638565ddf22468/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6974616c7973747261702f73746f72616765)](https://camo.githubusercontent.com/e08c319b37e7700016ca91245a783d79fc1b85847da702af7f638565ddf22468/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6974616c7973747261702f73746f72616765)[![Mutation testing badge](https://camo.githubusercontent.com/ca6b4e34a882c66e79be3842cd4ac53de2eeac884f16b8ffc781609e87532e3d/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f7374796c653d666c61742675726c3d687474707325334125324625324662616467652d6170692e737472796b65722d6d757461746f722e696f2532466769746875622e636f6d2532464974616c79537472617025324673746f726167652532466d6173746572)](https://dashboard.stryker-mutator.io/reports/github.com/ItalyStrap/storage/master)

Storage API for WordPress the OOP way This package provides API for WordPress Transients, Cache, Options, and ThemeMods.

Table Of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Contributing](#contributing)
- [License](#license)

Installation
------------

[](#installation)

The best way to use this package is through Composer:

```
composer require italystrap/storage
```

This package adheres to the [SemVer](http://semver.org/) specification and will be fully backward compatible between minor versions.

Introduction
------------

[](#introduction)

### What is the purpose of this library?

[](#what-is-the-purpose-of-this-library)

The first idea is to have a common API for all the storage system in WordPress, like [WordPress Cache API](https://developer.wordpress.org/reference/classes/wp_object_cache/), [WordPress Transients API](https://developer.wordpress.org/apis/transients/), [WordPress Options API](https://developer.wordpress.org/apis/options/), [WordPress Theme Mods API](https://codex.wordpress.org/Theme_Modification_API) and so on. These libraries try to uniform some WordPress API that have similar behavior under the same umbrella. This means that you could extend the API of this library to create your own storage system. To name a few you can use this API for metadata, post meta, user meta, and so on.

### Why the Storage word for the library?

[](#why-the-storage-word-for-the-library)

In this case the `Storage` word is used to refer to some data stored in a DB table or in a file as well as in memory like `array` or `object`, but in those case you may need to create your own class.

Now in this library you can find API for `Options` (or similar) and API for `Cache` (or similar), you may ask why :-D, the first reason is that I already have a library called [Cache](https://github.com/ItalyStrap/cache) used to implements the PSR-6 and PSR-16, so I don't want to duplicate the name, and the second reason is to group all the similar storage system you could find in WordPress.

Right now the interfaces used in this library are placed in another library called [Common](https://github.com/ItalyStrap/common) because I want to use them in other libraries.

### Why the OOP way?

[](#why-the-oop-way)

With this library you can inject the storage system you need to use in your class instead of coupling your class to a specific storage system and simplify the testing of your class by mocking this library.

This API takes some concept from the [PSR-16](https://www.php-fig.org/psr/psr-16/), and also it could be applied to other kind of storage system in WordPress not only for the Transients, Options, Mods, etc., to naming a few you can use this API for metadata, post meta, user meta, and so on.

If you need a PSR-6 or PSR-16 implementation for WordPress transient and cache you can use the [ItalyStrap\\Cache](https://github.com/ItalyStrap/cache) package and this library used as a driver, remember that you can use only the driver that extend the Cache API and not the Store API because of the missing TTL in the Store API.

Think of this like a wrapper around the WordPress Transients API, Options API, Mods API, etc. but with some differences.

### Differences with the WordPress Transients API, Options API, Mods API, etc.

[](#differences-with-the-wordpress-transients-api-options-api-mods-api-etc)

The most important difference is the return value of the `Class::get()` method, in the WordPress Transients API, Cache API, Option API and so on the `\get_*()` functions return `false` if the result does not exist or has expired, in this API the `Class::get()` method return `null` if the result does not exist or has expired.

I'm not a fan of the `null` value but this adheres to the PSR-16 specification where no value means `null` and `false` could be a valid value.

### The expiration time

[](#the-expiration-time)

The `StoreInterface::class` has no expiration time so think of it like a forever storage system that never expire.

If you need to store a value for a specific time you should use the `CacheInterface::class`.

The second difference is that if you provide a `0` value as the expiration time it means you will store the value per `0` second and not `forever` like WordPress does.

Maybe you would ask why?

Because if you provide a `0` second to the expiration time you are telling to the library to store the value for `0` second and not forever (f\*\*k), it does not make any sense to use the `0` value as `forever` (if you have a very good reason to do that please open an issue, and we will discuss about it). If you want to store a value forever just use the `::set()` method without the expiration time at all or pass `null` as the expiration time, internally the library will set expiration time to `1 year`, and `1 year` should be enough for a `forever` value.

### The expiration time and the Cache API

[](#the-expiration-time-and-the-cache-api)

Another important thing is that if you use the `Cache::class` and pass any value as the expiration time this will have no effect, because the `Cache::class` is a wrapper of the [WordPress Cache API](https://developer.wordpress.org/reference/classes/wp_object_cache/) and the default API will not persist any data. If you install some other plugin that provide to you another implementation of the Cache API refer to the documentation of that plugin to know if it supports expiration time or not.

### Why the `::update()` method exists?

[](#why-the-update-method-exists)

You may ask why the `::update()` method exists, in fact you could use the `::set()` method to update a value, there was only a `\wp_cache_replace()` function in the WordPress Cache API that return false if value does not exist and `\update_option()` function that instead create a value if it does not exist, so I decided to create the `::update()` method to have the same behavior of the Options API to all other storage system.

It is a bad decision? I leave the decision to you :-D I think this method is not necessary, but I decided to leave it there for the sake of completeness.

### The return value of the `Class::delete()` method

[](#the-return-value-of-the-classdelete-method)

As always in WordPress there is no real standard between API (f\*\*k), and the `Class::delete()` method is another example about this. The `\remove_theme_mod()` is the only function that does not return anything, all the other functions return `true` if the value has been deleted or `false` if the value does not exist. Now, to make this more similar to the PSR-16 specification, the `Class::delete()` method return `true` if the value has been deleted and if the value does not exist, the only way to return a false value is to provide an empty string as the key.

Basic Usage
-----------

[](#basic-usage)

Remember that the maximum length of the key used for [transients](https://developer.wordpress.org/reference/functions/set_transient/) is <=172 characters, more characters will rise an Exception.

### Option API

[](#option-api)

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\Option;

$option = new Option();

$option->set('my_option', 'my_value');

'my_value' === $option->get('my_option'); // true

$option->delete('my_option');

null === $option->get('my_option'); // true

$option->setMultiple([
    'option_1'	=> 'value_1',
    'option_2'	=> 'value_2',
]);

[
    'option_1'	=> 'value_1',
    'option_2'	=> 'value_2',
] === $option->getMultiple([
    'option_1',
    'option_2',
]); // true

$option->deleteMultiple([
    'option_1',
    'option_2',
]);

null === $option->get('option_1'); // true
null === $option->get('option_2'); // true
```

### Mods API

[](#mods-api)

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\Mods;

$mods = new Mod();

$mods->set('my_mod', 'my_value');

'my_value' === $mods->get('my_mod'); // true

$mods->delete('my_mod');

null === $mods->get('my_mod'); // true

$mods->setMultiple([
    'mod_1'	=> 'value_1',
    'mod_2'	=> 'value_2',
]);

[
    'mod_1'	=> 'value_1',
    'mod_2'	=> 'value_2',
] === $mods->getMultiple([
    'mod_1',
    'mod_2',
]); // true

$mods->deleteMultiple([
    'mod_1',
    'mod_2',
]);

null === $mods->get('mod_1'); // true
null === $mods->get('mod_2'); // true

$mods->clear();
```

From [WordPress Transients API docs](https://codex.wordpress.org/Transients_API)

### Timer constants

[](#timer-constants)

In the WordPress environment you can use the following constants to set the expiration time if you want.

```
const MINUTE_IN_SECONDS  = 60; // (seconds)
const HOUR_IN_SECONDS    = 60 * MINUTE_IN_SECONDS;
const DAY_IN_SECONDS     = 24 * HOUR_IN_SECONDS;
const WEEK_IN_SECONDS    = 7 * DAY_IN_SECONDS;
const MONTH_IN_SECONDS   = 30 * DAY_IN_SECONDS;
const YEAR_IN_SECONDS    = 365 * DAY_IN_SECONDS;
```

### Common usage with WordPress Transients API

[](#common-usage-with-wordpress-transients-api)

This is an example of how you can use the WordPress Transients API.

```
if (false === ($special_data_to_save = \get_transient('special_data_to_save'))) {
    // It wasn't there, so regenerate the data and save the transient
    $special_data_to_save = ['some-key' => 'come value'];
    \set_transient('special_data_to_save', $special_data_to_save, 12 * HOUR_IN_SECONDS);
}
```

And this is the same example above but with this library.

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\Transient;
$transient = new Transient();

if (false === ($special_data_to_save = $transient->get('special_data_to_save'))) {
    // It wasn't there, so regenerate the data and save the transient
    $special_data_to_save = ['some-key' => 'come value'];
    $transient->set('special_data_to_save', $special_data_to_save, 12 * HOUR_IN_SECONDS);
}
```

The same is with the `Cache::class` class.

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\Cache;

$cache = new Cache();

if (false === ($special_data_to_save = $cache->get('special_data_to_save'))) {
    // It wasn't there, so regenerate the data and save the transient
    $special_data_to_save = ['some-key' => 'come value'];
    $cache->set('special_data_to_save', $special_data_to_save, 12 * HOUR_IN_SECONDS);
}
```

### Transient API

[](#transient-api)

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\Transient;

$transient = new Transient();

/**
 * Ttl value must be in seconds
 */
$transient->set('my_transient', 'my_value', 60);

'my_value' === $transient->get('my_transient'); // true

$transient->delete('my_transient');

null === $transient->get('my_transient'); // true

$transient->setMultiple([
    'mod_1'	=> 'value_1',
    'mod_2'	=> 'value_2',
], 60);

[
    'mod_1'	=> 'value_1',
    'mod_2'	=> 'value_2',
] === $transient->getMultiple([
    'mod_1',
    'mod_2',
]); // true

$transient->deleteMultiple([
    'mod_1',
    'mod_2',
]);

null === $transient->get('mod_1'); // true
null === $transient->get('mod_2'); // true
```

### Cache API

[](#cache-api)

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\Cache;

$cache = new Cache();

/**
 * Ttl value must be in seconds
 */
$cache->set('my_cache', 'my_value', 60);

'my_value' === $cache->get('my_cache'); // true

$cache->delete('my_cache');

null === $cache->get('my_cache'); // true

$cache->setMultiple([
    'mod_1'	=> 'value_1',
    'mod_2'	=> 'value_2',
], 60);

[
    'mod_1'	=> 'value_1',
    'mod_2'	=> 'value_2',
] === $cache->getMultiple([
    'mod_1',
    'mod_2',
]); // true

$cache->deleteMultiple([
    'mod_1',
    'mod_2',
]);

null === $cache->get('mod_1'); // true
null === $cache->get('mod_2'); // true
```

Advanced Usage
--------------

[](#advanced-usage)

### How to crete keyword for the Cache API and Transients API

[](#how-to-crete-keyword-for-the-cache-api-and-transients-api)

It is good idea to prefix the keyword with some other string like your namespace, your class name, method name, and so on, you could also use constant, this will help you to avoid conflicts with other plugins or themes.

A simple example:

```
declare(strict_types=1);

namespace Your\Namespace;

use ItalyStrap\Storage\CacheInterface;use phpDocumentor\Reflection\Types\Mixed_;

$cache = new Cache();

$your_class = new class($cache) {
    private $cache;
    private $prefix = 'your_namespace';

    public function __construct(CacheInterface $cache)
    {
        $this->cache = $cache;
    }

    public function getSomething(): mixed
    {
        $keyword = $this->prefix . __CLASS__ . __METHOD__;

        if (false === ($data = $this->cache->get($keyword))) {
            // It wasn't there, so regenerate the data and save the transient
            $data = ['some-key' => 'come value'];
            $this->cache->set($keyword, $data, 12 * HOUR_IN_SECONDS);
        }

        return $data;
    }
};

}
```

Contributing
------------

[](#contributing)

All feedback / bug reports / pull requests are welcome.

License
-------

[](#license)

Copyright (c) 2019 Enea Overclokk, ItalyStrap

This code is licensed under the [MIT](LICENSE).

Credits
-------

[](#credits)

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance36

Infrequent updates — may be unmaintained

Popularity23

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 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 ~267 days

Total

3

Last Release

586d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/13d145319a065be260ee79e728655780ddd63002e5ac6c317701c8996ec8d94c?d=identicon)[overclokk](/maintainers/overclokk)

---

Top Contributors

[![overclokk](https://avatars.githubusercontent.com/u/4604932?v=4)](https://github.com/overclokk "overclokk (40 commits)")

---

Tags

cachecache-storagemodsoptionoptionstransienttransientswordpresswordpress-php-librarystorageItalyStrap

###  Code Quality

Static AnalysisPsalm, Rector

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/italystrap-storage/health.svg)

```
[![Health](https://phpackages.com/badges/italystrap-storage/health.svg)](https://phpackages.com/packages/italystrap-storage)
```

###  Alternatives

[alekseykorzun/memcached-wrapper-php

Optimized PHP 5 wrapper for Memcached extension that supports dog-piling, igbinary and local storage

2984.6k1](/packages/alekseykorzun-memcached-wrapper-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)