Download the PHP package lucinda/db without Composer

On this page you can find all versions of the php package lucinda/db. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

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 PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • 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.
Please rate this library. Is it a good library?

Example code of lucinda/db

Informations about the package db

Lucinda DB: Pure PHP Tag-Based Key-Value Store

Table of contents:

About

Lucinda DB is serverless KEY-VALUE store originally designed to help developers cache results of resource-intensive SQL queries based to criteria (aka TAG) query depends on. It is different from other KV stores by having KEYs self-generate based on TAGs query result depended on and VALUEs saved as individual JSON files (instead of RAM) named by KEY in one/more SCHEMAs. This brings following advantages:

API relies on an interplay of following concepts:

Data

This is result to cache as VALUE in KV store, convertible to JSON.

Example query:

Processed into following PHP array structure:

Tag

A tag corresponds to name of criteria based on whom DATA was generated (eg: "users" and "roles" for example above). A tag's value must obey following requirements:

Key

A key is unique identifier of TAGs results into a single KEY, regardless of how they were ordered by caller! The rules based on whom key name is calculated are:

Key creation is encapsulated by Lucinda\DB\Key class. Usage example:

Value

A value is a JSON-ed representation of SCHEMA folder according to following rules:

Value operations are encapsulated by Lucinda\DB\Value class. Usage example:

Load Balancing

For performance, consistency or scalability reasons, users can opt for VALUEs to be load balanced across multiple Lucinda\DB\Value in order to insure that:

Usage example:

Schema

A schema is simply the folder where Lucinda\DB\Schema encapsulates operations one can perform on a single schema. Usage example:

Load Balancing

For performance, consistency or scalability reasons, users can opt for SCHEMAs to be load balanced and evenly distributed. This is done via Lucinda\DB\SchemaDriver class that insures all schema operations are automatically reflected in replicas. Usage example:

Installation

First choose a folder, then write this command there using console:

Then create at least one Lucinda\DB\Wrapper object. Usage example:

API uses composer autoload, requires PHP 8.1+ and has no external dependencies except SimpleXML, DOM and SPL extensions. All code inside is 100% unit tested and developed on simplicity and elegance principles!

Configuration

To configure this API you must have a XML with a lucinda_db tag inside:

Where:

Example:

Querying

Now that XML is configured, you can query entries or schemas via Lucinda\DB\Wrapper class and its methods available:

Method Arguments Returns Description
__construct string $xmlFilePath, string $developmentEnvironment void Sets location of configuration file along with development environment for later querying
getEntryDriver string[] $tags Lucinda\DB\ValueDriver Gets object to query load-balanced entry list of tags key depends on
getSchemaDriver void Lucinda\DB\SchemaDriver Gets object to query distributed schemas

Querying Entries

Usage example employing Lucinda\DB\ValueDriver:

Using Lucinda\DB\Value directly is useful only if your app requires no load balancing, lies in one development environment only and needs only primitive maintenance. Usage example:

Both Lucinda\DB\Value and its Lucinda\DB\ValueDriver wrapper abide to a single contract defining blueprints of Lucinda\DB\ValueOperations, which comes with following prototype methods:

Method Arguments Returns Description
set mixed $value void Sets entry value
get void mixed Gets entry value
exists void bool Checks if entry exists
increment int $step = 1 int Increments existing entry value using Handling Race Conditions
decrement int $step = 1 int Decrements existing entry value using Handling Race Conditions
delete void void Deletes entry

As one can see above, in case developers opt using Lucinda\DB\Value directly, class Lucinda\DB\Key needs to be instanced manually. It encapsulates creation of keys based on tags and defines following public methods:

Method Arguments Returns Description
__construct string[] tags void Compiles key based on TAGs break naming rules
getValue string Gets entry key compiled above.

Querying Schemas

Usage example employing Lucinda\DB\SchemaDriver:

Using Lucinda\DB\Schema directly is useful only if your app requires no load balancing, lies in one development environment only and needs only primitive maintenance. Usage example:

Both Lucinda\DB\Schema and Lucinda\DB\SchemaDriver abide to a single contract defining blueprints of Lucinda\DB\SchemaOperations, which comes with following prototype methods:

Method Arguments Returns Description
create void bool Creates schema(s)
exists void bool Checks if schema(s) exist
getAll void string[] Gets all keys in schema(s)
getByTag string $tag string[] Gets all keys in schema(s) matching tag
getCapacity void int Gets number of entries in schema(s)
deleteAll void int Deletes all entries in schema(s)
drop void bool Drops all schema(s), deleting all entries in the process

Maintenance

Modern operating systems allow up to 4,294,967,295 files in one folder but you shouldn't go anywhere near that value! Just like MySQL running out of disk space, LucindaDB may additionally run out of specialization is used at massive scale.

To fix such cases class Lucinda\DB\DatabaseMaintenance class was created, whose purpose is to do automated maintenance through following public methods:

Method Arguments Returns Description
__construct string $xmlFilePath, string $developmentEnvironment void Sets location of configuration file along with development environment for later querying
checkHealth float $maximumWriteDuration Lucinda\DB\SchemaStatus[string] Performs health checks of all load balanced schemas and returns results as status by schema.
See: Checking Schemas Health
plugIn string $schema void Plugs in schema to load-balanced DB without down times
See: Plugging Schema In
plugOut string $schema void Plugs out schema from load-balanced DB without down times
See: Plugging Schema Out
deleteByTag string $tag int Deletes all DB entries whose key matches Deleting Entries by Tag
deleteUntil int $secondsBeforeNow int Deletes all DB entries whose last modified time is more than #seconds old
See: Deleting Entries by Time
deleteByCapacity int $minCapacity, int $maxCapacity int Deletes all DB entries by keeping schema at fixed max capacity range based on entry last modified time.
See: Deleting Entries by Capacity

By Cron Job

This class should be used via a cron job whose periodicity depends on the chance of your project to get filled! Example:

By Console Command

If maintenance involves just one operation it can be done without programming by calling client.php file bundled in API root. Console syntax:

Where:

The greatest advantage of this solution is that it allows non-programmers (devops) to perform maintenance from command line. Example:

Advanced Guide

Specializing Keys

Sometimes, different KEY section at the same time. Solution is to add an extra specializer tag (eg: MD5 checksum of query) when creating key:

As a rule, specialization should be avoided as much as possible, since it enlarges database and has a duplication potential (for example a simple extra space in query above would generate another key)!

Handling Race Conditions

A complicated problem in all databases is managing race conditions. What happens when a increment or decrement operation is ran in parallel? Let's imagine DATA was 8 and increment is attempted at same moment Z by users X and Y:

Will end result be 10, as expected? The answer is no, because both processes got 8 to increment at same time! This situation is called a "race condition" and the only solution is to stack writes on that entry instead of letting them run in parallel.

For increment/decrement Lucinda\DB\LockException is thrown. Instead of letting exception bubble, developers can catch it and retry after delay:

Checking Schemas Health

Method checkHealth @ class Lucinda\DB\DatabaseMaintenance is to be used in checking the state of each replica Lucinda\DB\SchemaStatus. The algorithm by which statuses are produced is:

The end result of all checks will be returned as an array where key is schema and value is status found.

Plugging Schema In

Method plugIn @ class Lucinda\DB\DatabaseMaintenance is to be used for plugging a SCHEMA to replicas without database down times. The algorithm used is:

Plugging Schema Out

Method plugOut @ class Lucinda\DB\DatabaseMaintenance is to be used for plugging out a SCHEMA to replicas without database down times. The algorithm used is:

Deleting Entries by Tag

Method deleteByTag @ class Lucinda\DB\DatabaseMaintenance is to be used for removing all TAG from all replicas. The algorithm used is:

Deleting Entries by Time

Method deleteUntil @ class Lucinda\DB\DatabaseMaintenance is to be used for removing all VALUEs whose last modified time is more than $secondsBeforeNow old. The algorithm used is:

Deleting Entries by Capacity

Method deleteByCapacity @ class Lucinda\DB\DatabaseMaintenance is to be used to insure number of entries in database doesn't exceed $maxCapacity and, if it does, shrink it to $minCapacity by having older entries removed. The algorithm used is:

Avoiding API Disadvantages

This API, being disk based, comes with its own disadvantages compared to standard RAM-based KV stores:

It is always up for developers to decide which KV store model fits their application the best! More often than not you will need to employ multiple stores (eg: LucindaDB and Redis) to cover all usage cases (one for persistent query-able data, the other for volatile data).

Usage Examples

To see usage examples, these unit tests should be enough:

All versions of db with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1
ext-spl Version *
ext-simplexml Version *
ext-xml Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package lucinda/db contains the following files

Loading the files please wait ....