README

本软件包可与xlsx-laravel-spreadsheet-importer CLI 工具一起使用，快速从 xlsx 文件和其他兼容格式导入电子表格，然后将值存储到临时数据库表中，这些表更容易处理。

由于我们使用 Node 而不是 PHP，因此只需几秒钟即可导入更大的 xlsx 文件，并且由于我们将与 SQL 表一起工作，数据处理操作将更快。

• 包含一个命令，该命令根据 CLI 工具期望数据并触发一个带有导入进度的可观察事件。
• 添加一个特质，使您的模型能够像任何 Eloquent 关系一样轻松地处理临时数据。
• 导入完成后，将触发另一个可观察事件，以便您知道何时可以继续与导入相关的后续操作。
• 管理多种文件格式，请参阅（https://npmjs.net.cn/package/xlsx#file-formats）
• 与 PostgreSQL 和 MySQL 兼容

安装

您可以通过 composer 安装此软件包

composer require alfonsobries/laravel-spreadsheet-importer

您还需要 npm 软件包（更多信息请参阅 alfonsobries/xlsx-laravel-spreadsheet-importer）

npm install @alfonsobries/xlsx-laravel-spreadsheet-importer --save

可选：通过运行以下命令发布配置文件

php artisan vendor:publish --provider="Alfonsobries\LaravelSpreadsheetImporter\LaravelSpreadsheetImporterServiceProvider" --tag="config"

配置您的模型

您将要导入的文件通常将关联到一个模型，您的模型也将用于存储导入进度。

首先，将 InteractsWithImporter 特质和 Importable 合同添加到模型中。

您还需要定义 Importable 合同中的方法

<?php

namespace App\Models;

use Alfonsobries\LaravelSpreadsheetImporter\Traits\InteractsWithImporter;
use Alfonsobries\LaravelSpreadsheetImporter\Contracts\Importable;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model implements Importable
{
    use InteractsWithImporter;

    /**
     * Return the full path of the file that will be imported
     * @return string
     */
    public function getFileToImportPath() {
        // Notice that this line should be adapted to your application, this is an example for
        // a path that comes from a file that was stored using the spatie media library package
        return $this->getFirstMedia('file')->getPath();
    }

    /**
     * Return the temporaly table name that will be used to store the spreadsheet contents
     *
     * @return string
     */
    public function getTemporalTableName() {
        // This is an example you should adapt this line to your own application
        // You should create a method that always return the same value for the same model
        return sprintf('file_%s', $this->id);
    }

向 Importable 模型添加必要的列

您的模型需要一些列来存储导入的进度和状态，要添加这些列，您可以创建一个像以下这样的迁移（只需更改表名以匹配您的模型表名）

<?php

use Illuminate\Support\Facades\Schema;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Database\Migrations\Migration;

class AddImportableColumnsToModel extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('my_model_table', function (Blueprint $table) {
            $table->string('importable_process_id')->nullable();
            $table->string('importable_table_name')->nullable();
            $table->string('importable_total_rows')->nullable();
            $table->string('importable_processed')->nullable();
            $table->string('importable_status')->default('new');
            $table->mediumText('importable_output')->nullable();
            $table->mediumText('importable_feedback')->nullable();
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::table('my_model_table', function (Blueprint $table) {
            $table->dropColumn('importable_process_id');
            $table->dropColumn('importable_table_name');
            $table->dropColumn('importable_total_rows');
            $table->dropColumn('importable_processed');
            $table->dropColumn('importable_status');
            $table->dropColumn('importable_output');
            $table->dropColumn('importable_feedback');
        });
    }
}

一旦配置了模型并导入了电子表格，您就可以使用 tempData() 关系与存储在临时表中的数据进行交互。

例如，假设您的电子表格有一个销售列，您想计算总数

$totalSales = $myModel->tempData()->sum('sales');

导入文件

导入文件时，需要根据此处的说明调用 xlsx-laravel-spreadsheet-importer 命令，但为了使您的工作更简单，此软件包包括一个 StartImport 任务，该任务会为您构建命令（别忘了将必要的进度存储列添加到您的模型中）。

您可以在任何时候调度作业，它接收 importable 模型作为参数。

例如，您可以在控制器中的 store 方法保存模型时调用作业（假设您的模型关联了一个文件，并且会在 getFileToImportPath() 方法中返回一个有效的文件路径）

public function store(Request $request, MyModel $model)
{
    $model->addFile($request->file);

    \Alfonsobries\LaravelSpreadsheetImporter\Jobs\StartImport::dispatch($model);

    // ...The rest of the code
}

该作业将创建并触发Node命令，然后Node命令将每次有进度要通知时调用ReportImporterProgress artisan命令，最后artisan命令将触发一个ImporterProgressEvent，您可以通过自定义事件监听器或添加此包中包含的ImporterProgressEventListener来监听此事件，该监听器负责将您的导入进度存储到您的模型中

要配置事件监听器，请将以下行添加到您的app/Providers/EventServiceProvider.php

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        // Every time the importer has some progress
        \Alfonsobries\LaravelSpreadsheetImporter\Events\ImporterProgressEvent => [
            // (Or use your own event listener)
            \Alfonsobries\LaravelSpreadsheetImporter\Listeners\ImporterProgressEventListener::class,
        ],

        // The `ImporterProgressEventListener` also creates the following observable events:
        // When the import finished
        \Alfonsobries\LaravelSpreadsheetImporter\Events\ImporterProgressFinishedEvent => [
            // In this case you will need to define your own event listener 
        ],

        // When the import reports an error:
        \Alfonsobries\LaravelSpreadsheetImporter\Events\ImporterProgressErrorEvent => [
            // In this case you will need to define your own event listener 
        ],
    ];
    // ...

测试

要运行测试，您需要安装依赖项并拥有一个有效的测试数据库

• 安装composer包：composer install
• 因为此包与数据库交互，您需要定义一个包含有效mysql或postgresql数据库数据的.env文件（以env.example为例）
• 您还需要安装npm依赖项：npm install

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全性

如果您发现任何安全相关的问题，请通过电子邮件alfonso@vexilo.com而不是使用问题跟踪器。

鸣谢

• Alfonso Bribiesca
• 所有贡献者

许可协议

MIT许可协议（MIT）。请参阅许可文件以获取更多信息。