README

概述

一个用于对CSV和XLS文件应用验证规则的Laravel包。提供了一种接口，以确保您在应用程序中读取的文件与您定义的模式相符。

该类从本地磁盘加载文件，接受多个选项进行验证，然后提供一系列验证结果。

use Mdcass\FileValidator\Facades\FileValidator;

$results = FileValidator::load('file.csv')->execute();
$results->file_exists; // true

1. 安装
2. 验证和读取

• 验证整个文件
• 遍历文件
• 简写实例化

1. 方法

• 属性

1. 示例

• 文件存在
• 设置标题行
• 指定工作表
• 验证规则
• 检索唯一值

1. 访问器

• 别名

1. 结果包

• 可用属性
• 计时器

1. 常见问题解答
2. 贡献

• 测试

安装

安装说明适用于Laravel 5.3

需要库

composer require mdcass/file-validator

将服务提供者添加到config/app.php中的providers列表

// config/app.php

'providers' => [
    ...
    /*
     * Third Party Service Providers
     */
    Mdcass\FileValidator\FileValidatorServiceProvider::class
]

可选地在config/app.php中的aliases列表中别名门面

// config/app.php

'aliases' => [
    ...
    'FileValidator' => Mdcass\FileValidator\Facades\FileValidator::class
]

该包将文件加载到在config('filesystems.disks.local.root')设置的路径。

验证和读取

以下两种方法表示此库的建议实现。

验证整个文件

验证门面上的execute方法使用您指定的配置返回一个结果包。

$results = FileValidator::load('relative/file/path.csv')
                             ->rules([
                                    'required' => [
                                        ['date']
                                    ],
                                    'date' => [
                                        ['date']
                                    ],
                                    'in' => [
                                        ['company', ['Schoen-Kertzmann']]
                                    ],
                                    'lengthMax' => [
                                        ['company', 255]
                                    ]
                               ])
                             ->execute();
$results->valid; // true

遍历文件

验证门面上的reader属性表示类的底层Reader类（其配置可以以与设置标题行相同的方式指定）。

以下示例使用底层库的chunk方法以更有效的方式从大文件中获取结果。

$validator = FileValidator::load('accessor.csv')
                                ->aliases([
                                    'date' => 'datum'
                                ])
                                ->rules([
                                    'required' => [
                                        ['datum']
                                    ],
                                ]);

// The $validator is passed by reference into the chunk callback,
// as each $row it is given to validate will contribute to the internal
// results (such as the total row_count, valid_row_count, and invalid_row_count)
$validator->reader->chunk(1000, function($row) use (&$validator) {
    // Pass the row into the validator to validate, as well as set
    // any aliased rows and accessors
    $results = $validator->validateRow($row);

    $results; // ['valid' => true, 'row' => Mdcass\FileValidator\Support\Row]
    $results['row']->toArray(); // ['date' => '2016-11-23', ..., 'datum' => '2016-11-23']

}, false); // Third parameter prevents the underlying library for queueing the chunk

$results = $validator->results;
$results->valid // true        

简写实例化

可以通过向要调用的方法构造函数传递一个数组来实例化类。

$validator = new FileValidator([
                    'load' => 'simple.csv',
                    'rules' => [
                                    'required' => [
                                        ['date']
                                    ]
                               ],
                    'distinct' => ['randomelementab'],

                ]);

$results = $validator->execute();

方法

属性

示例

文件存在

验证文件是否存在。传递给 load 方法的路径应相对于 config('filesystems.disks.local.root') 中的 Laravel 存储配置变量。

$results = FileValidator::load('simple.csv')->execute();

$results->file_exists; // true
$results->has_data; // true

如果工作表中只有标题存在，则结果中的 has_data 标志将为 false

设置标题行

设置要使用的标题行

$results = FileValidator::load('simple.csv')
                             ->config(['start_row' => 2])
                             ->execute();

$results->has_data; // true

config 方法自定义了底层 Excel 操作包上的属性，您可以在 这里 查看可以配置的内容（Maatwebsite/Laravel-Excel@2.1）

指定工作表

$results = FileValidator::load('multisheet.xls')
                             ->sheet('Second Sheet')
                             ->execute();

$results->has_data; // true

如果工作表不存在，则结果中的 has_data 标志将为 false

验证规则

验证规则参考出色的库 vlucas/valitron

simple_rules.csv

$results = FileValidator::load('simple_rules.csv')
                             ->rules([
                                    'required' => [
                                        ['date']
                                    ],
                                    'date' => [
                                        ['date']
                                    ],
                                    'in' => [
                                        ['company', ['Schoen-Kertzmann']]
                                    ],
                                    'lengthMax' => [
                                        ['company', 255]
                                    ]
                               ])
                             ->execute();
$results->valid; // false
$results->row_count; // 2
$results->valid_row_count; // 1
$results->invalid_row_count; // 1
$results->errors; // ['company' => 1]

检索唯一值

该库可以收集文件中字段的唯一值，这可能有助于在库外部进行进一步验证。

任何设置为返回唯一值的字段都将在验证规则中添加为 required

simple_distinct.csv

$results = FileValidator::load('simple_distinct.csv')
            ->distinct(['date'])
            ->execute();

$results->values->date; // ['2016-11-30', '2016-12-01']

访问器

您可以为字段指定一个回调以操作行返回的值。

验证发生在回调返回的值上

accessors.csv

// define an accessor for the date field to change the format from Y-m-d to m/d/Y
$validator = FileValidator::load('accessor.csv')
                            ->accessors([
                                    [
                                    'field' => 'date',
                                    'callback' => function($val) {
                                        return \Carbon\Carbon::parse($val)->format('m/d/Y');
                                    },
                                ],
                            ]);

// Retrieve a row from the underlying reader and
// pass it to the $validator for a validation result
$row = $validator->reader->take(1)->get();
$res = $validator->validateData($row);

$res['row']->date; // 30/11/2016

别名

您可以使用给定的回调将访问器别名为一个别名，并将其与原始字段分别验证。

$validator = FileValidator::load('accessor.csv')
                            ->accessors([
                                [
                                    'field' => 'date',
                                    'callback' => function($val) {
                                        return 1;
                                    },
                                    'alias' => 'datum',
                                ],
                            ])
                            ->rules([
                                'required' => [
                                    ['datum']
                                ],
                                'numeric' => [
                                    ['datum']
                                ],
                            ]);

$row = $validator->reader->take(1)->get();
$res = $validator->validateData($row);

$res['valid']; // true
$res['row']->toArray(); // ['date' => '2016-11-23', ..., 'datum' => 1]

结果包

可用属性

execute 方法返回一个类 Mdcass\FileValidator\ResultsBag，它具有以下属性

计时器

结果包还包含一个 timers 属性，它是一个脚本执行时间的列表。列表中的每个项目都包含 start 和 end 的 Unix 时间戳（微秒）以及 result（秒）。

$results = FileValidator::load('file.csv')->execute();

$results->timers->load; // [ 'start' => 1482743338.946, 'end' => 1482743338.9575, 'result' => 0.011478900909424 ]

var_dump($results->timers->toArray()); // ['load' => [...], 'has_data' => [...], 'execute' => [...]]

常见问题解答（FAQ）

库能否从流中加载文件，或者能否指定存储磁盘？

不可以，文件必须存在于本地磁盘上。虽然这不在本包的范围内，但未来的另一个包将包含此功能（然而将只是一个简单地本地存储、验证、删除的方式，如这个 GitHub 上的讨论所示，这是关于本包底层文件读取包依赖的讨论）

贡献

测试

包的测试遵循这篇文章。要测试

$ cd /path/to/package/mdcass/file-validator
$ ../../../vendor/bin/phpunit

测试将在包的配置文件 config/file-validator-testing.php 中定义的位置创建模拟数据文件，变量为 storage_path。