Documentation Index
Fetch the complete documentation index at: https://mintlify.com/PHPOffice/PhpSpreadsheet/llms.txt
Use this file to discover all available pages before exploring further.
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
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');
// 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()
- 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
$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
RichText object with the comment content
__toString()
Get plain text content of the comment.
public function __toString(): string
$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
The name of the comment author
$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 in CSS style (e.g., ‘100pt’, ‘150px’). Default unit is pt.
$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 in CSS style (e.g., ‘100pt’, ‘150px’). Default unit is pt.
$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
Left margin in CSS style (e.g., ‘150pt’). Default unit is pt.
$comment->setMarginLeft('150pt');
getMarginTop() / setMarginTop()
Get or set the top margin.
public function getMarginTop(): string
public function setMarginTop(string $margin): self
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
True to show the comment by default, false to show only on hover
// 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 object for the background
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
One of the Alignment constants (e.g., Alignment::HORIZONTAL_CENTER)
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
Text direction: Comment::TEXTBOX_DIRECTION_LTR, Comment::TEXTBOX_DIRECTION_RTL, or Comment::TEXTBOX_DIRECTION_AUTO
Comment::TEXTBOX_DIRECTION_LTR - Left to rightComment::TEXTBOX_DIRECTION_RTL - Right to leftComment::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
Drawing object with the image. Supported types: PNG, JPEG, BMP, GIF
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
$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);
$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);
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();
// 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 contentStyle\Color - For background colorsStyle\Alignment - For text alignment constantsWorksheet\Drawing - For background images
See Also
