README

Fi 允许您查询一个文本文件集合，就像文件夹的文件是一个数据库（几乎是）。

Fi（与“派”押韵）设计成可以作为静态站点生成器的一部分使用。

超级快速开始

有一个可运行的示例您可以玩玩。

$ git clone https://github.com/yuanqing/fi
$ cd fi
$ composer install
$ php example/example.php

还有测试。

快速开始

假设我们已经将文本文件组织得井井有条，例如按照日期排序

data/
|-- _defaults.md
`-- 2014/
    |-- 01/
    |   |-- _defaults.md
    |   |-- 01-foo.md
    |   |-- 02-bar.md
    |   `-- ...
    |-- 02/
    |   `-- ...
    `-- ...

每个文本文件都包含YAML 前置和内容。文件 01-foo.md 可能如下所示

---
title: foo title
---
foo content

我们可以这样查询我们的 data 目录

$dataDir = 'data';
$filePathFormat = '{{ date.year: 4d }}/{{ date.month: 2d }}/{{ date.day: 2d }}-{{ title: s }}.md';
$collection = Fi::query($dataDir, $filePathFormat); #=> Collection object

与给定的 $filePathFormat 匹配的每个文件都是一个文档。因此，集合就是一个对一组文档的迭代器。

foreach ($collection as $document) {
  $document->getFilePath(); #=> 'data/2014/01/01-foo.md', ...
  $document->getField('title'); #=> 'foo title', ...
  $document->getField('date'); #=> ['year' => 2014, 'month' => 1, 'day' => 1], ...
  $document->getContent(); #=> 'foo content', ...
}

我们还可以直接通过索引访问文档

$document = $collection->getDocument(0); #=> Document object
$document->getFilePath(); #=> 'data/2014/01/01-foo.md'
$document->getField('title'); #=> 'foo title'
$document->getField('date'); #=> ['year' => 2014, 'month' => 1, 'day' => 1]
$document->getContent(); #=> 'foo content'

映射、过滤、排序

Fi 还支持对文档集合执行映射、过滤和排序操作。

# set the date to a DateTime object
$collection->map(function($document) {
  $date = DateTime::createFromFormat('Y-m-d', implode('-', $document->getField('date')));
  return $document->setField('date', $date);
});

# filter out Documents with date 2014-01-01
$collection->filter(function($document) {
  return $document->getField('date') != DateTime::createFromFormat('Y-m-d', '2014-01-01');
});

# sort by date in descending order
$collection->sort(function($document1, $document2) {
  return $document1->getField('date') < $document2->getField('date');
});

默认值

文本文件将从任何在同一目录或父目录中找到的 _defaults.md 文件继承默认值（字段或内容）。默认值是所说的级联；在文件层次结构中找到的更低的 _defaults.md 文件将覆盖更高的层次结构中的那些。

API

Fi

Fi::query ( string $dataDir, string $filePathFormat [, string $defaultsFileName = '_defaults.md' ] )

创建一个集合对象。

$dataDir = './data';
$filePathFormat = '{{ year: 4d }}/{{ month: 2d }}/{{ date: 2d }}-{{ title: s }}.md';
$collection = Fi::query($dataDir, $filePathFormat);

$dataDir 是 Fi 查找匹配 $filePathFormat 的文本文件的目录。
$filePathFormat 使用类似正则表达式的语法指定；请参阅 Extract.php。
$defaultsFileName 是 Fi 在解决默认值时查找的文本文件名称。

集合

map ( callable $callback )

将 $callback 应用到集合中的每个文档。返回集合对象。

# sets the title of all Documents to 'foo'
$collection->map(function($document) {
  $document->setField('title', 'foo');
  return $document;
}); #=> Collection

$callback 接收一个类型为 Document 的参数。它必须返回一个类型为 Document 的对象。

filter ( callable $callback )

使用 $callback 过滤 Collection 中的 Document。返回 Collection 对象。

# filters out Documents with the title 'foo'
$collection->filter(function($document) {
  return $document->getField('title') !== 'foo';
}); #=> Collection

$callback 接收一个类型为 Document 的参数。返回 false 以排除那个 Document。

sort ( callable $callback )

使用 $callback 对 Collection 进行排序。返回 Collection 对象。

# sorts by title in ascending order
$collection->sort(function($document1, $document2) {
  return strnatcasecmp($document1->getField('title'), $document2->getField('title'));
}); #=> Collection

$callback 接收两个类型为 Document 的参数。如果第一个 Document 参数应该在第二个之前排序，则返回 1，否则返回 -1。

sort ( mixed $fieldName [, int $sortOrder = Fi::ASC ] )

按指定的 $sortOrder 对 Collection 进行排序，按 $fieldName 排序。返回 Collection 对象。

# sorts by title in ascending order
$collection->sort('title', Fi::ASC); #=> Collection

# sorts by title in descending order
$collection->sort('title', Fi::DESC); #=> Collection

$sortOrder 必须是 Fi::ASC 或 Fi::DESC。

toArr ( )

获取 Collection 中所有 Document 作为数组。

$collection->toArr(); #=> [Document, Document, ...]

Document

getFilePath ( )

获取与 Document 对应的文本文件路径（相对于 $dataDir）。

$document->getFilePath(); #=> 'data/2014/01/01-foo.md'

getFields ( )

获取 Document 的所有字段。

$document->getFields(); #=> ['title' => 'foo', 'date' => ['year' => 2014, 'month' => 1, 'day' => 1]]

hasField ( mixed $fieldName )

检查 Document 是否有指定 $fieldName 的字段。

$document->hasField('title'); #=> true

getField ( mixed $fieldName )

获取指定 $fieldName 的值。

$document->getField('title'); #=> 'foo'

setField ( mixed $fieldName, mixed $fieldValue )

将 $fieldName 的字段设置为指定的 $fieldValue。返回 Document 对象。

$document->setField('title', 'bar'); #=> Document

hasContent ( )

检查 Document 内容是否非空。

$document->hasContent(); #=> true

getContent ( )

获取 Document 内容。

$document->getContent(); #=> 'bar'

setContent ( string $content )

将 Document 内容设置为指定的 $content。返回 Document 对象。

$document->setContent('baz'); #=> Document

需求

Fi 至少需要 PHP 5.3 或 HHVM，以及 Composer。

安装

安装 Composer。
安装 Composer 包
```
$ composer require yuanqing/fi ~0.2
```
在您的 PHP 文件中，包含 Composer 自动加载器
```
require_once __DIR__ . '/vendor/autoload.php';
```

测试

您需要 PHPUnit 来运行测试

$ git clone https://github.com/yuanqing/fi
$ cd fi
$ composer install
$ phpunit

许可证

麻省理工学院许可证

源清 / fi

维护者

详细信息