Laravel excel maatwebsite 3.1 import, date column in excel cell returns as unknown format number. How to solve this?

Laravel excel maatwebsite 3.1 import, date column in excel cell returns as unknown format number. How to solve this?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Laravel Excel Maatwebsite 3.1 Import: Handling Date Column Format Issues

When integrating Maatwebsite/Laravel-Excel version 3.1 into a legacy application or an existing codebase, you may encounter specific data parsing quirks that deviate from modern expectations. A common friction point arises when importing spreadsheets containing date values like "29/07/1989", which the library might return as a serial number such as 32178 instead of a formatted date object. This behavior is not a bug in your logic but rather a consequence of how Excel internally stores dates and how the older version of the Maatwebsite package interprets cell types by default.

Excel treats dates fundamentally differently than text strings or numeric values. Internally, an Excel date is stored as an integer representing the number of days elapsed since January 1, 1900 (the "Excel Epoch"). The serial number 32178 corresponds exactly to July 29, 1989, according to this epoch calculation. When a cell in an Excel file contains a date but is formatted as text or lacks specific formatting metadata that the reader can infer, the Laravel-Excel 3.1 engine often defaults to reading the underlying raw integer value if it cannot definitively classify the cell as a date string based on locale settings alone.

To resolve this in version 3.1, you must explicitly instruct the reader how to interpret the data. The solution lies within the useHeaderRow or the map closure logic, but specifically leveraging the Cell::setDataType() method or configuring the column mapping before the import occurs. However, a more robust approach in 3.1 involves using the Reader configuration options to force date parsing.

If you are manually defining columns within your import model, ensure that you are not relying solely on automatic type inference. You can override the default behavior by accessing the reader's cell data attributes or by configuring the sheet reader directly. In many cases with version 3.1, simply ensuring that the column in Excel is formatted as a "Date" prior to export resolves the issue, as this embeds the necessary metadata into the file stream. If you cannot control the upstream Excel generation, you must handle the conversion within your import class.

One effective strategy involves overriding the map function in your model to check the raw value and convert it if necessary:

use Maatwebsite\Excel\Concerns\ToModel;
use Carbon\Carbon;

class UserImport implements ToModel
{
    public function map($row)
    {
        // Check if the date column is stored as a serial number
        $rawDate = $row->dob; 
        
        if (is_numeric($rawDate)) {
            // Convert the Excel epoch number to a Carbon instance
            // Note: Ensure your server timezone matches or adjust the offset if needed
            $carbonDate = Carbon::createFromTimestampStrict((float)$rawDate * 86400);
            
            // Re-inject the formatted date
            $row->dob = $carbonDate;
        }

        return new User([
            'name' => $row->name,
            'dob' => $row->dob,
            // ... other fields
        ]);
    }
}

This approach is pragmatic but relies on knowing the specific column name. A more declarative solution available in Maatwebsite 3.1 is using the useHeaderRow with a custom reader that sets the data type for specific cells. However, version 3.1 has limitations compared to later versions regarding dynamic cell type injection during the mapping phase.

The most reliable fix without upgrading the library involves ensuring the Excel file itself contains the correct metadata. If you are generating the file dynamically using PhpSpreadsheet, set the column format to a date string before writing:

$spreadsheet->getActiveSheet()->getStyle('A')->getNumberFormat()
    ->setFormatCode(\PhpOffice\PhpSpreadsheet\Style\NumberFormat::FORMAT_DATE_YYYYMMDD);

If you must accept files from external sources where the formatting is lost, the map function logic using Carbon::createFromTimestampStrict remains the safest programmatic fix. It handles the conversion explicitly rather than relying on ambiguous type guessing. Be aware that floating-point precision issues can sometimes arise when converting large epoch numbers directly to timestamps, so validating the input range before conversion is a prudent trade-off to consider.

Our network