Laravel Excel 套件筆記（Maatwebsite/Excel）

📦 套件簡介

Laravel Excel 提供導入與導出 Excel 的強大功能，底層使用 PhpSpreadsheet。主要功能包含：

  1. 匯入／匯出 Excel（支援 XLS, XLSX, CSV, PDF）
  2. 支援資料來源：模型、查詢、Collection、Array
  3. 支援大資料量處理
  4. 支援事件、佇列、自訂欄位、格式化、視圖匯出等功能
  5. 支援 Laravel 的佇列與排程

🔧 安裝與設定

安裝套件

composer require maatwebsite/excel

註冊 ServiceProvider（Laravel 5.x 可選）

// config/app.php

'providers' => [
    Maatwebsite\Excel\ExcelServiceProvider::class,
],

'aliases' => [
    'Excel' => Maatwebsite\Excel\Facades\Excel::class,
],

Laravel 5.5+ 支援 package auto-discovery，通常可省略手動註冊。

發佈設定檔（可選）

php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config

會產生 config/excel.php 設定檔。

📤 匯出 Excel（Export）

建立匯出類別

php artisan make:export UsersExport --model=User

UsersExport 範例

namespace App\Exports;

use App\Models\User;
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\WithHeadings;

class UsersExport implements FromCollection, WithHeadings
{
    public function collection()
    {
        return User::all();
    }

    public function headings(): array
    {
        return ['ID', '名稱', 'Email', '建立時間'];
    }
}

Controller 範例

namespace App\Http\Controllers;

use App\Exports\UsersExport;
use Maatwebsite\Excel\Facades\Excel;

class UsersController extends Controller
{
    public function export()
    {
        return Excel::download(new UsersExport, 'users.xlsx');
    }
}

路由設定

Route::get('users/export', [UsersController::class, 'export']);

📥 匯入 Excel（Import）

建立匯入類別

php artisan make:import UsersImport --model=User

UsersImport 範例

namespace App\Imports;

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

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

Controller 範例

use App\Imports\UsersImport;
use Maatwebsite\Excel\Facades\Excel;
use Illuminate\Http\Request;

class UsersController extends Controller
{
    public function import(Request $request)
    {
        $file = $request->file('excel');

        Excel::import(new UsersImport, $file);

        return redirect('/')->with('success', '匯入成功！');
    }
}

路由設定

Route::post('users/import', [UsersController::class, 'import']);

🧩 Laravel Admin 的 Grid 匯出

內建 CSV 匯出功能

$grid->export(function ($export) {
    $export->filename('users.csv');
    $export->except(['password']);
    $export->only(['id', 'name', 'email']);
    $export->originalValue(['status']);
    $export->column('status', function ($value, $original) {
        return $value == 1 ? '啟用' : '停用';
    });
});

自訂 Excel 匯出類別

建立自訂類別

namespace App\Admin\Extensions;

use Encore\Admin\Grid\Exporters\ExcelExporter;

class PostsExporter extends ExcelExporter
{
    protected $fileName = '文章列表.xlsx';

    protected $columns = [
        'id'      => 'ID',
        'title'   => '標題',
        'content' => '內容',
    ];
}

使用自訂匯出器

use App\Admin\Extensions\PostsExporter;

$grid->exporter(new PostsExporter());

進階數據格式化（WithMapping）

namespace App\Admin\Extensions\Export;

use Encore\Admin\Grid\Exporters\ExcelExporter;
use Maatwebsite\Excel\Concerns\WithMapping;

class UsersExporter extends ExcelExporter implements WithMapping
{
    protected $fileName = '用戶列表.xlsx';

    protected $columns = [
        'id'               => 'ID',
        'name'             => '姓名',
        'status'           => '狀態',
        'profile.homepage' => '主頁',
    ];

    public function map($user): array
    {
        return [
            $user->id,
            $user->name,
            $user->status ? '啟用' : '停用',
            data_get($user, 'profile.homepage'),
        ];
    }
}

📚 參考資源