alex-kalanis/kw_storage

Universal storage library for store data as key-value pairs

v6.0.0 2025-05-04 21:59 UTC

This package is auto-updated.

Last update: 2025-05-06 20:37:32 UTC


README

Build Status Scrutinizer Code Quality Latest Stable Version Minimum PHP Version Downloads License Code Coverage

Simple system for accessing key-value storages. Original is part of UploadPerPartes, where it's necessary for store states of upload. To data it behaves like simple key-value storage. Which can derive to real flat storages like memory or redis or tree-like structures like your normal filesystem. No streams here.

The main thing about this package are the interfaces. Especially IStorage which represents all supported operations over storages and shall be used on upper layers as the only necessary dependency.

It is also the correct way to get it via Access\Factory class which select the best possible storage in accordance with passed params from your configuration. That can be put inside your DI.

This package also contains translations interface. So you can customize error messages for your devs and users.

PHP Installation

composer.phar require alex-kalanis/kw_storage

(Refer to Composer Documentation if you are not familiar with composer)

Changes

  • 6.0 - Use DateTime interfaces, tests for 8.4 and own namespaces
  • 5.0 - Streams are on different level, not here
  • 4.0 - Redefine factories and some key classes
  • 3.0 - Redefine interfaces for targets
  • 2.0 - Redefine Key-Value storing data
    • Remove formats and cache support (that should not be a problem of storage)
    • Added stream variant support
    • Added interface for catching content with sub-content (so directories) on storage-level
  • 1.0 - Initial version, with basics and cache support

PHP Usage

It partially depends on real storage. Can be local filesystem, can be remote service too. But the interfaces in this package make them all equal in terms of usage. So...

1.) Use your autoloader (if not already done via Composer autoloader)

2.) Add some external packages with connection to the local or remote services. Can be Redis or AWS or something else. Or nothing if it is only local FS.

3.) Connect either kalanis\kw_storage\Interfaces\IStorage, kalanis\kw_storage\Storage or kalanis\kw_storage\Helper into your app. That usually happens in DI. Extend it for setting your case, especially if you use tree with dirs.

4.) Extend your libraries by interfaces inside the package. Mainly kalanis\kw_storage\Interfaces\IStorage which represents that available actions or kalanis\kw_storage\Storage which packs it like facade.

5.) Just use inside your app.

// DI-like
return function (array $params): \kalanis\kw_storage\Interfaces\IStorage {
    $storage = (new \kalanis\kw_storage\Storage(
        new \kalanis\kw_storage\Storage\Factory()) // here can be changed to select different storage
    );
    $storage->init($params);
    return $storage->getStorage();
}
// Classes
class Counter
{
    protected const string MY_KEY = 'my_key';

    public function __construct(
        // ...
        protected readonly \kalanis\kw_storage\Interfaces\IStorage $storage,
        // ...
    ) {
    }

    public function __destruct()
    {
        $this->storage->remove(static::MY_KEY);
    }

    public function clear(): bool
    {
        return $this->storage->write(static::MY_KEY, '0');
    }

    public function increment(): bool
    {
        return $this->storage->increment(static::MY_KEY);
    }

    public function get(): int
    {
        try {
            return intval($this->storage->read(static::MY_KEY));
        } catch (\kalanis\kw_storage\StorageException $ex) {
            return 0;
        }
    }
}

Notes

Listing output contains storage separators. Asked root record is empty, the rest has that separator at least on the beginning. It depends on storage and class if the listing came with complete tree with sub-entries or just first level.