Update docs

Author: patrickbrouwers

.vuepress/theme/styles/code.styl

@@ -20,6 +20,7 @@
       background-color rgb(227 220 241)
       border-radius 16px
       font-weight bold
+      white-space nowrap
 
 .content__default
   pre, pre[class*="language-"]

4.x/exports/columns.md

@@ -108,6 +108,12 @@ If no `attribute` is passed, the title will be converted to a snake case attribu
 Text::make('Name'); // uses "name" attribute
 ```
 
+When working with relationships (e.g. HasOne and BelongsTo), you can use a dot notation as attribute:
+
+```php
+Text::make('Office', 'office.name'); // uses "name" attribute of the "office" BelongsTo relationship.
+```
+
 A callback can also be passed as second argument. The closure will get the row or Model. Whatever is returned within the
 closure, will be inserted in the cell.
 

4.x/exports/concern-overview.md

@@ -0,0 +1 @@
+# Concern overview

4.x/exports/data.md

@@ -1,7 +1,7 @@
 # Data sources
 
-An important part of each export is where the data should come from. Laravel Excel offers several ways of
-feeding data to the spreadsheet.
+An important part of each export is where the data should come from. Laravel Excel offers several ways of feeding data
+to the spreadsheet.
 
 [[toc]]
 
@@ -13,34 +13,70 @@ Using the `FromCollection` and `FromArray` concerns any type list of rows can be
 
 <span class="inline-step">2</span> **Exporting a Model query**
 
-Models can be exported using the `FromQuery` concern. Behind the scenes the query will be chunked for improved performance.
+Models can be exported using the `FromQuery` concern. Behind the scenes the query will be chunked for improved
+performance.
 
 <span class="inline-step">3</span> **Exporting a Blade View**
 
-To have more control on how the export should be presented `FromView` can be used with a Blade view that has a HTML table.
+To have more control on how the export should be presented `FromView` can be used with a Blade view that has a HTML
+table.
 
 ## Collection
 
 ### Eloquent collections
 
+`FromCollection` allows a collection of Eloquent models to be returned. Every Model will become a row in the export. 
+
 ```php
 namespace App\Exports;
 
 use App\Invoice;
 use Maatwebsite\Excel\Concerns\FromCollection;
 
-class InvoicesExport implements FromCollection
+class UsersExport implements FromCollection
 {
     public function collection()
     {
-        return Invoice::all();
+        // All User models.
+        return User::all();
+        
+        // Query some User models.
+        return User::query()->select('')->where('country', 'NL')->get();
     }
 }
 ```
 
+You can also do a more complex query with select, joins, where conditions etc. Just like with any Export object, you can pass any data via the constructor (or setters).
+
+```php
+class UsersExport implements FromCollection
+{
+    public function __construct(
+        public string $country
+    ) {
+    }
+
+    public function collection()
+    {
+        return User::query()
+            ->join('orders', 'users.id', '=', 'orders.user_id')
+            ->select('users.name', 'users.country', 'orders.price')
+            ->where('users.country', $this->country)
+            ->get();
+    }
+}
+```
+
+In the controller you can pass any required data to the export.
+
+```php
+return Excel::download(new UsersExport('NL'));
+```
+
 ### Custom collections
 
-If you are not using Eloquent or having another datasource (e.g. an API, MongoDB, Cache, ...) you can also return a custom collection:
+If you are not using Eloquent or having another datasource (e.g. an API, MongoDB, Cache, ...) you can also return a
+custom collection:
 
 ```php
 class InvoicesExport implements FromCollection
@@ -96,9 +132,11 @@ class InvoicesExport implements FromArray
 
 ## Query
 
-In the previous examples, we did the query inside the export class. While this is a good solution for small exports, for bigger exports this will come at a hefty performance price.
+In the previous examples, we did the query inside the export class. While this is a good solution for small exports, for
+bigger exports this will come at a hefty performance price.
 
-By using the `FromQuery` concern, we can prepare a query for an export. Behind the scenes this query is executed in chunks.
+By using the `FromQuery` concern, we can prepare a query for an export. Behind the scenes this query is executed in
+chunks to limit the amount of models held in memory.
 
 In the `InvoicesExport` class, add the `FromQuery` concern and return a query. Be sure to not `->get()` the results!
 
@@ -154,10 +192,10 @@ It will convert an HTML table into an Excel spreadsheet. For example; `exports/u
     </thead>
     <tbody>
     @foreach($users as $user)
-        <tr>
-            <td>{{ $user->name }}</td>
-            <td>{{ $user->email }}</td>
-        </tr>
+    <tr>
+        <td>{{ $user->name }}</td>
+        <td>{{ $user->email }}</td>
+    </tr>
     @endforeach
     </tbody>
 </table>
@@ -167,7 +205,8 @@ It will convert an HTML table into an Excel spreadsheet. For example; `exports/u
 
 Exports can be created from a PHP generator class, by using the `FromGenerator` concern.
 
-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.
+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.
 
 ```php
 namespace App\Exports;
@@ -186,3 +225,35 @@ class DataExport implements FromGenerator
     }
 }
 ```
+
+## Generic data manipulations
+
+### Strict null comparison
+
+If you want your `0` values to be actual `0` values in your Excel sheet instead of `null` (empty cells), you can use `WithStrictNullComparison`.
+
+```php
+use Maatwebsite\Excel\Concerns\WithStrictNullComparison;
+
+class UsersExport implements FromCollection, WithStrictNullComparison
+```
+
+### Custom start cell
+
+The default start cell is A1. Implementing the `WithCustomStartCell` concern in your export class allows you to specify a custom start cell.
+
+```php
+use Maatwebsite\Excel\Concerns\WithCustomStartCell;
+
+class UsersExport implements FromCollection, WithCustomStartCell
+{
+    public function startCell(): string
+    {
+        return 'B2';
+    }
+}
+```
+
+:::warning
+WithCustomStartCell is only supported for FromCollection exports.
+:::

4.x/exports/exporting.md

@@ -103,6 +103,54 @@ Instead of using the facade, you can now chain methods like `download` and `stor
 return (new UsersExport)->download('users.xlsx');
 ```
 
+### Responsables
+
+The previous (download) example can be made even shorter when adding Laravel's `Responsable` interface to the export class:
+
+```php
+namespace App\Exports;
+
+use App\User;
+use Maatwebsite\Excel\Excel;
+use Illuminate\Contracts\Support\Responsable;
+use Maatwebsite\Excel\Concerns\FromCollection;
+use Maatwebsite\Excel\Concerns\Exportable;
+
+class UsersExport implements FromCollection, Responsable
+{
+    use Exportable;
+    
+    /**
+    * It's required to define the fileName within
+    * the export class when making use of Responsable.
+    */
+    private $fileName = 'users.xlsx';
+    
+    /**
+    * Optional Writer Type
+    */
+    private $writerType = Excel::XLSX;
+    
+    /**
+    * Optional headers
+    */
+    private $headers = [
+        'Content-Type' => 'text/csv',
+    ];
+
+    public function collection()
+    {
+        return User::all();
+    }
+}
+```
+
+Within your controller you can now, just return the Export class and it will internally trigger the download response.
+
+```php
+return new UsersExport();
+```
+
 ### Dependency injection
 
 ```php

4.x/exports/performance.md

@@ -0,0 +1,15 @@
+# Performance
+
+[[toc]]
+
+## TLDR;
+
+<span class="inline-step">1</span> ****
+
+## Limiting data
+
+## Limiting query size
+
+## Using LazyCollections/Generators
+
+## Cell caching

4.x/exports/presentation.md

@@ -63,17 +63,17 @@ In case of using the Eloquent query builder:
 use Maatwebsite\Excel\Concerns\FromQuery;
 use Maatwebsite\Excel\Concerns\WithMapping;
 
-class InvoicesExport implements FromQuery, WithMapping
+class UsersExport implements FromQuery, WithMapping
 {    
     /**
-    * @var Invoice $invoice
+    * @var User $user
     */
-    public function map($invoice): array
+    public function map($user): array
     {
         return [
-            $invoice->invoice_number,
-            $invoice->user->name,
-            Date::dateTimeToExcel($invoice->created_at),
+            $user->id,
+            $user->lastOrder->description,
+            Date::dateTimeToExcel($user->created_at),
         ];
     }
 }
@@ -84,29 +84,71 @@ class InvoicesExport implements FromQuery, WithMapping
 You can also return multiple rows inside the map function.
 
 ```php
-public function map($invoice): array
+public function map($user): array
 {
     // This example will return 3 rows.
     // First row will have 2 column, the next 2 will have 1 column
     return [
         [
-            $invoice->invoice_number,
-            Date::dateTimeToExcel($invoice->created_at),
+            $user->id,
+            Date::dateTimeToExcel($user->created_at),
         ],
         [
-            $invoice->lines->first()->description,
+            $user->orders->first()->description,
         ],
         [
-            $invoice->lines->last()->description,
+            $user->orders->last()->description,
         ]
     ];
 }
 ```
 
+## Heading row
+
+If you are using columns, the heading row will already be applied by using the name of the column.
+
+```php
+use Maatwebsite\Excel\Concerns\WithColumns;
+
+class UsersExport implements WithColumns
+{   
+    public function columns(): array
+    {
+        return [
+            Number::make('#', 'id'),
+            Text::make('Name'),
+            Text::make('Email'),
+            Text::make('Registration Date'),
+        ];
+    }
+}
+```
+
+You can also add a heading row by adding the `WithHeadings` concern. The heading row will be added as very first row of the sheet.
+
+```php
+use Maatwebsite\Excel\Concerns\WithHeadings;
+
+class UsersExport implements WithHeadings
+{   
+    public function headings(): array
+    {
+        return [
+            '#',
+            'Name',
+            'Email',
+            'Date',
+        ];
+    }
+}
+```
+
 ## Styling
 
 ### Column styling
 
+Styles can be applied on a per-column basis. Styles can be passed as a PhpSpreadsheet style array via the `style()` method.
+
 ```php
 Text::make('Name')->style([
     'font' => [
@@ -115,6 +157,8 @@ Text::make('Name')->style([
 ]);
 ```
 
+Styles can also be applied by using the Fluent syntax.
+
 ```php
 Text::make('Name')
     ->font('Calibri', 16.0)
@@ -143,7 +187,7 @@ namespace App\Exports;
 use Maatwebsite\Excel\Concerns\WithStyles;
 use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
 
-class InvoicesExport implements WithStyles
+class UsersExport implements WithStyles
 {
     public function styles(Worksheet $sheet)
     {
@@ -171,7 +215,7 @@ namespace App\Exports;
 use Maatwebsite\Excel\Concerns\WithStyles;
 use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;
 
-class InvoicesExport implements WithStyles
+class UsersExport implements WithStyles
 {
     public function styles(Worksheet $sheet)
     {
@@ -198,7 +242,7 @@ namespace App\Exports;
 
 use Maatwebsite\Excel\Concerns\ShouldAutoSize;
 
-class InvoicesExport implements ShouldAutoSize
+class UsersExport implements ShouldAutoSize
 {
     ...
 }

4.x/exports/testing.md

@@ -0,0 +1 @@
+# Testing