meyersm / simple-datastore
A PHP library to store objects between sessions using only the local file system
Requires
- php: >=5.3.0
This package is not auto-updated.
Last update: 2024-05-06 23:55:41 UTC
README
A PHP library to store objects between sessions using only the local file system.
Objects can be stored in json or serialized formats and be opened in read only mode or a read/write mode that locks the datastore to prevent overwriting or race conditions.
Good uses for simpleDatastore
- Need to preserve data between scripts/sessions and a database is overkill or not feasable
- Need to share data with another non-php script/code and json is the most convienient
- Fallback to preserve data incase a database connection failed.
This library should NOT be used as a replacement for a database in any application that has high traffic and many concurrent writes, while the files are locked while writing, every other thread/script that wants to write will have to wait for the lock causing slowdowns.
Installation
To install with composer, add this to your composer.json
"require": {
"meyersm/simple-datastore":">=0.5.2"
},
Then run composer update
and add this to your code,
use meyersm\simpleDatastore;
Alternativly you can just download the simpleDatastore.php file and add this to your code,
require('simpleDatastore.php'); use meyersm\simpleDatastore;
Usage
Creating a new Datastore:
$datastore = new simpleDatastore("datastore-name");
Then you can start adding data, and save to the new datastore
$datastore->fish_hooks = 50; $datastore->fish_names = array("bob","archibold","thomas"); $datastore->enable_fish= true; $datastore['array_access'] = "yup"; $datastore[] = "new array entry"; $datastore->save();
The datastore still has a write lock on the file until the file is closed, at that point another script can open and read the data
$datastore->close(); //You can also call $datastore->save(true) to save then close in 1 line $NEWdatastore = new simpleDatastore("datastore-name"); print $NEWdatastore->fish_hooks; //50 print $NEWdatastore['fish_names'][0] //bob
If you want to delete a datastore file, use the destroy function
$datastore->destroy();
When you try to open a datastore that already has a lock on it, the library will re-try for a configurable amount of time then error out. If you want to access a datastore while its locked, you can open it in read only mode
$datastore = new simpleDatastore("myDatastore",true);
Working with php classes that would be better stored as serialized objects instead of json? Set the serialize flag to true when opening a datastore
$datastore = new simpleDatastore("myDatastore",false,true); $datastore->complexClass = $CC; $datastore->otherDatastore = $someOtherDatastore //You can even serialize other simpleDatastore objects if you like.
By default the library will store all datastores and thier lock files in a sub directory called "datastore". It also throws exceptions in case of an error, if you would like to change either of those defaults you can.
$datastore = new simpleDatastore("teststore",false,false,"anotherDirectory"); //Different directory for datastore files $teamB = new simpleDatastore(); //If you are going to change the error mode, you may want to wait to load the file instead of doing so at instantiation $teamB->error_mode = simpleDatastore::$ERROR_MODE_SILENT; //Fails silently, will leave datastore null if error on read $teamB->error_mode = simpleDatastore::$ERROR_MODE_DIE; //Dies on fatal error, ending script execution $teamB->error_mode = simpleDatastore::$ERROR_MODE_EXCEPTION; //Default, throws exceptions on fatal errors $teamB->open("teststore");
To change the way the library handles a locked datastore file, use the setLockConfig function. Again if doing this, delay opening the datastore file like in the example above
/** * @param int $secondsBetweenLockAttempts Seconds to wait between lock attempts * @param int $lockAttempts Number of tries to try and lock datastore */ public function setLockConfig($secondsBetweenLockAttempts=1,$lockAttempts=20)
For more examples on how to use this library, check out the unit tests