Styling cell borders with PhpSpreadsheet PHP

Styling cell borders with PhpSpreadsheet PHP

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

Stefan Bogdanescu

Founder & Senior Architect

Styling cell borders with PhpSpreadsheet PHP

You are encountering a common pitfall when working with PhpOffice\PhpSpreadsheet: the distinction between applying styles to a range and ensuring that specific border elements are explicitly defined for every side of the cell. In your current implementation, you are defining an outline border style within the $styleArray. However, simply assigning this array to the range 'B2:G8' does not guarantee that the visual borders appear as expected if the underlying cell object state is not correctly initialized or if the specific border sides (top, bottom, left, right) are not individually addressed in the context of the worksheet's rendering engine.

The core issue likely stems from how applyFromArray interprets nested structures when dealing with complex styles like borders. When you specify 'borders' => array('outline' => ...), you are telling PhpSpreadsheet to apply that style only if the cell has an explicit definition for that specific border type. If the cell's internal representation of borders is empty or reset, applying a global style might fail silently depending on the version and how the factory loaded the sheet. More critically, applyFromArray expects a structure that mirrors the Excel schema exactly.

To ensure robust styling, it is often more reliable to explicitly define all four border sides (outside, insideHorizontal, insideVertical) or use the specific side keys (top, bottom, left, right). The outline key is a convenience wrapper, but in some versions of PhpSpreadsheet or when loading existing sheets with merged cells, this can behave inconsistently if the internal state isn't clean.

Here is a more explicit approach that guarantees the borders render:

$fxls = 'myfile.xlsx';
$spreadsheet = \PhpOffice\PhpSpreadsheet\IOFactory::load($fxls);
$sheet = $spreadsheet->getActiveSheet();

// Define the border style explicitly for all sides
$borderStyle = [
    'borders' => [
        'allBorders' => [
            'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK,
            'color'      => ['argb' => 'FFFF0000'] // Red border
        ],
        'outline'     => [
            'borderStyle' => \PhpOffice\PhpSpreadsheet\Style\Border::BORDER_THICK,
            'color'      => ['argb' => 'FFFF0000']
        ]
    ]
];

$sheet->getStyle('B2:G8')->applyFromArray($borderStyle);

// Generate the Excel File
header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
header('Content-Disposition: attachment;filename="myNEWFile.xlsx"');
header('Cache-Control: max-age=0');
header('Expires: Mon, 26 Jul 1997 05:00:00 GMT');
header('Pragma: public');

$writer = new \PhpOffice\PhpSpreadsheet\Writer\Xlsx($spreadsheet);
$writer->save('php://output');
exit;

The key adjustment here is the inclusion of 'allBorders' alongside or instead of relying solely on 'outline'. By setting borderStyle and color for allBorders, you ensure that every edge of the selected range receives the intended formatting. This approach bypasses ambiguity regarding whether the library applies a "default" border when only an outline is specified in certain contexts.

Another frequent oversight involves cell merging. If your data contains merged cells (which is common when reading from Excel), applying styles to a range that spans merged cells can sometimes result in borders appearing only on specific edges or not at all, depending on where the merge starts. Always verify whether toArray or subsequent operations have altered the grid structure. If you are writing new data rather than modifying an existing file, ensure you initialize the cell objects before applying styles to avoid inheriting null states from a previous load operation that might have been cleared.

If you are building a dynamic application where users upload files and you need to apply conditional formatting or specific border rules, consider using PhpSpreadsheet\Style\Border::BORDER_THIN for internal grid lines and BORDER_THICK for outlines to maintain visual hierarchy. This mimics the look of standard Excel grids while allowing your custom borders to stand out.

When troubleshooting why a style doesn't appear, check the actual output in Excel rather than assuming the file is empty. Sometimes the border color is transparent or conflicts with the cell fill color, making it invisible. Ensure that if you are setting a background fill, the border color has sufficient contrast. For example, setting a white fill with a yellow border (FFFF0000) will work, but a light gray fill might make the yellow appear washed out.

For complex projects involving Laravel or other frameworks, remember that PhpSpreadsheet is a heavy library. If you are deploying this to a production environment, consider caching the loaded spreadsheet object if you are making multiple modifications to avoid reloading the file repeatedly. Also, always close the output stream after saving to php://output using exit; to prevent any further code execution that might append content to the download.

Our network