README

Balloon是一个支持不同数据格式的文件数据访问层。

它可以帮助您从csv、json、xml或yaml等文件中获取、添加、修改或删除数据（CRUD基本操作）。

您可以使用对象或数组进行操作。使用数组时，Balloon将提取文件中的数据，并为每个数据提供一个数组列表。使用对象时，Balloon将根据您选择的特定类将数据映射到对象。然后，您还可以使用特定的对象集合进行操作。

最后，您可以使用不同的文件系统抽象（本地、云等）。Balloon提供了一个适配器来使用Gaufrette（但您也可以添加自己的适配器）。

安装

执行Composer

$ composer require raphhh/balloon

支持的文件格式

• json
• yaml
• xml（待定）
• csv（待定）

CRUD操作

使用对象

在对象使用中，Balloon将文件数据映射到特定类的对象。

初始化

$balloonFactory = new BalloonFactory();
$balloon = $balloonFactory->create('path/to/my/file.json', 'My\Class', 'pkPropertyName');

（注意，pk不是必需的。对象的ID将是简单索引。）

获取对象

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

添加对象

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

修改对象

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

删除对象

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

使用数组

在数组使用中，Balloon将文件数据映射到数组。

初始化

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

获取数据

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

添加数据

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

修改数据

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

删除数据

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

缓存

Balloon的缓存可以防止在尝试读取文件时多次访问同一文件。

$balloon->getAll(); //first time, we read the file
$balloon->getAll(); //next times, we read the cache

您可以使用“Balloon::invalidate()”方法无效化缓存。

$balloon->getAll(); //we read the file
$balloon->invalidate();
$balloon->getAll(); //we read the file

工作单元

Balloon的工作单元可以防止在尝试写入文件时多次访问同一文件。这意味着您需要在写入文件时刷新Balloon。

$balloon->add($data); //nothing added into the file
$balloon->flush(); //now only, we put $data into the file

您还可以回滚您的修改（只有当您还没有刷新时！）。

$balloon->add($data); //nothing added into the file
$balloon->clear(); //your previous modification has been canceled.

对象映射

对象

Balloon使用JMS Serializer来序列化对象。

这个库可以与yaml、xml或注释一起使用来映射数据到对象。

例如，如果您使用注释

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');

您可以在Balloon工厂的第二个参数中重新定义默认序列化器

$serializer = JMS\Serializer\SerializerBuilder::create()->build();
$balloonFactory = new BalloonFactory(null, $serializer);

有关JMS Serializer的更多信息，请参阅文档。

集合

默认情况下，如果您处理数据集合，Balloon将返回这些数据的一个数组。

但如果您使用对象处理数据，您也可以使用特定的集合类。您只需要声明一个与您的数据类同名但为复数形式的类。这个类将接收一个对象数组作为构造函数的第一个参数。

例如，如果您处理类'Foo'的数据对象，您可以声明一个名为'Foos'的集合。

//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

文件系统抽象

默认情况下，Balloon将本地读取和写入。但您可以使用其他驱动程序，并使用其他类型的文件系统。

最好的做法是使用库如Gaufrette。Balloon为此库提供了一个适配器。

//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');

扩展Balloon

您可以通过创建一个子类来扩展Balloon

class BeachBall extends Balloon
{
    //your own methods here...
}

但为了轻松实例化这个新类，您还应该扩展BalloonFactory并指定您的类名

class BeachBallFactory extends BalloonFactory
{
    protected function getClassName()
    {
        return 'BeachBall';
    }
}

然后您可以使用BeachBallFactory以与Balloon相同的方式创建BeachBall

$beachBallFactory = new BeachBallFactory();
$beachBall = $beachBallFactory->create('path/to/my/file.json');
$beachBall->getAll();