How to change cell color in PHPSpreadsheet

How to change cell color in PHPSpreadsheet

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

Stefan Bogdanescu

Founder & Senior Architect

How to change cell color in PHPSpreadsheet

Changing the background or font color of a cell in an .xlsx file is a common requirement for generating reports, but it often trips up developers working with PHPSpreadsheet. The confusion usually stems from the library's architecture: PHPSpreadsheet_Cell objects do not expose direct methods like setBackground() or setFontColor(). Instead, the library relies on the OpenXML Spreadsheet Schema (SS) namespace to handle formatting. To achieve this, you must interact with the cell's style properties directly through the getStyle()->get*() and set*() chain.

The underlying mechanism involves modifying the XML structure that Excel uses to render styles. PHPSpreadsheet abstracts this complexity, but when a direct method is missing from the fluent interface, you must access the internal Style object. This object acts as a container for all formatting rules associated with a specific cell or range.

To change the background color of a single cell, you first need to ensure that the cell's style is not inherited from a default row or column style unless you explicitly want that behavior. Once you have access to the PHPSpreadsheet_Cell object, you can chain the style setters. The standard approach involves using the getStyle() method followed by getFill() and setFill().

Here is how you would apply a specific background color to cell A1:

use PhpOffice\PhpSpreadsheet\Cell\Cell;

// Assuming $spreadsheet is your instantiated PHPSpreadsheet object
$cell = $spreadsheet->getActiveSheet()->getCell('A1');

// Access the fill object and set the solid fill pattern
$fill = $cell->getStyle()->getFill();
$fill->setFillType(\PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID);

// Set the foreground color (background of the cell)
$fill->getStartColor()->getRGB() = 'FF5500'; // Example: Dark Orange

// If you are using named colors, PHPSpreadsheet supports them too:
// $fill->getStartColor()->setARGB('FF5500'); 
// Or using a named color string if the version supports it directly on some versions
// $fill->getStartColor()->getName() = 'Orange'; // Only works in specific contexts

// Save the changes
$spreadsheet->getActiveSheet()->getStyle('A1')->getFill();

There is a subtle but critical distinction between setting colors for a single cell versus an entire column or range. If you apply styles to a single cell, you are often overriding the default cellXf that PHPSpreadsheet initializes. However, if your goal is to color-code an entire column based on data (conditional logic), hardcoding the fill on every row via a loop can be inefficient and may result in file size bloat.

For dynamic coloring, such as highlighting cells where value > 1000 in red, you might initially think you need to set the style for every matching cell individually. While that works, there is a more elegant approach using conditional formatting rules defined via getActiveSheet()->getConditionalStyles(). This allows Excel to evaluate the condition and apply the color automatically, keeping your PHP logic clean and the generated file size smaller.

$conditionalStyle = [
    'cellXfId' => 64, // Or use a newly created style index if managing styles manually
    'fontColor'  => ['val' => 'FF0000', 'rgb' => true], // Example font color
    'fill'       => [
        'type'   => \PhpOffice\PhpSpreadsheet\Style\Fill::FILL_SOLID,
        'startColor' => ['argb' => 'FFFF00'] // Yellow background
    ]
];

$conditional = $spreadsheet->getActiveSheet()->getConditionalStyles('A1');
// Logic to set specific fill based on cell value would go here

One common pitfall is attempting to set the color without first defining a FILL_SOLID type. Excel requires an explicit fill pattern; leaving it default often results in no visible change even if a color code is provided. Additionally, be mindful of the RGB string format. PHPSpreadsheet expects specific hex formats (usually 8 characters including alpha) for its internal getStartColor() methods depending on the version you are using.

If you require complex styling that goes beyond simple colors, such as gradients or patterns, the same getStyle()->getFill() chain applies, but you must instantiate the gradient or pattern object specifically. The library is robust enough to handle these nuances provided you understand that style properties live on the Style facade attached to the cell, not on the cell itself as a property.

For developers building complex reporting tools where consistent styling is paramount, consider wrapping these direct style manipulations into helper methods. This prevents code duplication and ensures that color consistency is maintained across different parts of your application without rewriting the XML schema logic every time.

Our network