Tutorial Laravel Excel: Como Importar e Exportar Dados com Facilidade

No desenvolvimento de aplicações Laravel, frequentemente precisamos lidar com planilhas — seja para exportar relatórios ou importar grandes quantidades de dados. O pacote Laravel Excel, criado pela Spartner, simplifica esse processo ao integrar o poder do PhpSpreadsheet com a elegância do Laravel. Neste tutorial, vamos explorar como instalar e usar o Laravel Excel para importar uma lista de usuários de um arquivo Excel e exportar dados do banco de dados para uma planilha. Vamos lá!

Passo 1: Instalação

Primeiro, instale o Laravel Excel via Composer:

composer require maatwebsite/excel

Se você estiver usando Laravel 12.x, o pacote será registrado automaticamente graças ao recurso de auto-descoberta. Caso contrário (em versões mais antigas), adicione o provedor de serviço ao config/app.php:

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

E, opcionalmente, publique o arquivo de configuração:

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

Passo 2: Configurando o Projeto

Para este tutorial, vamos assumir que temos uma tabela users com os campos name, email, created_at e updated_at. Certifique-se de que o modelo User está configurado e que a tabela existe no banco de dados.

Crie a migration, se necessário:

php artisan make:migration create_users_table

Edite o arquivo de migração:

Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->unique();
    $table->timestamps();
});

Execute a migração:

php artisan migrate

Passo 3: Criando uma Exportação

Vamos criar uma classe para exportar todos os usuários do banco para um arquivo Excel.

Crie a exportação com o Artisan:

php artisan make:export UsersExport --model=User

Edite o arquivo gerado em app/Exports/UsersExport.php:

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::select('name', 'email')->get();
    }

    public function headings(): array
    {
        return ['Nome', 'E-mail'];
    }
}

Aqui, definimos:

• collection(): Retorna os dados dos usuários (apenas name e email).
• headings(): Define os cabeçalhos da planilha.

Agora, crie uma rota em routes/web.php:

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

Route::get('/export-users', function () {
    return Excel::download(new UsersExport, 'usuarios.xlsx');
});

Acesse /export-users no navegador, e o arquivo usuarios.xlsx será baixado com os dados da tabela.

Passo 4: Criando uma Importação

Agora, vamos importar usuários de um arquivo Excel para o banco de dados.

Crie a classe de importação:

php artisan make:import UsersImport --model=User

Edite o arquivo em app/Imports/UsersImport.php:

namespace App\Imports;

use App\Models\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['nome'],
            'email' => $row['email'],
            'created_at' => now(),
            'updated_at' => now(),
        ]);
    }
}

• ToModel: Mapeia cada linha do Excel para um modelo User.
• WithHeadingRow: Indica que o arquivo tem uma linha de cabeçalho (ex.: "Nome", "E-mail"), que será usada como chave no array $row.

Crie uma rota para importar:

use App\Imports\UsersImport;
use Maatwebsite\Excel\Facades\Excel;

Route::post('/import-users', function () {
    Excel::import(new UsersImport, request()->file('file'));
    return redirect()->back()->with('success', 'Usuários importados com sucesso!');
});

E um formulário simples em uma view (ex.: resources/views/import.blade.php):

<form method="POST" action="/import-users" enctype="multipart/form-data">
    @csrf
    <input type="file" name="file" accept=".xlsx, .xls">
    <button type="submit">Importar</button>
    @if (session('success'))
        <p>{{ session('success') }}</p>
    @endif
</form>

Prepare um arquivo Excel com colunas "Nome" e "E-mail", envie-o pelo formulário, e os dados serão inseridos no banco.

Passo 5: Otimizando para Arquivos Grandes

Para arquivos grandes, use o recurso de "chunking" para reduzir o uso de memória. Atualize o UsersImport.php:

use Maatwebsite\Excel\Concerns\WithChunkReading;

class UsersImport implements ToModel, WithHeadingRow, WithChunkReading
{
    public function model(array $row)
    {
        return new User([
            'name' => $row['nome'],
            'email' => $row['email'],
            'created_at' => now(),
            'updated_at' => now(),
        ]);
    }

    public function chunkSize(): int
    {
        return 1000; // Processa 1000 linhas por vez
    }
}

Isso faz com que o Laravel Excel leia o arquivo em blocos, evitando problemas de desempenho.

Conclusão

O Laravel Excel é uma ferramenta indispensável para quem precisa manipular planilhas no Laravel. Com poucos passos, você pode exportar relatórios e importar dados de forma eficiente, mesmo em cenários com grandes volumes de informação. Experimente personalizar as exportações com estilos ou integrar com filas (queues) para processos assíncronos. Agora que você conhece o básico, que tal aplicar isso ao seu próximo projeto?