README

在 fw3/streams: Flywheel3 stream library 中公开的 StreamFilter，为了在 PHP5.3.3 以上的版本中也能运行，已经进行了实用化的流过滤器。

如果您想轻松简单地立即使用，请参考注意点和用法，导入库后，请尝试应用：将初始化设置也委托给库的实现中的实现。

如果不需要对 PHP7.2.0 以下的版本进行兼容，请使用 fw3/streams。

目标版本和测试版本

目标版本：PHP5.3.3 及以上

测试版本

5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.3.8
5.3.9
5.4.16
5.4.39
5.4.45
5.5.38
5.6.40
7.0.33
7.1.33
7.2.33
7.3.21
7.4.0
7.4.9
8.0.0beta2

对 5.3.3 及以上各个小版本的最新版本，以及在处理版本变动时的版本进行了测试。

设置等注意事项

Windows (PHP7.2.0 以下)

请取消注释 php.ini 中的以下行。

- ; extension_dir = "ext"
+ extension_dir = "ext"

- ;extension=php_mbstring.dll
+ extension=php_mbstring.dll

Windows (PHP7.2.0 以上)

请取消注释 php.ini 中的以下行。

- ; extension_dir = "ext"
+ extension_dir = "ext"

- ;extension=mbstring
+ extension=mbstring

Linux 系列 (使用包管理器)

请使用各种包管理器安装 php-mbstring 或类似软件。

Linux 系列 (使用 phpenv)

请向 default_configure_options 或各个 definition 添加以下一项。

--enable-mbstring

Linux 系列 (从源代码构建)

请向 configure 选项添加以下一项。详细信息请参考PHP 手册函数参考自然语言和字符编码多字节字符串安装/设置。

--enable-mbstring

用法

1. 安装

如果可以使用 composer 的环境

执行以下命令进行安装。

composer require fw3_for_old/streams

如果不能使用 composer 的环境

从下载 ZIP 下载 zip 文件，并将其复制到任意目录。

在使用目标处理之前，请将 src/filters_require_once.php 以 require_once sprintf('%s/src/filters_require_once.php', $path_to_copy_dir); 的形式进行读取。

2. 注册流过滤器

<?php

use fw3_for_old\streams\filters\utilitys\StreamFilterSpec;

//----------------------------------------------
// フィルタ登録
//----------------------------------------------
// 引数を使用することでお好きなフィルタ名を設定することができます。
//
// StreamFilterSpec::registerConvertEncodingFilter(StreamFilterConvertEncodingSpec::DEFAULT_FILTER_NAME);
// StreamFilterSpec::registerConvertLinefeedFilter(StreamFilterConvertLinefeedSpec::DEFAULT_FILTER_NAME);
//----------------------------------------------
StreamFilterSpec::registerConvertEncodingFilter();
StreamFilterSpec::registerConvertLinefeedFilter();

3. CSV 输出

请在执行前后分别进行本地设置和恢复。

<?php

use fw3_for_old\streams\filters\ConvertEncodingFilter;
use fw3_for_old\streams\filters\utilitys\StreamFilterSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertEncodingSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertLinefeedSpec;

// 設定
$path_to_csv    = '';       // 出力CSVファイルパス
$rows           = array(    // 出力する内容を持つ二次元配列
    array(),
);

// 実行時のロカールと代替文字設定を先行して設定します
ConvertEncodingFilter::startChangeLocale();
ConvertEncodingFilter::startChangeSubstituteCharacter();

// フィルタ設定の構築：書き込み用として UTF-8 => SJIS-win、任意の行末改行コード => CRLF に変換するストリームフィルタ設定を構築する。
$spec   = StreamFilterSpec::resource($path_to_csv)->write(array(
    StreamFilterConvertEncodingSpec::toSjisWin()->fromUtf8(),
    StreamFilterConvertLinefeedSpec::toCrLf()->fromAll(),
));

// CSVファイルの出力
$fp     = \fopen($spec->build(), 'wb');
foreach ($rows as $row) {
    \fputcsv($fp, $row);
}
\fclose($fp);

// 実行時のロカールと代替文字設定を元に戻します
ConvertEncodingFilter::endChangeSubstituteCharacter();
ConvertEncodingFilter::endChangeLocale();

4. CSV 输入

<?php

use fw3_for_old\streams\filters\ConvertEncodingFilter;
use fw3_for_old\streams\filters\utilitys\StreamFilterSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertEncodingSpec;

// 設定
$path_to_csv    = '';       // 入力CSVファイルパス

// 実行時のロカールと代替文字設定を先行して設定します
ConvertEncodingFilter::startChangeLocale();
ConvertEncodingFilter::startChangeSubstituteCharacter();

// フィルタ設定の構築：読み込み用として 任意のエンコーディング => UTF-8 に変換するストリームフィルタ設定を構築する。
$spec   = StreamFilterSpec::resource($path_to_csv)->read([
    StreamFilterConvertEncodingSpec::toUtf8()->fromDefault(),
]);

$fp     = fopen($spec->build(), 'rb');
$rows   = array();
while ($row = fgetcsv($fp)) {
    $rows[] = $row;
}
fclose($fp);

// 実行時のロカールと代替文字設定を元に戻します
ConvertEncodingFilter::endChangeSubstituteCharacter();
ConvertEncodingFilter::endChangeLocale();

应用：将初始化设置也委托给库的实现

可以将注册过滤器、本地和替代字符的设置以及执行后的恢复等容易变成模板化的处理委托给库执行。

安全的 CSV 输入输出

<?php

use fw3_for_old\streams\filters\utilitys\StreamFilterSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertEncodingSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertLinefeedSpec;

//==============================================
// 設定
//==============================================
$rows   = array(array());   // データ

$path_to_csv    = '';   // CSVファイルのパスを設定して下さい

//----------------------------------------------
// 一括即時実行
//----------------------------------------------
// フィルタ登録、ロカールと代替文字の設定と実行後のリストアも包括して実行します。
// コールバックの実行中に例外が発生してもロカールと代替文字のリストアは実行されます。
//----------------------------------------------
$result = StreamFilterSpec::decorateForCsv(function () use ($path_to_csv, $rows) {
    //==============================================
    // 書き込み
    //==============================================
    // フィルタの設定
    $spec   = StreamFilterSpec::resource($path_to_csv)->write(array(
        StreamFilterConvertEncodingSpec::toSjisWin()->fromUtf8(),
        StreamFilterConvertLinefeedSpec::toCrLf()->fromAll(),
    ));

    // CP932、行末の改行コードCRLFとしてCSV書き込みを行う（\SplFileObjectでも使用できます。）
    $fp     = \fopen($spec->build(), 'r+b');
    foreach ($rows as $row) {
        \fputcsv($fp, $row);
    }
    \fclose($fp);

    //==============================================
    // 読み込み
    //==============================================
    // フィルタの設定
    $spec   = StreamFilterSpec::resource($path_to_csv)->read(array(
        StreamFilterConvertEncodingSpec::toUtf8()->fromSjisWin(),
    ));

    // UTF-8としてCSV読み込みを行う（\SplFileObjectでも使用できます。）
    $rows   = array();
    $fp     = \fopen($spec->build(), 'r+b');
    for (;($row = \fgetcsv($fp, 1024)) !== FALSE;$rows[] = $row);
    \fclose($fp);

    return $rows;
});

通过 HTTP 下载 CSV

<?php

use fw3_for_old\streams\filters\utilitys\StreamFilterSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertEncodingSpec;
use fw3_for_old\streams\filters\utilitys\specs\StreamFilterConvertLinefeedSpec;

//----------------------------------------------
// 一括即時実行
//----------------------------------------------
// フィルタ登録、ロカールと代替文字の設定と実行後のリストアも包括して実行します。
// コールバックの実行中に例外が発生してもロカールと代替文字のリストアは実行されます。
//----------------------------------------------
StreamFilterSpec::decorateForCsv(function () {
    //==============================================
    // 例：PDOで取得したデータをそのままCSVとしてDLさせてみる
    //==============================================
    // フィルタの設定
    $spec   = StreamFilterSpec::resourceOutput()->write(array(
        StreamFilterConvertEncodingSpec::toSjisWin()->fromUtf8(),
        StreamFilterConvertLinefeedSpec::toCrLf()->fromAll(),
    ));

    // 仮のDB処理：実際のDB処理に置き換えてください
    $pdo    = new \PDO('spec to dsn');
    $pdo->setAttribute(\PDO::ATTR_DEFAULT_FETCH_MODE, \PDO::FETCH_ASSOC);
    $stmt   = $pdo->prepare('SELECT * FROM table');
    $stmt->execute();

    // 仮のHTTP Response Header
    \header('Content-Type: application/octet-stream');
    \header('Content-Disposition: attachment; filename=fw3-sample.csv');

    // CP932、行末の改行コードCRLFとしてCSV書き込みを行う（\SplFileObjectでも使用できます。）
    $fp     = \fopen($spec->build(), 'wb');
    foreach ($stmt as $row) {
        \fputcsv($fp, $row);
    }
    \fclose($fp);
});

单元测试

以以下形式执行 tests/test.php。

php tests/test.php

fw3_for_old / streams

维护者

详细信息