laravel-excel maatwebsite excel 导入的中文文档

项目里需要导入了，正好 3.1 版本，也支持导入了，补充下 excel 导入的翻译文档。(工作比较忙，大概过了一遍，可能有不少错误的地方)

1.5分钟快速入门
	在 app/Import 创建一个导入类
		php artisan make:import UsersImport --model=User

	会在 app/Imports 发现新创建的文件:
		.
		├── app
		│   ├── Imports
		│   │   ├── UsersImport.php
		│ 
		└── composer.json

	如果你更喜欢手动创建导入，可以在 app/Imports 下创建如下文件：
		<?php

		namespace App\Imports;

		use App\User;
		use Illuminate\Support\Facades\Hash;
		use Maatwebsite\Excel\Concerns\ToModel;

		class UsersImport implements ToModel
		{
		    /**
		     * @param array $row
		     *
		     * @return User|null
		     */
		    public function model(array $row)
		    {
		        return new User([
		           'name'     => $row[0],
		           'email'    => $row[1], 
		           'password' => Hash::make($row[2]),
		        ]);
		    }
		}

	在控制器中调用导入：
		use App\Imports\UsersImport;
		use Maatwebsite\Excel\Facades\Excel;
		use App\Http\Controllers\Controller;

		class UsersController extends Controller 
		{
		    public function import() 
		    {
		        Excel::import(new UsersImport, 'users.xlsx');
		        
		        return redirect('/')->with('success', 'All good!');
		    }
		}

2.基本导入
	如果已经按 5 分钟快速入门练习，我们已经有了一个 UsersImport 类。
		...

	从默认文件系统导入：
		将 UsersImport 传递给 Excel::import() 方法，将告知包如何导入第二个参数传递的 excel 文件。导入的 excel 文件需要位于我们的默认文件系统(查看 config/filesystems.php)。
			Excel::import(new UsersImport, 'users.xlsx');

	从另一个文件系统导入：
		我们可以通过传递第三个参数，来指定另一个文件系统，例如：Amazon s3 文件系统
			Excel::import(new UsersImport, 'users.xlsx', 's3');

	导入上传文件：
		如果让用户上传 excel 文件，我们也可以直接传递上传的文件
			Excel::import(new UsersImport, request()->file('excel.xls'));

	导入全路径：
		如果要指定文件所在的路径，而不必将其移动到文件系统，我们可以直接将该文件路径传递给 import 方法
			Excel::import(new UsersImport, storage_path('users.xlsx'));

	导入为数组或集合：
		如果想要省略 ToArray 或 ToCollection concern，并且希望在控制中得到一个导入数据的数组(注意性能)，可以使用 ::toArray() 或 ::toCollection() 方法
			$array = Excel::toArray(new UsersImport, 'users.xlsx');
			$collection = Excel::toCollection(new UsersImport, 'users.xlsx');

	指定 'reader' 类型：
		如果通过文件扩展名无法检测到 reader 类型，我们可以传递第 4 个参数来指定一个 reader 类型
			Excel::import(new UsersImport, 'users.xlsx', 's3', \Maatwebsite\Excel\Excel::XLSX);

3.导入到集合
	开始导入的最简单方式是，创建一个自定义的导入类。我们将使用一个 UsersImport 导入类作为示例。

	在 App/Imports 下创建一个新的 UsersImport 导入类：
		namespace App\Imports;

		use App\User;
		use Illuminate\Support\Collection;
		use Maatwebsite\Excel\Concerns\ToCollection;

		class UsersImport implements ToCollection
		{
		    public function collection(Collection $rows)
		    {
		        foreach ($rows as $row) 
		        {
		            User::create([
		                'name' => $row[0],
		            ]);
		        }
		    }
		}

	collection() 方法接收一个行集合。每一行是一个由单元格的值填充的数组。

	如果文件有多个工作表，collection() 方法将会被调用多次。

	在控制器中，现在我们可以像下面这样导入：
		public function import()
		{
			Excel::import(new UsersImport, 'users.xlsx');
		}

	警告：
		不管我们在 collection() 方法中返回什么内容，都不会返回给控制器

4.导入到模型
	如果我们想要将一个工作簿导入到一个 Eloquent 模型，可以使用 ToModel concern。ToModel concern 将强制 model() 方法返回一个 model 类型
		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;

		class UsersImport implements ToModel
		{
		    public function model(array $row)
		    {
		        return new User([
		            'name' => $row[0],
		        ]);
		    }
		}

	返回的模型将为我们保存。每行将导致(至少)一次保存，并且还将触发模型事件。

	警告：
		当使用 ToModel 时，我们不应该自己保存模型，因为这将破坏批量插入的功能。如果我们需要自己保存模型，可以考虑使用 OnEachRow

	跳过行
		如果想要跳过行，可以返回 null
			public function model(array $row)
			{
			    if (!isset($row[0])) {
			        return null;
			    }

			    return new User([
			        'name' => $row[0],
			    ]);
			}

	可能的列名(导入一个列，可尝试几个字段，直到给定的列存在值。例如：用户名：username -> nick_name -> mobile)
		如果想要通过几个可能的列名导入行(使用 WithHeadingRow)，可以使用 null 合并操作符(??)。如果 first name 的列存在(示例中是 client_name)，并且不是 Null，则返回它的值；否则寻找第二个可能的列名(示例中是 client)。
			public function model(array $row) {
			  	return new User([
			    	'name' => $row['client_name'] ?? $row['client'] ?? $row['name'] ?? null
			  	]);
			}

	自己来处理持久化
		在某些情况下，我们可能并没有一个导入，该导入的每一行都是一个 Eloquent 模型，并且我们想要更多的控制发生了什么。在这些情况下，我们可以使用 OnEachRow concern
			namespace App\Imports;

			use App\User;
			use Maatwebsite\Excel\Row;
			use Maatwebsite\Excel\Concerns\OnEachRow;

			class UsersImport implements OnEachRow
			{
			    public function onRow(Row $row)
			    {
			        $rowIndex = $row->getIndex();
			        $row      = $row->toArray();
			        
			        $group = Group::firstOrCreate([
			            'name' => $row[1],
			        ]);
			    
			        $group->users()->create([
			            'name' => $row[0],
			        ]);
			    }
			}

		警告：
			当使用 OnEachRow，我们不能使用批量插入，因为该模型已经在 onRow 方法中持久化的保存。

5.可导入
	在之前的示例中，我们使用 Excel::import facade 来开始一个导入。

	Laravel Excel 也提供了一个 'Maatwebsite\Excel\Concerns\Importable' trait，来使得导入类可导入。
		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\Importable;

		class UsersImport implements ToModel
		{
		    use Importable;

		    public function model(array $row)
		    {
		        return new User([
		            'name' => $row[0],
		        ]);
		    }
		}

	导入
		我们现在可以不需要 facade 来导入：
			(new UsersImport)->import('users.xlsx', 'local', \Maatwebsite\Excel\Excel::XLSX);

	队列
		或队列导入：
			(new UsersImport)->queue('users.xlsx');

	导入到数组
		导入可以加载到数组：
			$array = (new UsersImport)->toArray('users.xlsx');

	导入到集合
		导入可以加载到集合：
			$collection = (new UsersImport)->toCollection('users.xlsx');

6.导入格式
	默认情况下，导入格式由文件的扩展名决定。如果要显式配置导入格式，可以将其作为第 3 个参数传递。

	XLSX
		(new UsersImport)->import('users.xlsx', null, \Maatwebsite\Excel\Excel::XLSX);

	CSV
		(new UsersImport)->import('users.csv', null, \Maatwebsite\Excel\Excel::CSV);

	TSV
		(new UsersImport)->import('users.tsv', null, \Maatwebsite\Excel\Excel::TSV);

	ODS
		(new UsersImport)->import('users.ods', null, \Maatwebsite\Excel\Excel::ODS);

	XLS
		(new UsersImport)->import('users.xls', null, \Maatwebsite\Excel\Excel::XLS);

	SLK
		(new UsersImport)->import('users.slk', null, \Maatwebsite\Excel\Excel::SLK);

	XML
		(new UsersImport)->import('users.xml', null, \Maatwebsite\Excel\Excel::XML);

	GUNMERIC
		(new UsersImport)->import('users.gnumeric', null, \Maatwebsite\Excel\Excel::GNUMERIC);

	HTML
		(new UsersImport)->import('users.html', null, \Maatwebsite\Excel\Excel::HTML);

7.多个工作表
	当一个文件有多个工作表时，每个工作表都将通过导入对象。如果想要单独处理每个工作表，需要实现 WithMultipleSheets concern。

	sheets() 方法希望返回一个 '工作表导入对象' 的数组。工作表的顺序很重要，数组中第一个工作表导入对象，将自动链接到 Excel 文件的第一个工作表。
		namespace App\Imports;

		use Maatwebsite\Excel\Concerns\WithMultipleSheets;

		class UsersImport implements WithMultipleSheets 
		{
		   
		    public function sheets(): array
		    {
		        return [
		            new FirstSheetImport()
		        ];
		    }
		}

	工作表导入类可以导入 '与普通导入对象相同的' concerns
		namespace App\Imports;

		use Illuminate\Support\Collection;
		use Maatwebsite\Excel\Concerns\ToCollection;

		class FirstSheetImport implements ToCollection
		{
		    public function collection(Collection $rows)
		    {
		        //
		    }
		}

	通过工作表索引选择工作表
		如果想要更多地控制，选择哪些工作表，以及如何将它们映射到指定的工作表导入对象，我们可以使用工作表索引作为下标。工作表索引从 0 开始。
			namespace App\Imports;

			use Maatwebsite\Excel\Concerns\WithMultipleSheets;

			class UsersImport implements WithMultipleSheets 
			{
			   
			    public function sheets(): array
			    {
			        return [
			            0 => new FirstSheetImport(),
			            1 => new SecondSheetImport(),
			        ];
			    }
			}

	通过工作表名称选择工作表
		如果我们只知道工作表名称，而不知道工作表索引，我们也可以使用工作表名称作为选择器。将工作表名称作为数组索引，来将工作表链接到工作表导入对象。
			namespace App\Imports;

			use Maatwebsite\Excel\Concerns\WithMultipleSheets;

			class UsersImport implements WithMultipleSheets 
			{
			    public function sheets(): array
			    {
			        return [
			            'Worksheet 1' => new FirstSheetImport(),
			            'Worksheet 2' => new SecondSheetImport(),
			        ];
			    }
			}

		警告：
			未显式定义在 sheet() 方法中的工作表，将被忽略，因此不会被导入。

	跳过未知的工作表
		当我们定义了不存在的工作表名称或索引后，将抛出 Maatwebsite\Excel\Exceptions\SheetNotFoundException 异常

		当工作表不存在时，我们不想抛出异常，可以使用 Maatwebsite\Excel\Concerns\SkipsUnknownSheets concern
			namespace App\Imports;

			use Maatwebsite\Excel\Concerns\WithMultipleSheets;
			use Maatwebsite\Excel\Concerns\SkipsUnknownSheets;

			class UsersImport implements WithMultipleSheets, SkipsUnknownSheets
			{
			    public function sheets(): array
			    {
			        return [
			            'Worksheet 1' => new FirstSheetImport(),
			            'Worksheet 2' => new SecondSheetImport(),
			        ];
			    }
			    
			    public function onUnknownSheet($sheetName)
			    {
			    	// 例如，我们可以记录未找到工作表
			        info("Sheet {$sheetName} was skipped");
			    }
			}

		仅跳过指定的工作表
			如果想要一个可选的工作表，并且其他的工作表仍然失败，还可以让工作表导入对象实现 SkipsUnknownSheets
				namespace App\Imports;

				use Maatwebsite\Excel\Concerns\SkipsUnknownSheets;

				class FirstSheetImport implements SkipsUnknownSheets
				{
				    public function onUnknownSheet($sheetName)
				    {
				    	// 例如，我们可以记录未找到工作表
				        info("Sheet {$sheetName} was skipped");
				    }
				}

			现在，只有 FirstSheetImport 在没找到时，会被跳过。任意其他定义的工作表将被跳过(将报错吧，这里应该写错了)

	有条件地加载工作表
		如果要指定每个导入应该导入哪些工作表，可以使用 Maatwebsite\Excel\Concerns\WithConditionalSheets trait
			namespace App\Imports;

			use Maatwebsite\Excel\Concerns\WithMultipleSheets;
			use Maatwebsite\Excel\Concerns\WithConditionalSheets;

			class UsersImport implements WithMultipleSheets 
			{
			    use WithConditionalSheets;

			    public function conditionalSheets(): array
			    {
			        return [
			            'Worksheet 1' => new FirstSheetImport(),
			            'Worksheet 2' => new SecondSheetImport(),
			            'Worksheet 3' => new ThirdSheetImport(),
			        ];
			    }
			}

		现在可以使用 onlySheets 方法来指定本次导入应该加载哪些工作表
			$import = new UsersImport();
			$import->onlySheets('Worksheet 1', 'Worksheet 3');

			Excel::import($import, 'users.xlsx');

8.标题行
	如果文件包含标题行，并且希望将这些名称作为每一行的数组的键，可以实现 WithHeadingRow concern

	假设我们的 Excel 文件如下所示：
		Name 			Email  			@Field
		dongxuemin 		[email protected] 	30

	我们现在可以引用这些标题，来替代之前的数字格式的数组键
		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\WithHeadingRow;

		class UsersImport implements ToModel, WithHeadingRow
		{
		    public function model(array $row)
		    {
		        return new User([
		            'name'  => $row['name'],
		            'email' => $row['email'],
		            'at'    => $row['at_field'],
		        ]);
		    }
		}

	标题行在其他行(非第一行)
		如果标题行不在第一行，可以在导入类中简单地指定：
			namespace App\Imports;

			use App\User;
			use Maatwebsite\Excel\Concerns\ToModel;
			use Maatwebsite\Excel\Concerns\WithHeadingRow;

			class UsersImport implements ToModel, WithHeadingRow
			{
			    public function model(array $row)
			    {
			        return new User([
			            'name'  => $row['name'],
			            'email' => $row['email'],
			        ]);
			    }
			    
			    public function headingRow(): int
			    {
			        return 2;
			    }
			}

		现在第二行将作为标题行

	标题键格式
		默认情况下，标题键使用 Laravel 的 str_slug() 帮助函数进行格式化，例如，这意味着所有的空格被转换为 _

		如果想要改变该默认行为，可以通过扩展 HeadingRowFormatter 来实现。

		不格式化
			如果不需要格式化，可以使用 none 格式化程序。数组建将包含标题行中的确切数据。
				use Maatwebsite\Excel\Imports\HeadingRowFormatter;

				HeadingRowFormatter::default('none');

				public function model(array $row)
				{
				    return new User([
				        'name'  => $row['Name'],
				        'email' => $row['Email'],
				    ]);
				}

		自定义格式化程序
			可以在服务提供者中，使用 ::extend() 来定义一个自定义格式化程序
				HeadingRowFormatter::extend('custom', function($value) {
				    return 'do-something-custom' . $value; 
				});

			可以在 config/excel.php 中设置自定义格式化程序
				'imports' => [
				    'heading_row' => [
				        'formatter' => 'custom',
				    ],
				],

			或者之后可以在服务提供者中设置新的格式化程序
				HeadingRowFormatter::default('custom');

	只导入标题行
		有时我们可能希望预先获取标题行来进行一些验证，有一个简单的快捷方式：HeadingRowImport
			use Maatwebsite\Excel\HeadingRowImport;

			class UsersImportController extends Controller 
			{
			    public function import()
			    {
			        $headings = (new HeadingRowImport)->toArray('users.xlsx');
			    }
			}

		标题数组包含每张工作表的一个标题数组

9.批量插入
	将大文件导入到 Eloquent 模型，可能很快会有瓶颈，因为每一行都会导致一次插入查询。

	使用 WithBatchInserts concern，我们可以通过指定一个批处理大小，来限制查询数量。该批处理大小将决定一次将多少模型插入到数据库。这将大大减少导入时间。
		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\WithBatchInserts;

		class UsersImport implements ToModel, WithBatchInserts
		{
		    public function model(array $row)
		    {
		        return new User([
		            'name' => $row[0],
		        ]);
		    }
		    
		    public function batchSize(): int
		    {
		        return 1000;
		    }
		}

	ToModel
		该 concern 只与 ToModel concern 一起工作时有效。

	批处理大小
		1000 的批处理大小，并不是导入的最佳情况。我们需要根据自己的系统，来找到最佳的数值。

10.分块读取
	导入大文件，会占用很大内存，因为库尝试将整个工作表加载到内存。

	要减少内存使用的增加，我们可以使用 WithChunkReading concern。这将以分块的方式来读取工作表，并控制内存使用量。
		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\WithChunkReading;

		class UsersImport implements ToModel, WithChunkReading
		{
		    public function model(array $row)
		    {
		        return new User([
		            'name' => $row[0],
		        ]);
		    }
		    
		    public function chunkSize(): int
		    {
		        return 1000;
		    }
		}

	警告：
		1000 的块大小，并不是导入的最佳情况。我们需要根据自己的系统，来找到最佳的数值。

	与批量插入一起使用
		(考虑时间和内存的消耗)最完美的解决方案是，将批量插入和分块读取结合使用
			namespace App\Imports;

			use App\User;
			use Maatwebsite\Excel\Concerns\ToModel;
			use Maatwebsite\Excel\Concerns\WithBatchInserts;
			use Maatwebsite\Excel\Concerns\WithChunkReading;

			class UsersImport implements ToModel, WithBatchInserts, WithChunkReading
			{
			    public function model(array $row)
			    {
			        return new User([
			            'name' => $row[0],
			        ]);
			    }
			    
			    public function batchSize(): int
			    {
			        return 1000;
			    }
			    
			    public function chunkSize(): int
			    {
			        return 1000;
			    }
			}

11.队列读取
	队列分块读取
		当使用 WithChunkReading concern 时，我们也可以选择将每个分块放入到队列中。只需简单地添加 ShouldQueue contract 即可。
			namespace App\Imports;

			use App\User;
			use Maatwebsite\Excel\Concerns\ToModel;
			use Illuminate\Contracts\Queue\ShouldQueue;
			use Maatwebsite\Excel\Concerns\WithChunkReading;

			class UsersImport implements ToModel, WithChunkReading, ShouldQueue
			{
			    public function model(array $row)
			    {
			        return new User([
			            'name' => $row[0],
			        ]);
			    }
			    
			    public function chunkSize(): int
			    {
			        return 1000;
			    }
			}

		现在，包含 1000 行的块，将被放入到队列

		警告：
			ShouldQueue 仅支持和 WithChunkReading 结合使用

		显式地队列导入
			通过使用 ::queueImport，我们可以显式地队列导入
				Excel::queueImport(new UsersImport, 'users.xlsx');

			当使用 Importable trait 时，我们可以使用 queue 方法：
				(new UsersImport)->queue('users.xlsx');

			警告：
				ShouldQueue 总是需要的

		隐式地队列导入
			当使用了 ShouldQueue，导入将被自动放入队列	
				Excel::import(new UsersImport, 'users.xlsx');

	追加任务(注意：这个任务，并不一定是导入任务，可以是任意的任务)
		当队列导入时，将返回 Laravel 的 PendingDispatch 实例。这意味着我们可以链式地将额外的任务添加到队列的末尾，并且只有在所有导入任务正确执行完毕后，才会执行追加的任务
			(new UsersImport)->queue('users.xlsx')->chain([
			    new NotifyUserOfCompletedImport(request()->user()),
			]);

			namespace App\Jobs;

			use App\User;
			use Illuminate\Bus\Queueable;
			use Illuminate\Contracts\Queue\ShouldQueue;
			use Illuminate\Queue\SerializesModels;

			class NotifyUserOfCompletedImport implements ShouldQueue
			{
			    use Queueable, SerializesModels;
			    
			    public $user;
			    
			    public function __construct(User $user)
			    {
			        $this->user = $user;
			    }

			    public function handle()
			    {
			        $this->user->notify(new ImportReady());
			    }
			}

	自定义队列
		由于返回了 PendingDispatch，我们也可以改变使用的队列
			(new UsersImport)->queue('users.xlsx')->allOnQueue('imports')

	多服务器设置
		如果正在处理多服务器设置(例如：负载均衡)，我们可能希望确保每个任务的临时文件是相同的。我们可以在配置中，配置一个远程的临时文件来实现。

		在 config/excel.php：
			'temporary_files' => [
			    'remote_disk' => 's3',
			],

	注意
		警告：
			目前不能队列 xls 导入。 PhpSpreadsheet 的 Xls 读取器，包含了一些非 utf8 字符，导致无法队列

12.行验证
	有时候我们想要在插入数据库之前，验证每一行。通过实现 WithValidation concern，我们可以指定每一行需要遵从的规则。

	rule() 方法，希望返回一个 Laravel Validation 规则
		<?php

		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\Importable;
		use Maatwebsite\Excel\Concerns\WithValidation;

		class UsersImport implements ToModel, WithValidation
		{
		    use Importable;

		    public function model(array $row)
		    {
		        return new User([
		            'name'     => $row[0],
		            'email'    => $row[1],
		            'password' => 'secret',
		        ]);
		    }

		    public function rules(): array
		    {
		        return [
		            '1' => Rule::in(['[email protected]']),

		             // Above is alias for as it always validates in batches
		             '*.1' => Rule::in(['[email protected]']),
		             
		             // Can also use callback validation rules
		             '0' => function($attribute, $value, $onFailure) {
		                  if ($value !== 'Patrick Brouwers') {
		                       $onFailure('Name is not Patrick Brouwers');
		                  }
		              }
		        ];
		    }
		}

	使用标题行进行验证
		当使用 WithHeadingRow concern，我们可以使用标题行名称作为规则属性
			<?php

			namespace App\Imports;

			use App\User;
			use Maatwebsite\Excel\Concerns\ToModel;
			use Maatwebsite\Excel\Concerns\Importable;
			use Maatwebsite\Excel\Concerns\WithValidation;
			use Maatwebsite\Excel\Concerns\WithHeadingRow;

			class UsersImport implements ToModel, WithValidation, WithHeadingRow
			{
			    use Importable;

			    public function model(array $row)
			    {
			        return new User([
			            'name'     => $row['name'],
			            'email'    => $row['email'],
			            'password' => 'secret',
			        ]);
			    }

			    public function rules(): array
			    {
			        return [
			            'email' => Rule::in(['[email protected]']),

			             // Above is alias for as it always validates in batches
			             '*.email' => Rule::in(['[email protected]']),
			        ];
			    }
			}

	自定义验证消息
		通过给导入添加 customValidationMessages() 方法，我们可以为每个失败的验证指定自定义消息
			/**
			* @return array
			*/
			public function rules(): array
			{
			    return [
			        '1' => Rule::in(['[email protected]']),
			    ];
			}

			/**
			 * @return array
			 */
			public function customValidationMessages()
			{
			    return [
			        '1.in' => 'Custom message for :attribute.',
			    ];
			}

	自定义验证属性
		通过给导入添加 customValidationAttributes() 方法，我们可以为每一列指定自定义属性名
			/**
			* @return array
			*/
			public function rules(): array
			{
			    return [
			        '1' => Rule::in(['[email protected]']),
			    ];
			}

			/**
			 * @return array
			 */
			public function customValidationAttributes()
			{
			    return ['1' => 'email'];
			}

	处理验证错误
		数据库事务
			整个导入会自动包装到一个数据库事务中，这意味着每个错误将回滚整个导入。当使用批量插入时，只会回滚当前批次。

		禁用事务
			如果你更希望在导入(或块导入)时，没有任何数据库事务，可以在配置中，改变想要的事务处理器：

			在 config/excel.php
				'transactions' => [
				    'handler' => 'db',
				],

			目前支持的处理器有：null 或 db

		自定义事务处理器
			如果想要自定义一个事务处理器(例如：MongoDB 数据库)，可以如下添加我们自己的处理器：
				$this->app->make(\Maatwebsite\Excel\Transactions\TransactionManager::class)->extend('your_handler', function() {
				    return new YourTransactionHandler();
				});

			处理器应该实现 \Maatwebsite\Excel\Transactions\TransactionManager

		在最后收集所有错误
			当与批处理一起使用时，我们可以在导入结束后，收集所有的验证失败。我们可以 try-catch ValidationException。在此异常中，我们可以获得所有失败详情。

			每个失败详情是 Maatwebsite\Excel\Validators\Failure 的一个实例。Failure 包含的信息有：哪一行，哪一列，以及单元格的验证错误
				try {
				    $import->import('import-users.xlsx');
				} catch (\Maatwebsite\Excel\Validators\ValidationException $e) {
				     $failures = $e->failures();
				     
				     foreach ($failures as $failure) {
				         $failure->row(); // row that went wrong
				         $failure->attribute(); // either heading key (if using heading row concern) or column index
				         $failure->errors(); // Actual error messages from Laravel validator
				         $failure->values(); // The values of the row that has failed.
				     }
				}

		跳过失败
			有时候我们可能想要跳过失败。通过使用 SkipsOnFailure concern，我们可以控制验证失败发生时的情况。使用 SkipsOnFailure，当发生失败时，不会回滚整个导入
				<?php

				namespace App\Imports;

				use App\User;
				use Maatwebsite\Excel\Concerns\ToModel;
				use Maatwebsite\Excel\Validators\Failure;
				use Maatwebsite\Excel\Concerns\Importable;
				use Maatwebsite\Excel\Concerns\SkipsOnFailure;
				use Maatwebsite\Excel\Concerns\WithValidation;

				class UsersImport implements ToModel, WithValidation, SkipsOnFailure
				{
				    use Importable;

				    /**
				     * @param Failure[] $failures
				     */
				    public function onFailure(Failure ...$failures)
				    {
				        // Handle the failures how you'd like.
				    }
				}

			如果想要自动跳过所有失败的行，并在导入最后收集所有的失败，可以使用 Maatwebsite\Excel\Concerns\SkipsFailures trait。
				<?php

				namespace App\Imports;

				use App\User;
				use Maatwebsite\Excel\Concerns\ToModel;
				use Maatwebsite\Excel\Validators\Failure;
				use Maatwebsite\Excel\Concerns\Importable;
				use Maatwebsite\Excel\Concerns\SkipsOnFailure;
				use Maatwebsite\Excel\Concerns\WithValidation;
				use Maatwebsite\Excel\Concerns\SkipsFailures;

				class UsersImport implements ToModel, WithValidation, SkipsOnFailure
				{
				    use Importable, SkipsFailures;
				}

			已经跳过了，验证规则失败的每一行。现在我们可以在最后收集所有失败：
				$import = new UsersImport();
				$import->import('users.xlsx');

				foreach ($import->failures() as $failure) {
				     $failure->row(); // row that went wrong
				     $failure->attribute(); // either heading key (if using heading row concern) or column index
				     $failure->errors(); // Actual error messages from Laravel validator
				     $failure->values(); // The values of the row that has failed.
				}

		跳过错误
			有时候我们可能想要跳过所有错误，例如：重复的数据库记录。通过使用 SkipOnError concern，我们可以控制模型导入失败时的前那股看。使用 SkipOnError，当发生数据库异常时，不会回滚整个导入
				<?php

				namespace App\Imports;

				use App\User;
				use Maatwebsite\Excel\Concerns\ToModel;
				use Maatwebsite\Excel\Concerns\Importable;
				use Maatwebsite\Excel\Concerns\SkipsOnError;
				use Maatwebsite\Excel\Concerns\WithValidation;

				class UsersImport implements ToModel, WithValidation, SkipsOnError
				{
				    use Importable;

				    /**
				     * @param \Throwable $e
				     */
				    public function onError(\Throwable $e)
				    {
				        // Handle the exception how you'd like.
				    }
				}

			如果想要自动跳过所有异常，并在导入最后收集所有它们，可以使用 Maatwebsite\Excel\Concerns\SkipsErrors trait。
				<?php

				namespace App\Imports;

				use App\User;
				use Maatwebsite\Excel\Concerns\ToModel;
				use Maatwebsite\Excel\Validators\Failure;
				use Maatwebsite\Excel\Concerns\Importable;
				use Maatwebsite\Excel\Concerns\SkipsOnError;
				use Maatwebsite\Excel\Concerns\WithValidation;
				use Maatwebsite\Excel\Concerns\SkipsErrors;

				class UsersImport implements ToModel, WithValidation, SkipsOnError
				{
				    use Importable, SkipsErrors;
				}

			已经跳过了，发生错误的每一行。现在我们可以在最后收集所有错误：
				$import = new UsersImport();
				$import->import('users.xlsx');

				dd($import->errors());

	没有 ToModel 的行验证
		如果没有使用 ToModel concern，我们可以通过使用 Laravel Validator 非常简单地进行行验证。
			<?php

			namespace App\Imports;

			use App\User;
			use Illuminate\Support\Collection;
			use Illuminate\Support\Facades\Validator;
			use Maatwebsite\Excel\Concerns\ToCollection;

			class UsersImport implements ToCollection
			{
			    public function collection(Collection $rows)
			    {
			         Validator::make($rows->toArray(), [
			             '*.0' => 'required',
			         ])->validate();

			        foreach ($rows as $row) {
			            User::create([
			                'name' => $row[0],
			            ]);
			        }
			    }
			}

		验证规则
			所有的验证规则，参考 Laravel 验证规则文档

13.映射单元格
	如果有一个更加自定义化的电子表格，并且只想访问指定的单元格，可以实现 WithMappedCells concern

	我们可能有如下的电子表格：
		name 		Patrick Brouwers
		email 		[email protected]

	现在我们可以将 name 映射到 B1，将 email 映射到 B2。这些座标的值，之后将在给定的数组键下可用。
		namespace App\Imports;

		use App\User;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\WithMappedCells;

		new UsersImport implements WithMappedCells, ToModel 
		{
		    public function mapping(): array
		    {
		        return [
		            'name'  => 'B1',
		            'email' => 'B2',
		        ];
		    }
		    
		    public function model(array $row)
		    {
		        return new User([
		            'name' => $row['name'],
		            'email' => $row['email'],
		        ]);
		    }
		}

	警告：
		该 concern 并不意味着映射列，只允许引用指定的单元格。

14.自定义 CSV 配置
	默认情况下，Laravel Excel 使用配置文件(config/excel.php)的默认配置。我们可以通过添加 WithCustomCsvSettings 接口来改变该行为。
		namespace App\Imports;

		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;

		class UsersImport implements ToModel, WithCustomCsvSettings
		{
		    public function model(array $row)
		    {
		        return new User([
		            'name' => $row['0'],
		            'email' => $row['1']
		        ]);
		    }
		    
		    public function getCsvSettings(): array
		    {
		        return [
		            'input_encoding' => 'ISO-8859-1'
		        ];
		    }
		}

	可用的配置有：
		delimiter
		enclosure
		line_ending
		use_bom
		include_separator_line
		excel_compatibility
		escape_character
		contiguous
		input_encoding

15.进度条	
	当通过 console 来导入一个 Excel 文件，我们可以实现 WithProgressBar concern 来显示一个进度条。

	例如，我们的导入类如下所示：
		<?php

		namespace App\Imports;

		use App\User;
		use Illuminate\Support\Facades\Hash;
		use Maatwebsite\Excel\Concerns\Importable;
		use Maatwebsite\Excel\Concerns\ToModel;
		use Maatwebsite\Excel\Concerns\WithProgressBar;

		class UsersImport implements ToModel, WithProgressBar
		{
		    use Importable;

		    public function model(array $row)
		    {
		        return new User([
		            'name'     => $row[0],
		            'email'    => $row[1],
		            'password' => Hash::make($row[2]),
		        ]);
		    }
		}

	在我们的 console 命令中，如下使用：
		<?php

		namespace App\Console\Commands;

		use App\Imports\UsersImport;
		use Illuminate\Console\Command;

		class ImportExcel extends Command
		{
		    protected $signature = 'import:excel';

		    protected $description = 'Laravel Excel importer';

		    public function handle()
		    {
		        $this->output->title('Starting import');
		        (new UsersImport)->withOutput($this->output)->import('users.xlsx');
		        $this->output->success('Import successful');
		    }
		}

	在命令行，通过调用 php artisan import:excel，开始导入。现在应该就会看到开始信息，进度条，以及完成后的成功信息

16.导入 concern
	看文档

17.扩展
	看文档

18.测试
	Excel facade 可用于将导入器变换为 fake，来进行测试？？

	看文档