The Library is a file-based, searchable data and file storage solution written in PHP.
It's easy to setup and use. It's intended for cheap shared hosting, small virtual servers, your NAS or RaspberryPi and similar thingies where a node.js or Rails based solution is too much or simply not installable.
It can handle a couple thousand entries without any problems. It's perfect for small personal single-user applications: a self-hosted photo album, a tweet backup, a personal checkins db, an address book, a personal invoice app, a book inventory, a todo app — you name it.
The Library is also a perfect combination of any kind of text-based data combined with attached files. Each stored item can have any number of additional images, documents, videos, etc. attached.
The Library has no schema. You can add any number of fields per item and individual items can have different sets of fields.
- Philosophy
- Folder structure
- Sqlite index
- Requirements
- Installation
- Getting started
- Creating items
- Item anatomy
- Item getters
- Additional item methods
- Updates
- Queries
- Attachments
- Deleting items
- Roadmap
- License
- Author
- practical
- simple
- robust
- low fancy-level
- high usefulness-level
- for everyone
The Library stores each item in its own folder. The folder structure follows the creation date of the item:
- library
-- 2015
--- 06
---- 10
----- 32-char-item-id
------ item.yaml
------ attachment-1.jpg
------ attachment-2.pdf
------ attachment-3.zip
etc.
You can easily have multiple libraries per app and user in different folders.
The Library uses a simple SQLite database as a searchable index and builds on the database class of the Kirby toolkit to provide a nice and clean query api.
The index is stored in the main directory of the library and can be removed at any time. The Library will take care of rebuilding the index once it's gone. The folder structure, attachments and yaml files are always the original data source, which makes this solution very robust.
- PHP 5.4+
- sqlite
- mbstring
git clone https://github.com/bastianallgeier/library.git
require('library/bootstrap.php');
$library = new Library(__DIR__ . '/mylibrary');
Make sure the library folder is writable. Otherwise the library will not be able to store any data for you.
$item = $library->create('article', array(
'title' => 'Hello World',
'text' => 'Lorem ipsum…'
));
Each item is stored in its own folder. The path to the folder follows the format YYYY/MM/DD/ID. The creation date is used herefor. Each item has the following default fields:
- id (unique 32 char alphanumeric string)
- status (draft|public|private)
- type (can be any alphanumeric string between 2 and 32 characters)
- created (unix timestamp)
- updated (unix timestamp)
Additionally you can add any number of fields to an item.
// standard getters
$item->id();
$item->status();
$item->type();
$item->created();
$item->updated();
// magic getters for your additional fields
$item->title();
$item->text();
// etc.
// i.e. 2012/12/12/5gWsOULCwbkInoVQbJ0MxcjybX5hfkv9
$item->path();
// i.e. 2012
$item->path('year');
// i.e. 2012/12
$item->path('month');
// i.e. 2012/12/12
$item->path('day');
// i.e. /var/www/library/2012/12/12/5gWsOULCwbkInoVQbJ0MxcjybX5hfkv9
$item->root();
// i.e. /var/www/library/2012
$item->root('year');
// i.e. /var/www/library/2012/12
$item->root('month');
// i.e. /var/www/library/2012/12/12
$item->root('day');
// Kirby toolkit folder object
// http://getkirby.com/docs/toolkit/api#folder
$item->folder();
// returns an associative array of all item fields
$item->toArray();
// checks if the item exists
$item->exists();
Check the following examples for more specific stuff.
$item->update(array(
'title' => 'New title',
'text' => 'Lorem ipsum dolor sit amet',
'date' => time()
));
$item->title = 'New title';
$item->text = 'Lorem ipsum…';
$item->store();
$item->set('title', 'New title');
$item->set('text', 'Lorem ipsum…');
$item->store();
$item->set(array(
'title' => 'New title',
'text' => 'Lorem ipsum dolor sit amet'
));
$item->store();
$item->type('blogpost');
$item->created('2012-12-12 22:33');
$item->status('public');
Available statuses: draft (default), public, private
$item = $library->find('ekM9AZMIWbkm48hlpRCJO52FVCQSkClL');
$items = $library->all();
$items = $library->page($page, $limit);
$count = $library->count();
$items = $library->type('article')->all();
$items = $library->type('article')->page($page, $limit);
$count = $library->type('article')->count();
$items = $library->status('draft')->all();
$items = $library->status('public')->page($page, $limit);
$count = $library->status('private')->count();
$items = $library->year('2015')->all();
$items = $library->year('2015')->page($page, $limit);
$count = $library->year('2015')->count();
$items = $library->month('2015-06')->all();
$items = $library->month('2015-06')->page($page, $limit);
$count = $library->month('2015-06')->count();
$items = $library->day('2015-06-10')->all();
$items = $library->day('2015-06-10')->page($page, $limit);
$count = $library->day('2015-06-10')->count();
$items = $library->search($query)->all();
$items = $library->search($query)->page($page, $limit);
$count = $library->search($query)->count();
$items = $library->year('2015')->type('article')->status('public')->search($query)->all();
$items = $library->year('2015')->type('article')->status('public')->search($query)->page($page, $limit);
$count = $library->year('2015')->type('article')->status('public')->search($query)->count();
$item->attach('http://example.com/image.jpg');
$item->attach('/some/path/image.jpg');
$item->attach('/some/path/image.jpg', 'myimage.jpg');
// all files
$files = $item->files();
// all images
$images = $item->images();
// all videos
$videos = $item->videos();
// all documents
$documents = $item->documents();
All methods above return a Kirby Toolkit Collection of Media objects:
$item->detach('myimage.jpg);
$item->delete();
$library->type('article')->delete();
- more docs
- "between" query method for dates
- maybe geo queries
- Travis setup
- Composer support
http://www.opensource.org/licenses/mit-license.php
Bastian Allgeier