## 1. Project Overview & Quickstart (SpartnerNL/Laravel-Excel)
## 1. Project Overview & Quickstart (SpartnerNL/Laravel-Excel)
## 1. Project Overview & Quickstart (SpartnerNL/Laravel-Excel)
# Technical Documentation: SpartnerNL/Laravel-Excel
> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/SpartnerNL/Laravel-Excel)
### Overview (`README.md`)
Supercharged Excel exports and imports
A simple, but elegant Laravel wrapper around PhpSpreadsheet
exports and imports.
## ✨ Features
- **Easily export collections to Excel.** Supercharge your Laravel collections and export them directly to an Excel or CSV document. Exporting has never been so easy.
- **Supercharged exports.** Export queries with automatic chunking for better performance. You provide us the query, we handle the performance. Exporting even larger datasets? No worries, Laravel Excel has your back. You can queue your exports so all of this happens in the background.
- **Supercharged imports.** Import workbooks and worksheets to Eloquent models with chunk reading and batch inserts! Have large files? You can queue every chunk of a file! Your entire import will happen in the background.
- **Export Blade views.** Want to have a custom layout in your spreadsheet? Use a HTML table in a Blade view and export that to Excel.
## 🎓 Learning Laravel Excel
You can find the full documentation of Laravel Excel [on the website](https://docs.laravel-excel.com).
We welcome suggestions for improving our docs. The documentation repository can be found at [https://github.com/SpartnerNL/laravel-excel-docs](https://github.com/SpartnerNL/laravel-excel-docs).
Some articles and tutorials can be found on our blog: https://medium.com/maatwebsite/laravel-excel/home
## :mailbox_with_mail: License & Postcardware
Laravel Excel is created with love and care by Spartner (formerly known as Maatwebsite) to give back to the Laravel community. It is completely free (MIT license) to use, however the package is licensed as Postcardware. This means that if it makes it to your production environment, we would very much appreciate receiving a postcard from your hometown.
**Spartner**
Markt 2
6231 LS Meerssen
The Netherlands.
More about the license can be found at: [https://docs.laravel-excel.com/3.1/getting-started/license.html](https://docs.laravel-excel.com/3.1/getting-started/license.html)
## Created by Spartner (formerly Maatwebsite)
We are a strategic development partner, creating web-based custom built software from Laravel. In need of a digital solution for your challenge? Give us a call.
https://spartner.software
info@spartner.nl
+31 (0) 10 - 7449312
## :wrench: Supported Versions
Versions will be supported for a limited amount of time.
| Version | Laravel Version | Php Version | Support |
|---- |----|----|----|
| 2.1 | <=5.6 | <=7.0 | Unsupported since 15-5-2018 |
| 3.0 | ^5.5 | ^7.0 | Unsupported since 31-12-2018 |
| 3.1 | >=5.8 \| <=13.x | ^7.2 \| ^8.0 | No active support, CVE only |
| 4.0 | >=12 \| <=13.x | ^8.3 | New features |
---
--- METRICS ---
- Files Extracted: 1
- Estimated Token Budget: ~1160 tokens
- Canonical Reference: https://codewiki.google/github.com/SpartnerNL/Laravel-Excel
## 2. Official Technical Reference & Guides (SpartnerNL/laravel-excel-docs)
## File: 2.1/import/README.md
# Importing a file
To start importing a file, you can use `->load($filename)`. The callback is optional.
Excel::load('file.xls', function($reader) {
// reader methods
});
---
## File: 2.1/getting-started/README.md
# Installation
Require this package in your `composer.json` and update composer. This will download the package and PHPExcel of PHPOffice.
#### Laravel 4
"maatwebsite/excel": "~1.3"
#### Laravel 5
"maatwebsite/excel": "~2.1.0"
After updating composer, add the ServiceProvider to the providers array in `app/config/app.php`
Maatwebsite\Excel\ExcelServiceProvider::class,
You can use the facade for shorter code. Add this to your aliasses:
'Excel' => Maatwebsite\Excel\Facades\Excel::class,
The class is binded to the ioC as `excel`
$excel = App::make('excel');
---
## File: 2.1/export/README.md
# Simple Excel Export
### Basics
A new file can be created using the `create` method with the filename as first parameter.
Excel::create('Filename');
To manipulate the creation of the file you can use the callback with `LaravelExcelWriter` parameter
Excel::create('Filename', function($excel) {
// Call writer methods here
});
### Changing properties
There are a couple of properties we can change inside the closure. Most of them are set to the config values by default. See `app/config/packages/maatwebsite/excel/config.php`.
Excel::create('Filename', function($excel) {
// Set the title
$excel->setTitle('Our new awesome title');
// Chain the setters
$excel->setCreator('Maatwebsite')
->setCompany('Maatwebsite');
// Call them separately
$excel->setDescription('A demonstration to change the file properties');
});
> Go to the reference guide to see a list of available properties.
---
## File: 3.0/getting-started/README.md
# Introduction
:rocket: Laravel Excel is intended at being Laravel-flavoured PhpSpreadsheet: a simple, but elegant wrapper around PhpSpreadsheet with the goal of simplifying
exports.
:fire: [PhpSpreadsheet](https://phpspreadsheet.readthedocs.io/) is a library written in pure PHP and providing a set of classes that allow you to read from and to write to different spreadsheet file formats, like Excel and LibreOffice Calc.
Laravel Excel features:
* Easily export collections to Excel
* Export queries with automatic chunking for better performance
* Queue exports for better performance
* Easily export Blade views to Excel
---
## File: 3.0/exports/README.md
## :rocket: 5 minute quick start
:muscle: Create an export class in `app/Exports`
You may do this by using the `make:export` command.
```
php artisan make:export UsersExport --model=User
```
If you prefer to create the export manually, you can create the following in `app/Exports`:
```php
$row[0],
'email' => $row[1],
'password' => Hash::make($row[2]),
]);
}
}
```
:fire: In your controller you can call this import now:
```php
use App\Imports\UsersImport;
use Maatwebsite\Excel\Facades\Excel;
use App\Http\Controllers\Controller;
class UsersController extends Controller
{
public function import()
{
Excel::import(new UsersImport, 'users.xlsx');
return redirect('/')->with('success', 'All good!');
}
}
```
:page_facing_up: Find the imported users in your database!
---
## File: 3.1/getting-started/README.md
---
pageClass: no-toc
---
# Introduction
:rocket: Laravel Excel is intended at being Laravel-flavoured PhpSpreadsheet: a simple, but elegant wrapper around PhpSpreadsheet with the goal of simplifying
exports and imports.
:fire: [PhpSpreadsheet](https://phpspreadsheet.readthedocs.io/) is a library written in pure PHP and providing a set of classes that allow you to read from and to write to different spreadsheet file formats, like Excel and LibreOffice Calc.
## Laravel Excel Features
* Easily export collections to Excel.
* Export queries with automatic chunking for better performance.
* Queue exports for better performance.
* Easily export Blade views to Excel.
* Easily import to collections.
* Read the Excel file in chunks.
* Handle the import inserts in batches.
---
## File: 3.1/exports/README.md
---
pageClass: no-toc
---
# :rocket: 5 minute quick start
[[toc]]
:muscle: Create an export class in `app/Exports`
You may do this by using the `make:export` command.
```
php artisan make:export UsersExport --model=User
```
The file can be found in `app/Exports`:
::: vue
.
├── app
│ ├── `Exports`
│ │ ├── UsersExport.php
│
└── composer.json
:::
If you prefer to create the export manually, you can create the following in `app/Exports`:
```php
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');
}
}
```
#### Contract
You can also use the `Maatwebsite\Excel\Exporter` interface to decouple more from the concrete Excel manager implementation. The contract offers the same methods as the `Excel` class.
It will make it easier to e.g. stub out the Exporter in your unit tests. The `Exporter` contract can be either injected via the constructor or a method in a controller.
```php
use App\Exports\UsersExport;
use Maatwebsite\Excel\Exporter;
class ExportsController
{
private $exporter;
public function __construct(Exporter $exporter)
{
$this->exporter = $exporter;
}
public function export()
{
return $this->exporter->download(new UsersExport, 'users.xlsx');
}
}
```
#### Container binding
If you want to bind the `Maatwebsite\Excel\Excel` manager to your own class via a container binding, you can use the `excel` container binding.
```php
$this->app->bind(YourCustomExporter::class, function() {
return new YourCustomExporter($this->app['excel']);
});
```
#### Exportable trait
If you prefer a sprinkle of magic, you can use the `Maatwebsite\Excel\Concerns\Exportable` trait in your `Export` object. This trait will expose a couple of methods that will make it possible to directly export an `Export` object.
```php
namespace App\Exports;
use App\User;
use Maatwebsite\Excel\Concerns\FromCollection;
use Maatwebsite\Excel\Concerns\Exportable;
class UsersExport implements FromCollection
{
use Exportable;
public function collection()
{
return User::all();
}
}
```
You can now download the export without the need for the `facade` or `Excel` manager.
```php
return (new UsersExport)->download('users.xlsx');
```
Read more about the exportable trait in the [exportables](/3.1/exports/exportables.html) docs.
### Handling the Export object
#### Writer type detection
After using one of the above methods to pass on the `Export` object to the `Excel` manager, it will try to figure out what export it needs to be generated to.
This will be either based on the extension of the file, the explicitly passed writer type. You can find the extension to writer type mapping in the `excel.php` config, in the `extension_detector` section.
In case no writer type can be detected, a `Maatwebsite\Excel\Exceptions\NoTypeDetectedException` exception is thrown and the export process will be stopped.
#### Starting the Writing process
The `Excel` manager will then delegate the handling to the `Maatwebsite\Excel\Writer`. The first action of the `Writer` is to register the event listeners that are registered.
Next it will create a new `PhpOffice\PhpSpreadsheet\Spreadsheet` instance that we will use to convert our `Export` object to.
The first event raised is the `BeforeExport` event. This is raised just after the `Spreadsheet` instance is created and allows early access to it.
#### Multiple sheets
Next the `Writer` will determine if multiple sheets are configured, by checking for the `Maatwebsite\Excel\Concerns\WithMultipleSheets` concern.
Then it will delegate the further handling of each sheet to the `Maatwebsite\Excel\Sheet` class.
#### Processing the sheets
In the `Sheet` class, the most heavy lifting happens. It first will create a `PhpOffice\PhpSpreadsheet\Worksheet\Worksheet` instance. Then it will raise the `BeforeSheet` event which allows you to hook into the moment just before the sheet handling starts.
Then it will determine what kind of export we are dealing with: `FromQuery`, `FromArray`, `FromCollection` or `FromView`. Based on that it will start the connected export process.
- `FromView` will pass on the rendered `Blade` view to PhpSpreadsheet's `Html` Reader. That Reader will turn the table html into Excel cells. It also handles some inline styles (color and background color) and col/rowspans.
- The **Query** passed with the `FromQuery` will automatically be chunked and each chunk will be appended to the Sheet. The chunking is done to limit the amount of Eloquent objects it needs to keep in memory. It greatly reduces memory usage.
- The entire array of Collection will directly be appended to the Sheet.
When the `Sheet` starts appending records, it will first call the `map()` method if the `WithMapping` concern is used. This allows the `Export` object to format the data before it is inserted.
Then it will handle column formatting (`WithColumnFormatting` concern) and cell autosizing (`ShouldAutoSize`).
To close off the Sheet processing, it will raise a `AfterSheet` event.
### Passing on to PhpSpreadsheet
After the sheets are processed, the writing process will start. The writing process is started by raising the `BeforeWriting` event; this allows you to hook into the process of writing.
Next we will create a new `PhpSpreadsheet Writer` based on the writer type that was determined. Then it will save it to a temporary file and return that filepath to the `Excel` manager.
### Creating a Response
The `Excel` manager basically has 2 types of responses, it either starts the **download** process or it will **store** the file to disk.
#### Download the file
We will take the temporary file that was returned by the `Writer` and use Laravel's `ResponseFactory` to create a `Symfony\Component\HttpFoundation\BinaryFileResponse`. When returning this response in your controller, it will start a download.
#### Storing the file
The storing of the file will be handled by Laravel's `Filesystem`. By default the file will be stored on your `default` disk, but you can also pass a custom disk via the `Excel::store()` method.
## Imports Lifecycle Overview
This section will try to give you an overview of how the import works behind the scenes.
### Import Object
Everything starts with the `Import` object. This object **encapsulates** your entire import logic.
It both configures and handles the import logic.
A simple example of an import object is:
```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)
{
foreach ($rows as $row)
{
User::create([
'name' => $row[0],
]);
}
}
}
```
If you want to read more about imports objects, go to the architecture page of [imports objects](/3.1/architecture/objects.html).
### Passing on the Import object
Next the Import object will be passed on to the Laravel Excel package. The main entry point for this is the `Maatwebsite/Excel/Excel` class. This class can be called in the same way as outlined in the Export lifecycle.
#### Contract
You can also use the `Maatwebsite\Excel\Importer` interface to decouple more from the concrete Excel manager implementation. The contract offers the same methods as the `Excel` class.
It will make it easier to e.g. stub out the Importer in your unit tests. The `Importer` contract can be either injected via the constructor or the method of a controller.
```php
use App\Imports\UsersImport;
use Maatwebsite\Excel\Importer;
class ImportsController
{
private $importer;
public function __construct(Importer $importer)
{
$this->importer = $importer;
}
public function import()
{
return $this->importer->import(new UsersImport, 'users.xlsx');
}
}
```
#### Importable trait
If you prefer a sprinkle of magic, you can use the `Maatwebsite\Excel\Concerns\Importable` trait in your `Import` object. This trait will expose a couple of methods that will make it possible to directly import an `Import` object.
```php
namespace App\Imports;
use App\User;
use Maatwebsite\Excel\Concerns\ToCollection;
use Maatwebsite\Excel\Concerns\Importable;
class UsersImport implements ToCollection
{
use Importable;
...
}
```
You can now import without the need for the `facade` or `Excel` manager.
```php
(new UsersImport)->import('users.xlsx');
```
Read more about the importable trait in the [importables](/3.1/imports/importables.html) docs.
### Handling the Import object
#### Reader type detection
After using one of the above methods to pass on the `Import` object to the `Excel` manager, it will try to figure out what reader type it is .
This will be either based on the extension of the file or the explicitly passed reader type. You can find the extension to reader type mapping in the `excel.php` config, in the `extension_detector` section.
In case no reader type can be detected, a `Maatwebsite\Excel\Exceptions\NoTypeDetectedException` exception is thrown and the import process will be stopped.
#### Starting the Reading process
The `Excel` manager will then delegate the handling to the `Maatwebsite\Excel\Reader`. The first action of the `Reader` is to register the event listeners that are registered.
It will copy the file from Laravel's `Filesystem` to the local filesystem, so PhpSpreadsheet can read it.
Next it will create a PhpSpreadsheet `Reader` based on the reader type that was given and load the file into a `PhpOffice\PhpSpreadsheet\Spreadsheet` instance.
Next it will create a new `PhpOffice\PhpSpreadsheet\Spreadsheet` instance that we will use to read our `Import` object from.
The first event that is raised, is the `BeforeImport` event. This is raised just after the `Spreadsheet` instance is loaded and allows early access to it.
#### Multiple sheets
Next we will determine if we are dealing with multiple sheets. This is done based on the `WithMultipleSheets` concern.
#### Processing the sheets
Then each Sheet gets processed. This process gets started off by raising the `BeforeSheet` event.
Then it will either import it to a Collection, an array or handle each row as an Eloquent model.
- When using `ToModel`, each returned model will be persisted via Eloquent. When using this in combination with `WithBatchInserts`, it will defer the persistence till the batch is complete and then insert them as one batch in the database.
- When using `ToCollection` or `ToArray`, the entire dataset will be passed to the Import method and the user can determine itself how to use it.
The sheet handling is ended by raising the `AfterSheet` event.
## 2. Official Technical Reference & Guides (SpartnerNL/laravel-excel-docs)
## File: README.md
---
## File: index.md
---
head:
- - meta
- http-equiv: refresh
content: 0;url=/4.x/getting-started/
---
Redirecting to the [Laravel Excel 4.x documentation](/4.x/getting-started/)…
---
## File: package.json
{
"private": true,
"type": "module",
"engines": {
"node": ">=20.19.0"
},
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"
},
"devDependencies": {
"@fontsource-variable/ibm-plex-sans": "^5.3.0",
"@fontsource/ibm-plex-mono": "^5.3.0",
"markdown-it-container": "^4.0.0",
"vitepress": "^1.6.4",
"vitepress-plugin-llms": "^1.14.0"
}
}
---
## File: 2.1/index.md
---
## File: 2.1/blade/load-view.md
# @Blade to Excel
We can utilise the magic of Laravel's Blade engine to power our Excel export. Sharing a view, loading a view per sheet, creating a html table inside a view, basic CSS styling, ...
# Loading a view for a single sheet
We can load a view for every sheet we create with `->loadView()`.
Excel::create('New file', function($excel) {
$excel->sheet('New sheet', function($sheet) {
$sheet->loadView('folder.view');
});
});
# Using different views for different sheets
Excel::create('New file', function($excel) {
$excel->sheet('First sheet', function($sheet) {
$sheet->loadView('view_first');
});
$excel->sheet('Second sheet', function($sheet) {
$sheet->loadView('view_second');
});
});
# Sharing a view for all sheets
We can share a view for all sheets with `shareView()`.
Excel::shareView('folder.view')->create();
# Unsetting a view for a sheet
When we are using a shared view, but we don't want to use a view for the current sheet, we can use `->unsetView()`.
$sheet->unsetView();
---
## File: 2.1/blade/styling.md
# Styling sheets
### General styling
If you want to change the general styling of your sheet (not cell or range specific), you can use the `->setStyle()` method or any of the other setters which can be found inside the export documentation.
// Font family
$sheet->setFontFamily('Comic Sans MS');
// Set font with ->setStyle()`
$sheet->setStyle(array(
'font' => array(
'name' => 'Calibri',
'size' => 12,
'bold' => true
)
));
### Styling with PHPExcel methods
It's possible to style the sheets and specific cells with help of PHPExcel methods. This package includes a lot of shortcuts (see export documentation), but also always the use of the native methods.
// Set background color for a specific cell
$sheet->getStyle('A1')->applyFromArray(array(
'fill' => array(
'type' => PHPExcel_Style_Fill::FILL_SOLID,
'color' => array('rgb' => 'FF0000')
)
));
### Using HTML tags
Most of the HTML tags are supported.
Big title
**Bold cell**
**Bold cell**
*Italic cell*
> Inside the `view.php` config you can change how these tags will be interpreted by Excel by default.
### Using HTML attributes
Some of the basic styling can be done with HTML attributes.
Big title
Bold cell
Bold cell
Italic cell
Cell with width of 100
Cell with height of 100
### Styling through inline-styles
It's possible to use inline styles inside your view files. Most of the general styles are supported.
Cell
> Inside the reference guide you can find a list of supported styles.
### Styling through external CSS file
Styling can be done through an external CSS file.
External css file:
#cell {
background-color: #000000;
color: #ffffff;
}
.cell {
background-color: #000000;
color: #ffffff;
}
tr td {
background-color: #ffffff;
}
tr > td {
border-bottom: 1px solid #000000;
}
Table:
```html
{{ HTML::style('css/table.css') }}
Cell |
Cell |
```
> Inside the reference guide you can find a list of supported styles.
> It's advised to include `` into the view to fix problems with UTF-8 encoding.
---
## File: 2.1/blade/vars.md
# Passing variables to the view
### As parameter
We can pass variables to the view by using the second parameter inside the `loadView()` method.
$sheet->loadView('view', array('key' => 'value'));
### With with()
Alternatively you can use the `with()` method which works the same as with Laravel views.
// Using normal with()
$sheet->loadView('view')
->with('key', 'value');
// using dynamic with()
$sheet->loadView('view')
->withKey('value');
---
## File: 2.1/changelog/version-1.md
# Version 1
### 1.3.5
- PHPExcel 1.8.1 compatibility
- Clean-up ServiceProvider
- Fix short array syntax for PHP5.3
### 1.3.4
- Fix usage of sheet callback when modifying an existing file
- Modifying existing files improvements (support style overriding)
- Add text-indent support to HtmlReader
- Add simple sheet password protection
- Add support for exporting multiple pdf pages
- Add inline cell formatting to Blade
### 1.3.3
- Fix issue with different start row in chunk filter
### 1.3.2
- Custom value binders
- Html reader update
### 1.3.1
- Fix short array syntax
### 1.3.0
- Additional headers with export()
- Float, integer, string, timestamps problems
- Cell content ending by zeros
- Images in html
- Font family bug
- Setting row number of row with headings
### 1.2.3
- PDF writer
- Include charts config
- Chunk filter with selected sheet
- Compatibility fix with new PHPExcel release
- setDateColumns fix
- Optional dependencies to require-dev
- Several bugfixes
### 1.2.2
- Chunk filter fixes
- Isset() CellCollection fixes
- PHP 5.3 support
- Missing border styles
- Add CSV settings (delimiter, enclosure, lineEnding) to ExcelFile objects
### 1.2.1
- Fix with() method parameters
### 1.2.0
- Filters
- Chunk filter (with chunked importer)
- ExcelFile (method) injections
- NewExcelFile (method) injections
- Edit existing worksheets
- Converting existing worksheet
- Laravel 4.* + 5.0 support
### 1.1.9
- PHP 5.3 fixes
### 1.1.8
- PHP 5.3 support
- fromArray bugfix
### 1.1.7
- Fix heading generation for export with `->fromArray()`
- Bugfix for non-Unix kernels
- Enhanced CSS parser (thanks to `tijsverkoyen/CssToInlineStyles`)
- Support for nested CSS styles
- Support for multiple css attributes per class
- Support for internal and external CSS files
- Support for inline style blocks (`