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 Drawing class allows you to embed images into worksheets. It supports various image formats including PNG, JPEG, GIF, BMP, and can handle both local files and URLs.
Namespace: PhpOffice\PhpSpreadsheet\Worksheet
Extends: BaseDrawing
- PNG (
.png)
- JPEG (
.jpg, .jpeg)
- GIF (
.gif) - converted to PNG on save
- BMP (
.bmp) - converted to PNG on save
- EMF (
.emf)
Creating a Drawing
Basic Example
use PhpOffice\PhpSpreadsheet\Worksheet\Drawing;
$drawing = new Drawing();
$drawing->setName('Company Logo');
$drawing->setDescription('Company Logo');
$drawing->setPath('/path/to/logo.png');
$drawing->setCoordinates('B2');
$drawing->setHeight(50);
$drawing->setWorksheet($worksheet);
Using URL Image
$drawing = new Drawing();
$drawing->setName('Remote Image');
$drawing->setPath('https://example.com/image.png');
$drawing->setCoordinates('D5');
$drawing->setWorksheet($worksheet);
Using Base64 Encoded Image
$base64Image = 'data:image/png;base64,iVBORw0KGgoAAAANS...';
$drawing = new Drawing();
$drawing->setPath($base64Image);
$drawing->setCoordinates('A1');
$drawing->setWorksheet($worksheet);
Constructor
public function __construct()
Key Methods
setPath()
Set the path to the image file.
public function setPath(
string $path,
bool $verifyFile = true,
?ZipArchive $zip = null,
bool $allowExternal = true,
?callable $isWhitelisted = null
): static
File path, URL, or base64-encoded image data
Whether to verify the file exists and is valid
ZipArchive instance for reading from archives
Whether to allow external URLs
Callback function to validate URLs
http://, https://, file://, ftp://, s3://
Example:
// Local file
$drawing->setPath('/path/to/image.png');
// URL
$drawing->setPath('https://example.com/logo.png');
// Base64
$drawing->setPath('data:image/png;base64,iVBORw0KG...');
getPath()
Get the image path.
public function getPath(): string
getIsURL()
Check if the drawing is loaded from a URL.
public function getIsURL(): bool
setCoordinates()
Set the top-left cell position for the drawing.
public function setCoordinates(string $coordinates): self
Cell address (e.g., ‘B2’, ‘D5’)
$drawing->setCoordinates('B2');
getCoordinates()
Get the cell coordinates.
public function getCoordinates(): string
setWorksheet()
Attach the drawing to a worksheet.
public function setWorksheet(
?Worksheet $worksheet = null,
bool $overrideOld = false
): self
The worksheet to attach to
Whether to override if already attached to another worksheet
$drawing->setWorksheet($worksheet);
getWorksheet()
Get the attached worksheet.
public function getWorksheet(): ?Worksheet
Sizing Methods
setWidth()
Set the width in pixels.
public function setWidth(int $width): self
resizeProportional is enabled, height will be adjusted automatically.
getWidth()
Get the width in pixels.
public function getWidth(): int
setHeight()
Set the height in pixels.
public function setHeight(int $height): self
getHeight()
Get the height in pixels.
public function getHeight(): int
setWidthAndHeight()
Set both width and height with proportional resize.
public function setWidthAndHeight(int $width, int $height): self
$drawing->setResizeProportional(true);
$drawing->setWidthAndHeight(160, 120);
setResizeProportional()
Enable or disable proportional resizing.
public function setResizeProportional(bool $resizeProportional): self
Whether to maintain aspect ratio when resizing
$drawing->setResizeProportional(true);
$drawing->setWidth(320); // Height adjusted automatically
getResizeProportional()
Check if proportional resizing is enabled.
public function getResizeProportional(): bool
Position and Offset Methods
setOffsetX() / setOffsetY()
Set the pixel offset from the top-left corner of the cell.
public function setOffsetX(int $offsetX): self
public function setOffsetY(int $offsetY): self
$drawing->setCoordinates('B2');
$drawing->setOffsetX(5);
$drawing->setOffsetY(5);
getOffsetX() / getOffsetY()
Get the pixel offsets.
public function getOffsetX(): int
public function getOffsetY(): int
setCoordinates2()
Set the bottom-right cell for two-cell anchor.
public function setCoordinates2(string $coordinates2): self
Bottom-right cell address (e.g., ‘G6’)
$drawing->setCoordinates('B2');
$drawing->setCoordinates2('G6');
$drawing->setResizeProportional(false);
$drawing->setWidth(320);
getCoordinates2()
Get the bottom-right cell coordinates.
public function getCoordinates2(): string
setEditAs()
Set how the drawing behaves when cells are resized.
public function setEditAs(string $editAs): self
One of: absolute, oneCell, or twoCell
BaseDrawing::EDIT_AS_ABSOLUTE - Drawing doesn’t move or resize with cellsBaseDrawing::EDIT_AS_ONECELL - Drawing moves but doesn’t resize with cellsBaseDrawing::EDIT_AS_TWOCELL - Drawing moves and resizes with cells
Example:
$drawing->setEditAs(BaseDrawing::EDIT_AS_TWOCELL);
setName()
Set the drawing name.
public function setName(string $name): self
getName()
Get the drawing name.
public function getName(): string
setDescription()
Set the drawing description.
public function setDescription(string $description): self
getDescription()
Get the drawing description.
public function getDescription(): string
setRotation()
Set the rotation angle in degrees.
public function setRotation(int $rotation): self
Rotation angle (0-360 degrees)
getRotation()
Get the rotation angle.
public function getRotation(): int
setFlipHorizontal()
Flip the image horizontally.
public function setFlipHorizontal(bool $flipHorizontal): self
setFlipVertical()
Flip the image vertically.
public function setFlipVertical(bool $flipVertical): self
setOpacity()
Set the image opacity.
public function setOpacity(?int $opacity): self
Opacity percentage multiplied by 1000 (e.g., 40000 = 40%)
getFilename()
Get the filename from the path.
public function getFilename(): string
getExtension()
Get the file extension.
public function getExtension(): string
getType()
Get the image type constant (IMAGETYPE_PNG, IMAGETYPE_JPEG, etc.).
public function getType(): int
getImageWidth() / getImageHeight()
Get the original image dimensions in pixels.
public function getImageWidth(): int
public function getImageHeight(): int
getImageMimeType()
Get the MIME type of the image.
public function getImageMimeType(): string
Advanced Features
Hyperlinks
Add a hyperlink to the drawing.
use PhpOffice\PhpSpreadsheet\Cell\Hyperlink;
$hyperlink = new Hyperlink('https://example.com');
$drawing->setHyperlink($hyperlink);
Shadow Effects
use PhpOffice\PhpSpreadsheet\Worksheet\Drawing\Shadow;
$shadow = new Shadow();
$shadow->setVisible(true);
$shadow->setBlurRadius(6);
$drawing->setShadow($shadow);
In-Cell Drawing
Place the drawing inside a cell rather than floating over it.
$drawing->setInCell(true);
$drawing->setWorksheet($worksheet);
Complete Example
use PhpOffice\PhpSpreadsheet\Worksheet\Drawing;
use PhpOffice\PhpSpreadsheet\Worksheet\BaseDrawing;
// Create a drawing
$drawing = new Drawing();
$drawing->setName('Blue Square');
$drawing->setDescription('A blue square image');
$drawing->setPath(__DIR__ . '/images/blue_square.png');
// Position and size
$drawing->setCoordinates('B2');
$drawing->setCoordinates2('G6');
$drawing->setResizeProportional(false);
$drawing->setWidth(320);
// Configure behavior
$drawing->setEditAs(BaseDrawing::EDIT_AS_TWOCELL);
$drawing->setOffsetX(5);
$drawing->setOffsetY(5);
// Add to worksheet
$drawing->setWorksheet($worksheet, true);
MemoryDrawing - For GD image resources in memoryBaseDrawing - Parent class with common functionalityDrawing\Shadow - Shadow effects for drawingsCell\Hyperlink - Hyperlink functionality
See Also
