Download the PHP package italystrap/storage without Composer
On this page you can find all versions of the php package italystrap/storage. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download italystrap/storage
More information about italystrap/storage
Files in italystrap/storage
Package storage
Short Description A storage library for ItalyStrap
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package storage
ItalyStrap Storage API
Storage API for WordPress the OOP way This package provides API for WordPress Transients, Cache, Options, and ThemeMods.
Table Of Contents
- Installation
- Basic Usage
- Advanced Usage
- Contributing
- License
Installation
The best way to use this package is through Composer:
This package adheres to the SemVer specification and will be fully backward compatible between minor versions.
Introduction
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, WordPress Transients API, WordPress Options API, WordPress Theme Mods 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?
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 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 because I want to use them in other libraries.
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, 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 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.
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 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
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 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?
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
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
Remember that the maximum length of the key used for transients is <=172 characters, more characters will rise an Exception.
Option API
Mods API
From WordPress Transients API docs
Timer constants
In the WordPress environment you can use the following constants to set the expiration time if you want.
Common usage with WordPress Transients API
This is an example of how you can use the WordPress Transients API.
And this is the same example above but with this library.
The same is with the Cache::class class.
Transient API
Cache API
Advanced Usage
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:
Contributing
All feedback / bug reports / pull requests are welcome.
License
Copyright (c) 2019 Enea Overclokk, ItalyStrap
This code is licensed under the MIT.
