Pages & Coordinates

A Page is a fixed-size canvas — every image, line of text, path and field placed on it is positioned in points from a corner you choose.

Creating a Page#

Pass a size constant to the constructor and the page takes that size's width and height:

use Pop\Pdf\Document\Page;

$page = new Page(Page::LETTER);

A second, numeric argument sets the page's index — its position among an imported PDF's original pages, for a Page pulled from an existing file rather than built from scratch:

$page = new Page(Page::LETTER, 3);
echo $page->getIndex(); // 3

See Modifying Imported Pages — a page built for a new document has no need for one.

A size is the one argument every Page needs — there's no default width or height, so new Page() with nothing passed raises Pop\Pdf\Document\Exception. Give it a size constant or the custom width and height covered next.

Page Sizes#

Pass any of these 30 constants to the constructor. Every dimension is in points:

LEDGER and TABLOID are the same sheet in each orientation — LEDGER landscape, TABLOID portrait — which is why LEDGER alone is wider than it is tall.

Custom Sizes#

Skip the constant and pass a width and height directly, to the constructor or after, with setWidth() and setHeight():

use Pop\Pdf\Document\Page;

$page = new Page(400, 600);

$page = new Page(Page::LETTER);
$page->setWidth(500)->setHeight(700);

Both setters store the value as a whole number of points, truncating a fractional argument rather than rounding it — setWidth(500.9) leaves the page 500 points wide, not 501.

The Coordinate System#

Every x and y a page accepts is in points, measured from the origin — the 0, 0 point — which by default sits at the bottom left corner, x increasing right and y increasing upward.

setOrigin() moves that reference point. It lives on the document rather than the page, so one call affects every page the document holds:

use Pop\Pdf\Document;

$document = new Document();
$document->setOrigin(Document::ORIGIN_TOP_LEFT);

The five constants:

A 10-point square drawn at 100, 200 on a letter page lands differently under each origin:

• ORIGIN_BOTTOM_LEFT — stays at 100, 200
• ORIGIN_TOP_LEFT — 100, 592, flipping only y
• ORIGIN_TOP_RIGHT — 512, 592, flipping both
• ORIGIN_BOTTOM_RIGHT — 512, 200, flipping only x
• ORIGIN_CENTER — 406, 596, an offset from the page's center rather than a corner

Every coordinate is measured from whichever origin is in force when the document compiles — switching origins after content is drawn moves that content.

Page Content#

A page keeps what's added to it in six collections, each with a get*() that returns the collection and a has*() that reports whether it holds anything:

• getImages() / hasImages() — images placed with addImage()
• getText() / hasText() — single lines added with addText()
• getTextStreams() / hasTextStreams() — flowed text blocks added with addTextStream()
• getAnnotations() / hasAnnotations() — links and URLs added with addAnnotation(), addUrl() or addLink()
• getPaths() / hasPaths() — shapes added with addPath()
• getFields() / hasFields() — form fields added with addField()

use Pop\Pdf\Document\Page;
use Pop\Pdf\Document\Page\Path;
use Pop\Color\Color\Rgb;

$page = new Page(Page::LETTER);
$page->hasPaths(); // false

$path = new Path(Path::FILL);
$path->setFillColor(new Rgb(0, 102, 204));
$path->drawRectangle(100, 200, 300, h: 150);
$page->addPath($path);

$page->hasPaths();       // true
count($page->getPaths()); // 1

Each collection stores its own shape:

• getPaths() / getTextStreams() — return the Path and Stream objects themselves
• getImages() / getText() / getAnnotations() / getFields() — return arrays pairing the object with the x and y it was placed at; getFields() also carries the form name

See Adding Text, Text Streams, Images, Links & Annotations, Drawing & Paths and Forms & Fields for each collection's add*() method.

Clearing a Page#

clearContent() empties all six collections in one call, leaving the page's size and index untouched. It clears only page-native additions; an imported page's original content lives outside the six collections and survives:

use Pop\Pdf\Document\Page;
use Pop\Pdf\Document\Page\Path;
use Pop\Color\Color\Rgb;

$page = new Page(Page::LETTER);
$path = new Path(Path::FILL);
$path->setFillColor(new Rgb(0, 102, 204));
$path->drawSquare(100, 200, 50);
$page->addPath($path);

$page->clearContent();

$page->hasPaths();  // false
$page->getWidth();  // 612 — the size survives the clear

copyPage($p, preserveContent: false) on a document uses clearContent() internally — see Copying, Reordering and Deleting.

Page Index#

setIndex() and getIndex() read and write the same index the constructor's optional second argument sets:

use Pop\Pdf\Document\Page;

$page = new Page(Page::LETTER);
echo var_export($page->getIndex(), true); // NULL — a page built for a new document has none

$page->setIndex(5);
echo $page->getIndex(); // 5

getIndex() returns null until something sets it; Importing's Pdf::importFromFile() is what produces a real value.

See Also#

• Creating Documents — assembling pages into a document, and the current-page pointer
• Drawing & Paths — the full drawing surface, coordinates and all
• Metadata — the document's title, author and the rest of the info object