README

一个友好的、面向对象的库，用于使用 PHP 解析和过滤 CSV 文件。

（以上）是使用 Coseva 的最简单示例。然而，它的功能远不止于此。 :)

这是什么？

Coseva（发音为 co•see•vah）是一个抽象库，用于使处理 .csv 文件变得更加容易。但使其特殊的是，它允许你在数据过滤逻辑中拥有清晰的 关注点分离。这是 Coseva 的一个主要特点，即为开发者提供将无关逻辑彼此分离的能力。在许多情况下，所有的数据过滤逻辑都包含在一个大循环中。这种“意大利面条式代码”会导致代码库难以维护和更新，并且当你几个月后回来时几乎无法阅读。但是，通过将你的逻辑分解成更小的独立块（Coseva 将这些块称为“过滤器”），你可以避免许多由“大循环中一切都有”的方法带来的麻烦。

安装

安装 Coseva 的推荐方式是通过 composer。只需创建一个 composer.json 文件，并运行 composer install 命令即可安装。

{
    "minimum-stability": "dev",
    "require": {
        "johnnyfreeman/coseva": "*"
    }
}

或者，你可以下载 coseva.zip 文件并将其解压缩。

入门

在深入之前，有一些事情你应该知道。

首先，Coseva 除了解析 CSV 并提供结果外，不做任何其他事情；不查询数据库，不跳一只脚等。这些取决于你自己。

其次，是过滤器的运行顺序。解析器按顺序遍历 CSV 文件，从上到下，逐行运行在注册时相同的顺序的所有过滤器。

所以如果我们注册了两个过滤器，比如这样

<?php

// delete 1st column
$csv->filter(function($columns) {
	unset($columns[0]);
	return $columns;
});

// Capitalize first letter of 1st column (which used to be the 2nd column)
$csv->filter(0, function($column) {
    return ucfirst($column);
});

首先，从数组中删除第一列，然后在执行第二个过滤器时，将引发 "PHP Notice: Undefined offset" 错误，因为该列不再存在。

示例

<?php

$csv = new CSV('path/to/file.csv');

// parse first column as date
$csv->filter(0, function($column1) {
    return (new DateTime($column1))->format('Y-m-d H:i:s');
});

// split column five at every colon and serialize
$csv->filter(4, function($column5) {
    return serialize(explode(':', $column5));
});

$csv->parse();

API

__construct( $filename, $open_mode = 'r', $use_include_path = false )

要实例化CSV对象，只需将.csv文件的路径传递给CSV构造函数。

参数

返回值

返回CSV实例。

示例

<?php

$csv = new CSV('path/to/file.csv');

filter( $column, $callable[, mixed $argument1, ...] )

此方法允许您对CSV内容注册任意数量的过滤器。但有两种方式可以使用此方法。

第一种方法，您将传递一个列号和一个可调用项，如下所示

// convert data in column 2 to a `number` if it is numeric
$csv->filter(1, function($value) {
	return is_numeric($value) ? (float) $value : $value;
});

// trim the whitespace around column 1
$csv->filter(0, 'trim');

// Format a numeric column to always display 2 decimals.
$csv->filter(1, 'number_format', 2);

第二种方法，您只需传递一个回调，如下所示

// overwrite column three based on values from columns 1 and 2
$csv->filter(function($columns) {
	if ($columns[0] == 'this' && $columns[1] == 'that') {
		$columns[2] = 'something';
	}

	return $columns;
});

// reverse the order of all columns
$csv->filter('array_reverse');

参数

返回值

返回CSV实例以允许方法链。

示例

<?php

// split column four at every colon and serialize
$csv->filter(3, function($column4) {
    return serialize(explode(':', $column4));
});

// remove the first column from the results
$csv->filter(function($columns) {
	unset($columns[0]);
    return $columns;
});

parse( $offset = 0 )

此方法将csv转换为数组，并对它运行所有已注册的过滤器。

参数

返回值

返回CSV实例以允许方法链。

示例

<?php

// parse csv while executing any filters that may have been registered.
$csv->parse();

toJSON()

使用此方法以JSON格式获取整个CSV。

返回值

返回JSON 字符串。

示例

<?php

// to JSON
echo $csv->toJSON();

toTable()

这是在开发过程中向您显示过滤后的csv内容的好方法（用于调试目的）。

返回值

返回HTML 字符串。

示例

<?php

// let's take a look
echo $csv->toTable();

getInstance( $filename, $open_mode = 'r', $use_include_path = false )

我们还允许实例存在，保留内存并在作用域之间保持可达性。

参数

示例

<?php

use \Coseva\CSV;

// Create an instance of CSV.
$csv = CSV::getInstance('comma-separated-nonsense.csv');

// Fetch another one.
$dupe = CSV::getInstance('comma-separated-nonsense.csv');

// Parse the CSV.
$csv->parse();

// And display that parsed CSV as JSON.
echo $dupe->toJSON();

打包/独立的CSV解析器

为了方便起见，我们创建了一个打包器，这样您就可以将脚本和CSV文件合并成一个压缩的可执行包。我们使用了自5.3.0以来就有的Phar技术。

优点很简单

• 只需保留一个文件
• 您的数据被压缩
• 您可以将所有脚本功能与CSV文件一起保留
• 不需要Coseva作为外部库
• PHP 5.2及以上版本可以执行它

使用方法

NAME
			packager - Combine Coseva, your script and CSV

SYNOPSIS
			packager input.csv script.php [output.phar [alias.phar]]

DESCRIPTION
			input.csv
						The input file which holds the CSV data.

			script.php
						The PHP script which uses Coseva to do filtering and parsing.
						It can make use of the automatically defined constant SOURCE_FILE
						to succesfully target the CSV file for file operations.
						Also, including / requiring Coseva is no longer needed, as the
						package will do so when bootstrapping.

			output.phar [optional]
						The output location of the package.

			alias.phar [optional]
						The internal alias of the package. Really useful when wanting to
						target the package from within your script.
						E.g. "phar://alias.phar/input.csv"

配置

打包器应该可以原样运行。在某些机器上，可能需要设置某些标志。不过不用担心。打包器将自动检测需要设置哪些标志以及在哪里可以找到它们。

在大多数机器上，设置phar.readonly = Off就足够了。对于运行suhosin的机器，当需要时，有一个向suhosin的执行器白名单中添加"phar"的指令。

更新

想保持更新？请关注我的Github和Twitter。