raphhh / balloon
Tiny file ORM
Requires
- php: >=5.4
- icanboogie/inflector: ~1.3
- jms/serializer: ^1.0
- symfony/yaml: ~3.0
Requires (Dev)
- knplabs/gaufrette: 0.1.*
- phpunit/phpunit: @stable
This package is auto-updated.
Last update: 2024-09-25 22:03:24 UTC
README
Balloon is a file data access layer which supports different kinds of data formats.
It help you to get, add, modify or remove data (CRUD basic actions) from files like csv, json, xml or yaml.
You can work with objects or with arrays. With arrays, Balloon will extract the data of the file and gives you a list of array for every data. With objects, Balloon will map these data with objects of a specific class of your choice. Then, you can also work with specific collections of objects.
Finally, you can work with different file system abstractions (local, cloud,...). Balloon provides an adapter to use Gaufrette (but you can also add your own adapter).
Installation
Execute Composer:
$ composer require raphhh/balloon
Supported file formats
- json
- yaml
- xml (todo)
- csv (todo)
CRUD actions
Work with objects
With the object usage, Balloon will map data of your file into objects of a specific class.
Init
$balloonFactory = new BalloonFactory(); $balloon = $balloonFactory->create('path/to/my/file.json', 'My\Class', 'pkPropertyName');
(Note that the pk is not mandatory. Id of object will be simple index.)
Get objects
$objects = $balloon->getAll(); var_dump($objects); // contains an array of the objects of your file
Add object
$balloon->add($myObject); $balloon->flush();
Modify object
$balloon->modify($id, $myObject); $balloon->flush();
Remove object
$balloon->remove($id); $balloon->flush();
Work with arrays
With the array usage, Balloon will map data of your file into arrays.
Init
$balloonFactory = new BalloonFactory(); $balloon = $balloonFactory->create('path/to/my/file.json');
Get data
$dataList = $balloon->getAll(); var_dump($dataList); // contains an array of the data of your file
Add data
$balloon->add(['key1' => 'value1']); $balloon->flush();
Modify data
$balloon->modify($id, ['key1' => 'value1']); $balloon->flush();
Remove data
$balloon->remove($id); $balloon->flush();
Cache
The cache of Balloon prevents to access to the same file more than once when you try to read it.
$balloon->getAll(); //first time, we read the file $balloon->getAll(); //next times, we read the cache
You can invalidate the cache with the method "Balloon::invalidate()".
$balloon->getAll(); //we read the file $balloon->invalidate(); $balloon->getAll(); //we read the file
Unit of work
The unit of work of Balloon prevents to access to the same file more than once when you try to write it. So, that means you have to flush Balloon if you want to write into the file.
$balloon->add($data); //nothing added into the file $balloon->flush(); //now only, we put $data into the file
You can also rollback your modifications (only if you have not flushed!).
$balloon->add($data); //nothing added into the file $balloon->clear(); //your previous modification has been canceled.
Object Mapping
Object
Balloon uses the JMS Serializer to serialize the objects.
This library can work with yaml, xml or annotations to map the data to their object.
For example, if you use annotations:
namespace Bar; //declare the annotation namespace use JMS\Serializer\Annotation\Type; //register the doctrine auto load AnnotationRegistry::registerLoader('class_exists'); //declare the data class class Foo { /** * @Type("string") */ private $name; } //declare the class in Balloon $balloonFactory = new BalloonFactory(); $balloon = $balloonFactory->create('path/to/my/file.json', 'Bar\Foo');
You can redefine the default Serializer in the second arg of the Balloon Factory:
$serializer = JMS\Serializer\SerializerBuilder::create()->build(); $balloonFactory = new BalloonFactory(null, $serializer);
For more information about JMS Serializer, see the documentation.
Collection
By default, if you work with a collection of data, Balloon returns an array of these data.
But if you work with objects for data, you can also work with specific collection class. You just have to declare a class with the same name as your data class, but in plural. This class will receive an array of the objects as first arg of the constructor.
For example, if you work with data object of the class 'Foo', you can declare a class 'Foos' as a collection.
//declare the data class class Foo { ... }
//declare the collection class Foos extends \ArrayObject { ... }
//run Balloon $balloonFactory = new BalloonFactory(); $balloon = $balloonFactory->create('path/to/my/file.json', 'Foo'); $balloon->getAll(); //return an instance of Foos
Filesystem abstraction
By default, Balloon will read and write locally. But you can use other drivers, and work with other kind of filesystems.
The best way to proceed is to use a library such Gaufrette. Balloon provides an adapter for this library.
//declare Gaufrette $adapter = new LocalAdapter('/var/media'); $filesystem = new Filesystem($adapter); //declare Ballooon $gaufretteAdapter = new GaufretteAdapter($filesystem) $balloonFactory = new BalloonFactory($gaufretteAdapter); $balloon = $balloonFactory->create('path/to/my/file.json');
Extending Balloon
You can extend Balloon by creating a child:
class BeachBall extends Balloon { //your own methods here... }
But to instantiate easily this new class, you should also extend BalloonFactory and specify the name of your class:
class BeachBallFactory extends BalloonFactory { protected function getClassName() { return 'BeachBall'; } }
Then you can use BeachBallFactory to create BeachBall in a same way than Balloon:
$beachBallFactory = new BeachBallFactory(); $beachBall = $beachBallFactory->create('path/to/my/file.json'); $beachBall->getAll();