PHPackages                             raphhh/balloon - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. raphhh/balloon

ActiveLibrary[PDF & Document Generation](/categories/documents)

raphhh/balloon
==============

Tiny file ORM

3.0.0(10y ago)932621MITPHPPHP >=5.4

Since May 2Pushed 10y ago2 watchersCompare

[ Source](https://github.com/Raphhh/balloon)[ Packagist](https://packagist.org/packages/raphhh/balloon)[ RSS](/packages/raphhh-balloon/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (5)Versions (6)Used By (1)

Balloon - A tiny file data access layer (csv, json, xml, yaml)
==============================================================

[](#balloon---a-tiny-file-data-access-layer-csv-json-xml-yaml)

[![Latest Stable Version](https://camo.githubusercontent.com/69bf6e0fb5ab838048380881b08eba86082aa4833123bab35757961d0be5c22c/68747470733a2f2f706f7365722e707567782e6f72672f7261706868682f62616c6c6f6f6e2f762f737461626c652e737667)](https://packagist.org/packages/raphhh/balloon)[![Build Status](https://camo.githubusercontent.com/515aa91f59f692adcfeb5bb3ef3be1da52b272bc850c3f0c046332b2b871c3f8/68747470733a2f2f7472617669732d63692e6f72672f5261706868682f62616c6c6f6f6e2e706e67)](https://travis-ci.org/Raphhh/balloon)[![Scrutinizer Quality Score](https://camo.githubusercontent.com/27098c536d320d9abe4b4042aae964863afa371046e881faea516e63e8303593/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f5261706868682f62616c6c6f6f6e2f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Raphhh/balloon/)[![Code Coverage](https://camo.githubusercontent.com/7ca19369e9564d79619c0e7b54b62a9de39c5ba57f40b219e4c2130d2afa7227/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f5261706868682f62616c6c6f6f6e2f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/Raphhh/balloon/)[![Total Downloads](https://camo.githubusercontent.com/8d5b85105104de3a5387a206703c4442c16da72a91db275abf42ce690aa240d6/68747470733a2f2f706f7365722e707567782e6f72672f7261706868682f62616c6c6f6f6e2f646f776e6c6f6164732e737667)](https://packagist.org/packages/raphhh/balloon)[![Reference Status](https://camo.githubusercontent.com/09dadc23ba12d19c09afc8b664b095b59fd63781f100509c46a5888944ebdcd9/68747470733a2f2f7777772e76657273696f6e6579652e636f6d2f7068702f7261706868683a62616c6c6f6f6e2f7265666572656e63655f62616467652e7376673f7374796c653d666c6174)](https://www.versioneye.com/php/raphhh:balloon/references)[![License](https://camo.githubusercontent.com/0f00d8354735789eee3e0d763ba4e95f39bb438cbc2bd430e568a099ef658a9b/68747470733a2f2f706f7365722e707567782e6f72672f7261706868682f62616c6c6f6f6e2f6c6963656e73652e737667)](https://packagist.org/packages/raphhh/balloon)

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](https://github.com/KnpLabs/Gaufrette) (but you can also add your own adapter).

Installation
------------

[](#installation)

Execute [Composer](https://getcomposer.org/):

```
$ composer require raphhh/balloon

```

Supported file formats
----------------------

[](#supported-file-formats)

- json
- yaml
- xml (todo)
- csv (todo)

CRUD actions
------------

[](#crud-actions)

### Work with objects

[](#work-with-objects)

With the object usage, Balloon will map data of your file into objects of a specific class.

#### Init

[](#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

[](#get-objects)

```
$objects = $balloon->getAll();
var_dump($objects); // contains an array of the objects of your file
```

#### Add object

[](#add-object)

```
$balloon->add($myObject);
$balloon->flush();
```

#### Modify object

[](#modify-object)

```
$balloon->modify($id, $myObject);
$balloon->flush();
```

#### Remove object

[](#remove-object)

```
$balloon->remove($id);
$balloon->flush();
```

### Work with arrays

[](#work-with-arrays)

With the array usage, Balloon will map data of your file into arrays.

#### Init

[](#init-1)

```
$balloonFactory = new BalloonFactory();
$balloon = $balloonFactory->create('path/to/my/file.json');
```

#### Get data

[](#get-data)

```
$dataList = $balloon->getAll();
var_dump($dataList); // contains an array of the data of your file
```

#### Add data

[](#add-data)

```
$balloon->add(['key1' => 'value1']);
$balloon->flush();
```

#### Modify data

[](#modify-data)

```
$balloon->modify($id, ['key1' => 'value1']);
$balloon->flush();
```

#### Remove data

[](#remove-data)

```
$balloon->remove($id);
$balloon->flush();
```

Cache
-----

[](#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
------------

[](#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-mapping)

Object
------

[](#object)

Balloon uses the [JMS Serializer](http://jmsyst.com/libs/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](http://jmsyst.com/libs/serializer).

Collection
----------

[](#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
----------------------

[](#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](https://github.com/KnpLabs/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
-----------------

[](#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();
```

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~108 days

Total

4

Last Release

3709d ago

Major Versions

1.1.0 → 2.0.02015-07-26

2.0.0 → 3.0.02016-03-23

### Community

Maintainers

![](https://www.gravatar.com/avatar/5fd55d984cf31c25f875f5636331a20f8be77e9443f2fd17fbccf1f9c4fe7a4c?d=identicon)[raphhh](/maintainers/raphhh)

---

Top Contributors

[![Raphhh](https://avatars.githubusercontent.com/u/5206490?v=4)](https://github.com/Raphhh "Raphhh (69 commits)")

---

Tags

jsonxmlyamlcsvObject Relational Mappingfilemanagerdata access layer

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/raphhh-balloon/health.svg)

```
[![Health](https://phpackages.com/badges/raphhh-balloon/health.svg)](https://phpackages.com/packages/raphhh-balloon)
```

###  Alternatives

[mledoze/countries

List of world countries in JSON, CSV, XML and YAML

6.2k699.7k6](/packages/mledoze-countries)[faisalman/simple-excel-php

Easily parse / convert / write between Microsoft Excel XML / CSV / TSV / HTML / JSON / etc formats

582599.4k1](/packages/faisalman-simple-excel-php)[soapbox/laravel-formatter

A formatting library that converts data output between XML, CSV, JSON, TXT, YAML and a few others.

2501.1M12](/packages/soapbox-laravel-formatter)[rodenastyle/stream-parser

PHP Multiformat Streaming Parser

443195.7k2](/packages/rodenastyle-stream-parser)[dracoblue/craur

A lossless xml to json and json to xml converter (and csv/xlsx/yaml). Writing PHP Json/Xml/Csv/Yaml/excel Importers made easy

4643.1k2](/packages/dracoblue-craur)[ee/dataexporter-bundle

Easy export data to CSV, XML, HTML, JSON or XLS

4982.5k](/packages/ee-dataexporter-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)