README

A unified API for Excel imports and exports in Laravel, supporting both Maatwebsite/Excel (rich features) and OpenSpout (high performance).

Features

• 🎯 Unified Column Definition - Define columns once using ColumnDef data objects
• 📐 Typed Cells - Real dates and numbers with Excel number formats, so files sort, filter and sum
• 🔄 Two Drivers - Choose between Maatwebsite/Excel (styling, formulas) or OpenSpout (speed, memory efficiency)
• ✅ Built-in Validation - Laravel validation rules integrated into imports
• 📊 Multi-Sheet Support - Export and import multiple sheets in a single file
• 🎨 Conditional Formatting - Color coding based on values (Maatwebsite only)
• 📦 Chunked Processing - Handle large files efficiently
• 🔧 Type Transformations - Automatic formatting for dates, booleans, amounts, etc.
• 🧾 Blade Sheets - Render a sheet from a Blade template for document-shaped output
• 🧮 Sheet Polish - Totals row, title rows, freeze panes, autofilter and autosize, all opt-in

Installation

composer require mohd-arbaaz/laravel-excel-wrapper

Then install at least one of the underlying drivers:

# For Laravel Excel (rich features, styling)
composer require maatwebsite/excel

# For OpenSpout (high performance, low memory)
composer require openspout/openspout

Publish Configuration (Optional)

php artisan vendor:publish --tag=excel-wrapper-config

Quick Start

Export Example

use ExcelWrapper\Abstracts\LaravelExcelExport;
use ExcelWrapper\Data\ColumnDef;
use Illuminate\Support\Collection;

class UsersExport extends LaravelExcelExport
{
    public function columnConfig(): Collection
    {
        return collect([
            ColumnDef::make('name', 'Full Name')->string()->width(25),
            ColumnDef::make('email', 'Email Address')->string()->width(30),
            ColumnDef::make('balance', 'Account Balance')
                ->amount()
                ->colored()
                ->summable()
                ->width(15),
            ColumnDef::make('created_at', 'Joined')
                ->date()
                ->width(15),
        ]);
    }

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

    protected function showTotals(): bool
    {
        return true;
    }

    protected function freezeHeader(): bool
    {
        return true;
    }
}

// Usage
return (new UsersExport)->download('users.xlsx');

Import Example

use ExcelWrapper\Abstracts\LaravelExcelImport;
use ExcelWrapper\Data\ColumnDef;
use Illuminate\Support\Collection;

class UsersImport extends LaravelExcelImport
{
    public function columnConfig(): Collection
    {
        return collect([
            ColumnDef::make('name', 'Name')
                ->string()
                ->rules('required|string|max:255'),
            ColumnDef::make('email', 'Email')
                ->string()
                ->alias(['E-mail', 'Email Address'])
                ->rules('required|email|unique:users,email'),
            ColumnDef::make('balance', 'Balance')
                ->amount()
                ->rules('nullable|numeric'),
        ]);
    }

    public function onRow(array $row): void
    {
        User::create($row);
    }
}

// Usage
$result = (new UsersImport)->import('users.xlsx');

if ($result->hasErrors()) {
    foreach ($result->errors as $error) {
        echo "Row {$error['row']}: {$error['field']} - {$error['messages'][0]}";
    }
}

Choosing a Driver

Use Laravel Excel when:

• You need styling, conditional formatting, or complex formulas
• File sizes are moderate (< 50k rows)
• You need Excel-specific features

Use OpenSpout when:

• Processing large files (100k+ rows)
• Memory is constrained
• You don't need advanced styling

Switching Drivers

Simply change the base class - the columnConfig() and data methods remain the same:

// Laravel Excel
use ExcelWrapper\Abstracts\LaravelExcelExport;
class UsersExport extends LaravelExcelExport { ... }

// OpenSpout
use ExcelWrapper\Abstracts\OpenSpoutExport;
class UsersExport extends OpenSpoutExport { ... }

Documentation

• Getting Started
• Column Definitions
• Formatting
• Blade Exports
• Laravel Excel Guide
• OpenSpout Guide
• Multi-Sheet Operations
• Validation

Requirements

• PHP 8.4+
• Laravel 12 or 13
• spatie/laravel-data ^4.23

Driver Requirements:

• maatwebsite/excel ^4.0 (for Laravel Excel driver)
• openspout/openspout ^5.1 (for OpenSpout driver)

Staying on Laravel 11, PHP 8.2/8.3, maatwebsite/excel 3.x or openspout 4.x? Use the 1.x branch. The floors above come from the drivers: maatwebsite/excel 4 requires Laravel 12+, and openspout 5 requires PHP 8.4+.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Upgrading

Upgrading from 1.x? See UPGRADING.md.

Contributing

Please see CONTRIBUTING.md for branch layout, test conventions and the constraint rules.

Security

If you discover a security-related issue, please email mohd.arbaz2207@gmail.com rather than opening a public issue, and allow time for a fix before disclosing it.

Credits

• Mohd Arbaaz
• All Contributors

License

The MIT License (MIT). Please see License File for more information.