README

This package allows you to generate Microsoft Excel files from any collection or array. You can easily apply formatting, styles or themes. It comes bundled with beautiful themes ready to use.

This php library is a wrapper around PhpSpreadsheet library.

Motivation

We needed to export beautiful excel reports and with as little boilerplate as possible. PhpSpreadsheet does a good job working with excel files and we needed something on top just to avoid the repetitive work.

✨ Features

• Easily export collection/array to Excel. Take your Laravel collection/array and export them directly to an Excel document.

• Beautiful themes ready to go. Beautiful templates easy customizable already prepared for you.

• Customize any cell. Hooks to easily customize any cell based on values or coordinates.

Basic Usage

composer require excel-report/excel-report

Just create a file in anywhere in your app folder or use an artisan command:

php artisan excel:report ProjectDetailsExcelReport

This by default will create the file ProjectDetailsExcelReport.php with folder app\ExcelReport.

<?php
namespace App\ExcelReport;

use Lab36\ExcelReport\ExcelReport;

class ProjectDetailsExcelReport extends ExcelReport
{
    public function columnMappings(): array
    {
        return [
            'project' => 'Project name',
            'start_date' => 'Project date',
            'cost' => 'Cost',
            'type' => 'Type',
            'state'=> 'State',
            'client_name'=>'Client name',
            'client_address'=>'Client address',
        ];
    }
}

In your controller:

<?php

namespace App\Http\Controllers;

use App\ExcelReport\ProjectDetailsExcelReport;
use App\Http\Controllers\Controller;
use Faker\Factory;


class ReportController extends Controller
{
    public function exportProjects()
    {
        $faker = Factory::create();

         $project_data = collect([
            [
                'project' => $faker->lastName,
                'start_date' => $faker->date('Y-m-d'),
                'cost' => $faker->numberBetween(2500, 3000),
                'type' => $faker->numberBetween(0, 3),
                'state'=> $faker->numberBetween(0,1),
                'client_name'=>$faker->name,
                'client_address'=>$faker->address,
            ],
            [
                'project' => $faker->lastName,
                'start_date' => $faker->date('Y-m-d'),
                'cost' => $faker->numberBetween(1000, 2000),
                'type' => $faker->numberBetween(0, 3),
                'state'=> $faker->numberBetween(0,1),
                'client_name'=>$faker->name,
                'client_address'=>$faker->address,
            ],
            [
                'project' => $faker->lastName,
                'start_date' => $faker->date('Y-m-d'),
                'cost' => $faker->numberBetween(4200, 4500),
                'type' => $faker->numberBetween(0, 3),
                'state'=> $faker->numberBetween(0,1),
                'client_name'=>$faker->name,
                'client_address'=>$faker->address,
            ],
        ]);

     
        return ProjectDetailsExcelReport::fromCollection(
             'Project details',
             $project_data
        )->download();
    }
}

For more examples follow this link.

Installation

You can install the package via composer:

composer require excel-report/excel-report

and then publish the config

php artisan vendor:publish --provider="Lab36\ExcelReport\ExcelReportServiceProvider"

Options

First thing you need the ExcelReport file. It's just a php class that extends ExcelReport. You can use

php artisan excel:report ClassName

Column mappings

The ExcelReport file must have a columnMappings function. This function maps array/collection values to Spreadsheet columns.

Exemple: Let's say we have an array

 $employee_data = [
        [
            'name' => $faker->name,
            'start_date' => $faker->date('Y-m-d'),
            'employee_cost' => $faker->numberBetween(100, 200),
        ],
        [
            'name' => $faker->name,
            'start_date' => $faker->date('Y-m-d'),
            'employee_cost' => $faker->numberBetween(100, 200),
        ],
    ];

the columnMappings function would be:

public function columnMappings(): array
    {
        return [
            'name' => __('Name'),
            'start_date' => 'Start date',
            'employee_cost' => 'Employee cost',
        ];
    }

columnMappings values would become the header for the excel report. If you want to ignore a column from the array just omit it from columnMappings. You can also use translations here.

Column alignment

By default PhpSpreadsheet does a good job aligning data. If you want to provide some exceptions you can implement columnAlignment function and specify the alignment.

Possible values:

• LEFT
• RIGHT
• CENTER
• HORIZONTAL_GENERAL
• HORIZONTAL_LEFT
• HORIZONTAL_RIGHT
• HORIZONTAL_CENTER
• HORIZONTAL_CENTER_CONTINUOUS
• HORIZONTAL_JUSTIFY
• HORIZONTAL_FILL
• HORIZONTAL_DISTRIBUTED

    public function columnAlignment(): array
    {
        return [
            'start_date' => 'CENTER',
        ];
    }

You can specify only the columns for which you need to change the alignment.

Column formats

You can specify column formats by implementing the function columnFormats

• NUMERIC
• TEXT
• DATE_DD-MM-YYYY
• NUMERIC_FORMATTED
• DATE_YYYY-MM-DD
• CURRENCY_LEI
• FORMAT_GENERAL
• FORMAT_TEXT
• FORMAT_NUMBER
• FORMAT_NUMBER_00
• FORMAT_NUMBER_COMMA_SEPARATED1::FORMAT_NUMBER_COMMA_SEPARATED1,
• FORMAT_NUMBER_COMMA_SEPARATED2::FORMAT_NUMBER_COMMA_SEPARATED2,
• FORMAT_PERCENTAGE
• FORMAT_PERCENTAGE_00
• FORMAT_DATE_YYYYMMDD2
• FORMAT_DATE_YYYYMMDD
• FORMAT_DATE_DDMMYYYY
• FORMAT_DATE_DMYSLASH
• FORMAT_DATE_DMYMINUS
• FORMAT_DATE_DMMINUS
• FORMAT_DATE_MYMINUS
• FORMAT_DATE_XLSX14
• FORMAT_DATE_XLSX15
• FORMAT_DATE_XLSX16
• FORMAT_DATE_XLSX17
• FORMAT_DATE_XLSX22
• FORMAT_DATE_DATETIME
• FORMAT_DATE_TIME1
• FORMAT_DATE_TIME2
• FORMAT_DATE_TIME3
• FORMAT_DATE_TIME4
• FORMAT_DATE_TIME5
• FORMAT_DATE_TIME6
• FORMAT_DATE_TIME7
• FORMAT_DATE_TIME8
• FORMAT_DATE_YYYYMMDDSLASH
• FORMAT_CURRENCY_USD_SIMPLE
• FORMAT_CURRENCY_USD
• FORMAT_CURRENCY_EUR_SIMPLE
• FORMAT_CURRENCY_EUR

    public function columnFormats(): array
    {
        return [
            'start_date' => 'DATE_YYYY-MM-DD',
            'employee_cost' => 'NUMERIC_FORMATTED',
        ];
    }

You can also specify any PhpSpreadsheet format by using the function addColumnFormats(), which will merge default formats with the one specified.

Column width

You can define any custom column width in character units implementing the following function.

    public function columnWidth(): array
    {
        return [
            'name' => '40',
        ];
    }

By default PhpSpreadsheet tries to guess the correct width for the column but there are cases when they become too long so we need to adjust. When a column gets smaller width, data in that column will wrap. Depending on your settings (default_row_height) rows will adjust to wrapping.

Special row positioning

You can override the default positioning for title, header and filters. For this you must call the coresponding setters.

In your Controller you can have

 return ProjectDetailsExcelReport::fromCollection(
             'Project details',
             $project_data
        )
        ->setTitleRowNo(2)
        ->setFilterRowNo(5)
        ->setHeaderRowNo(6)
        ->download();

Choosing a theme

This package comes with two themes. The default theme is set in the config file. You can create other themes by implementing ExcelThemeInterface.

Filter reports

This filters represent the values used to obtain data for the report. If the filter doesn't have a corresponding column it will appear after the last column.

Filters are an array in form:

[column_name => filter_value, ...]

$project_data = Project::where('name','=','John')
                        ->where('start_date', '=', '2018-01-01')
                        ->get();

return ProjectDetailsExcelReport::fromCollection(
                                                 'Project details',
                                                 $project_data)
                                ->setFilters([
                                            'name' => 'John',
                                            'start_date' => '2018-01-01',
                                            ])
                                ->download();

Download/store

You can choose to download or store on the server the created file. You can provide the file name to be used.

return ProjectDetailsExcelReport::fromCollection(
                                                 'Project details',
                                                 $project_data)
                                ->download('Project details '.Carbon::now()->toDateString());

To store the file you must specify the path

return ProjectDetailsExcelReport::fromCollection(
                                                 'Project details',
                                                 $project_data)
                                ->store('Project details '.Carbon::now()->toDateString(), public_path());

OverrideCell

To override any cell of the report you can implement the overrideCell method in you ExcelReport file with the following parameters:

• active_sheet
• current_row_no
• column_no
• value
• row_data
• column_name

public function overrideCell(Worksheet $active_sheet, int $current_row_no, int $column_no, $value, array $row_data, string $column_name)
{
    if ($column_name == 'order_type' && is_numeric($value)) {
        $active_sheet->setCellValue(Coordinate::stringFromColumnIndex($column_no).$current_row_no,
                                    config('enums.order_type')[$value]);
    }
}

Here you can override data, formatting, styling, alignment, etc. You can use any PhpSpreadsheet function available for the active sheet.

If you are not using a flat array with overrideCell you can pick the values that you want to appear in your cell. You can check the example here.

Config file

In the config file you can define

• excel file metadata
• namespace used for artisan command
• default theme
• default row height

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

• Lab36
• Cosmin Natea
• Andrea Molnar
• All Contributors

License

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