Configuration

• Exports
  • exports.chunk_size
  • exports.pre_calculate_formulas
  • exports.strict_null_comparison
  • exports.csv
  • exports.properties
  • exports.source_handlers
• Imports
  • imports.read_only
  • imports.ignore_empty
  • imports.heading_row.formatter
  • imports.csv
  • imports.cells.middleware
• Extension detector
• Value binder
• Cache
  • cache.driver
  • cache.batch.memory_limit
  • cache.illuminate.store
  • cache.default_ttl
• Transactions
  • transactions.handler
  • transactions.db.connection
• Temporary files
  • temporary_files.local_path
  • temporary_files.local_permissions
  • temporary_files.remote_disk
  • temporary_files.remote_prefix
  • temporary_files.force_resync_remote

The configuration file is published to config/excel.php during installation. It is not required to republish it when upgrading — defaults are always applied for any missing keys.

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

---

Exports

exports.chunk_size

Default: 1000

Number of rows per database query chunk when using FromQuery. Tune this when you hit memory limits or want to reduce query time.

'chunk_size' => 500,

exports.pre_calculate_formulas

Default: false

When true, PhpSpreadsheet recalculates all formulas before saving. Useful if downstream consumers cannot calculate formulas themselves.

exports.strict_null_comparison

Default: false

When true, empty strings ('') are written as empty cells rather than being treated as null. Enable this if 0 values are being swallowed.

exports.csv

CSV-specific export settings:

Key	Default	Description
delimiter	,	Column delimiter
enclosure	"	Value enclosure character
line_ending	PHP_EOL	Row terminator
use_bom	false	Prepend a UTF-8 BOM
include_separator_line	false	Add a sep= line for Excel CSV compatibility
excel_compatibility	false	Full Excel CSV compatibility mode
output_encoding	''	Output encoding (empty = UTF-8)
test_auto_detect	true	Test auto-detection of delimiter/enclosure

exports.properties

Default document properties written to every export:

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

Override per-export using the WithProperties concern.

exports.source_handlers

Default: []

Register custom SheetSourceHandler or QueuedSheetSourceHandler class names here. They are resolved from the service container and take priority over the built-in From* handlers. See Data sources.

---

Imports

imports.read_only

Default: true

When true, style information is not loaded from the file, which speeds up reading. Set to false if your import logic needs to inspect cell styles.

imports.ignore_empty

Default: false

When true, rows where every cell is null or an empty string are skipped automatically.

imports.heading_row.formatter

Default: 'slug'

Controls how heading row values are formatted into array keys. Options:

Value	Behaviour
slug	Converts headings to snake_case slugs (default)
none	Uses heading values as-is
custom	Supply your own formatter class

imports.csv

CSV-specific import settings:

Key	Default	Description
delimiter	null	Column delimiter; null = auto-detect
enclosure	"	Value enclosure character
escape_character	\\	Escape character
contiguous	false	Merge contiguous delimiters
input_encoding	Csv::GUESS_ENCODING	Input file encoding

imports.cells.middleware

Default: []

An array of middleware classes executed on each cell value as it is read. Two built-in middleware classes are available (commented out by default):

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

---

Extension detector

Maps file extensions to reader/writer type constants. This is how the package decides which PhpSpreadsheet reader or writer to use when no explicit type is passed.

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

Available PDF drivers: Excel::MPDF, Excel::TCPDF, Excel::DOMPDF. Requires installing the corresponding composer package.

---

Value binder

Default: Maatwebsite\Excel\DefaultValueBinder::class

Controls how cell values are written by default. PhpSpreadsheet ships three binders:

Class	Behaviour
Maatwebsite\Excel\DefaultValueBinder	Intelligent type detection (recommended)
PhpOffice\PhpSpreadsheet\Cell\StringValueBinder	All values written as strings
PhpOffice\PhpSpreadsheet\Cell\AdvancedValueBinder	Extended type detection (currency, fractions, etc.)

Override per-export using the WithCustomValueBinder concern.

---

Cache

Cell caching reduces memory use at the cost of speed.

cache.driver

Default: 'memory'

Driver	Description
memory	All cell values kept in PHP memory (default, fastest)
illuminate	Each cell value stored in a Laravel cache store
batch	Values stored in cache only when the memory limit is reached

cache.batch.memory_limit

Default: 60000 (bytes)

Memory threshold for the batch driver. When PHP memory usage exceeds this value, the batch is flushed to the cache store.

cache.illuminate.store

Default: null (uses the default cache store)

Specify a named cache store from config/cache.php to use a dedicated store for cell caching.

cache.default_ttl

Default: 10800 (seconds — 3 hours)

TTL for cached cell values. Set to null to cache indefinitely.

WARNING

default_ttl is only applied when the cache is called without a TTL argument. An explicit null TTL stores the cell forever, whatever default_ttl is set to.

If you wrap or extend the batch driver (for example with CacheManager::extend()), don't forward a null TTL to it. Leave the argument out, or resolve it yourself with $ttl ?? config('excel.cache.default_ttl'). Otherwise, the cells of any import or export that fails before PhpSpreadsheet releases them (out of memory, a timeout, a killed worker) stay in the cache store permanently.

---

Transactions

Imports are wrapped in a database transaction by default so that a failed import can be retried cleanly.

transactions.handler

Default: 'db'

Value	Behaviour
'db'	Wraps each import in a database transaction (default)
null	Disables transactions

transactions.db.connection

Default: null (uses the default database connection)

Specify a named connection from config/database.php.

---

Temporary files

temporary_files.local_path

Default: storage_path('framework/cache/laravel-excel')

Where temporary files are stored during export/import processing.

temporary_files.local_permissions

Permissions for the temporary directory and files:

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

temporary_files.remote_disk

Default: null

In a multi-server queue setup, workers on different machines cannot share a local temporary path. Set this to a shared disk name (e.g. 's3') so every worker retrieves the temporary file from the same location.

temporary_files.remote_prefix

Default: null

Optional path prefix for remote temporary files on the shared disk.

temporary_files.force_resync_remote

Default: null

When true, the local copy of the temporary file is deleted after each chunk job completes, preventing local disk exhaustion in multi-server setups. Only relevant when remote_disk is set.