or via phone +31 (0)10 744 9312.
8 |
9 | ## Supported Versions
10 |
11 | Versions will be supported for a limited amount of time.
12 |
13 | | Version | Laravel Version | Php Version | Support |
14 | |---- |----|----|----|
15 | | 2.1 | <=5.6 | <=7.0 | EOL since 15-05-2018 |
16 | | 3.0 | ^5.5 | ^7.0 | New features |
17 |
18 | ::: warning PHP version support
19 | Support for PHP versions will only be maintained for a period of six months beyond the end-of-life of that PHP version.
20 | :::
21 |
22 |
23 | ## Requesting support
24 | Before you request support, please check the following:
25 | * Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
26 | * Check to make sure your support request isn't already present within the project.
27 | * Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
28 | * Use the [issue template](https://github.com/SpartnerNL/Laravel-Excel/blob/3.0/.github/ISSUE_TEMPLATE.md).
29 |
30 | Filling out the template is required. Issues that do not include enough information might not be picked up. Please write in English (or Dutch).
31 |
32 | Please prefix your issue with one of the following: [BUG] [PROPOSAL] [QUESTION].
33 |
34 | And please be considerate towards maintainers when raising issues.
35 |
--------------------------------------------------------------------------------
/3.0/getting-started/upgrade.md:
--------------------------------------------------------------------------------
1 | # Upgrade Guide
2 |
3 | [[toc]]
4 |
5 | ## Upgrading to 3.0 from 2.1
6 |
7 | Version 3.0 is not backwards compatible with 2.*. It's not possible to provide a step-by-step migration guide as it's a complete paradigm shift.
8 |
9 | __New dependencies__
10 |
11 | 3.0 introduces some new dependencies.
12 |
13 | * Requires PHP 7.0 or higher.
14 | * Requires Laravel 5.5 (or higher).
15 | * Requires PhpSpreadsheet instead of PHPExcel.
16 |
17 | __Deprecations__
18 |
19 | ALL Laravel Excel 2.* methods are deprecated and will not be able to use in 3.0 .
20 |
21 | - Excel::load() is removed and will not be re-added until 3.1
22 | - Excel::create() is removed and replaced by Excel::download/Excel::store($yourExport)
23 | - 3.0 provides no convenience methods for styling, you are encouraged to use PhpSpreadsheets native methods.
24 |
--------------------------------------------------------------------------------
/3.1/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/3.1/architecture/concerns.md:
--------------------------------------------------------------------------------
1 | # Concerns
2 |
3 | [[toc]]
4 |
5 | Most of the export/import configuration is done by using **Concerns**.
6 |
7 | ## Contracts
8 |
9 | Concerns are basically just simple interfaces. Implementing them will make the object adhere to a
10 | certain contract. This contract can request specific methods that e.g. data can be passed through.
11 |
12 | For instance, the `FromCollection` requests the Export object to implement a `collection` method, that needs to return a `Collection` instance.
13 |
14 | ```php
15 | namespace App\Exports;
16 |
17 | use App\User;
18 | use Maatwebsite\Excel\Concerns\FromCollection;
19 |
20 | class UsersExport implements FromCollection
21 | {
22 | public function collection()
23 | {
24 | return User::all();
25 | }
26 | }
27 | ```
28 |
29 | ## Pointer interface
30 |
31 | In other cases it might not ask for any methods to be implemented, but merely functions as a pointer interface.
32 |
33 | For instance, the `ShouldAutoSize` concern doesn't pass on any specific information, but does tell the Export process that the columns need to be automatically sized.
34 |
35 | ```php
36 | namespace App\Exports;
37 |
38 | use App\User;
39 | use Maatwebsite\Excel\Concerns\ShouldAutoSize;
40 |
41 | class UsersExport implements ShouldAutoSize
42 | {
43 |
44 | }
45 | ```
46 |
--------------------------------------------------------------------------------
/3.1/exports/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # :rocket: 5 minute quick start
6 |
7 | [[toc]]
8 |
9 | :muscle: Create an export class in `app/Exports`
10 |
11 | You may do this by using the `make:export` command.
12 |
13 | ```
14 | php artisan make:export UsersExport --model=User
15 | ```
16 |
17 | The file can be found in `app/Exports`:
18 |
19 | ::: vue
20 | .
21 | ├── app
22 | │ ├── `Exports`
23 | │ │ ├── UsersExport.php
24 | │
25 | └── composer.json
26 | :::
27 |
28 | If you prefer to create the export manually, you can create the following in `app/Exports`:
29 |
30 | ```php
31 | 'text/csv',
25 | ]);
26 | ```
27 |
28 | :::tip Laravel CSV
29 | You may have a look at our [Laravel CSV](/csv/1.0/getting-started/) package as well.
30 | :::
31 |
32 | ## TSV
33 |
34 | ```php
35 | return Excel::download(new InvoicesExport, 'invoices.tsv', \Maatwebsite\Excel\Excel::TSV);
36 | ```
37 |
38 | ## ODS
39 |
40 | ```php
41 | return Excel::download(new InvoicesExport, 'invoices.ods', \Maatwebsite\Excel\Excel::ODS);
42 | ```
43 |
44 | ## XLS
45 |
46 | ```php
47 | return Excel::download(new InvoicesExport, 'invoices.xls', \Maatwebsite\Excel\Excel::XLS);
48 | ```
49 |
50 | ## HTML
51 |
52 | ```php
53 | return Excel::download(new InvoicesExport, 'invoices.html', \Maatwebsite\Excel\Excel::HTML);
54 | ```
55 |
56 | ::: warning Exporting to PDF
57 | If you'd like to export to PDF, you must now install a PDF rendering library yourself. Please refer to the [PhpSpreadsheet Documentation](https://phpspreadsheet.readthedocs.io/en/latest/topics/reading-and-writing-to-file/#pdf) for more information.
58 | :::
59 |
60 | ## MPDF
61 |
62 | ```php
63 | return Excel::download(new InvoicesExport, 'invoices.pdf', \Maatwebsite\Excel\Excel::MPDF);
64 | ```
65 |
66 | ## DOMPDF
67 |
68 | ```php
69 | return Excel::download(new InvoicesExport, 'invoices.pdf', \Maatwebsite\Excel\Excel::DOMPDF);
70 | ```
71 |
72 | ## TCPDF
73 |
74 | ```php
75 | return Excel::download(new InvoicesExport, 'invoices.pdf', \Maatwebsite\Excel\Excel::TCPDF);
76 | ```
77 |
--------------------------------------------------------------------------------
/3.1/exports/exportables.md:
--------------------------------------------------------------------------------
1 | # Exportables
2 |
3 | [[toc]]
4 |
5 | In the previous example, we used the `Excel::download` facade to start an export.
6 |
7 | Laravel Excel also provides a `Maatwebsite\Excel\Concerns\Exportable` trait, to make export classes exportable.
8 |
9 | ```php
10 | namespace App\Exports;
11 |
12 | use App\Invoice;
13 | use Maatwebsite\Excel\Concerns\FromCollection;
14 | use Maatwebsite\Excel\Concerns\Exportable;
15 |
16 | class InvoicesExport implements FromCollection
17 | {
18 | use Exportable;
19 |
20 | public function collection()
21 | {
22 | return Invoice::all();
23 | }
24 | }
25 | ```
26 |
27 | We can now download the export without the need for the facade:
28 |
29 | ```php
30 | return (new InvoicesExport)->download('invoices.xlsx');
31 | ```
32 |
33 | You can also pass the Writer Type and optional headers to the download method:
34 |
35 | ```php
36 | return (new InvoicesExport)->download('invoices.csv', Excel::CSV, ['Content-Type' => 'text/csv']);
37 | ```
38 |
39 | Or store it on a disk:
40 |
41 | ```php
42 | return (new InvoicesExport)->store('invoices.xlsx', 's3');
43 | ```
44 |
45 | You can also pass options to the disk if you like:
46 |
47 | ```php
48 | return (new InvoicesExport)->store('invoices.xlsx', 's3', null, 'private');
49 | ```
50 |
51 | ## Responsable
52 |
53 | The previous (download) example can be made even shorter when adding Laravel's `Responsable` interface to the export class:
54 |
55 | ```php
56 | namespace App\Exports;
57 |
58 | use App\Invoice;
59 | use Maatwebsite\Excel\Excel;
60 | use Illuminate\Contracts\Support\Responsable;
61 | use Maatwebsite\Excel\Concerns\FromCollection;
62 | use Maatwebsite\Excel\Concerns\Exportable;
63 |
64 | class InvoicesExport implements FromCollection, Responsable
65 | {
66 | use Exportable;
67 |
68 | /**
69 | * It's required to define the fileName within
70 | * the export class when making use of Responsable.
71 | */
72 | private $fileName = 'invoices.xlsx';
73 |
74 | /**
75 | * Optional Writer Type
76 | */
77 | private $writerType = Excel::XLSX;
78 |
79 | /**
80 | * Optional headers
81 | */
82 | private $headers = [
83 | 'Content-Type' => 'text/csv',
84 | ];
85 |
86 | public function collection()
87 | {
88 | return Invoice::all();
89 | }
90 | }
91 | ```
92 |
93 | You can now easily return the export class, without the need of calling `->download()`.
94 |
95 | ```php
96 | return new InvoicesExport();
97 | ```
98 |
--------------------------------------------------------------------------------
/3.1/exports/from-generator.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # From Generator
6 |
7 | Exports can be created from a PHP [generator](https://www.php.net/manual/en/class.generator.php) class, by using the `FromGenerator` concern.
8 |
9 | A generator allows you to write code that uses foreach to iterate over a set of data without needing to build an array in memory.
10 |
11 | ```php
12 | namespace App\Exports;
13 |
14 | use Generator;
15 | use Maatwebsite\Excel\Concerns\Exportable;
16 | use Maatwebsite\Excel\Concerns\FromGenerator;
17 |
18 | class DataExport implements FromGenerator
19 | {
20 | use Exportable;
21 |
22 | public function generator(): Generator
23 | {
24 | for ($i = 1; $i <= 100; $i++) {
25 | yield [$i, $i+1, $i+2];
26 | }
27 | }
28 | }
29 | ```
30 |
31 | You can download the export in your controller:
32 |
33 | ```php
34 | public function export()
35 | {
36 | return (new DataExport)->download('data.xlsx');
37 | }
38 | ```
39 |
--------------------------------------------------------------------------------
/3.1/exports/from-view.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # From View
6 |
7 | Exports can be created from a Blade view, by using the `FromView` concern.
8 |
9 | ```php
10 | namespace App\Exports;
11 |
12 | use App\Invoice;
13 | use Illuminate\Contracts\View\View;
14 | use Maatwebsite\Excel\Concerns\FromView;
15 |
16 | class InvoicesExport implements FromView
17 | {
18 | public function view(): View
19 | {
20 | return view('exports.invoices', [
21 | 'invoices' => Invoice::all()
22 | ]);
23 | }
24 | }
25 | ```
26 |
27 | It will convert an HTML table into an Excel spreadsheet. For example; `invoices.blade.php`:
28 |
29 | ```html
30 |
31 |
32 |
33 | | Name |
34 | Email |
35 |
36 |
37 |
38 | @foreach($invoices as $invoice)
39 |
40 | | {{ $invoice->name }} |
41 | {{ $invoice->email }} |
42 |
43 | @endforeach
44 |
45 |
46 | ```
47 |
48 | Attribute in tag html support:
49 |
50 | |Attributes|Description
51 | |-----------|-------------
52 | |bgcolor| set background color to cell ``
53 | |colspan| merge column cell
54 | |rowspan| merge row cell
55 | |width| set width to cell
56 | |height| set height to cell
57 | |data-format| set format `PhpOffice\PhpSpreadsheet\Style::NumberFormat`
58 | |data-type| set type `PhpOffice\PhpSpreadsheet\Cell`
59 | |align| set text align to cell
60 | |valign| set vertical align to cell
61 | |style| set style to cell
62 |
63 | Style inline support
64 | - background
65 | - background-color
66 | - color
67 | - border|border-top|border-bottom|border-left|border-right
68 | - font-size|font-weight|font-sytle|font-family
69 | - text-decoration: underline|line-through
70 | - text-align
71 | - vertical-align
72 | - with|height
73 | - word-wrap
74 | - text-indent
75 |
76 | You can download the export in your controller:
77 |
78 | ```php
79 | public function export()
80 | {
81 | return Excel::download(new InvoicesExport, 'invoices.xlsx');
82 | }
83 | ```
84 |
--------------------------------------------------------------------------------
/3.1/exports/multiple-sheets.md:
--------------------------------------------------------------------------------
1 | # Multiple Sheets
2 |
3 | [[toc]]
4 |
5 | To allow the export to have multiple sheets, the `WithMultipleSheets` concern should be used.
6 | The `sheets()` method expects an array of sheet export objects to be returned.
7 |
8 | ```php
9 | namespace App\Exports;
10 |
11 | use Maatwebsite\Excel\Concerns\Exportable;
12 | use Maatwebsite\Excel\Concerns\WithMultipleSheets;
13 |
14 | class InvoicesExport implements WithMultipleSheets
15 | {
16 | use Exportable;
17 |
18 | protected $year;
19 |
20 | public function __construct(int $year)
21 | {
22 | $this->year = $year;
23 | }
24 |
25 | /**
26 | * @return array
27 | */
28 | public function sheets(): array
29 | {
30 | $sheets = [];
31 |
32 | for ($month = 1; $month <= 12; $month++) {
33 | $sheets[] = new InvoicesPerMonthSheet($this->year, $month);
34 | }
35 |
36 | return $sheets;
37 | }
38 | }
39 | ```
40 |
41 | ## Sheet classes
42 |
43 | The `InvoicesPerMonthSheet` can implement concerns like `FromQuery`, `FromCollection`, `FromView`, ...
44 |
45 | _Note: The WithTitle concern is needed in order to name each sheet using the `title()` method_
46 | ```php
47 | namespace App\Exports\Sheets;
48 |
49 | use Maatwebsite\Excel\Concerns\FromQuery;
50 | use Maatwebsite\Excel\Concerns\WithTitle;
51 |
52 | class InvoicesPerMonthSheet implements FromQuery, WithTitle
53 | {
54 | private $month;
55 | private $year;
56 |
57 | public function __construct(int $year, int $month)
58 | {
59 | $this->month = $month;
60 | $this->year = $year;
61 | }
62 |
63 | /**
64 | * @return Builder
65 | */
66 | public function query()
67 | {
68 | return Invoice
69 | ::query()
70 | ->whereYear('created_at', $this->year)
71 | ->whereMonth('created_at', $this->month);
72 | }
73 |
74 | /**
75 | * @return string
76 | */
77 | public function title(): string
78 | {
79 | return 'Month ' . $this->month;
80 | }
81 | }
82 | ```
83 |
84 | The code below can be implemented in any class in order to download an xlsx of all invoices from the current year, with 12 worksheets representing each month of the year.
85 |
86 | ```php
87 | public function downloadInvoices()
88 | {
89 | return (new InvoicesExport(2018))->download('invoices.xlsx');
90 | }
91 | ```
92 |
--------------------------------------------------------------------------------
/3.1/exports/store.md:
--------------------------------------------------------------------------------
1 | # Storing exports on disk
2 |
3 | [[toc]]
4 |
5 | Exports can easily be stored on any [filesystem](https://laravel.com/docs/master/filesystem) that Laravel supports.
6 |
7 |
8 | ## Default disk
9 |
10 | ```php
11 | public function storeExcel()
12 | {
13 | // Store on default disk
14 | Excel::store(new InvoicesExport(2018), 'invoices.xlsx');
15 | }
16 | ```
17 |
18 | ## Custom disks
19 |
20 | ```php
21 | public function storeExcel()
22 | {
23 | // Store on a different disk (e.g. s3)
24 | Excel::store(new InvoicesExport(2018), 'invoices.xlsx', 's3');
25 |
26 | // Store on a different disk with a defined writer type.
27 | Excel::store(new InvoicesExport(2018), 'invoices.xlsx', 's3', Excel::XLSX);
28 | }
29 | ```
30 |
31 | ## Disk options
32 |
33 | If you want to pass some options to the disk, pass them to Excel::store() as the fifth parameter.
34 |
35 | ```php
36 | public function storeExcel()
37 | {
38 | Excel::store(new InvoicesExport(2018), 'invoices.xlsx', 's3', null, [
39 | 'visibility' => 'private',
40 | ]);
41 | }
42 | ```
43 |
44 | Laravel has a shortcut for private files:
45 |
46 | ```php
47 | public function storeExcel()
48 | {
49 | Excel::store(new InvoicesExport(2018), 'invoices.xlsx', 's3', null, 'private');
50 | }
51 | ```
52 |
53 | ::: warning File names cannot include certain characters:
54 | - `<` (less than)
55 | - `>` (greater than)
56 | - `:` (colon)
57 | - `"` (double quote)
58 | - `/` (forward slash)
59 | - `\` (backslash)
60 | - `|` (vertical bar or pipe)
61 | - `?` (question mark)
62 | - `*` (asterisk)
63 | :::
64 |
65 | ## Note about queuing
66 | If you are storing the export using `Excel::queue()` or using the `ShouldQueue` interface, make sure to have a look at the [queuing docs](https://docs.laravel-excel.com/3.1/exports/queued.html)
67 |
--------------------------------------------------------------------------------
/3.1/getting-started/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Introduction
6 |
7 | :rocket: Laravel Excel is intended at being Laravel-flavoured PhpSpreadsheet: a simple, but elegant wrapper around PhpSpreadsheet with the goal of simplifying
8 | exports and imports.
9 |
10 | :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.
11 |
12 | ## Laravel Excel Features
13 |
14 | * Easily export collections to Excel.
15 | * Export queries with automatic chunking for better performance.
16 | * Queue exports for better performance.
17 | * Easily export Blade views to Excel.
18 | * Easily import to collections.
19 | * Read the Excel file in chunks.
20 | * Handle the import inserts in batches.
--------------------------------------------------------------------------------
/3.1/getting-started/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | [[toc]]
4 |
5 | ## Requirements
6 |
7 | * PHP: `^7.2\|^8.0`
8 | * Laravel: `^5.8`
9 | * PhpSpreadsheet: `^1.21`
10 | * PHP extension `php_zip` enabled
11 | * PHP extension `php_xml` enabled
12 | * PHP extension `php_gd2` enabled
13 | * PHP extension `php_iconv` enabled
14 | * PHP extension `php_simplexml` enabled
15 | * PHP extension `php_xmlreader` enabled
16 | * PHP extension `php_zlib` enabled
17 |
18 | ## Installation
19 |
20 | Require this package in the `composer.json` of your Laravel project. This will download the package and _PhpSpreadsheet_.
21 |
22 | ```
23 | composer require "maatwebsite/excel:^3.1"
24 | ```
25 |
26 | If installing your receive the following error
27 |
28 | ```
29 | Your requirements could not be resolved to an installable set of packages.
30 |
31 | Problem 1
32 | - Root composer.json requires maatwebsite/excel 3.1 -> satisfiable by maatwebsite/excel[3.1.0].
33 | - maatwebsite/excel 3.1.0 requires php ^7.0 -> your php version (8.2.8) does not satisfy that requirement.
34 | ```
35 |
36 | You can try simply to install without the caret
37 |
38 | ```
39 | composer require maatwebsite/excel
40 | ```
41 |
42 | If you don't get the latest version or run into more composer errors, please make sure you have installed all required PHP extensions like zip, gd, etc.
43 |
44 | The `Maatwebsite\Excel\ExcelServiceProvider` is __auto-discovered__ and registered by default.
45 |
46 | If you want to register it yourself, add the ServiceProvider in `config/app.php`:
47 |
48 | ```php
49 | 'providers' => [
50 | /*
51 | * Package Service Providers...
52 | */
53 | Maatwebsite\Excel\ExcelServiceProvider::class,
54 | ]
55 | ```
56 |
57 | The `Excel` facade is also __auto-discovered__.
58 |
59 | If you want to add it manually, add the Facade in `config/app.php`:
60 |
61 | ```php
62 | 'aliases' => [
63 | ...
64 | 'Excel' => Maatwebsite\Excel\Facades\Excel::class,
65 | ]
66 | ```
67 |
68 | To publish the config, run the vendor publish command:
69 |
70 | ```
71 | php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config
72 | ```
73 |
74 | This will create a new config file named `config/excel.php`.
75 |
--------------------------------------------------------------------------------
/3.1/getting-started/license.md:
--------------------------------------------------------------------------------
1 | # License
2 |
3 | [[toc]]
4 |
5 | ## MIT
6 | Our software is open source and licensed under the [MIT license](https://choosealicense.com/licenses/mit/). You are free to use the software as you like. The code can be forked and modified, but the original copyright author should always be included!
7 |
8 | ## Postcardware
9 | According to the [postcardware](https://en.wikipedia.org/wiki/Postcardware) concept, if you use the software for your project(s) we would appreciate to receive a postcard of your hometown. Please send it to:
10 |
11 | **Spartner**
12 | Markt 2
13 | 6231 LS Meerssen
14 | The Netherlands
15 |
16 | ## Created by Spartner (formerly Maatwebsite)
17 |
18 | 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.
19 |
20 | [https://spartner.software](https://spartner.software)
21 | [info@spartner.nl](mailto:info@spartner.nl)
22 | +31 (0) 10 - 7449312
23 |
24 | ## Support
25 |
26 | ::: warning Support
27 | We hold no liability and will provide support on a best effort basis. For more information about support please see [support](https://docs.laravel-excel.com/3.1/getting-started/support.html).
28 | :::
29 |
30 | :::tip Commercial Support
31 | :rocket: If you use the software commercially and need support urgently, we can offer this on a commercial basis. Please contact or phone +31 (0)10 744 9312.
32 | :::
33 |
--------------------------------------------------------------------------------
/3.1/getting-started/support.md:
--------------------------------------------------------------------------------
1 | # Support
2 |
3 | [[toc]]
4 |
5 | Our software is free and open source, meaning that the use of our software is optional. We hold no liability and there is no obligation to support. We will provide support on a best effort basis.
6 |
7 | :::tip Commercial Support
8 | If you use the software commercially and need elaborate support or need it urgently, we can offer this on a commercial basis. Please contact or via phone +31 (0)10 744 9312.
9 | :::
10 |
11 | ## Supported Versions
12 |
13 | Versions will be supported for a limited amount of time.
14 |
15 | | Version | Laravel Version | Php Version | Support |
16 | |---- |----|----|----|
17 | | 2.1 | <=5.6 | <=7.0 | Unsupported since 15-5-2018 |
18 | | 3.0 | ^5.5 | ^7.0 | Unsupported since 31-12-2018 |
19 | | 3.1 | ^5.8\|^6.0\|^7.0\|^8.0\|^9.0\|^10.0 | ^7.2\|^8.0 | New features |
20 |
21 | ::: warning PHP version support
22 | Support for PHP versions will only be maintained for a period of six months beyond the end-of-life of that PHP version.
23 | :::
24 |
25 | ## Requesting support
26 | Before you request support, please check the following:
27 | * Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
28 | * Check to make sure your support request isn't already present within the project.
29 | * Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
30 | * Use one of the [issue templates](https://github.com/SpartnerSoftware/Laravel-Excel/tree/3.1/.github/ISSUE_TEMPLATE).
31 |
32 | Filling out the template is required. Issues that do not include enough information might not be picked up. Please write in English (or Dutch).
33 |
34 | Please prefix your issue with one of the following: [BUG] [PROPOSAL] [QUESTION].
35 |
36 | And please be considerate towards maintainers when raising issues.
37 |
--------------------------------------------------------------------------------
/3.1/getting-started/upgrade.md:
--------------------------------------------------------------------------------
1 | # Upgrade Guide
2 |
3 | [[toc]]
4 |
5 | ## Upgrading to 3.1 from 3.0
6 |
7 | Version 3.1 is backwards compatible with 3.0. Only features were added in this release.
8 |
9 | __Additions__
10 |
11 | * Imports feature.
12 | * ChunkReading
13 | * BatchInserts
14 | * Queued imports
15 | * ToArray concern for Exports.
16 | * Custom value binders for Imports and Exports.
17 |
18 | __Removals__
19 |
20 | * `Excel::filter('chunk')` method is removed, chunk filter is automatically added when using chunk reading.
21 |
22 | ## Upgrading to 3.* from 2.1
23 |
24 | Version 3.* is not backwards compatible with 2.*. It's not possible to provide a step-by-step migration guide as it's a complete paradigm shift.
25 |
26 | __New dependencies__
27 |
28 | 3.* introduces some new dependencies.
29 |
30 | * Requires PHP 7.0 or higher.
31 | * Requires Laravel 5.5 (or higher).
32 | * Requires PhpSpreadsheet instead of PHPExcel.
33 |
34 | __Deprecations__
35 |
36 | ALL Laravel Excel 2.* methods are deprecated and will not be able to use in 3.0 .
37 |
38 | - `Excel::load()` is removed and replaced by `Excel::import($yourImport)`
39 | - `Excel::create()` is removed and replaced by `Excel::download/Excel::store($yourExport)`
40 | - `Excel::create()->string('xlsx')` is removed an replaced by `Excel::raw($yourExport, Excel::XLSX)`
41 | - 3.0 provides no convenience methods for styling, you are encouraged to use PhpSpreadsheets native methods.
42 |
43 | You can find an example upgrade for an export here: [https://github.com/SpartnerNL/Laravel-Excel/issues/1799](https://github.com/SpartnerNL/Laravel-Excel/issues/1799)
44 |
--------------------------------------------------------------------------------
/3.1/imports/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | ## :rocket: 5 minute quick start
6 |
7 | :muscle: Create an import class in `app/Imports`
8 |
9 | You may do this by using the `make:import` command.
10 |
11 | ```
12 | php artisan make:import UsersImport --model=User
13 | ```
14 |
15 | The file can be found in `app/Imports`:
16 |
17 | ::: vue
18 | .
19 | ├── app
20 | │ ├── `Imports`
21 | │ │ ├── UsersImport.php
22 | │
23 | └── composer.json
24 | :::
25 |
26 | If you prefer to create the import manually, you can create the following in `app/Imports`:
27 |
28 | ```php
29 | $row[0],
48 | 'email' => $row[1],
49 | 'password' => Hash::make($row[2]),
50 | ]);
51 | }
52 | }
53 | ```
54 |
55 | :fire: In your controller you can call this import now:
56 |
57 | ```php
58 |
59 | use App\Imports\UsersImport;
60 | use Maatwebsite\Excel\Facades\Excel;
61 | use App\Http\Controllers\Controller;
62 |
63 | class UsersController extends Controller
64 | {
65 | public function import()
66 | {
67 | Excel::import(new UsersImport, 'users.xlsx');
68 |
69 | return redirect('/')->with('success', 'All good!');
70 | }
71 | }
72 | ```
73 |
74 | :page_facing_up: Find the imported users in your database!
75 |
--------------------------------------------------------------------------------
/3.1/imports/basics.md:
--------------------------------------------------------------------------------
1 | ## Importing basics
2 |
3 | [[toc]]
4 |
5 | If you have followed the 5 minute quick start, you'll already have a `UsersImport` class.
6 |
7 | ```php
8 | $row[0],
27 | 'email' => $row[1],
28 | 'password' => Hash::make($row[2]),
29 | ]);
30 | }
31 | }
32 | ```
33 |
34 | ## Importing from default disk
35 |
36 | Passing the UsersImport object to the `Excel::import()` method will tell the package how to import the file that is passed as second parameter.
37 | The file is expected to be located in your default filesystem disk (see `config/filesystems.php`).
38 |
39 | ```php
40 | Excel::import(new UsersImport, 'users.xlsx');
41 | ```
42 |
43 | ### Importing from another disk
44 |
45 | You can specify another disk with the third parameter like your Amazon s3 disk. (see `config/filesystems.php`)
46 |
47 | ```php
48 | Excel::import(new UsersImport, 'users.xlsx', 's3');
49 | ```
50 |
51 | ## Importing uploaded files
52 |
53 | If you let your user upload the document, you can also just pass the uploaded file directly.
54 |
55 | ```php
56 | Excel::import(new UsersImport, request()->file('your_file'));
57 | ```
58 |
59 | ### Importing full path
60 |
61 | If you want to specifiy the path where your file is, without having to move it to a disk, you can directly pass that file path to the import method.
62 |
63 | ```php
64 | Excel::import(new UsersImport, storage_path('users.xlsx'));
65 | ```
66 |
67 | ## Importing to array or collection
68 |
69 | If you want to bypass the `ToArray` or `ToCollection` concerns and want to have an array of imported data in your controller (beware of performance!), you can use the `::toArray()` or `::toCollection()` method.
70 |
71 | ```php
72 | $array = Excel::toArray(new UsersImport, 'users.xlsx');
73 |
74 | $collection = Excel::toCollection(new UsersImport, 'users.xlsx');
75 | ```
76 |
77 | ## Specifying a reader type
78 |
79 | If the reader type is not detectable by the file extension, you can specify a reader type by passing it as fourth parameter.
80 |
81 | ```php
82 | Excel::import(new UsersImport, 'users.xlsx', 's3', \Maatwebsite\Excel\Excel::XLSX);
83 | ```
84 |
--------------------------------------------------------------------------------
/3.1/imports/collection.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Importing to collections
6 |
7 | [[toc]]
8 |
9 | The easiest way to start an import is to create a custom import class. We'll use a user import as example.
10 |
11 | Create a new class called `UsersImport` in `app/Imports`:
12 |
13 | ```php
14 | namespace App\Imports;
15 |
16 | use App\User;
17 | use Illuminate\Support\Collection;
18 | use Maatwebsite\Excel\Concerns\ToCollection;
19 |
20 | class UsersImport implements ToCollection
21 | {
22 | public function collection(Collection $collection)
23 | {
24 | foreach ($collection as $row)
25 | {
26 | User::create([
27 | 'name' => $row[0],
28 | ]);
29 | }
30 | }
31 | }
32 | ```
33 |
34 | The collection method will receive a collection of rows. A row is an array filled with the cell values.
35 |
36 | In case of the file having multiple sheets, the `collection()` method will be called multiple times.
37 |
38 | In your controller we can now import this:
39 |
40 | ```php
41 | public function import()
42 | {
43 | Excel::import(new UsersImport, 'users.xlsx');
44 | }
45 | ```
46 |
47 | :::warning
48 | Whatever you return in the `collection()` method will **not** be returned to the controller.
49 | :::
50 |
--------------------------------------------------------------------------------
/3.1/imports/custom-csv-settings.md:
--------------------------------------------------------------------------------
1 | # Custom CSV Settings
2 |
3 | [[toc]]
4 |
5 | By default Laravel Excel uses the defaults from the config (`config/excel.php`). You can change this by adding the `WithCustomCsvSettings` interface.
6 |
7 | ```php
8 | namespace App\Imports;
9 |
10 | use Maatwebsite\Excel\Concerns\ToModel;
11 | use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;
12 |
13 | class UsersImport implements ToModel, WithCustomCsvSettings
14 | {
15 | public function model(array $row)
16 | {
17 | return new User([
18 | 'name' => $row['0'],
19 | 'email' => $row['1']
20 | ]);
21 | }
22 |
23 | public function getCsvSettings(): array
24 | {
25 | return [
26 | 'input_encoding' => 'ISO-8859-1'
27 | ];
28 | }
29 | }
30 | ```
31 |
32 |
33 | A CSV file stores data in rows and the values in each row is separated with a separator, also known as a delimiter. Although the file is defined as Comma Separated Values, the delimiter could be anything. Delimiter requires a single character. For Tab use `"\t"`. The most common delimiters are: a comma `,`, a semicolon `;`, a tab `\t`, a space ` `, or a pipe `|`.
34 |
35 | ```php
36 | public function getCsvSettings(): array
37 | {
38 | return [
39 | 'delimiter' => "\t"
40 | ];
41 | }
42 | ```
43 |
44 | ## Available settings
45 |
46 | * `delimiter`
47 | * `enclosure`
48 | * `escape_character`
49 | * `contiguous`
50 | * `input_encoding`
51 |
--------------------------------------------------------------------------------
/3.1/imports/custom-formatting-values.md:
--------------------------------------------------------------------------------
1 | # Custom Formatting Values
2 |
3 | [[toc]]
4 |
5 | ## Value Binder
6 |
7 | By default Laravel Excel uses PhpSpreadsheet's default value binder to intelligently format a cell's value when reading it. You may override this behavior by implementing the `WithCustomValueBinder` concern and the `bindValue` method. Your import class may also extend `DefaultValueBinder` to return the default behavior.
8 |
9 | ```php
10 | namespace App\Imports;
11 |
12 | use PhpOffice\PhpSpreadsheet\Cell\Cell;
13 | use Maatwebsite\Excel\Concerns\ToModel;
14 | use PhpOffice\PhpSpreadsheet\Cell\DataType;
15 | use Maatwebsite\Excel\Concerns\WithCustomValueBinder;
16 | use PhpOffice\PhpSpreadsheet\Cell\DefaultValueBinder;
17 |
18 | class UsersImport extends DefaultValueBinder implements WithCustomValueBinder, ToModel
19 | {
20 | public function bindValue(Cell $cell, $value)
21 | {
22 | if (is_numeric($value)) {
23 | $cell->setValueExplicit($value, DataType::TYPE_NUMERIC);
24 |
25 | return true;
26 | }
27 |
28 | // else return default behavior
29 | return parent::bindValue($cell, $value);
30 | }
31 | }
32 | ```
33 |
34 | ## Available DataTypes
35 |
36 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_STRING`
37 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_FORMULA`
38 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_NUMERIC`
39 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_BOOL`
40 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_NULL`
41 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_INLINE`
42 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_ERROR`
43 |
44 | ## Disable intelligent formatting
45 |
46 | If you want to disable the intelligent formatting of values, you can extend your import class with `\PhpOffice\PhpSpreadsheet\Cell\StringValueBinder`. In this case all values are passed on as strings.
47 |
48 | ```php
49 | namespace App\Imports;
50 |
51 | use Maatwebsite\Excel\Concerns\ToModel;
52 | use Maatwebsite\Excel\Concerns\WithCustomValueBinder;
53 |
54 | class UsersImport extends \PhpOffice\PhpSpreadsheet\Cell\StringValueBinder implements WithCustomValueBinder, ToModel
55 | {
56 |
57 | }
58 | ```
59 |
60 | ## Default Value Binder
61 |
62 | If you want to use one value binder for all your imports, you can configure the default value binder in the config.
63 |
64 | In `config/excel.php`:
65 |
66 | ```php
67 | 'value_binder' => [
68 | 'default' => Maatwebsite\Excel\DefaultValueBinder::class,
69 | ],
70 | ```
71 |
--------------------------------------------------------------------------------
/3.1/imports/import-formats.md:
--------------------------------------------------------------------------------
1 | # Import formats
2 |
3 | [[toc]]
4 |
5 | By default, the import format is determined by the extension of the file. If you want
6 | to explicitly configure the import format, you can pass it through as 3rd parameter.
7 |
8 | ## XLSX
9 |
10 | ```php
11 | (new UsersImport)->import('users.xlsx', null, \Maatwebsite\Excel\Excel::XLSX);
12 | ```
13 |
14 | ## CSV
15 |
16 | ```php
17 | (new UsersImport)->import('users.csv', null, \Maatwebsite\Excel\Excel::CSV);
18 | ```
19 |
20 | ## TSV
21 |
22 | ```php
23 | (new UsersImport)->import('users.tsv', null, \Maatwebsite\Excel\Excel::TSV);
24 | ```
25 |
26 | ## ODS
27 |
28 | ```php
29 | (new UsersImport)->import('users.ods', null, \Maatwebsite\Excel\Excel::ODS);
30 | ```
31 |
32 | ## XLS
33 |
34 | ```php
35 | (new UsersImport)->import('users.xls', null, \Maatwebsite\Excel\Excel::XLS);
36 | ```
37 |
38 | ## SLK
39 |
40 | ```php
41 | (new UsersImport)->import('users.slk', null, \Maatwebsite\Excel\Excel::SLK);
42 | ```
43 |
44 | ## XML
45 |
46 | ```php
47 | (new UsersImport)->import('users.xml', null, \Maatwebsite\Excel\Excel::XML);
48 | ```
49 |
50 | ## GNUMERIC
51 |
52 | ```php
53 | (new UsersImport)->import('users.gnumeric', null, \Maatwebsite\Excel\Excel::GNUMERIC);
54 | ```
55 |
56 | ## HTML
57 |
58 | ```php
59 | (new UsersImport)->import('users.html', null, \Maatwebsite\Excel\Excel::HTML);
60 | ```
61 |
--------------------------------------------------------------------------------
/3.1/imports/importables.md:
--------------------------------------------------------------------------------
1 | # Importables
2 |
3 | [[toc]]
4 |
5 | In the previous example, we used the `Excel::import` facade to start an import.
6 |
7 | Laravel Excel also provides a `Maatwebsite\Excel\Concerns\Importable` trait, to make import classes importable.
8 |
9 | ```php
10 | namespace App\Imports;
11 |
12 | use App\User;
13 | use Maatwebsite\Excel\Concerns\ToModel;
14 | use Maatwebsite\Excel\Concerns\Importable;
15 |
16 | class UsersImport implements ToModel
17 | {
18 | use Importable;
19 |
20 | public function model(array $row)
21 | {
22 | return new User([
23 | 'name' => $row[0],
24 | ]);
25 | }
26 | }
27 | ```
28 |
29 | ## Importing
30 |
31 | We can now import without the need for the facade:
32 |
33 | ```php
34 | (new UsersImport)->import('users.xlsx', 'local', \Maatwebsite\Excel\Excel::XLSX);
35 | ```
36 |
37 | ## Queuing
38 |
39 | Or queue the import:
40 |
41 | ```php
42 | (new UsersImport)->queue('users.xlsx');
43 | ```
44 |
45 | ## To array
46 |
47 | The import can be loaded into an array :
48 |
49 | ```php
50 | $array = (new UsersImport)->toArray('users.xlsx');
51 | ```
52 |
53 | ## To collection
54 |
55 | The import can be loaded into a collection:
56 |
57 | ```php
58 | $collection = (new UsersImport)->toCollection('users.xlsx');
59 | ```
--------------------------------------------------------------------------------
/3.1/imports/mapped-cells.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Mapped Cells
6 |
7 | In case you have a more custom spreadsheet and only want to access specific **cells**, you can implement the `WithMappedCells` concern.
8 |
9 | You might have a speadsheet looking like this:
10 |
11 | |name | Patrick Brouwers|
12 | |---- |----|
13 | | email | patrick@maatwebsite.nl |
14 |
15 | We can now map `name` to `B1` and `email` to `B2`. The value of those coordinates will then be available under the given array key.
16 |
17 | ```php
18 | namespace App\Imports;
19 |
20 | use App\User;
21 | use Maatwebsite\Excel\Concerns\ToModel;
22 | use Maatwebsite\Excel\Concerns\WithMappedCells;
23 |
24 | class UsersImport implements WithMappedCells, ToModel
25 | {
26 | public function mapping(): array
27 | {
28 | return [
29 | 'name' => 'B1',
30 | 'email' => 'B2',
31 | ];
32 | }
33 |
34 | public function model(array $row)
35 | {
36 | return new User([
37 | 'name' => $row['name'],
38 | 'email' => $row['email'],
39 | ]);
40 | }
41 | }
42 | ```
43 |
44 | ::: warning
45 | This concern is not meant to map **columns**, only specific **cell** reference are allowed.
46 | :::
47 |
48 | ## Multi-dimensional Mapping
49 |
50 | In case you have repeating data in your table, e. g. a spreadsheet looking like this:
51 |
52 | | Team 1 | | Team 2| |
53 | |-|-|-|-|
54 | | Max | 2 | Peter | 3 |
55 | | Annie | 0 | Alex | 1 |
56 |
57 | you are also able to define cell coordinates in a nested array:
58 |
59 | ```php
60 | public function mapping(): array
61 | {
62 | return [
63 | 'team1' => [
64 | [
65 | 'name' => 'A2',
66 | 'score' => 'B2',
67 | ],
68 | [
69 | 'name' => 'A3',
70 | 'score' => 'B3',
71 | ],
72 | ],
73 | 'team2' => [
74 | [
75 | 'name' => 'C2',
76 | 'score' => 'D2',
77 | ],
78 | [
79 | 'name' => 'C3',
80 | 'score' => 'D3',
81 | ],
82 | ],
83 | ];
84 | }```
85 |
86 | Note that an array of the same form will be returned.
87 |
--------------------------------------------------------------------------------
/3.1/imports/progress-bar.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Progress Bar
6 |
7 | You can implement the `WithProgressBar` concern to display a progress bar when importing an Excel file via the console.
8 |
9 | For example, your import class could look like this:
10 |
11 | ```php
12 | $row[0],
30 | 'email' => $row[1],
31 | 'password' => Hash::make($row[2]),
32 | ]);
33 | }
34 | }
35 | ```
36 |
37 | In your console command, you'd use it as follows:
38 |
39 | ```php
40 | output->title('Starting import');
56 | (new UsersImport)->withOutput($this->output)->import('users.xlsx');
57 | $this->output->success('Import successful');
58 | }
59 | }
60 | ```
61 |
62 | By calling `php artisan import:excel` on the command line, your import will start.
63 | You should now see the start message, the progress bar and (when completed) the success message.
64 |
--------------------------------------------------------------------------------
/3.1/imports/start-row.md:
--------------------------------------------------------------------------------
1 | # Start row
2 |
3 | [[toc]]
4 |
5 | If you want to skip a certain number of rows during an import, you can specify the starting row by implementing the `WithStartRow` concern.
6 |
7 | ```php
8 | namespace App\Imports;
9 |
10 | use App\User;
11 | use Maatwebsite\Excel\Concerns\ToModel;
12 | use Maatwebsite\Excel\Concerns\WithStartRow;
13 |
14 | class UsersImport implements ToModel, WithStartRow
15 | {
16 | public function model(array $row)
17 | {
18 | return new User([
19 | 'name' => $row[0],
20 | ]);
21 | }
22 |
23 | public function startRow(): int
24 | {
25 | return 2;
26 | }
27 | }
28 | ```
29 |
--------------------------------------------------------------------------------
/3.1/imports/testing.md:
--------------------------------------------------------------------------------
1 | # Testing
2 |
3 | [[toc]]
4 |
5 | The Excel facade can be used to swap the importer to a fake.
6 |
7 | ## Testing imports
8 |
9 | ```php
10 | /**
11 | * @test
12 | */
13 | public function user_can_import_users()
14 | {
15 | Excel::fake();
16 |
17 | $this->actingAs($this->givenUser())
18 | ->get('/users/import/xlsx');
19 |
20 | Excel::assertImported('filename.xlsx', 'diskName');
21 |
22 | Excel::assertImported('filename.xlsx', 'diskName', function(UsersImport $import) {
23 | return true;
24 | });
25 |
26 | // When passing the callback as 2nd param, the disk will be the default disk.
27 | Excel::assertImported('filename.xlsx', function(UsersImport $import) {
28 | return true;
29 | });
30 | }
31 | ```
32 |
33 | ## Testing queuing imports
34 |
35 | ```php
36 | /**
37 | * @test
38 | */
39 | public function user_can_queue_the_users_import()
40 | {
41 | Excel::fake();
42 |
43 | $this->actingAs($this->givenUser())
44 | ->get('/users/queue/xlsx');
45 |
46 | Excel::assertQueued('filename.xlsx', 'diskName');
47 |
48 | Excel::assertQueued('filename.xlsx', 'diskName', function(UsersImport $import) {
49 | return true;
50 | });
51 |
52 | // When passing the callback as 2nd param, the disk will be the default disk.
53 | Excel::assertQueued('filename.xlsx', function(UsersImport $import) {
54 | return true;
55 | });
56 | }
57 | ```
58 |
59 | ## Testing imports with dynamic file name/path
60 |
61 | If you have dynamic naming for files or paths, you can use a regular expression to represent those while testing:
62 |
63 | ```php
64 | /**
65 | * @test
66 | */
67 | public function user_can_import_users()
68 | {
69 | Excel::fake();
70 |
71 | $this->actingAs($this->givenUser())
72 | ->get('/users/import/xlsx');
73 |
74 | // Tells the mock to use regular expressions
75 | Excel::matchByRegex();
76 | // For a given dynamic named file 'dynamic_1234_filename.xlsx'
77 | Excel::assertImported('/\w{7}_\d{4}\_\w{8}\.xlsx/', 'diskName');
78 | }
79 | ```
80 | Please note that your expression must match only one file/path. If more than one match is found, the test will fail.
81 |
--------------------------------------------------------------------------------
/4.x/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/4.x/architecture/concerns.md:
--------------------------------------------------------------------------------
1 | # Concerns
2 |
3 | [[toc]]
4 |
5 | Most of the export/import configuration is done by using **Concerns**.
6 |
7 | ## Contracts
8 |
9 | Concerns are basically just simple interfaces. Implementing them will make the object adhere to a
10 | certain contract. This contract can request specific methods that e.g. data can be passed through.
11 |
12 | For instance, the `FromCollection` requests the Export object to implement a `collection` method, that needs to return a `Collection` instance.
13 |
14 | ```php
15 | namespace App\Exports;
16 |
17 | use App\User;
18 | use Maatwebsite\Excel\Concerns\FromCollection;
19 |
20 | class UsersExport implements FromCollection
21 | {
22 | public function collection()
23 | {
24 | return User::all();
25 | }
26 | }
27 | ```
28 |
29 | ## Pointer interface
30 |
31 | In other cases it might not ask for any methods to be implemented, but merely functions as a pointer interface.
32 |
33 | For instance, the `ShouldAutoSize` concern doesn't pass on any specific information, but does tell the Export process that the columns need to be automatically sized.
34 |
35 | ```php
36 | namespace App\Exports;
37 |
38 | use App\User;
39 | use Maatwebsite\Excel\Concerns\ShouldAutoSize;
40 |
41 | class UsersExport implements ShouldAutoSize
42 | {
43 |
44 | }
45 | ```
46 |
--------------------------------------------------------------------------------
/4.x/exports/advanced.md:
--------------------------------------------------------------------------------
1 | # Advanced concepts
2 |
3 | [[toc]]
4 |
5 | ## Using PhpSpreadsheet
6 |
--------------------------------------------------------------------------------
/4.x/exports/concern-overview.md:
--------------------------------------------------------------------------------
1 | # Concern overview
2 |
--------------------------------------------------------------------------------
/4.x/exports/performance.md:
--------------------------------------------------------------------------------
1 | # Performance
2 |
3 | [[toc]]
4 |
5 | ## TLDR;
6 |
7 | 1 Data
8 |
9 | 2 Queuing
10 |
11 | 3 Cell caching
12 |
13 | ### Data
14 |
15 | Most important part of performance is the amount of data that is held in memory...
16 |
17 | ### Limiting data
18 |
19 | ```php
20 | public function query()
21 | {
22 | return User::query()
23 | ->with('role')
24 | ->select('users.id', 'users.name', 'users.email', 'role.name');
25 | }
26 | ```
27 |
28 | ### Joining data
29 |
30 | ```php
31 | public function query()
32 | {
33 | return User::query()
34 | ->innerJoin('roles')
35 | ->select('users.id', 'users.name', 'users.email', 'roles.name');
36 | }
37 | ```
38 |
39 | ### Skipping Eloquent hydration
40 |
41 | ```php
42 | public function query()
43 | {
44 | return DB
45 | ::table('users')
46 | ->innerJoin('roles')
47 | ->select('users.id', 'users.name', 'users.email', 'roles.name');
48 | }
49 | ```
50 |
51 | ### Using LazyCollections/Generators
52 |
53 | ```php
54 | public function collection()
55 | {
56 | return DB::table('users')->select('id', 'name', 'email')->lazy();
57 | }
58 | ```
59 |
60 | ## Queuing
61 |
62 | When the data set is too big for the user to wait sync, u can queue it.
63 |
64 | ```php
65 | class ExportUsers implements ShouldQueue
66 | {
67 | use Queuable;
68 |
69 | public $queue = 'long-running';
70 | public $timeout = 900;
71 |
72 | public function handle()
73 | {
74 | Excel::store(new UsersExport, 'users.xlsx');
75 | }
76 | }
77 | ```
78 |
79 | ## Cell caching
80 |
81 | By default PhpSpreadsheet keeps all cell values in memory, however when dealing with large files, this might result into memory issues. If you want to mitigate that, you can configure a cell caching driver here.
82 |
83 | When using the illuminate driver, it will store each value in the cache store. This can slow down the process, because it needs to store each value. However it will use less memory. It will automatically use your default cache store. However if you prefer to have the cell cache on a separate store, you can configure the store name here. You can use any store defined in your cache config. When leaving at "null" it will use the default store.
84 |
85 | You can use the "batch" store if you want to only persist to the store when the memory limit is reached. You can tweak the memory limit in the config.
86 |
--------------------------------------------------------------------------------
/4.x/exports/settings.md:
--------------------------------------------------------------------------------
1 | # Settings
2 |
3 | [[toc]]
4 |
5 | ## Properties
6 |
7 | By default the Worksheet properties get configured in `config/excel.php`. You can configure a default title, description, creator, etc.
8 |
9 | If you want to overrule on a per export basis, you can use the `WithProperties` concern.
10 |
11 | ```php
12 | namespace App\Exports;
13 |
14 | use Maatwebsite\Excel\Concerns\WithProperties;
15 |
16 | class UsersExport implements WithProperties
17 | {
18 | public function properties(): array
19 | {
20 | return [
21 | 'creator' => 'Patrick Brouwers',
22 | 'lastModifiedBy' => 'Patrick Brouwers',
23 | 'title' => 'Users Export',
24 | 'description' => 'Latest Users',
25 | 'subject' => 'Users',
26 | 'keywords' => 'users,export,spreadsheet',
27 | 'category' => 'Users',
28 | 'manager' => 'Patrick Brouwers',
29 | 'company' => 'Maatwebsite',
30 | ];
31 | }
32 | }
33 | ```
34 |
35 | It's not required to return all properties, you can ommit the keys you don't want to overrule.
36 |
37 | ```php
38 | public function properties(): array
39 | {
40 | return [
41 | 'creator' => 'Patrick Brouwers',
42 | ];
43 | }
44 | ```
45 |
46 | ## Custom CSV Settings
47 |
48 | By default Laravel Excel uses the defaults from the config (`config/excel.php`). You can change this by adding the `WithCustomCsvSettings` interface.
49 |
50 | ```php
51 | namespace App\Exports;
52 |
53 | use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;
54 |
55 | class UsersExport implements WithCustomCsvSettings
56 | {
57 | public function getCsvSettings(): array
58 | {
59 | return [
60 | 'delimiter' => ';'
61 | ];
62 | }
63 | }
64 | ```
65 |
66 | ### Available csv settings settings
67 |
68 | - delimiter
69 | - enclosure
70 | - line_ending
71 | - use_bom
72 | - include_separator_line
73 | - excel_compatibility
74 |
--------------------------------------------------------------------------------
/4.x/exports/testing.md:
--------------------------------------------------------------------------------
1 | # Testing
2 |
--------------------------------------------------------------------------------
/4.x/getting-started/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Introduction
6 |
7 | :rocket: Laravel Excel is intended at being Laravel-flavoured PhpSpreadsheet: a simple, but elegant wrapper around PhpSpreadsheet with the goal of simplifying
8 | exports and imports.
9 |
10 | :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.
11 |
12 | ## Laravel Excel Features
13 |
14 | * Easily export collections to Excel.
15 | * Export queries with automatic chunking for better performance.
16 | * Queue exports for better performance.
17 | * Easily export Blade views to Excel.
18 | * Easily import to collections.
19 | * Read the Excel file in chunks.
20 | * Handle the import inserts in batches.
--------------------------------------------------------------------------------
/4.x/getting-started/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | [[toc]]
4 |
5 | ## Requirements
6 |
7 | * PHP: `^7.4\|^8.0`
8 | * Laravel: `^8.0`
9 | * PhpSpreadsheet: `^1.16`
10 | * PHP extension `php_zip` enabled
11 | * PHP extension `php_xml` enabled
12 | * PHP extension `php_gd2` enabled
13 | * PHP extension `php_iconv` enabled
14 | * PHP extension `php_simplexml` enabled
15 | * PHP extension `php_xmlreader` enabled
16 | * PHP extension `php_zlib` enabled
17 |
18 | ## Installation
19 |
20 | Require this package in the `composer.json` of your Laravel project. This will download the package and _PhpSpreadsheet_.
21 |
22 | ```
23 | composer require maatwebsite/excel
24 | ```
25 |
26 | The `Maatwebsite\Excel\ExcelServiceProvider` is __auto-discovered__ and registered by default.
27 |
28 | If you want to register it yourself, add the ServiceProvider in `config/app.php`:
29 |
30 | ```php
31 | 'providers' => [
32 | /*
33 | * Package Service Providers...
34 | */
35 | Maatwebsite\Excel\ExcelServiceProvider::class,
36 | ]
37 | ```
38 |
39 | The `Excel` facade is also __auto-discovered__.
40 |
41 | If you want to add it manually, add the Facade in `config/app.php`:
42 |
43 | ```php
44 | 'aliases' => [
45 | ...
46 | 'Excel' => Maatwebsite\Excel\Facades\Excel::class,
47 | ]
48 | ```
49 |
50 | To publish the config, run the vendor publish command:
51 |
52 | ```
53 | php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider" --tag=config
54 | ```
55 |
56 | This will create a new config file named `config/excel.php`.
57 |
--------------------------------------------------------------------------------
/4.x/getting-started/license.md:
--------------------------------------------------------------------------------
1 | # License
2 |
3 | [[toc]]
4 |
5 | ## MIT
6 | Our software is open source and licensed under the [MIT license](https://choosealicense.com/licenses/mit/). You are free to use the software as you like. The code can be forked and modified, but the original copyright author should always be included!
7 |
8 | ## Postcardware
9 | According to the [postcardware](https://en.wikipedia.org/wiki/Postcardware) concept, if you use the software for your project(s) we would appreciate to receive a postcard of your hometown. Please send it to:
10 |
11 | **Maatwebsite**
12 | Markt 2
13 | 6231 LS Meerssen
14 | The Netherlands
15 |
16 | ## Support
17 |
18 | ::: warning Support
19 | We hold no liability and will provide support on a best effort basis. For more information about support please see [support](https://docs.laravel-excel.com/3.1/getting-started/support.html).
20 | :::
21 |
22 | :::tip Commercial Support
23 | :rocket: If you use the software commercially and need support urgently, we can offer this on a commercial basis. Please contact or phone +31 (0)10 744 9312.
24 | :::
25 |
--------------------------------------------------------------------------------
/4.x/getting-started/support.md:
--------------------------------------------------------------------------------
1 | # Support
2 |
3 | [[toc]]
4 |
5 | Our software is free and open source, meaning that the use of our software is optional. We hold no liability and there is no obligation to support. We will provide support on best effort basis.
6 |
7 | :::tip Commercial Support
8 | If you use the software commercially and need elaborate support or need it urgently, we can offer this on a commercial basis. Please contact or via phone +31 (0)10 744 9312.
9 | :::
10 |
11 | ## Supported Versions
12 |
13 | Versions will be supported for a limited amount of time.
14 |
15 | | Version | Laravel Version | Php Version | Support |
16 | |---- |----|----|----|
17 | | 4.x | ^8.0 | ^7.4\|^8.0 | New features |
18 | | 3.1 | ^5.8\|^6.0\|^7.0\|^8.0 | ^7.2\|^8.0 | Support till ... |
19 | | 3.0 | ^5.5 | ^7.0 | Unsupported since 31-12-2018 |
20 | | 2.1 | <=5.6 | <=7.0 | Unsupported since 15-5-2018 |
21 |
22 | ::: warning PHP version support
23 | Support for PHP versions will only be maintained until the end-of-life of that PHP version.
24 | :::
25 |
26 | ## Requesting support
27 | Before you request support, please check the following:
28 | * Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
29 | * Check to make sure your support request isn't already present within the project.
30 | * Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
31 | * Use one of the [issue templates](https://github.com/SpartnerNL/Laravel-Excel/tree/3.1/.github/ISSUE_TEMPLATE).
32 |
33 | Filling out the template is required. Issues that do not include enough information might not be picked up. Please write in English (or Dutch).
34 |
35 | Please prefix your issue with one of the following: [BUG] [PROPOSAL] [QUESTION].
36 |
37 | And please be considerate towards maintainers when raising issues.
38 |
--------------------------------------------------------------------------------
/4.x/getting-started/upgrade.md:
--------------------------------------------------------------------------------
1 | # Upgrade Guide
2 |
3 | [[toc]]
4 |
5 | ## Upgrading to 4.x from 3.1
6 |
7 | Version 4.x is backwards compatible with 3.1. Only features were added.
8 |
9 | __Additions__
10 |
11 | * Column exports
12 | * Column imports
13 |
14 | __Deprecations__
15 |
16 | * Queued exports are deprecated and will be removed in 5.x. Please check the performance documentation for the new and improved way.
17 |
18 | ## Upgrading to 3.1 from 3.0
19 |
20 | Version 3.1 is backwards compatible with 3.0. Only features were added in this release.
21 |
22 | __Additions__
23 |
24 | * Imports feature.
25 | * ChunkReading
26 | * BatchInserts
27 | * Queued imports
28 | * ToArray concern for Exports.
29 | * Custom value binders for Imports and Exports.
30 |
31 | __Removals__
32 |
33 | * `Excel::filter('chunk')` method is removed, chunk filter is automatically added when using chunk reading.
34 |
35 | ## Upgrading to 3.* from 2.1
36 |
37 | Version 3.* is not backwards compatible with 2.*. It's not possible to provide a step-by-step migration guide as it's a complete paradigm shift.
38 |
39 | __New dependencies__
40 |
41 | 3.* introduces some new dependencies.
42 |
43 | * Requires PHP 7.0 or higher.
44 | * Requires Laravel 5.5 (or higher).
45 | * Requires PhpSpreadsheet instead of PHPExcel.
46 |
47 | __Deprecations__
48 |
49 | ALL Laravel Excel 2.* methods are deprecated and will not be able to use in 3.0 .
50 |
51 | - `Excel::load()` is removed and replaced by `Excel::import($yourImport)`
52 | - `Excel::create()` is removed and replaced by `Excel::download/Excel::store($yourExport)`
53 | - `Excel::create()->string('xlsx')` is removed an replaced by `Excel::raw($yourExport, Excel::XLSX)`
54 | - 3.0 provides no convenience methods for styling, you are encouraged to use PhpSpreadsheets native methods.
55 |
56 | You can find an example upgrade for an export here: [https://github.com/SpartnerNL/Laravel-Excel/issues/1799](https://github.com/SpartnerNL/Laravel-Excel/issues/1799)
57 |
--------------------------------------------------------------------------------
/4.x/imports/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | ## :rocket: 5 minute quick start
6 |
7 | :muscle: Create an import class in `app/Imports`
8 |
9 | You may do this by using the `make:import` command.
10 |
11 | ```
12 | php artisan make:import UsersImport --model=User
13 | ```
14 |
15 | The file can be found in `app/Imports`:
16 |
17 | ::: vue
18 | .
19 | ├── app
20 | │ ├── `Imports`
21 | │ │ ├── UsersImport.php
22 | │
23 | └── composer.json
24 | :::
25 |
26 | If you prefer to create the import manually, you can create the following in `app/Imports`:
27 |
28 | ```php
29 | $row[0],
48 | 'email' => $row[1],
49 | 'password' => Hash::make($row[2]),
50 | ]);
51 | }
52 | }
53 | ```
54 |
55 | :fire: In your controller you can call this import now:
56 |
57 | ```php
58 |
59 | use App\Imports\UsersImport;
60 | use Maatwebsite\Excel\Facades\Excel;
61 | use App\Http\Controllers\Controller;
62 |
63 | class UsersController extends Controller
64 | {
65 | public function import()
66 | {
67 | Excel::import(new UsersImport, 'users.xlsx');
68 |
69 | return redirect('/')->with('success', 'All good!');
70 | }
71 | }
72 | ```
73 |
74 | :page_facing_up: Find the imported users in your database!
75 |
--------------------------------------------------------------------------------
/4.x/imports/basics.md:
--------------------------------------------------------------------------------
1 | ## Importing basics
2 |
3 | [[toc]]
4 |
5 | If you have followed the 5 minute quick start, you'll already have a `UsersImport` class.
6 |
7 | ```php
8 | $row[0],
27 | 'email' => $row[1],
28 | 'password' => Hash::make($row[2]),
29 | ]);
30 | }
31 | }
32 | ```
33 |
34 | ## Importing from default disk
35 |
36 | Passing the UsersImport object to the `Excel::import()` method, will tell the package how to import the file that is passed as second parameter.
37 | The file is expected to be located in your default filesystem disk (see `config/filesystems.php`).
38 |
39 | ```php
40 | Excel::import(new UsersImport, 'users.xlsx');
41 | ```
42 |
43 | ### Importing from another disk
44 |
45 | You can specify another disk with the third parameter like your Amazon s3 disk. (see `config/filesystems.php`)
46 |
47 | ```php
48 | Excel::import(new UsersImport, 'users.xlsx', 's3');
49 | ```
50 |
51 | ## Importing uploaded files
52 |
53 | If you let your user upload the document, you can also just pass the uploaded file directly.
54 |
55 | ```php
56 | Excel::import(new UsersImport, request()->file('your_file'));
57 | ```
58 |
59 | ### Importing full path
60 |
61 | If you want to specifiy the path where your file is, without having to move it to a disk, you can directly pass that file path to the import method.
62 |
63 | ```php
64 | Excel::import(new UsersImport, storage_path('users.xlsx'));
65 | ```
66 |
67 | ## Importing to array or collection
68 |
69 | If you want to bypass the `ToArray` or `ToCollection` concerns and want to have an array of imported data in your controller (beware of performance!), you can use the `::toArray()` or `::toCollection()` method.
70 |
71 | ```php
72 | $array = Excel::toArray(new UsersImport, 'users.xlsx');
73 |
74 | $collection = Excel::toCollection(new UsersImport, 'users.xlsx');
75 | ```
76 |
77 | ## Specifying a reader type
78 |
79 | If the reader type is not detectable by the file extension, you can specify a reader type by passing it as fourth parameter.
80 |
81 | ```php
82 | Excel::import(new UsersImport, 'users.xlsx', 's3', \Maatwebsite\Excel\Excel::XLSX);
83 | ```
84 |
--------------------------------------------------------------------------------
/4.x/imports/batch-inserts.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Batch inserts
6 |
7 | Importing a large file to Eloquent models, might quickly become a bottleneck as every row results into an insert query.
8 |
9 | With the `WithBatchInserts` concern you can limit the amount of queries done by specifying a batch size. This batch size will determine how many models will be inserted into the database in one time. This will drastically reduce the import duration.
10 |
11 | ```php
12 | namespace App\Imports;
13 |
14 | use App\User;
15 | use Maatwebsite\Excel\Concerns\ToModel;
16 | use Maatwebsite\Excel\Concerns\WithBatchInserts;
17 |
18 | class UsersImport implements ToModel, WithBatchInserts
19 | {
20 | public function model(array $row)
21 | {
22 | return new User([
23 | 'name' => $row[0],
24 | ]);
25 | }
26 |
27 | public function batchSize(): int
28 | {
29 | return 1000;
30 | }
31 | }
32 | ```
33 |
34 | :::warning ToModel
35 | This concern **only** works with the `ToModel` concern.
36 | :::
37 |
38 | :::tip Batch Size
39 | A batch size of `1000` will not be the most optimal situation for your import. Play around with this number to find the sweet spot.
40 | :::
41 |
42 | ## Batch upserts
43 |
44 | For batch upserts, you can additionally implement the `WithUpserts` concern.
45 |
46 | ```php
47 | class UsersImport implements ToModel, WithBatchInserts, WithUpserts
48 | {
49 | public function model(array $row)
50 | {
51 | return new User([
52 | 'name' => $row[0],
53 | ]);
54 | }
55 |
56 | public function batchSize(): int
57 | {
58 | return 1000;
59 | }
60 |
61 | public function uniqueBy()
62 | {
63 | return 'email';
64 | }
65 | }
66 | ```
67 |
68 | In the example above, if a user already exists with the same email, the row will be updated instead. Behind the scenes, this feature uses the Laravel `upsert` method and the `uniqueBy` method is used for the second argument of the `upsert` method, which lists the column(s) that uniquely identify records within the associated table.
69 |
70 | :::warning
71 | All databases except SQL Server require the `uniqueBy` columns to have a "primary" or "unique" index.
72 | :::
73 |
--------------------------------------------------------------------------------
/4.x/imports/collection.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Importing to collections
6 |
7 | [[toc]]
8 |
9 | The easiest way to start an import is to create a custom import class. We'll use a user import as example.
10 |
11 | Create a new class called `UsersImport` in `app/Imports`:
12 |
13 | ```php
14 | namespace App\Imports;
15 |
16 | use App\User;
17 | use Illuminate\Support\Collection;
18 | use Maatwebsite\Excel\Concerns\ToCollection;
19 |
20 | class UsersImport implements ToCollection
21 | {
22 | public function collection(Collection $rows)
23 | {
24 | foreach ($rows as $row)
25 | {
26 | User::create([
27 | 'name' => $row[0],
28 | ]);
29 | }
30 | }
31 | }
32 | ```
33 |
34 | The collection method will receive a collection of rows. A row is an array filled with the cell values.
35 |
36 | In case of the file having multiple sheets, the `collection()` method will be called multiple times.
37 |
38 | In your controller we can now import this:
39 |
40 | ```php
41 | public function import()
42 | {
43 | Excel::import(new UsersImport, 'users.xlsx');
44 | }
45 | ```
46 |
47 | :::warning
48 | Whatever you return in the `collection()` method will **not** be returned to the controller.
49 | :::
50 |
--------------------------------------------------------------------------------
/4.x/imports/custom-csv-settings.md:
--------------------------------------------------------------------------------
1 | # Custom CSV Settings
2 |
3 | [[toc]]
4 |
5 | By default Laravel Excel uses the defaults from the config (`config/excel.php`). You can change this by adding the `WithCustomCsvSettings` interface.
6 |
7 | ```php
8 | namespace App\Imports;
9 |
10 | use Maatwebsite\Excel\Concerns\ToModel;
11 | use Maatwebsite\Excel\Concerns\WithCustomCsvSettings;
12 |
13 | class UsersImport implements ToModel, WithCustomCsvSettings
14 | {
15 | public function model(array $row)
16 | {
17 | return new User([
18 | 'name' => $row['0'],
19 | 'email' => $row['1']
20 | ]);
21 | }
22 |
23 | public function getCsvSettings(): array
24 | {
25 | return [
26 | 'input_encoding' => 'ISO-8859-1'
27 | ];
28 | }
29 | }
30 | ```
31 |
32 |
33 | Delimiter requires a single character. For Tab use `"\t"`
34 |
35 | ```php
36 | public function getCsvSettings(): array
37 | {
38 | return [
39 | 'delimiter' => "\t"
40 | ];
41 | }
42 | ```
43 |
44 | ## Available settings
45 |
46 | * `delimiter`
47 | * `enclosure`
48 | * `escape_character`
49 | * `contiguous`
50 | * `input_encoding`
51 |
--------------------------------------------------------------------------------
/4.x/imports/custom-formatting-values.md:
--------------------------------------------------------------------------------
1 | # Custom Formatting Values
2 |
3 | [[toc]]
4 |
5 | ## Value Binder
6 |
7 | By default Laravel Excel uses PhpSpreadsheet's default value binder to intelligently format a cell's value when reading it. You may override this behavior by implementing the `WithCustomValueBinder` concern and the `bindValue` method. Your import class may also extend `DefaultValueBinder` to return the default behavior.
8 |
9 | ```php
10 | namespace App\Imports;
11 |
12 | use PhpOffice\PhpSpreadsheet\Cell\Cell;
13 | use Maatwebsite\Excel\Concerns\ToModel;
14 | use PhpOffice\PhpSpreadsheet\Cell\DataType;
15 | use Maatwebsite\Excel\Concerns\WithCustomValueBinder;
16 | use PhpOffice\PhpSpreadsheet\Cell\DefaultValueBinder;
17 |
18 | class UsersImport extends DefaultValueBinder implements WithCustomValueBinder, ToModel
19 | {
20 | public function bindValue(Cell $cell, $value)
21 | {
22 | if (is_numeric($value)) {
23 | $cell->setValueExplicit($value, DataType::TYPE_NUMERIC);
24 |
25 | return true;
26 | }
27 |
28 | // else return default behavior
29 | return parent::bindValue($cell, $value);
30 | }
31 | }
32 | ```
33 |
34 | ## Available DataTypes
35 |
36 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_STRING`
37 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_FORMULA`
38 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_NUMERIC`
39 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_BOOL`
40 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_NULL`
41 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_INLINE`
42 | * `PhpOffice\PhpSpreadsheet\Cell\DataType::TYPE_ERROR`
43 |
44 | ## Disable intelligent formatting
45 |
46 | If you want to disable the intelligent formatting of values, you can extend your import class with `\PhpOffice\PhpSpreadsheet\Cell\StringValueBinder`. In this case all values are passed on as strings.
47 |
48 | ```php
49 | namespace App\Imports;
50 |
51 | use Maatwebsite\Excel\Concerns\ToModel;
52 | use Maatwebsite\Excel\Concerns\WithCustomValueBinder;
53 |
54 | class UsersImport extends \PhpOffice\PhpSpreadsheet\Cell\StringValueBinder implements WithCustomValueBinder, ToModel
55 | {
56 |
57 | }
58 | ```
59 |
60 | ## Default Value Binder
61 |
62 | If you want to use one value binder for all your imports, you can configure the default value binder in the config.
63 |
64 | In `config/excel.php`:
65 |
66 | ```php
67 | 'value_binder' => [
68 | 'default' => Maatwebsite\Excel\DefaultValueBinder::class,
69 | ],
70 | ```
71 |
--------------------------------------------------------------------------------
/4.x/imports/import-formats.md:
--------------------------------------------------------------------------------
1 | # Import formats
2 |
3 | [[toc]]
4 |
5 | By default, the import format is determined by the extension of the file. If you want
6 | to explicitly configure the import format, you can pass it through as 3rd parameter.
7 |
8 | ## XLSX
9 |
10 | ```php
11 | (new UsersImport)->import('users.xlsx', null, \Maatwebsite\Excel\Excel::XLSX);
12 | ```
13 |
14 | ## CSV
15 |
16 | ```php
17 | (new UsersImport)->import('users.csv', null, \Maatwebsite\Excel\Excel::CSV);
18 | ```
19 |
20 | ## TSV
21 |
22 | ```php
23 | (new UsersImport)->import('users.tsv', null, \Maatwebsite\Excel\Excel::TSV);
24 | ```
25 |
26 | ## ODS
27 |
28 | ```php
29 | (new UsersImport)->import('users.ods', null, \Maatwebsite\Excel\Excel::ODS);
30 | ```
31 |
32 | ## XLS
33 |
34 | ```php
35 | (new UsersImport)->import('users.xls', null, \Maatwebsite\Excel\Excel::XLS);
36 | ```
37 |
38 | ## SLK
39 |
40 | ```php
41 | (new UsersImport)->import('users.slk', null, \Maatwebsite\Excel\Excel::SLK);
42 | ```
43 |
44 | ## XML
45 |
46 | ```php
47 | (new UsersImport)->import('users.xml', null, \Maatwebsite\Excel\Excel::XML);
48 | ```
49 |
50 | ## GNUMERIC
51 |
52 | ```php
53 | (new UsersImport)->import('users.gnumeric', null, \Maatwebsite\Excel\Excel::GNUMERIC);
54 | ```
55 |
56 | ## HTML
57 |
58 | ```php
59 | (new UsersImport)->import('users.html', null, \Maatwebsite\Excel\Excel::HTML);
60 | ```
61 |
--------------------------------------------------------------------------------
/4.x/imports/importables.md:
--------------------------------------------------------------------------------
1 | # Importables
2 |
3 | [[toc]]
4 |
5 | In the previous example, we used the `Excel::import` facade to start an import.
6 |
7 | Laravel Excel also provides a `Maatwebsite\Excel\Concerns\Importable` trait, to make import classes importable.
8 |
9 | ```php
10 | namespace App\Imports;
11 |
12 | use App\User;
13 | use Maatwebsite\Excel\Concerns\ToModel;
14 | use Maatwebsite\Excel\Concerns\Importable;
15 |
16 | class UsersImport implements ToModel
17 | {
18 | use Importable;
19 |
20 | public function model(array $row)
21 | {
22 | return new User([
23 | 'name' => $row[0],
24 | ]);
25 | }
26 | }
27 | ```
28 |
29 | ## Importing
30 |
31 | We can now import without the need for the facade:
32 |
33 | ```php
34 | (new UsersImport)->import('users.xlsx', 'local', \Maatwebsite\Excel\Excel::XLSX);
35 | ```
36 |
37 | ## Queuing
38 |
39 | Or queue the import:
40 |
41 | ```php
42 | (new UsersImport)->queue('users.xlsx');
43 | ```
44 |
45 | ## To array
46 |
47 | The import can be loaded into an array :
48 |
49 | ```php
50 | $array = (new UsersImport)->toArray('users.xlsx');
51 | ```
52 |
53 | ## To collection
54 |
55 | The import can be loaded into a collection:
56 |
57 | ```php
58 | $collection = (new UsersImport)->toCollection('users.xlsx');
59 | ```
--------------------------------------------------------------------------------
/4.x/imports/mapped-cells.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Mapped Cells
6 |
7 | In case you have a more custom spreadsheet and only want to access specific **cells**, you can implement the `WithMappedCells` concern.
8 |
9 | You might have a speadsheet looking like this:
10 |
11 | |name | Patrick Brouwers|
12 | |---- |----|
13 | | email | patrick@maatwebsite.nl |
14 |
15 | We can now map `name` to `B1` and `email` to `B2`. The value of those coordinates will then be available under the given array key.
16 |
17 | ```php
18 | namespace App\Imports;
19 |
20 | use App\User;
21 | use Maatwebsite\Excel\Concerns\ToModel;
22 | use Maatwebsite\Excel\Concerns\WithMappedCells;
23 |
24 | class UsersImport implements WithMappedCells, ToModel
25 | {
26 | public function mapping(): array
27 | {
28 | return [
29 | 'name' => 'B1',
30 | 'email' => 'B2',
31 | ];
32 | }
33 |
34 | public function model(array $row)
35 | {
36 | return new User([
37 | 'name' => $row['name'],
38 | 'email' => $row['email'],
39 | ]);
40 | }
41 | }
42 | ```
43 |
44 | ::: warning
45 | This concern is not meant to map **columns**, only specific **cell** reference are allowed.
46 | :::
47 |
48 | ## Multi-demensional Mapping
49 |
50 | In case you have repeating data in your table, e. g. a spreadsheet looking like this:
51 |
52 | | Team 1 | | Team 2| |
53 | |-|-|-|-|
54 | | Max | 2 | Peter | 3 |
55 | | Annie | 0 | Alex | 1 |
56 |
57 | you are also able to define cell coordinates in a nested array:
58 |
59 | ```php
60 | public function mapping(): array
61 | {
62 | return [
63 | 'team1' => [
64 | [
65 | 'name' => 'A2',
66 | 'score' => 'B2',
67 | ],
68 | [
69 | 'name' => 'A3',
70 | 'score' => 'B3',
71 | ],
72 | ],
73 | 'team2' => [
74 | [
75 | 'name' => 'C2',
76 | 'score' => 'D2',
77 | ],
78 | [
79 | 'name' => 'C3',
80 | 'score' => 'D3',
81 | ],
82 | ],
83 | ];
84 | }```
85 |
86 | Note that an array of the same form will be returned.
87 |
--------------------------------------------------------------------------------
/4.x/imports/progress-bar.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Progress Bar
6 |
7 | You can implement the `WithProgressBar` concern to display a progress bar when importing an Excel file via the console.
8 |
9 | For example, your import class could look like this:
10 |
11 | ```php
12 | $row[0],
30 | 'email' => $row[1],
31 | 'password' => Hash::make($row[2]),
32 | ]);
33 | }
34 | }
35 | ```
36 |
37 | In your console command, you'd use it as follows:
38 |
39 | ```php
40 | output->title('Starting import');
56 | (new UsersImport)->withOutput($this->output)->import('users.xlsx');
57 | $this->output->success('Import successful');
58 | }
59 | }
60 | ```
61 |
62 | By calling `php artisan import:excel` on the command line, your import will start.
63 | You should now see the start message, the progress bar and (when completed) the success message.
64 |
--------------------------------------------------------------------------------
/4.x/imports/testing.md:
--------------------------------------------------------------------------------
1 | # Testing
2 |
3 | [[toc]]
4 |
5 | The Excel facade can be used to swap the importer to a fake.
6 |
7 | ## Testing imports
8 |
9 | ```php
10 | /**
11 | * @test
12 | */
13 | public function user_can_import_users()
14 | {
15 | Excel::fake();
16 |
17 | $this->actingAs($this->givenUser())
18 | ->get('/users/import/xlsx');
19 |
20 | Excel::assertImported('filename.xlsx', 'diskName');
21 |
22 | Excel::assertImported('filename.xlsx', 'diskName', function(UsersImport $import) {
23 | return true;
24 | });
25 |
26 | // When passing the callback as 2nd param, the disk will be the default disk.
27 | Excel::assertImported('filename.xlsx', function(UsersImport $import) {
28 | return true;
29 | });
30 | }
31 | ```
32 |
33 | ## Testing queuing imports
34 |
35 | ```php
36 | /**
37 | * @test
38 | */
39 | public function user_can_queue_the_users_import()
40 | {
41 | Excel::fake();
42 |
43 | $this->actingAs($this->givenUser())
44 | ->get('/users/queue/xlsx');
45 |
46 | Excel::assertQueued('filename.xlsx', 'diskName');
47 |
48 | Excel::assertQueued('filename.xlsx', 'diskName', function(UsersImport $import) {
49 | return true;
50 | });
51 |
52 | // When passing the callback as 2nd param, the disk will be the default disk.
53 | Excel::assertQueued('filename.xlsx', function(UsersImport $import) {
54 | return true;
55 | });
56 | }
57 | ```
58 |
59 | ## Testing imports with dynamic file name/path
60 |
61 | If you have dynamic naming for files or paths, you can use a regular expression to represent those while testing:
62 |
63 | ```php
64 | /**
65 | * @test
66 | */
67 | public function user_can_import_users()
68 | {
69 | Excel::fake();
70 |
71 | $this->actingAs($this->givenUser())
72 | ->get('/users/import/xlsx');
73 |
74 | // Tells the mock to use regular expressions
75 | Excel::matchByRegex();
76 | // For a given dynamic named file 'dynamic_1234_filename.xlsx'
77 | Excel::assertImported('/\w{7}_\d{4}\_\w{8}\.xlsx/', 'diskName');
78 | }
79 | ```
80 | Please note that your expression must match only one file/path. If more than one match is found, the test will fail.
81 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/csv/1.0/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/csv/1.0/exports/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # :rocket: 5 minute quick start
6 |
7 | [[toc]]
8 |
9 | :muscle: Create an export class in `app/Exports`
10 |
11 | ::: vue
12 | .
13 | ├── app
14 | │ ├── `Exports`
15 | │ │ ├── UsersExport.php
16 | :::
17 |
18 | ```php
19 | namespace App\Exports;
20 |
21 | use App\User;
22 | use Maatwebsite\LaravelCsv\Concerns\FromCollection;
23 |
24 | class UsersExport implements FromCollection
25 | {
26 | public function collection()
27 | {
28 | return User::all();
29 | }
30 | }
31 | ```
32 |
33 | :fire: In your controller you can call this export now:
34 |
35 | ```php
36 |
37 | use App\Exports\UsersExport;
38 | use App\Http\Controllers\Controller;
39 | use Maatwebsite\LaravelCsv\Facades\Csv;
40 |
41 | class UsersController extends Controller
42 | {
43 | public function export()
44 | {
45 | return Csv::download(new UsersExport, 'users.csv');
46 | }
47 | }
48 | ```
49 |
50 | :page_facing_up: Find your `users.csv` in your downloads folder!
--------------------------------------------------------------------------------
/csv/1.0/exports/collection.md:
--------------------------------------------------------------------------------
1 | # Exporting collections
2 |
3 | [[toc]]
4 |
5 | Create a new class called `UsersExport` in `app/Exports`:
6 |
7 | ::: vue
8 | .
9 | ├── app
10 | │ ├── `Exports`
11 | │ │ ├── UsersExport.php
12 | :::
13 |
14 | ```php
15 | [
13 | 'delimiter' => ',',
14 | 'enclosure' => '"',
15 | 'line_ending' => "\n",
16 | ],
17 | ];
18 | ```
19 |
20 | The default values match the default values used by League/Csv.
21 |
22 | __NB:__ The _delimiter_ and _enclosure_ both must be exactly one character in length.
23 |
24 | ## Query chunk size
25 | You can also customize the chunk size, which impacts performance for FromQuery concerns, as follows:
26 |
27 | ```php
28 | [
32 | 'chunk_size' => 10000,
33 | ],
34 | ];
35 | ```
36 |
37 | ::: warning
38 | You might need to find the sweet spot for your application, however we've experienced chunks bigger than 20000 to become slower.
39 | :::
--------------------------------------------------------------------------------
/csv/1.0/exports/exportables.md:
--------------------------------------------------------------------------------
1 | # Exportables
2 |
3 | [[toc]]
4 |
5 | In the previous example, we used the `Csv::download` facade to start an export.
6 |
7 | Laravel CSV also provides a `Maatwebsite\LaravelCsv\Concerns\Exportable` trait, to make export classes exportable.
8 |
9 | ```php
10 | download('users.csv');
33 | ```
34 |
35 | You can also pass optional headers to the download method:
36 |
37 | ```php
38 | return (new UsersExport)->download('users.csv', ['Content-Type' => 'text/csv']);
39 | ```
40 |
41 | Or store it on a disk:
42 |
43 | ```php
44 | return (new UsersExport)->store('users.csv', 's3');
45 | ```
46 |
47 | You can also pass options to the disk if you like:
48 |
49 | ```php
50 | return (new UsersExport)->store('users.csv', 's3', 'public');
51 | ```
52 |
53 | ## Responsable
54 |
55 | The previous (download) example can be made even shorter when adding Laravel's `Responsable` interface to the export class:
56 |
57 | ```php
58 | namespace App\Exports;
59 |
60 | use App\User;
61 | use Illuminate\Contracts\Support\Responsable;
62 | use Maatwebsite\LaravelCsv\Concerns\Exportable;
63 | use Maatwebsite\LaravelCsv\Concerns\FromCollection;
64 |
65 | class UsersExport implements FromCollection, Responsable
66 | {
67 | use Exportable;
68 |
69 | /**
70 | * It's required to define the fileName within
71 | * the export class when making use of Responsable.
72 | */
73 | private $fileName = 'users.csv';
74 |
75 | /**
76 | * Optional headers
77 | */
78 | private $headers = [
79 | 'Content-Type' => 'text/csv',
80 | ];
81 |
82 | public function collection()
83 | {
84 | return User::all();
85 | }
86 | }
87 | ```
88 |
89 | You can now easily return the export class, without the need of calling `->download()`.
90 |
91 | ```php
92 | return new UsersExport();
93 | ```
94 |
--------------------------------------------------------------------------------
/csv/1.0/exports/from-query.md:
--------------------------------------------------------------------------------
1 | # From Query
2 |
3 | [[toc]]
4 |
5 | Create a new class called `UsersExport` in `app/Exports`:
6 |
7 | ::: vue
8 | .
9 | ├── app
10 | │ ├── `Exports`
11 | │ │ ├── UsersExport.php
12 | :::
13 |
14 | ```php
15 | 10000,
58 | ];
59 | ```
60 |
--------------------------------------------------------------------------------
/csv/1.0/exports/heading-row.md:
--------------------------------------------------------------------------------
1 | # Heading row
2 |
3 | [[toc]]
4 |
5 |
6 | ## Adding a heading row
7 |
8 | A heading row can easily be added by adding the `WithHeadings` concern. The heading row will be added
9 | as very first row of the file.
10 |
11 | ```php
12 |
13 | use Maatwebsite\Excel\Concerns\FromQuery;
14 | use Maatwebsite\Excel\Concerns\WithHeadings;
15 |
16 | class InvoicesExport implements FromQuery, WithHeadings
17 |
18 | public function headings(): array
19 | {
20 | return [
21 | '#',
22 | 'Date',
23 | ];
24 | }
25 | }
26 | ```
27 |
28 | ## Multiple rows
29 | It is possible to return multiple heading rows. These will be added as the first x rows.
30 | Example:
31 | ```php
32 |
33 | use Maatwebsite\Excel\Concerns\FromQuery;
34 | use Maatwebsite\Excel\Concerns\WithHeadings;
35 |
36 | class InvoicesExport implements FromQuery, WithHeadings
37 |
38 | public function headings(): array
39 | {
40 | return [
41 | ['#', 'date'],
42 | ['Amount', 'Status'],
43 | ];
44 | }
45 | }
46 | ```
47 |
48 | This would result in the following export:
49 | ```
50 | "#","date"
51 | "amount","status"
52 | ```
--------------------------------------------------------------------------------
/csv/1.0/exports/mapping.md:
--------------------------------------------------------------------------------
1 | # Mapping data
2 |
3 | [[toc]]
4 |
5 | ## Mapping rows
6 |
7 | By adding `WithMapping` you map the data that needs to be added as row. This way you have control over the actual source for each column.
8 | In case of using the Eloquent query builder:
9 |
10 | ```php
11 |
12 | use App\Invoice;
13 | use Maatwebsite\LaravelCsv\Concerns\FromQuery;
14 | use Maatwebsite\LaravelCsv\Concerns\WithMapping;
15 |
16 | class InvoicesExport implements FromQuery, WithMapping
17 |
18 | /**
19 | * @var Invoice $invoice
20 | */
21 | public function map($invoice): array
22 | {
23 | return [
24 | $invoice->invoice_number,
25 | $invoice->created_at,
26 | ];
27 | }
28 | }
29 | ```
30 |
31 | ## Multiple rows
32 | When mapping data, you can also return multiple rows.
33 |
34 | Example:
35 | ```php
36 |
37 | use Maatwebsite\Excel\Concerns\FromQuery;
38 | use Maatwebsite\Excel\Concerns\WithHeadings;
39 |
40 | class InvoicesExport implements FromQuery, WithHeadings, WithMapping
41 |
42 | /**
43 | * @var Invoice $invoice
44 | */
45 | public function map($invoice): array
46 | {
47 | return [
48 | [
49 | $invoice->invoice_number,
50 | $invoice->created_at,
51 | ],
52 | [
53 | $invoice->order->amount,
54 | $invoice->order->status,
55 | ]
56 | ];
57 | }
58 | }
59 | ```
60 |
61 | This would result in the following export:
62 | ```
63 | "#","date"
64 | "amount","status"
65 | "201901564","2019-07-04"
66 | "350","paid"
67 | "201901566","2019-07-03"
68 | "645","pending"
69 | "201901568","2019-07-02"
70 | "100","paid"
71 | "201901458","2019-07-01"
72 | "999","cancelled"
73 | ```
--------------------------------------------------------------------------------
/csv/1.0/exports/queued.md:
--------------------------------------------------------------------------------
1 | # Queued
2 |
3 | [[toc]]
4 |
5 | In case you are working with a lot of data, it might be wise to queue the entire process.
6 |
7 | Create a new class called `UsersExport` in `app/Exports`:
8 |
9 | ::: vue
10 | .
11 | ├── app
12 | │ ├── `Exports`
13 | │ │ ├── UsersExport.php
14 | :::
15 |
16 | ```php
17 | chain([
65 | new AfterQueueExportJob(),
66 | ]);
67 | }
68 | }
69 | ```
70 |
71 | If you use the `store` method instead of the `queue` method, but the export class implements `ShouldQueue`,
72 | then `Csv::store` will still return a `PendingDispatch` instance, so this will still work:
73 | ```php
74 | use App\Exports\UsersExport;
75 | use App\Http\Controllers\Controller;
76 | use Maatwebsite\LaravelCsv\Facades\Csv;
77 |
78 | class UsersController extends Controller
79 | {
80 | public function export()
81 | {
82 | $queuedJob = Csv::store(new UsersExport, 'users.csv');
83 | $queuedJob->chain([
84 | new AfterQueueExportJob(),
85 | ]);
86 | }
87 | }
88 | ```
--------------------------------------------------------------------------------
/csv/1.0/exports/store.md:
--------------------------------------------------------------------------------
1 | # Storing exports on disk
2 |
3 | [[toc]]
4 |
5 | The store functionality uses the default Storage disk. It's possible to choose a different disk as well as custom disk options.
6 |
7 | In your controller you can customize the export like this:
8 |
9 | ```php
10 |
11 | use App\Exports\UsersExport;
12 | use App\Http\Controllers\Controller;
13 | use Maatwebsite\LaravelCsv\Facades\Csv;
14 |
15 | class UsersController extends Controller
16 | {
17 | public function export()
18 | {
19 | return Csv::store(
20 | new UsersExport,
21 | 'users.csv',
22 | 's3',
23 | 'public'
24 | );
25 | }
26 | }
27 | ```
28 |
29 | ## Disk options
30 | The disk option accepts:
31 | * disk name (_string_)
32 | * visibility option (_string_)
33 | * more advanced options (_array_)
34 |
--------------------------------------------------------------------------------
/csv/1.0/getting-started/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | pageClass: no-toc
3 | ---
4 |
5 | # Introduction
6 |
7 | :rocket: Laravel CSV is intended to be a Laravel-flavoured [League/Csv](https://csv.thephpleague.com/): a simple, but elegant wrapper around League/Csv with the goal of simplifying
8 | large exports.
9 |
10 | :fire: [League/Csv](https://csv.thephpleague.com/) is designed for developers who want to deal with CSV data using modern code and without the high levels of bootstrap and low levels of usefulness provided by existing core functions or third party-code.
11 |
12 | ## Laravel CSV Features
13 |
14 | * Easily export collections to CSV.
15 | * Export queries with automatic chunking for better performance.
16 | * Queue exports for better performance.
17 | * Download or store exports.
18 |
--------------------------------------------------------------------------------
/csv/1.0/getting-started/contributing.md:
--------------------------------------------------------------------------------
1 | # Contributing
2 |
3 | [[toc]]
4 |
5 | Please read and understand the contribution guide before creating an issue or pull request.
6 |
7 | ## Important Links
8 |
9 | - [Docs](https://docs.laravel-excel.com/)
10 | - [Issue tracker](https://github.com/SpartnerNL/Laravel-Csv/issues)
11 | - [Support](/csv/1.0/getting-started/support.html)
12 |
13 | ## Etiquette
14 |
15 | This project is an open source project, and as such, the maintainers use their free time to build and maintain it.
16 | The code is freely available and can be used, forked and modified.
17 |
18 | Please be considerate towards maintainers when raising issues or presenting pull requests.
19 |
20 | It's the duty of the maintainer to ensure that all submissions to the project are of sufficient
21 | quality to benefit the project. Many developers have different skill sets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used.
22 |
23 | ## Viability
24 |
25 | When requesting or submitting new features, first consider whether it might be useful to others. Open
26 | source projects are used by many developers, who may have entirely different needs to your own. Think about
27 | whether or not your feature is likely to be used by other users of the project.
28 |
29 | ## How to submit changes?
30 |
31 | - Check the codebase to ensure that your feature doesn't already exist.
32 | - Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
33 | - Use the [pull request template](https://github.com/SpartnerNL/Laravel-Excel/blob/3.1/.github/PULL_REQUEST_TEMPLATE.md).
34 |
35 | ## How to report a bug?
36 |
37 | - Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
38 | - Check to make sure your bug report isn't already present within the project.
39 | - Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
40 | - Check the pull requests tab to ensure that the feature isn't already in progress.
41 | - Use the [bug template](https://github.com/SpartnerNL/Laravel-Excel/blob/3.1/.github/ISSUE_TEMPLATE/1_Bug_report.md).
42 |
43 | ## Requirements
44 |
45 | - **[PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)**. - Style will get automatically fixed by StyleCI.
46 | - **Add tests backing up your change!** - You can run the test by running `vendor/bin/phpunit`
47 | - **Document any change in behaviour** - Documentation is located in the [https://github.com/SpartnerNL/laravel-excel-docs](https://github.com/SpartnerNL/laravel-excel-docs)
48 | - **One feature per Pull Request**
49 | - **Add meaningful commit messages**
50 |
--------------------------------------------------------------------------------
/csv/1.0/getting-started/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | [[toc]]
4 |
5 | ## Requirements
6 |
7 | * PHP: `^7.2`
8 | * Laravel: `^5.8`
9 | * League/Csv: `^9.0`
10 |
11 | ## Installation
12 |
13 | Require Laravel CSV in the `composer.json` of your Laravel project. This will download the package and _League/Csv_.
14 |
15 | ```
16 | composer require maatwebsite/laravel-csv
17 | ```
18 |
19 | The `Maatwebsite\LaravelCsv\LaravelCsvServiceProvider` is __auto-discovered__ and registered by default.
20 |
21 | If you want to register it yourself, add the ServiceProvider in `config/app.php`:
22 |
23 | ```php
24 | 'providers' => [
25 | /*
26 | * Package Service Providers...
27 | */
28 | Maatwebsite\LaravelCsv\LaravelCsvServiceProvider::class,
29 | ]
30 | ```
31 |
32 | The `Csv` facade is also __auto-discovered__.
33 |
34 | If you want to add it manually, add the Facade in `config/app.php`:
35 |
36 | ```php
37 | 'aliases' => [
38 | ...
39 | 'Csv' => Maatwebsite\LaravelCsv\Facades\Csv::class,
40 | ]
41 | ```
42 |
43 | To publish the config, run the `vendor:publish` command:
44 |
45 | ```
46 | php artisan vendor:publish --provider="Maatwebsite\LaravelCsv\LaravelCsvServiceProvider"
47 | ```
48 |
49 | This will create a new config file named `config/csv.php`.
50 |
--------------------------------------------------------------------------------
/csv/1.0/getting-started/license.md:
--------------------------------------------------------------------------------
1 | # License
2 |
3 | [[toc]]
4 |
5 | ## MIT
6 | Our software is open source and licensed under the [MIT license](https://choosealicense.com/licenses/mit/). You are free to use the software as you like. The code can be forked and modified, but the original copyright author should always be included!
7 |
8 | ## Postcardware
9 | According to the [postcardware](https://en.wikipedia.org/wiki/Postcardware) concept, if you use the software for your project(s) we would appreciate to receive a postcard of your hometown. Please send it to:
10 |
11 | **Maatwebsite**
12 | Markt 2
13 | 6231 LS Meerssen
14 | The Netherlands
15 |
16 | ## Support
17 |
18 | ::: warning Support
19 | We hold no liability and will provide support on a best effort basis. For more information about support please see [support](/csv/1.0/getting-started/support.html).
20 | :::
21 |
22 | :::tip Commercial Support
23 | :rocket: If you use the software commercially and need support urgently, we can offer this on a commercial basis. Please contact or phone +31 (0)10 744 9312.
24 | :::
25 |
--------------------------------------------------------------------------------
/csv/1.0/getting-started/support.md:
--------------------------------------------------------------------------------
1 | # Support
2 |
3 | [[toc]]
4 |
5 | Our software is free and open source, meaning that the use of our software is optional. We hold no liability and there is no obligation to support. We will provide support on a best effort basis.
6 |
7 | :::tip Commercial Support
8 | If you use the software commercially and need elaborate support or need it urgently, we can offer this on a commercial basis. Please contact or via phone +31 (0)10 744 9312.
9 | :::
10 |
11 | ## Supported Versions
12 |
13 | Versions will be supported for a limited amount of time.
14 |
15 | | Version | Laravel Version | Php Version | Support |
16 | |---- |----|----|----|
17 | | 1.0 | ^5.8 | ^7.2 | New features |
18 |
19 | ::: warning PHP version support
20 | Support for PHP versions will only be maintained for a period of six months beyond the end-of-life of that PHP version.
21 | :::
22 |
23 | ## Requesting support
24 | Before you request support, please check the following:
25 | * Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
26 | * Check to make sure your support request isn't already present within the project.
27 | * Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
28 | * Use one of the [issue templates](https://github.com/SpartnerNL/Laravel-Excel/tree/3.1/.github/ISSUE_TEMPLATE).
29 |
30 | Filling out the template is required. Issues that do not include enough information might not be picked up. Please write in English (or Dutch).
31 |
32 | Please prefix your issue with one of the following: [BUG] [PROPOSAL] [QUESTION].
33 |
34 | And please be considerate towards maintainers when raising issues.
35 |
--------------------------------------------------------------------------------
/csv/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/nova/1.0/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/nova/1.1/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/nova/1.x/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/nova/1.x/exports/README.md:
--------------------------------------------------------------------------------
1 | ## :rocket: 5 minute quick start
2 |
3 | :bulb: Require this package in the `composer.json` of your Laravel project. This will download the package and Laravel Excel.
4 |
5 | ```
6 | composer require maatwebsite/laravel-nova-excel
7 | ```
8 |
9 | :muscle: Go to your Nova resource. As example we'll use the `app/Nova/User.php`. Add `Maatwebsite\LaravelNovaExcel\Actions\DownloadExcel` action to your `actions()` list.
10 |
11 | ```php
12 | askForFilename()
21 | ];
22 | }
23 | ```
24 |
25 | The user will now be prompted with the question how he wants to name the file.
26 |
27 | 
28 |
29 | :bulb: If you want to have a custom label, you can simply pass that via the method: `(new DownloadExcel())->askForFilename(__('Filename for your export'))`
30 |
31 | :::warning
32 | When not specifying any default writer type, the user can control the file type by typing an extensions in the filename.
33 | E.g. `users.csv` will result into an Csv document. If the user doesn't specify any extension, it will default to `.xlsx`.
34 |
35 | If you don't want the user to have this kind of control,make sure to use `withWriterType()`.
36 | :::
37 |
38 | ## Asking the user for the writer type
39 |
40 | If you want your users to choose their own writer type when exporting a resource, you can use the `askForWriterType()` interaction.
41 |
42 | ```php
43 | /**
44 | * Get the actions available for the resource.
45 | *
46 | * @param \Illuminate\Http\Request $request
47 | *
48 | * @return array
49 | */
50 | public function actions(Request $request)
51 | {
52 | return [
53 | (new DownloadExcel())->askForWriterType()
54 | ];
55 | }
56 | ```
57 |
58 | 
59 |
60 | :bulb: If you want to specify the options the user can choose yourself, you can pass them via the `askForWriterType`:
61 |
62 | ```php
63 | /**
64 | * Get the actions available for the resource.
65 | *
66 | * @param \Illuminate\Http\Request $request
67 | *
68 | * @return array
69 | */
70 | public function actions(Request $request)
71 | {
72 | return [
73 | (new DownloadExcel)->askForWriterType([
74 | \Maatwebsite\Excel\Excel::CSV => __('Csv document'),
75 | ]),
76 | ];
77 | }
78 | ```
79 |
80 | :bulb: If you want to have a custom label, you can simply pass that via the method: `(new DownloadExcel())->askForWriterType(null, __('Filename for your export'))`
81 |
82 |
--------------------------------------------------------------------------------
/nova/1.x/exports/queued.md:
--------------------------------------------------------------------------------
1 | # Queued
2 |
3 | When dealing with a large resource selection (e.g. +20k models), you can choose to queue your export.
4 |
5 | In your resource class, add the `Maatwebsite\LaravelNovaExcel\Actions\QueuedExport` to `actions()`.
6 |
7 | ```php
8 | use Maatwebsite\LaravelNovaExcel\Actions\QueuedExport;
9 |
10 | public function actions(Request $request)
11 | {
12 | return [
13 | new QueuedExport(),
14 | ];
15 | }
16 | ```
17 |
18 | Now you should see "Export To Excel" in your list of actions.
19 |
20 | 
21 |
22 | The `users.xlxs` file will be stored in your `default` storage folder.
23 | Behind the scenes the query is chunked with a chunk count of **200** and each chunk is queued.
24 |
25 | You can customize this by using the `withChunkCount()` method.
26 |
27 | ```php
28 | /**
29 | * Get the actions available for the resource.
30 | *
31 | * @param \Illuminate\Http\Request $request
32 | *
33 | * @return array
34 | */
35 | public function actions(Request $request)
36 | {
37 | return [
38 | (new QueuedExport)->withChunkCount(1000),
39 | ];
40 | }
41 | ```
42 |
43 | ::: warning
44 | Queueing downloads is not supported! You can only queue exports that are stored to the disk.
45 | :::
46 |
--------------------------------------------------------------------------------
/nova/1.x/exports/store.md:
--------------------------------------------------------------------------------
1 | # Storing exports
2 |
3 | To store a resource export to a disk, add the `Maatwebsite\LaravelNovaExcel\Actions\ExportToExcel` to `actions()`.
4 |
5 | ```php
6 | use Maatwebsite\LaravelNovaExcel\Actions\ExportToExcel;
7 |
8 | public function actions(Request $request)
9 | {
10 | return [
11 | new ExportToExcel(),
12 | ];
13 | }
14 | ```
15 |
16 | Now you should see "Export To Excel" in your list of actions.
17 |
18 | 
19 |
20 | The `users.xlxs` file will be stored in your `default` storage folder. By default Laravel-settings this will be `storage/app`.
--------------------------------------------------------------------------------
/nova/1.x/getting-started/README.md:
--------------------------------------------------------------------------------
1 | # Introduction
2 |
3 | :rocket: Supercharge your Laravel Nova resource exports
4 |
5 | - **Easily export resources to Excel.** Supercharge your Nova resources and export them directly to an Excel or CSV document. Exporting has never been so easy.
6 |
7 | - **Supercharged resource exports.** Export resources with automatic chunking for better performance. You provide us the query, we handle the performance. Exporting even larger resources? No worries, Laravel Nova Excel has your back. You can queue your exports so all of this happens in the background.
8 |
9 | - **Export based on filters and selection.** Select or filter only certain resources and export only those to Excel!
10 |
11 | - **Export lenses.** Got custom lenses defined? When exporting from a lens, it will use the query of the lens to determine which data needs to be exported!
12 |
--------------------------------------------------------------------------------
/nova/1.x/getting-started/contributing.md:
--------------------------------------------------------------------------------
1 | # Contributing
2 |
3 | [[toc]]
4 |
5 | Please read and understand the contribution guide before creating an issue or pull request.
6 |
7 | ## Important Links
8 |
9 | - [Docs](https://docs.laravel-excel.com/)
10 | - [Issue tracker](https://github.com/SpartnerNL/Laravel-Nova-Excel/issues)
11 | - [Support](/nova/1.1/getting-started/support.html)
12 |
13 | ## Etiquette
14 |
15 | This project is an open source project, and as such, the maintainers use their free time to build and maintain it.
16 | The code is freely available and can be used, forked and modified.
17 |
18 | Please be considerate towards maintainers when raising issues or presenting pull requests.
19 |
20 | It's the duty of the maintainer to ensure that all submissions to the project are of sufficient
21 | quality to benefit the project. Many developers have different skill sets, strengths, and weaknesses. Respect the maintainer's decision, and do not be upset or abusive if your submission is not used.
22 |
23 | ## Viability
24 |
25 | When requesting or submitting new features, first consider whether it might be useful to others. Open
26 | source projects are used by many developers, who may have entirely different needs to your own. Think about
27 | whether or not your feature is likely to be used by other users of the project.
28 |
29 | ## How to submit changes?
30 |
31 | - Check the codebase to ensure that your feature doesn't already exist.
32 | - Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
33 | - Use the [pull request template](https://github.com/SpartnerNL/Laravel-Excel/blob/3.1/.github/PULL_REQUEST_TEMPLATE.md).
34 |
35 | ## How to report a bug?
36 |
37 | - Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
38 | - Check to make sure your bug report isn't already present within the project.
39 | - Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
40 | - Check the pull requests tab to ensure that the feature isn't already in progress.
41 | - Use the [bug template](https://github.com/SpartnerNL/Laravel-Excel/blob/3.1/.github/ISSUE_TEMPLATE/1_Bug_report.md).
42 |
43 | ## Requirements
44 |
45 | - **[PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)**. - Style will get automatically fixed by StyleCI.
46 | - **Add tests backing up your change!** - You can run the test by running `vendor/bin/phpunit`
47 | - **Document any change in behaviour** - Documentation is located in the [https://github.com/SpartnerNL/laravel-excel-docs](https://github.com/SpartnerNL/laravel-excel-docs)
48 | - **One feature per Pull Request**
49 | - **Add meaningful commit messages**
50 |
--------------------------------------------------------------------------------
/nova/1.x/getting-started/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | ## Requirements
4 |
5 | * PHP: `^7.1`
6 | * Laravel: `^5.5`
7 | * Laravel Nova:`Orion`
8 | * Maatwebsite Laravel Excel: `^3.0`
9 |
10 | ## Installation
11 |
12 | Before installing the package, make sure you have set-up Laravel Nova.
13 |
14 | Require this package (`maatwebsite/laravel-nova-excel`) in the `composer.json` of your Laravel project or run the following command in your console:
15 |
16 | ```
17 | composer require psr/simple-cache:^2.0 maatwebsite/laravel-nova-excel
18 | ```
19 |
20 | If composer require fails on Laravel 9 because of the simple-cache dependency, you will have to specify the psr/simple-cache version as ^2.0 in your composer.json to satisfy the PhpSpreadsheet dependency. You can install both at the same time as.
21 |
22 | ## Service Provider
23 |
24 | In case you don't have auto-discovery enabled, you'll have to add the following two service providers in `config/app.php`:
25 |
26 | ```
27 | 'providers' => [
28 | /*
29 | * Package Service Providers...
30 | */
31 | Maatwebsite\Excel\ExcelServiceProvider::class,
32 | Maatwebsite\LaravelNovaExcel\LaravelNovaExcelServiceProvider::class,
33 | ]
34 | ```
35 |
--------------------------------------------------------------------------------
/nova/1.x/getting-started/license.md:
--------------------------------------------------------------------------------
1 | # License
2 |
3 | [[toc]]
4 |
5 | ## MIT
6 | Our software is open source and licensed under the [MIT license](https://choosealicense.com/licenses/mit/). You are free to use the software as you like. The code can be forked and modified, but the original copyright author should always be included!
7 |
8 | ## Postcardware
9 | According to the [postcardware](https://en.wikipedia.org/wiki/Postcardware) concept, if you use the software for your project(s) we would appreciate to receive a postcard of your hometown. Please send it to:
10 |
11 | **Maatwebsite**
12 | Markt 2
13 | 6231 LS Meerssen
14 | The Netherlands
15 |
16 | ## Support
17 |
18 | ::: warning Support
19 | We hold no liability and will provide support on a best effort basis. For more information about support please see [support](/nova/1.1/getting-started/support.html).
20 | :::
21 |
22 | :::tip Commercial Support
23 | :rocket: If you use the software commercially and need support urgently, we can offer this on a commercial basis. Please contact or phone +31 (0)10 744 9312.
24 | :::
25 |
--------------------------------------------------------------------------------
/nova/1.x/getting-started/support.md:
--------------------------------------------------------------------------------
1 | # Support
2 |
3 | [[toc]]
4 |
5 | Our software is free and open source, meaning that the use of our software is optional. We hold no liability and there is no obligation to support. We will provide support on a best effort basis.
6 |
7 | :::tip Commercial Support
8 | If you use the software commercially and need elaborate support or need it urgently, we can offer this on a commercial basis. Please contact or via phone +31 (0)10 744 9312.
9 | :::
10 |
11 | ## Supported Versions
12 |
13 | Versions will be supported for a limited amount of time.
14 |
15 | | Version | Laravel Version | Php Version | Support |
16 | |---- |----|----|----|
17 | | 1.0 | ^5.5 | ^7.0 | Unsupported since DD-MM-YYYY |
18 | | 1.1 | ^5.5 | ^7.0 | New features |
19 |
20 | ::: warning PHP version support
21 | Support for PHP versions will only be maintained for a period of six months beyond the end-of-life of that PHP version.
22 | :::
23 |
24 | ## Requesting support
25 | Before you request support, please check the following:
26 | * Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
27 | * Check to make sure your support request isn't already present within the project.
28 | * Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
29 | * Use one of the [issue templates](https://github.com/SpartnerNL/Laravel-Excel/tree/3.1/.github/ISSUE_TEMPLATE).
30 |
31 | Filling out the template is required. Issues that do not include enough information might not be picked up. Please write in English (or Dutch).
32 |
33 | Please prefix your issue with one of the following: [BUG] [PROPOSAL] [QUESTION].
34 |
35 | And please be considerate towards maintainers when raising issues.
36 |
--------------------------------------------------------------------------------
/nova/README.md:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "scripts": {
3 | "docs:build": "vuepress build",
4 | "docs:dev": "vuepress dev"
5 | },
6 | "devDependencies": {
7 | "@vuepress/plugin-back-to-top": "^1.8.2",
8 | "@vuepress/plugin-google-analytics": "^1.8.2",
9 | "@vuepress/plugin-nprogress": "^1.8.2",
10 | "@vuepress/plugin-pwa": "^1.8.2",
11 | "vuepress": "^1.8.2",
12 | "vuepress-plugin-container": "^2.1.5",
13 | "vuepress-plugin-sitemap": "^2.3.1"
14 | }
15 | }
16 |
--------------------------------------------------------------------------------
|