Laravel Excel

https://docs.laravel-excel.com
Admin
Laravel Excel is a package for Laravel that allows you to import and export Excel files with ease.
Tokens:42,700
Snippets:610
Trust Score:8.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Implement WithCustomStartCell

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Use the WithCustomStartCell concern to define a starting cell other than A1. This is only supported for FromCollection exports.

```php
use Maatwebsite\\\Excel\\\Concerns\\\WithCustomStartCell;

class UsersExport implements FromCollection, WithCustomStartCell
{
    public function startCell(): string
    {
        return 'B2';
    }
}
```

--------------------------------

### Defining Columns with Column::make

Source: https://docs.laravel-excel.com/4.x/exports/columns.html

Example showing how to define columns using the Column class, where each instance represents a vertical series of cells in the spreadsheet.

```php
use Maatwebsite\\\Excel\\\Columns\\\Column;

[
    Column::make('Name'),  // A
    Column::make('Email'), // B
]
```

--------------------------------

### Implement WithExportTemplate for basic usage

Source: https://docs.laravel-excel.com/4.x/exports/template.html

Implement the WithExportTemplate concern and define the exportTemplate method to return the absolute path to your template file. This example also uses WithCustomStartCell to specify where data injection begins.

```php
namespace App
aye

use Maatwebsite\Excel\Concerns\Exportable;
use Maatwebsite\Excel\Concerns\FromArray;
use Maatwebsite\Excel\Concerns\WithCustomStartCell;
use Maatwebsite\Excel\Concerns\WithExportTemplate;

class ReportExport implements FromArray, WithCustomStartCell, WithExportTemplate
{
    use Exportable;

    public function array(): array
    {
        return [
            ['Patrick', 'Brouwers'],
            ['Taylor', 'Otwell'],
        ];
    }

    public function startCell(): string
    {
        return 'A3';
    }

    public function exportTemplate(): string
    {
        return storage_path('templates/report.xlsx');
    }
}
```

--------------------------------

### Install Laravel Excel via Composer

Source: https://docs.laravel-excel.com/4.x/getting-started/installation.html

Run this command in your Laravel project root to download the package and its dependency, PhpSpreadsheet.

```bash
composer require maatwebsite/excel
```

--------------------------------

### Invoking Export in Controller

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Example of triggering the download of an export class with constructor arguments from a controller.

```php
return Excel::download(new UsersExport('NL'));
```

--------------------------------

### Implement ToModel for row mapping

Source: https://docs.laravel-excel.com/4.x/imports/basics.html

The ToModel concern allows mapping each row of an Excel file to a model instance. This example demonstrates creating a User model from row data.

```php
<?php

namespace App\Imports;

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

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

--------------------------------

### Individual Sheet Export Class

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

An example of a sheet export class implementing WithTitle to define the sheet name.

```php
namespace App\Exports\Sheets;

use Maatwebsite\Excel\Concerns\WithTitle;

class AdminsSheet implements FromCollection, WithTitle
{
    public function collection(): Collection
    {
        return User::where('is_admin', true)->get();
    }

    public function title(): string
    {
        return 'Admins';
    }
}
```

--------------------------------

### Implementing WithValidation in an Import Class

Source: https://docs.laravel-excel.com/4.x/imports/validation.html

This example demonstrates how to implement the WithValidation concern in a class that also uses ToModel. It shows the use of Laravel validation rules, including Rule::in and custom callback validation.

```php
<?php

namespace App\
Imports;

use App\User;
use Illuminate\Validation\Rule;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\Importable;
use Maatwebsite\Excel\Concerns\WithValidation;

class UsersImport implements ToModel, WithValidation
{
    use Importable;

    public function model(array $row)
    {
        return new User([
            'name'     => $row[0],
            'email'    => $row[1],
            'password' => 'secret',
        ]);
    }

    public function rules(): array
    {
        return [
            '1' => Rule::in(['patrick@maatwebsite.nl']),

             // Above is alias for as it always validates in batches
             '*.1' => Rule::in(['patrick@maatwebsite.nl']),
             
             // Can also use callback validation rules
             '0' => function($attribute, $value, $onFailure) {
                  if ($value !== 'Patrick Brouwers') {
                       $onFailure('Name is not Patrick Brouwers');
                  }
              }
        ];
    }
}
```

--------------------------------

### Exporting data using FromQuery

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Use the FromQuery concern for large datasets to execute queries in chunks, preventing memory issues. Do not call ->get() on the query.

```php
namespace App\Exports;

use App\Invoice;
use Maatwebsite\Excel\Concerns\FromQuery;
use Maatwebsite\Excel\Concerns\Exportable;

class InvoicesExport implements FromQuery
{
    use Exportable;

    public function query(): Builder
    {
        return Invoice::query();
    }
}
```

--------------------------------

### Publish configuration file

Source: https://docs.laravel-excel.com/4.x/getting-started/installation.html

Run this artisan command to generate the config/excel.php configuration file.

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

--------------------------------

### Download Spreadsheet via Facade

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Directly download a spreadsheet after creation. This is recommended for small exports and must be returned to the controller or route.

```php
return Excel::download(new UsersExport, 'users.xlsx');
```

--------------------------------

### Queue import using UsersImport instance

Source: https://docs.laravel-excel.com/4.x/imports/importables.html

Queue the import process using the instance method.

```php
(new UsersImport)->queue('users.xlsx');
```

--------------------------------

### Get Raw Export Contents

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Retrieve the raw contents of an exported file, useful for API responses or mail attachments.

```php
$contents = Excel::raw(new UsersExport, 'users.xlsx');
```

--------------------------------

### Exporting with FromScout

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Use the FromScout concern to export data based on a Laravel Scout query. This requires the laravel/scout package to be installed.

```php
namespace App\Exports;

use Maatwebsite\Excel\Concerns\Exportable;
use Maatwebsite\Excel\Concerns\FromScout;

class ProductsExport implements FromScout
{
    use Exportable;

    public function scout(): \Laravel\Scout\Builder
    {
        return Product::search('*');
    }
}
```

--------------------------------

### Invoking export with constructor parameters

Source: https://docs.laravel-excel.com/4.x/architecture/objects

Shows how to instantiate the UsersExport class with a specific year and trigger the download.

```php
Excel::download(new UsersExport(2019), 'users.xlsx');
```

--------------------------------

### Extend Sheet with custom macro

Source: https://docs.laravel-excel.com/4.x/imports/extending.html

Adds a custom setOrientation macro to the Sheet class to configure page setup via PhpSpreadsheet.

```php
use \Maatwebsite\Excel\Sheet;

Sheet::macro('setOrientation', function (Sheet $sheet, $orientation) {
    $sheet->getDelegate()->getPageSetup()->setOrientation($orientation);
});
```

--------------------------------

### Manual Import Class Implementation

Source: https://docs.laravel-excel.com/4.x/imports

Implement the `ToModel` concern to define how each row of the Excel file should be converted into a model. Ensure all necessary facades and classes are imported.

```php
<?php

namespace App\Imports;

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

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

--------------------------------

### Import using a full file path

Source: https://docs.laravel-excel.com/4.x/imports/basics.html

Provide a direct file path to the import method to process files without moving them to a configured disk.

```php
Excel::import(new UsersImport, storage_path('users.xlsx'));
```

--------------------------------

### Registering Events with WithEvents

Source: https://docs.laravel-excel.com/4.x/architecture/objects

Implement the WithEvents concern to register event listeners within an export object. This example uses a closure to handle the BeforeExport event.

```php
namespace App\Exports;

use Maatwebsite\Excel\Concerns\WithEvents;
use Maatwebsite\Excel\Events\BeforeExport;

class UsersExport implements WithEvents
{
    public function registerEvents(): array
    {
        return [
            // Handle by a closure.
            BeforeExport::class => function(BeforeExport $event) {
                // Do something before the export process starts.
            },
        ];
    }
}
```

--------------------------------

### Select sheets by worksheet index

Source: https://docs.laravel-excel.com/4.x/imports/multiple-sheets.html

Use the sheet index as a key in the sheets() array to map specific sheets to import objects, starting from index 0.

```php
namespace App\Imports;

use Maatwebsite\Excel\Concerns\Import;
use Maatwebsite\Excel\Concerns\WithMultipleSheets;

class UsersImport implements Import, WithMultipleSheets 
{
   
    public function sheets(): array
    {
        return [
            0 => new FirstSheetImport(),
            1 => new SecondSheetImport(),
        ];
    }
}
```

--------------------------------

### Implement WithBatchInserts for optimized imports

Source: https://docs.laravel-excel.com/4.x/imports/batch-inserts.html

Use the WithBatchInserts concern alongside ToModel to group multiple model insertions into a single database query. The batchSize method defines the number of models to insert at once.

```php
namespace App\Imports;

use App\User;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithBatchInserts;

class UsersImport implements ToModel, WithBatchInserts
{
    public function model(array $row): User
    {
        return new User([
            'name' => $row[0],
        ]);
    }
    
    public function batchSize(): int
    {
        return 1000;
    }
}
```

--------------------------------

### Import from default disk

Source: https://docs.laravel-excel.com/4.x/imports/basics.html

Use Excel::import to process a file located on the default filesystem disk defined in config/filesystems.php.

```php
Excel::import(new UsersImport, 'users.xlsx');
```

--------------------------------

### Exporting data using FromView

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Use the FromView concern to generate an Excel spreadsheet from a Blade view. This example shows the export class and the corresponding Blade template.

```php
namespace App\Exports;

use App\User;
use Illuminate\Contracts\View\View;
use Maatwebsite\Excel\Concerns\FromView;

class UsersExport implements FromView
{
    public function view(): View
    {
        return view('exports.users', [
            'users' => User::all()
        ]);
    }
}
```

```html
<table>
    <thead>
    <tr>
        <th>Name</th>
        <th>Email</th>
    </tr>
    </thead>
    <tbody>
    @foreach($users as $user)
    <tr>
        <td>{{ $user->name }}</td>
        <td>{{ $user->email }}</td>
    </tr>
    @endforeach
    </tbody>
</table>
```

--------------------------------

### Global Event Listener Configuration

Source: https://docs.laravel-excel.com/4.x/architecture/objects

Configure event listeners globally using Writer::listen to apply logic to any export process.

```php
Writer::listen(BeforeExport::class, function () {
    // Do something before any export process starts.
});
```

--------------------------------

### Manual directory structure for Exports

Source: https://docs.laravel-excel.com/4.x/exports

Shows the expected file location for the UsersExport class within the app/Exports directory.

```text
.
├── app
│   ├── Exports
│   │   ├── UsersExport.php
│
└── composer.json
```

--------------------------------

### Passing Data to Export via Constructor

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Shows how to use a constructor to pass dynamic data to an export class for use in the collection query.

```php
class UsersExport implements FromCollection
{
    public function __construct(
        public string $country
    ) {
    }

    public function collection(): Collection
    {
        return User::query()
            ->join('orders', 'users.id', '=', 'orders.user_id')
            ->select('users.name', 'users.country', 'orders.price')
            ->where('users.country', $this->country)
            ->get();
    }
}
```

--------------------------------

### Combine Chunk Reading with Batch Inserts

Source: https://docs.laravel-excel.com/4.x/imports/chunk-reading.html

Combine WithChunkReading and WithBatchInserts for optimal time and memory consumption during imports.

```php
namespace App\Imports;

use App\User;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithBatchInserts;
use Maatwebsite\Excel\Concerns\WithChunkReading;

class UsersImport implements ToModel, WithBatchInserts, WithChunkReading
{
    public function model(array $row)
    {
        return new User([
            'name' => $row[0],
        ]);
    }
    
    public function batchSize(): int
    {
        return 1000;
    }
    
    public function chunkSize(): int
    {
        return 1000;
    }
}
```

--------------------------------

### Migrate FromQuery to FromScout for Scout integration

Source: https://docs.laravel-excel.com/4.x/getting-started/upgrade.html

FromQuery no longer supports Scout Builder instances. Use the FromScout interface and the scout() method instead.

```php
// Before (3.1)
use Maatwebsite\
Excel\\Concerns\\FromQuery;

class ProductsExport implements FromQuery
{
    public function query(): Builder
    {
        return Product::search('*');
    }
}

// After (4.0)
use Maatwebsite\\Excel\\Concerns\\FromScout;

class ProductsExport implements FromScout
{
    public function scout(): \\Laravel\\Scout\\Builder
    {
        return Product::search('*');
    }
}
```

--------------------------------

### Inject the Excel manager via constructor or method

Source: https://docs.laravel-excel.com/4.x/architecture

Demonstrates how to use dependency injection to access the Maatwebsite\Excel\Excel manager class in a controller.

```php
<?php
use App\Exports\UsersExport;
use Maatwebsite\Excel\Excel;

class ExportController
{
    private $excel;

    public function __construct(Excel $excel)
    {
        $this->excel = $excel;
    }
    
    public function exportViaConstructorInjection()
    {
        return $this->excel->download(new UsersExport, 'users.xlsx');
    }
    
    public function exportViaMethodInjection(Excel $excel)
    {
        return $excel->download(new UsersExport, 'users.xlsx');
    }
}
```

--------------------------------

### Basic import with WithColumns

Source: https://docs.laravel-excel.com/4.x/exports/columns.html

Implement WithColumns in your import class to define columns and handle automatic type casting for row data.

```php
use Maatwebsite\Excel\Concerns\Importable;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithColumns;
use Maatwebsite\Excel\Columns\Date;
use Maatwebsite\Excel\Columns\Number;
use Maatwebsite\Excel\Columns\Text;

class UsersImport implements ToModel, WithColumns
{
    use Importable;

    public function model(array $row): User
    {
        return new User([
            'name'  => $row['name'],
            'email' => $row['email'],
            'dob'   => $row['date_of_birth'], // cast to Carbon
        ]);
    }

    public function columns(): array
    {
        return [
            Text::make('name'),
            Text::make('email'),
            Date::make('Date of Birth', 'date_of_birth'),
            Number::make('id'),
        ];
    }
}
```

--------------------------------

### Apply column styles with Fluent syntax

Source: https://docs.laravel-excel.com/4.x/exports/presentation.html

Use fluent methods to apply styles to columns.

```php
Text::make('Name')
    ->font('Calibri', 16.0)
    ->textSize(16.0)
    ->bold()
    ->italic();
```

--------------------------------

### Invoking export with setter methods

Source: https://docs.laravel-excel.com/4.x/architecture/objects

Demonstrates configuring the export object using a setter before passing it to the Excel download method.

```php
$export = new UsersExport();
$export->setYear(2019);

Excel::download($export, 'users.xlsx');
```

--------------------------------

### Configure Default Value Binder

Source: https://docs.laravel-excel.com/4.x/exports/presentation.html

Set a global value binder for all exports by updating the configuration file.

```php
'value_binder' => [
    'default' => Maatwebsite\Excel\DefaultValueBinder::class,
],
```

--------------------------------

### Import from a specific disk

Source: https://docs.laravel-excel.com/4.x/imports/basics.html

Specify a custom disk, such as Amazon S3, by passing it as the third parameter to the import method.

```php
Excel::import(new UsersImport, 'users.xlsx', 's3');
```

--------------------------------

### Create UsersImport class implementing ToCollection

Source: https://docs.laravel-excel.com/4.x/imports/collection.html

Create a class in app/Imports that implements the ToCollection concern to iterate over rows and create User models.

```php
namespace App\Imports;

use App\User;
use Illuminate\Support\Collection;
use Maatwebsite\Excel\Concerns\ToCollection;

class UsersImport implements ToCollection
{
    public function collection(Collection $rows): void
    {
        foreach ($rows as $row) 
        {
            User::create([
                'name' => $row[0],
            ]);
        }
    }
}
```

--------------------------------

### BeforeWriting Event

Source: https://docs.laravel-excel.com/4.x/exports/events.html

Fires after the spreadsheet is set up but before chunk/data writing begins.

```APIDOC
## BeforeWriting

### Description
Fires after the spreadsheet is set up but before chunk/data writing begins. Use it for any last-minute configuration.

### Delegate
$event->writer : Writer
```

--------------------------------

### Handle import failures with events

Source: https://docs.laravel-excel.com/4.x/imports/queued.html

Implement the WithEvents concern and register the ImportFailed event to handle failures during queued imports.

```php
namespace App\Imports;

use App\User;
use App\Notifications\ImportHasFailedNotification;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithEvents;
use Maatwebsite\Excel\Events\ImportFailed;
use Illuminate\Contracts\Queue\ShouldQueue;
use Maatwebsite\Excel\Concerns\WithChunkReading;

class UsersImport implements ToModel, WithChunkReading, ShouldQueue, WithEvents
{
    public function __construct(User $importedBy)
    {
        $this->importedBy = $importedBy;
    }

    public function registerEvents(): array
    {
        return [
            ImportFailed::class => function(ImportFailed $event) {
                $this->importedBy->notify(new ImportHasFailedNotification);
            },
        ];
    }
}
```

--------------------------------

### Implement WithProgressBar in Import Class

Source: https://docs.laravel-excel.com/4.x/imports/progress-bar.html

Add the WithProgressBar concern to your import class to enable progress bar functionality.

```php
<?php

namespace App\Imports;

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

class UsersImport implements ToModel, WithProgressBar
{
    use Importable;

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

--------------------------------

### Tracking state with getters in UsersImport

Source: https://docs.laravel-excel.com/4.x/architecture/objects

Shows how to maintain internal state, such as a row count, within an import class and expose it via a getter method.

```php
namespace App\Imports;

use App\User;
use Maatwebsite\Excel\Concerns\ToModel;

class UsersImport implements ToModel
{
    private $rows = 0;

    public function model(array $row)
    {
        ++$this->rows;
    
        return new User([
            'name' => $row[0],
        ]);
    }
    
    public function getRowCount(): int
    {
        return $this->rows;
    }
}
```

--------------------------------

### Implementing ShouldBatch for queued imports

Source: https://docs.laravel-excel.com/4.x/imports/queued.html

Implement the ShouldBatch marker interface alongside ShouldQueue and WithChunkReading to dispatch chunked imports as a Laravel job batch.

```php
use Maatwebsite\\\Excel\\\Concerns\\\Importable;
use Maatwebsite\\\Excel\\\Concerns\\\ToModel;
use Maatwebsite\\\Excel\\\Concerns\\\WithChunkReading;
use Maatwebsite\\\Excel\\\Concerns\\\ShouldBatch;
use Illuminate\\\Contracts\\\Queue\\\ShouldQueue;

class UsersImport implements ToModel, WithChunkReading, ShouldQueue, ShouldBatch
{
    use Importable;

    public function model(array $row): User|null
    {
        return new User(['name' => $row[0]]);
    }

    public function chunkSize(): int
    {
        return 1000;
    }
}
```

--------------------------------

### Testing queued imports with Excel::assertQueued()

Source: https://docs.laravel-excel.com/4.x/imports/testing.html

Verify that imports are queued correctly using the Excel::assertQueued method.

```php
/**
* @test
*/
public function user_can_queue_the_users_import() 
{
    Excel::fake();

    $this->actingAs($this->givenUser())
         ->get('/users/queue/xlsx');

    Excel::assertQueued('filename.xlsx', 'diskName');
    
    Excel::assertQueued('filename.xlsx', 'diskName', function(UsersImport $import) {
        return true;
    });
    
    // When passing the callback as 2nd param, the disk will be the default disk.
    Excel::assertQueued('filename.xlsx', function(UsersImport $import) {
        return true;
    });
}
```

--------------------------------

### Export Using Responsable Interface

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Implement the Responsable interface to allow returning the export class directly from a controller, which automatically triggers the download.

```php
namespace App\Exports;

use App\User;
use Maatwebsite\Excel\Excel;
use Illuminate\Contracts\Support\Responsable;
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\Exportable;

class UsersExport implements FromCollection, Responsable
{
    use Exportable;
    
    /**
    * It's required to define the fileName within
    * the export class when making use of Responsable.
    */
    private $fileName = 'users.xlsx';
    
    /**
    * Optional Writer Type
    */
    private $writerType = Excel::XLSX;
    
    /**
    * Optional headers
    */
    private $headers = [
        'Content-Type' => 'text/csv',
    ];

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

```php
return new UsersExport();
```

--------------------------------

### Testing imports with dynamic file names using regex

Source: https://docs.laravel-excel.com/4.x/imports/testing.html

Enable regex matching for dynamic file names using Excel::matchByRegex() and verify with a regular expression.

```php
/**
* @test
*/
public function user_can_import_users() 
{
    Excel::fake();
    
    $this->actingAs($this->givenUser())
         ->get('/users/import/xlsx');
    
    // Tells the mock to use regular expressions
    Excel::matchByRegex(); 
    // For a given dynamic named file 'dynamic_1234_filename.xlsx'
    Excel::assertImported('/\w{7}_\d{4}\_\w{8}\.xlsx/', 'diskName');
}
```

--------------------------------

### Import file using UsersImport instance

Source: https://docs.laravel-excel.com/4.x/imports/importables.html

Perform an import directly from the class instance without using the Excel facade.

```php
(new UsersImport)->import('users.xlsx', 'local', \Maatwebsite\Excel\Excel::XLSX);
```

--------------------------------

### Trigger export download in routes

Source: https://docs.laravel-excel.com/4.x/exports

Use Excel::download to initiate a file download of the UsersExport object within a web route.

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

--------------------------------

### Implement WithCustomCsvSettings interface

Source: https://docs.laravel-excel.com/4.x/imports/custom-csv-settings.html

Add the WithCustomCsvSettings interface to your import class and define the getCsvSettings method to override CSV configuration, such as input_encoding.

```php
namespace App\Imports;

use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;

class UsersImport implements ToModel, WithCustomCsvSettings
{
    public function model(array $row): User|null
    {
        return new User([
            'name' => $row['0'],
            'email' => $row['1']
        ]);
    }
    
    public function getCsvSettings(): array
    {
        return [
            'input_encoding' => 'ISO-8859-1'
        ];
    }
}
```

--------------------------------

### Load import to array

Source: https://docs.laravel-excel.com/4.x/imports/importables.html

Load the contents of an import directly into an array.

```php
$array = (new UsersImport)->toArray('users.xlsx');
```

--------------------------------

### Testing Excel downloads

Source: https://docs.laravel-excel.com/4.x/exports/testing.html

Use Excel::assertDownloaded to verify that a file was downloaded and optionally inspect the export object.

```php
public function test_user_can_download_invoices_export()
{
    Excel::fake();

    $this->actingAs($this->givenUser())
         ->get('/invoices/download/xlsx');

    Excel::assertDownloaded('filename.xlsx', function(InvoicesExport $export) {
        // Assert that the correct export is downloaded.
        return $export->collection()->contains('#2018-01');
    });
}
```

--------------------------------

### Download an export using the Exportable trait

Source: https://docs.laravel-excel.com/4.x/architecture

Directly trigger a download from an export object that uses the Exportable trait.

```php
return (new UsersExport)->download('users.xlsx');
```

--------------------------------

### Export Eloquent Queries via Macros

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Use macros on the Eloquent Builder to download or store query results directly, with options for headers and disk selection.

```php
User::query()->where('name', 'Patrick')->downloadExcel('query-download.xlsx');
```

```php
User::query()->where('name', 'Patrick')->downloadExcel('query-download.xlsx', Excel::XLSX, true);
```

```php
User::query()->where('name', 'Patrick')->storeExcel('query-store.xlsx', 'your-disk');
```

--------------------------------

### Generate Import Class with Artisan

Source: https://docs.laravel-excel.com/4.x/imports

Use the `make:import` Artisan command to scaffold a new import class. This command requires the import class name and optionally a model name.

```bash
php artisan make:import UsersImport --model=User
```

--------------------------------

### Testing imports with Excel::fake()

Source: https://docs.laravel-excel.com/4.x/imports/testing.html

Use Excel::fake() to swap the importer and verify imports using Excel::assertImported with optional callbacks.

```php
/**
* @test
*/
public function user_can_import_users() 
{
    Excel::fake();
    
    $this->actingAs($this->givenUser())
         ->get('/users/import/xlsx');

    Excel::assertImported('filename.xlsx', 'diskName');
    
    Excel::assertImported('filename.xlsx', 'diskName', function(UsersImport $import) {
        return true;
    });
    
    // When passing the callback as 2nd param, the disk will be the default disk.
    Excel::assertImported('filename.xlsx', function(UsersImport $import) {
        return true;
    });
}
```

--------------------------------

### Implement ShouldBatch for job batching

Source: https://docs.laravel-excel.com/4.x/exports/performance.html

Implement the ShouldBatch interface to allow exports to be dispatched as a Laravel job batch.

```php
use Maatwebsite\Excel\Concerns\Exportable;
use Maatwebsite\Excel\Concerns\FromQuery;
use Maatwebsite\Excel\Concerns\ShouldBatch;
use Illuminate\Contracts\Queue\ShouldQueue;

class UsersExport implements FromQuery, ShouldQueue, ShouldBatch
{
    use Exportable;

    public function query(): Builder
    {
        return User::query();
    }
}
```

--------------------------------

### Implement WithStrictNullComparison

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Use the WithStrictNullComparison concern to ensure 0 values are exported as 0 instead of empty cells.

```php
use Maatwebsite\\\Excel\\\Concerns\\\WithStrictNullComparison;

class UsersExport implements FromCollection, WithStrictNullComparison
```

--------------------------------

### Configure imports.cells.middleware

Source: https://docs.laravel-excel.com/4.x/getting-started/configuration.html

An array of middleware classes executed on each cell value as it is read. Includes built-in options for trimming values and converting empty cells to null.

```php
'middleware' => [
    \Maatwebsite\Excel\Middleware\TrimCellValue::class,
    \Maatwebsite\Excel\Middleware\ConvertEmptyCellValuesToNull::class,
],
```

--------------------------------

### Register Excel Facade manually

Source: https://docs.laravel-excel.com/4.x/getting-started/installation.html

Add the Excel facade to the aliases array in config/app.php if you choose to disable auto-discovery.

```php
'aliases' => [
    ...
    'Excel' => Maatwebsite
Excel
Facades
Excel::class,
]
```

--------------------------------

### Generate UsersExport class via Artisan

Source: https://docs.laravel-excel.com/4.x/exports

Use the make:export command to scaffold a new export class for the User model.

```bash
php artisan make:export UsersExport --model=User
```

--------------------------------

### Configuring Source Handlers in config/excel.php

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Alternatively, register handler class names in the exports.source_handlers configuration array.

```php
'exports' => [
    'source_handlers' => [
        App\Exports\Handlers\ApiSourceHandler::class,
    ],
],
```

--------------------------------

### Download export with extension-based writer detection

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Detects the writer type automatically based on the provided file extension.

```php
Excel::download(new UsersExport, 'users.xls');
```

--------------------------------

### Chain jobs to a queued import

Source: https://docs.laravel-excel.com/4.x/imports/queued.html

Use the chain method on the PendingDispatch instance returned by queue to execute jobs after the import completes.

```php
(new UsersImport)->queue('users.xlsx')->chain([
    new NotifyUserOfCompletedImport(request()->user()),
]);
```

--------------------------------

### Use Export and Import marker interfaces for type hinting

Source: https://docs.laravel-excel.com/4.x/getting-started/upgrade.html

The new Export and Import marker interfaces can be used as type hints instead of the generic object type.

```php
use Maatwebsite\\Excel\\Concerns\\Export;

public function handle(Export $export): void { ... }
```

--------------------------------

### Explicitly queue an import

Source: https://docs.laravel-excel.com/4.x/imports/queued.html

Use the queueImport method on the Excel facade to explicitly queue an import process.

```php
Excel::queueImport(new UsersImport, 'users.xlsx');
```

--------------------------------

### Load import to collection

Source: https://docs.laravel-excel.com/4.x/imports/importables.html

Load the contents of an import directly into a collection.

```php
$collection = (new UsersImport)->toCollection('users.xlsx');
```

--------------------------------

### Export via Dependency Injection

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Inject the Excel service into a controller method to perform exports.

```php
use Maatwebsite\Excel\Excel;

public function export(Excel $excel)
{
    return $excel->download(new UsersExport, 'users.xlsx');
}
```

--------------------------------

### Exporting Eloquent Collections with FromCollection

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Demonstrates implementing the FromCollection concern to export Eloquent models. You can return all models or a filtered query result.

```php
namespace App\Exports;

use App\Invoice;
use Maatwebsite\Excel\Concerns\FromCollection;

class UsersExport implements FromCollection
{
    public function collection(): Collection
    {
        // All User models.
        return User::all();
        
        // Query some User models.
        return User::query()->select('')->where('country', 'NL')->get();
    }
}
```

--------------------------------

### Configure exports.properties

Source: https://docs.laravel-excel.com/4.x/getting-started/configuration.html

Defines default document properties written to every export. These can be overridden per-export using the WithProperties concern.

```php
'properties' => [
    'creator'        => '',
    'lastModifiedBy' => '',
    'title'          => '',
    'description'    => '',
    'subject'        => '',
    'keywords'       => '',
    'category'       => '',
    'manager'        => '',
    'company'        => '',
],
```

--------------------------------

### Set custom formatter in service provider

Source: https://docs.laravel-excel.com/4.x/imports/heading-row.html

Apply the custom formatter globally via a service provider.

```php
HeadingRowFormatter::default('custom');
```

--------------------------------

### Configure temporary_files.local_permissions

Source: https://docs.laravel-excel.com/4.x/getting-started/configuration.html

Sets the directory and file permissions for the temporary storage location used by Laravel Excel.

```php
'local_permissions' => [
    'dir'  => 0755,
    'file' => 0644,
],
```

--------------------------------

### Execute import with Importable trait

Source: https://docs.laravel-excel.com/4.x/architecture

Perform an import directly using the Import object without needing the facade or Excel manager.

```php
(new UsersImport)->import('users.xlsx');
```

--------------------------------

### Grouping columns with Column::multiple

Source: https://docs.laravel-excel.com/4.x/exports/columns.html

Use Column::multiple to group sub-columns under a single logical key, resulting in a nested array structure during import.

```php
Column::multiple(
    Text::make('Street', 'street'),
    Text::make('City', 'city'),
    Text::make('Country', 'country'),
)->key('address');
// row['address'] => ['street' => '...', 'city' => '...', 'country' => '...']
```

--------------------------------

### Enable Auto-sizing for All Columns

Source: https://docs.laravel-excel.com/4.x/exports/presentation.html

Implement the ShouldAutoSize concern in your export class to enable automatic width calculation for all columns in the spreadsheet.

```php
namespace App\Exports;

use Maatwebsite\Excel\Concerns\ShouldAutoSize;

class UsersExport implements ShouldAutoSize
{
    ...
}
```

--------------------------------

### Import uploaded files

Source: https://docs.laravel-excel.com/4.x/imports/basics.html

Pass an uploaded file directly from a request to the import method.

```php
Excel::import(new UsersImport, request()->file('your_file'));
```

--------------------------------

### Use Price column type

Source: https://docs.laravel-excel.com/4.x/exports/columns.html

The Price column supports currency configuration via inEuros(), inDollars(), or custom currency() strings.

```php
Price::make('Order Total');
```

```php
Price::make('Order Total')->inEuros();
```

```php
Price::make('Order Total')->inDollars();
```

```php
Price::make('Order Total')->currency('#,##0_-"€"');
```

--------------------------------

### Registering event listeners with WithEvents

Source: https://docs.laravel-excel.com/4.x/exports/events.html

Implement the WithEvents concern and return a map of event classes to callables in the registerEvents method. Note that closures cannot be serialized, so use static method array-callables for queued exports.

```php
namespace App\Exports;

use Maatwebsite\Excel\Concerns\FromQuery;
use Maatwebsite\Excel\Concerns\WithEvents;
use Maatwebsite\Excel\Events\BeforeExport;
use Maatwebsite\Excel\Events\AfterSheet;

class UsersExport implements FromQuery, WithEvents
{
    public function registerEvents(): array
    {
        return [
            BeforeExport::class => function (BeforeExport $event): void {
                $event->writer->getDelegate()->getProperties()->setCreator('Laravel');
            },

            AfterSheet::class => [self::class, 'afterSheet'],
        ];
    }

    public static function afterSheet(AfterSheet $event): void
    {
        $event->sheet->getDelegate()->getStyle('A1')->getFont()->setBold(true);
    }
}
```

--------------------------------

### Testing exports with dynamic file names

Source: https://docs.laravel-excel.com/4.x/exports/testing.html

Use Excel::matchByRegex() to enable regular expression matching for dynamic file paths or names.

```php
public function test_user_can_store_invoices_export()
{
    Excel::fake();

    $this->actingAs($this->givenUser())
         ->get('/invoices/store/xlsx');

    // Tells the mock to use regular expressions
    Excel::matchByRegex();
    // For a given dynamic named file 'invoices_2019.xlsx'
    Excel::assertStored('/invoices_\d{4}\.xlsx/', 'diskName');
}
```

--------------------------------

### Implementing a Custom SheetSourceHandler

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Create a class implementing SheetSourceHandler for synchronous exports or QueuedSheetSourceHandler for queued exports to handle custom data sources.

```php
use Maatwebsite\Excel\Concerns\Export;
use Maatwebsite\Excel\Contracts\SheetSourceHandler;
use Maatwebsite\Excel\Sheet;

class ApiSourceHandler implements SheetSourceHandler
{
    public function canHandle(Export $sheetExport): bool
    {
        return $sheetExport instanceof FromApi;
    }

    public function handle(Sheet $sheet, Export $sheetExport): void
    {
        foreach ($sheetExport->fetch() as $row) {
            $sheet->append([$row]);
        }
    }
}
```

--------------------------------

### Store Spreadsheet on Disk

Source: https://docs.laravel-excel.com/4.x/exports/exporting.html

Store an export file on the default disk or a specific disk like S3, with optional visibility settings.

```php
Excel::store(new UsersExport, 'users.xlsx');
```

```php
Excel::store(new UsersExport, 'users.xlsx', 's3');
```

```php
Excel::store(new UsersExport, 'users.xlsx', 's3', null, [
    'visibility' => 'private',
]);
```

--------------------------------

### Handling PendingBatch return values

Source: https://docs.laravel-excel.com/4.x/imports/queued.html

When ShouldBatch is implemented, queue() and import() return an Illuminate\Bus\PendingBatch instance.

```php
$batch = (new UsersImport)->queue('users.xlsx')
    ->name('Users import')
    ->then(fn () => // all chunks succeeded)
    ->catch(fn () => // at least one chunk failed);

$batch->dispatch();
```

--------------------------------

### Basic Column Definition

Source: https://docs.laravel-excel.com/4.x/exports/columns.html

The Column::make method requires a title for the header and an attribute name from the model.

```php
Column::make('{Title}', '{attribute}');
```

--------------------------------

### Specify a reader type

Source: https://docs.laravel-excel.com/4.x/imports/basics.html

If the file extension does not allow for automatic detection, specify the reader type as the fourth parameter.

```php
Excel::import(new UsersImport, 'users.xlsx', 's3', \Maatwebsite\Excel\Excel::XLSX);
```

--------------------------------

### Using Array Data Sources

Source: https://docs.laravel-excel.com/4.x/exports/columns.html

Columns can be used with array data sources by referencing array keys or using a closure to process the entire row.

```php
class UsersExport implements FromArray, WithColumns
{
    public function array(): array
    {
        return [
            ['firstname' => 'Patrick', 'lastname' => 'Brouwers'],
            ['firstname' => 'Taylor', 'lastname' => 'Otwell'],
        ];
    }
    
    public function columns(): array
    {
        return [
            Text::make('First Name', 'firstname'),
            Text::make('Last Name', 'lastname'),
            Text::make('Name', function(array $row) {
                return $row['firstname'] . ' ' . $row['lastname'];
            }),
        ];
    }
}
```

--------------------------------

### Apply generic styles with WithStyles

Source: https://docs.laravel-excel.com/4.x/exports/presentation.html

Implement the WithStyles concern to style columns, cells, and rows using coordinates or column identifiers.

```php
namespace App\Exports;

use Maatwebsite\Excel\Concerns\WithStyles;
use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;

class UsersExport implements WithStyles
{
    public function styles(Worksheet $sheet): array
    {
        return [
            // Style the first row as bold text.
            1    => ['font' => ['bold' => true]],

            // Styling a specific cell by coordinate.
            'B2' => ['font' => ['italic' => true]],

            // Styling an entire column.
            'C'  => ['font' => ['size' => 16]],
        ];
    }
}
```

--------------------------------

### Define a job for import completion

Source: https://docs.laravel-excel.com/4.x/imports/queued.html

This class implements ShouldQueue and is used as a chained job to notify a user after an import finishes.

```php
namespace App\Jobs;

use App\User;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\SerializesModels;

class NotifyUserOfCompletedImport implements ShouldQueue
{
    use Queueable, SerializesModels;

    public $user;

    public function __construct(User $user)
    {
        $this->user = $user;
    }

    public function handle()
    {
        $this->user->notify(new ImportReady());
    }
}
```

--------------------------------

### Configure extension_detector

Source: https://docs.laravel-excel.com/4.x/getting-started/configuration.html

Maps file extensions to reader/writer type constants to determine the appropriate PhpSpreadsheet driver when no explicit type is provided.

```php
'extension_detector' => [
    'xlsx' => Excel::XLSX,
    'xls'  => Excel::XLS,
    'csv'  => Excel::CSV,
    'ods'  => Excel::ODS,
    // ...
    'pdf'  => Excel::DOMPDF, // default PDF driver
],
```

--------------------------------

### Import SLK File - Laravel Excel

Source: https://docs.laravel-excel.com/4.x/imports/import-formats.html

Use this to explicitly import an SLK file. Ensure the file extension matches the format specified.

```php
(new UsersImport)->import('users.slk', null, \Maatwebsite\Excel\Excel::SLK);
```

--------------------------------

### Injecting data via constructor in UsersExport

Source: https://docs.laravel-excel.com/4.x/architecture/objects

Demonstrates passing data to an export class through its constructor to filter collection results.

```php
class UsersExport implements FromCollection {
    private $year;

    public function __construct(int $year) 
    {
        $this->year = $year;
    }
    
    public function collection()
    {
        return Users::whereYear('created_at', $this->year)->get();
    }
}
```

--------------------------------

### Exporting with LazyCollection

Source: https://docs.laravel-excel.com/4.x/exports/data.html

Utilize LazyCollection for memory-efficient exports when dealing with large datasets.

```php
namespace App\Exports;

use App\Invoice;
use Maatwebsite\Excel\Concerns\FromCollection;

class InvoicesExport implements FromCollection
{
    public function collection(): LazyCollection
    {
        return Invoice::query()->lazy();
    }
}
```

--------------------------------

### Implement WithChunkReading

Source: https://docs.laravel-excel.com/4.x/imports/chunk-reading.html

Use the WithChunkReading concern to read files in chunks. The chunkSize method defines the number of rows to process at once.

```php
namespace App\Imports;

use App\User;
use Maatwebsite\Excel\Concerns\ToModel;
use Maatwebsite\Excel\Concerns\WithChunkReading;

class UsersImport implements ToModel, WithChunkReading
{
    public function model(array $row): User|null
    {
        return new User([
            'name' => $row[0],
        ]);
    }
    
    public function chunkSize(): int
    {
        return 1000;
    }
}
```
Tokens:
Raw