README

使用方法

导出器

创建导出器有两种方式。

使用命令创建导出器

您可以使用 php artisan data-synchronize:make:exporter 命令创建导出器。

php artisan data-synchronize:make:exporter PostExporter

手动创建导出器

导出器应该看起来是这样的，下面是一个 PostExporter 类的示例。

<?php

namespace Botble\Blog\Exporters;

use Botble\Blog\Models\Post;
use Botble\DataSynchronize\Exporter\ExportColumn;
use Botble\DataSynchronize\Exporter\Exporter;
use Illuminate\Support\Collection;

class PostExporter extends Exporter
{
    public function label(): string
    {
        return 'Posts';
    }

    public function columns(): array
    {
        return [
            ExportColumn::make('name'),
            ExportColumn::make('description'),
            ExportColumn::make('created_at'),
        ];
    }

    public function collection(): Collection
    {
        return Post::all();
    }
}

这是如何在控制器中使用导出器的示例。

<?php

namespace Botble\Blog\Http\Controllers;

use Botble\DataSynchronize\Exporter\Exporter;
use Botble\DataSynchronize\Http\Controllers\ExportController;
use Botble\Blog\Exporters\PostExporter;

class ExportPostController extends ExportController
{
    protected function getExporter(): Exporter
    {
        return PostExporter::make();
    }
}

然后，在您的路由文件中注册路由。

use Botble\Base\Facades\AdminHelper;
use Illuminate\Support\Facades\Route;
use Botble\Blog\Http\Controllers\ExportPostController;

AdminHelper::registerRoutes(function () {
    Route::prefix('tools/data-synchronize')->name('tools.data-synchronize.')->group(function () {
        Route::group(['prefix' => 'export/posts', 'as' => 'export.posts.', 'permission' => 'posts.export'], function () {
            Route::get('/', [ExportPostController::class, 'index'])->name('index');
            Route::post('/', [ExportPostController::class, 'store'])->name('store');
        });
    });
});

每个导出器路由都应该有一个访问权限。您可以使用路由组中的 permission 键来定义权限。

在上面的路由定义中，权限是 posts.export 键，其父级是 tools.data-synchronize。您可以在您的插件中的 permissions.php 中定义权限。

return [
    [
        'name' => 'Export Posts',
        'flag' => 'posts.export',
        'parent_flag' => 'tools.data-synchronize',
    ],
];

现在，您可以通过 http://your-domain/tools/data-synchronize/export/posts 导出帖子。

将导出器添加到导出/导入数据面板部分

要将导出器添加到导出/导入数据面板部分，您可以使用 PanelSectionManager 类的 beforeRendering 方法将导出器注册到面板部分。

use Botble\Base\Facades\PanelSectionManager;
use Botble\Base\PanelSections\PanelSectionItem;
use Botble\DataSynchronize\PanelSections\ExportPanelSection;

public function boot(): void
{
    // ...

    PanelSectionManager::setGroupId('data-synchronize')->beforeRendering(function () {
        PanelSectionManager::default()
            ->registerItem(
                ExportPanelSection::class,
                fn () => PanelSectionItem::make('posts')
                    ->setTitle('Posts')
                    ->withDescription('Export post data to CSV or Excel file.')
                    ->withPriority(120)
                    ->withRoute('tools.data-synchronize.export.posts.index')
                    ->withPermission('posts.export')
            );
    });
    
    // ...
}

您可以在 导出/导入数据 面板部分看到导出器。

导入器

创建导入器有两种方式。

使用命令创建导入器

您可以使用 php artisan data-synchronize:make:importer 命令创建导入器。

php artisan data-synchronize:make:importer PostImporter

手动创建导入器

导入器应该看起来是这样的，下面是一个 PostImporter 类的示例。

<?php

namespace Botble\Blog\Importers;

use Botble\Blog\Models\Post;
use Botble\DataSynchronize\Importer\ImportColumn;
use Botble\DataSynchronize\Importer\Importer;

class PostImporter extends Importer
{
    public function chunkSize(): int
    {
        return 1000;
    }

    public function label(): string
    {
        return 'Posts';
    }
    
    public function getValidateUrl(): string
    {
        return route('tools.data-synchronize.import.posts.validate');
    }

    public function getImportUrl(): string
    {
        return route('tools.data-synchronize.import.posts.store');
    }

    public function getDownloadExampleUrl(): ?string
    {
        return route('tools.data-synchronize.import.posts.download-example');
    }

    public function columns(): array
    {
        return [
            ImportColumn::make('name')->rules(['required', 'string']),
            ImportColumn::make('description')->rules(['required', 'string']),
            ImportColumn::make('created_at')->rules(['required', 'string']),
        ];
    }
    
    public function examples(): array
    {
        return [
            [
                'name' => 'Post 1',
                'description' => 'Description 1',
                'created_at' => '2021-01-01 00:00:00',
            ],
            [
                'name' => 'Post 2',
                'description' => 'Description 2',
                'created_at' => '2021-01-02 00:00:00',
            ],
        ];
    }

    public function handle(array $data): int
    {
        $total = 0;
        
        foreach ($data as $item) {
            Post::create($item);
            $total++;
        }
        
        return $total;
    }
}

这是如何在控制器中使用导入器的示例。

<?php

namespace Botble\Blog\Http\Controllers;

use Botble\DataSynchronize\Http\Controllers\ImportController;
use Botble\DataSynchronize\Importer\Importer;

class ImportPostController extends ImportController
{
    protected function getImporter(): Importer
    {
        return PostImporter::make();
    }
}

然后，在您的路由文件中注册路由。

use Botble\Base\Facades\AdminHelper;

AdminHelper::registerRoutes(function () {
    Route::prefix('tools/data-synchronize')->name('tools.data-synchronize.')->group(function () {
        Route::group(['prefix' => 'import/posts', 'as' => 'import.posts.', 'permission' => 'posts.import'], function () {
            Route::get('/', [ImportPostController::class, 'index'])->name('index');
            Route::post('', [ImportPostController::class, 'store'])->name('store');
            Route::post('validate', [ImportPostController::class, 'validateData'])->name('validate');
            Route::get('download-example', [ImportPostController::class, 'downloadExample'])->name('download-example');
        });
    });
});

每个导入器路由都应该有一个访问权限。您可以使用路由组中的 permission 键来定义权限。

在上面的路由定义中，权限是 posts.import 键，其父级是 tools.data-synchronize。您可以在您的插件中的 permissions.php 中定义权限。

return [
    [
        'name' => 'Import Posts',
        'flag' => 'posts.import',
        'parent_flag' => 'tools.data-synchronize',
    ],
];

现在，您可以通过 http://your-domain/tools/data-synchronize/import/posts 导入帖子。

将导入器添加到导出/导入数据面板部分

要将导入器添加到导出/导入数据面板部分，您可以使用 PanelSectionManager 类的 beforeRendering 方法将导入器注册到面板部分。

use Botble\Base\Facades\PanelSectionManager;
use Botble\Base\PanelSections\PanelSectionItem;
use Botble\DataSynchronize\PanelSections\ImportPanelSection;

public function boot(): void
{
    // ...

    PanelSectionManager::setGroupId('data-synchronize')->beforeRendering(function () {
        PanelSectionManager::default()
            ->registerItem(
                ImportPanelSection::class,
                fn () => PanelSectionItem::make('posts')
                    ->setTitle('Posts')
                    ->withDescription('Import post data from CSV or Excel file.')
                    ->withPriority(120)
                    ->withRoute('tools.data-synchronize.import.posts.index')
                    ->withPermission('posts.import')
            );
    });
    
    // ...
}

您可以在 导出/导入数据 面板部分看到导入器。

通过命令行导入/导出数据