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
