Skip to main content

​
Overview

The Comment class allows you to add notes and annotations to worksheet cells. Comments can include rich text formatting, custom dimensions, positioning, background colors, and even background images. Namespace: PhpOffice\PhpSpreadsheet Implements: IComparable, Stringable

​
Creating a Comment

Comments are accessed through worksheet cells using the getComment() method.

​
Basic Example

use PhpOffice\PhpSpreadsheet\RichText\RichText;

// Add a simple comment
$comment = $worksheet->getComment('E11');
$comment->setAuthor('PhpSpreadsheet');
$comment->getText()->createTextRun('This is a comment');

​
Rich Text Comment

// Add a comment with formatted text
$comment = $worksheet->getComment('E11');
$comment->setAuthor('PhpSpreadsheet');

// Add bold header
$textRun = $comment->getText()->createTextRun('PhpSpreadsheet:');
$textRun->getFontOrThrow()->setBold(true);

// Add line break
$comment->getText()->createTextRun("\r\n");

// Add regular text
$comment->getText()->createTextRun('Total amount on the current invoice, excluding VAT.');

​
Constructor

public function __construct()
Creates a new Comment instance with default values:
  • Author: ‘Author’
  • Fill color: Light yellow (#FFFFFFE1)
  • Width: 96pt
  • Height: 55.5pt
  • Visible: false

​
Text Methods

​
getText()

Get the RichText object for the comment. 
public function getText(): RichText
Example: 
$richText = $comment->getText();
$richText->createTextRun('First line');
$richText->createTextRun("\r\n");
$richText->createTextRun('Second line');

​
setText()

Replace the entire text content. 
public function setText(RichText $text): self
​
text
RichText
required
RichText object with the comment content

​
__toString()

Get plain text content of the comment. 
public function __toString(): string
Example: 
$plainText = (string) $comment;

​
Author Methods

​
getAuthor()

Get the comment author. 
public function getAuthor(): string

​
setAuthor()

Set the comment author. 
public function setAuthor(string $author): self
​
author
string
required
The name of the comment author
Example: 
$comment->setAuthor('John Doe');

​
Size Methods

​
getWidth() / setWidth()

Get or set the comment width. 
public function getWidth(): string
public function setWidth(string $width): self
​
width
string
required
Width in CSS style (e.g., ‘100pt’, ‘150px’). Default unit is pt.
Example: 
$comment->setWidth('100pt');
$width = $comment->getWidth();

​
getHeight() / setHeight()

Get or set the comment height. 
public function getHeight(): string
public function setHeight(string $height): self
​
height
string
required
Height in CSS style (e.g., ‘100pt’, ‘150px’). Default unit is pt.
Example: 
$comment->setHeight('100pt');
$height = $comment->getHeight();

​
Position Methods

​
getMarginLeft() / setMarginLeft()

Get or set the left margin (distance from the cell). 
public function getMarginLeft(): string
public function setMarginLeft(string $margin): self
​
margin
string
required
Left margin in CSS style (e.g., ‘150pt’). Default unit is pt.
Example: 
$comment->setMarginLeft('150pt');

​
getMarginTop() / setMarginTop()

Get or set the top margin. 
public function getMarginTop(): string
public function setMarginTop(string $margin): self
​
margin
string
required
Top margin in CSS style. Default unit is pt.

​
Visibility Methods

​
getVisible() / setVisible()

Get or set whether the comment is visible by default. 
public function getVisible(): bool
public function setVisible(bool $visibility): self
​
visibility
bool
required
True to show the comment by default, false to show only on hover
Example: 
// Make comment always visible
$comment->setVisible(true);

​
Styling Methods

​
getFillColor() / setFillColor()

Get or set the comment background color. 
public function getFillColor(): Color
public function setFillColor(Color $color): self
​
color
Color
required
Color object for the background
Example: 
use PhpOffice\PhpSpreadsheet\Style\Color;

$comment->getFillColor()->setRGB('EEEEEE');
// or
$color = new Color('FF0000');
$comment->setFillColor($color);

​
getAlignment() / setAlignment()

Get or set the text alignment. 
public function getAlignment(): string
public function setAlignment(string $alignment): self
​
alignment
string
required
One of the Alignment constants (e.g., Alignment::HORIZONTAL_CENTER)
Example: 
use PhpOffice\PhpSpreadsheet\Style\Alignment;

$comment->setAlignment(Alignment::HORIZONTAL_CENTER);

​
getTextboxDirection() / setTextboxDirection()

Get or set the text direction for the comment. 
public function getTextboxDirection(): string
public function setTextboxDirection(string $textboxDirection): self
​
textboxDirection
string
required
Text direction: Comment::TEXTBOX_DIRECTION_LTR, Comment::TEXTBOX_DIRECTION_RTL, or Comment::TEXTBOX_DIRECTION_AUTO
Constants:
  • Comment::TEXTBOX_DIRECTION_LTR - Left to right
  • Comment::TEXTBOX_DIRECTION_RTL - Right to left
  • Comment::TEXTBOX_DIRECTION_AUTO - Automatic (context-based)
  • Comment::TEXTBOX_DIRECTION_CONTEXT - Alias for AUTO
Example: 
$comment->setTextboxDirection(Comment::TEXTBOX_DIRECTION_RTL);

​
Background Image Methods

​
hasBackgroundImage()

Check if the comment has a background image. 
public function hasBackgroundImage(): bool

​
getBackgroundImage()

Get the background image Drawing object. 
public function getBackgroundImage(): Drawing

​
setBackgroundImage()

Set a background image for the comment. 
public function setBackgroundImage(Drawing $objDrawing): self
​
objDrawing
Drawing
required
Drawing object with the image. Supported types: PNG, JPEG, BMP, GIF
Example: 
use PhpOffice\PhpSpreadsheet\Worksheet\Drawing;

$drawing = new Drawing();
$drawing->setPath('/path/to/background.png');
$comment->setBackgroundImage($drawing);

​
setSizeAsBackgroundImage()

Automatically resize the comment to match the background image size. 
public function setSizeAsBackgroundImage(): self
Example: 
$drawing = new Drawing();
$drawing->setPath('/path/to/image.png');
$comment->setBackgroundImage($drawing);
$comment->setSizeAsBackgroundImage();

​
Complete Example

use PhpOffice\PhpSpreadsheet\Style\Color;
use PhpOffice\PhpSpreadsheet\Style\Alignment;

// Get the comment for cell E13
$comment = $worksheet->getComment('E13');

// Set author
$comment->setAuthor('PhpSpreadsheet');

// Add formatted text
$textRun = $comment->getText()->createTextRun('Important:');
$textRun->getFontOrThrow()->setBold(true);
$textRun->getFontOrThrow()->setSize(12);

$comment->getText()->createTextRun("\r\n");
$comment->getText()->createTextRun('Total amount on the current invoice, including VAT.');

// Set dimensions
$comment->setWidth('100pt');
$comment->setHeight('100pt');

// Position relative to cell
$comment->setMarginLeft('150pt');
$comment->setMarginTop('10pt');

// Style the comment
$comment->getFillColor()->setRGB('EEEEEE');
$comment->setAlignment(Alignment::HORIZONTAL_LEFT);

// Make it visible by default
$comment->setVisible(true);

​
Multi-line Comments Example

$comment = $worksheet->getComment('A1');
$comment->setAuthor('System');

// Line 1 - Bold header
$run1 = $comment->getText()->createTextRun('Note:');
$run1->getFontOrThrow()->setBold(true);
$run1->getFontOrThrow()->setColor(new Color('FF0000'));

// Line break
$comment->getText()->createTextRun("\r\n");

// Line 2 - Regular text
$comment->getText()->createTextRun('This field is required.');

// Line break
$comment->getText()->createTextRun("\r\n");

// Line 3 - Italic text
$run3 = $comment->getText()->createTextRun('Please enter a valid value.');
$run3->getFontOrThrow()->setItalic(true);

​
Comment with Background Image

use PhpOffice\PhpSpreadsheet\Worksheet\Drawing;
use PhpOffice\PhpSpreadsheet\Shared\Drawing as SharedDrawing;

$comment = $worksheet->getComment('C5');
$comment->setAuthor('Designer');
$comment->getText()->createTextRun('Reference image');

// Add background image
$drawing = new Drawing();
$drawing->setPath('/path/to/reference.png');
$comment->setBackgroundImage($drawing);

// Resize comment to match image
$comment->setSizeAsBackgroundImage();

​
Accessing Multiple Comments

// Get all comments in a worksheet
foreach ($worksheet->getComments() as $cellCoordinate => $comment) {
    echo "Cell: {$cellCoordinate}\n";
    echo "Author: {$comment->getAuthor()}\n";
    echo "Text: {$comment}\n";
    echo "---\n";
}
  • RichText\RichText - For formatted text content
  • Style\Color - For background colors
  • Style\Alignment - For text alignment constants
  • Worksheet\Drawing - For background images

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us