PDF::API2::Page(3)

💖 PDF::API2::Page 💖

okay so bestie, this is the manual page for PDF::API2::Page from the PDF::API2 distribution (User Contributed Perl Documentation, iykyk) — it's the module that lets you mess with individual pages inside a PDF. let's get into it 🦋

---

✨ NAME ✨

PDF::API2::Page — methods to interact with individual pages 💅

---

🌸 SYNOPSIS 🌸

my $pdf = PDF::API2->new();

# Add a page to a new or existing PDF
my $page = $pdf->page();

# Set the page size
$page->size('letter');

# Set prepress page boundaries
$page->boundaries(media => '12x18', trim => 0.5 * 72);

# Add an image
my $image = $pdf->image('/path/to/file.jpg');
$page->object($image, $x, $y, $w, $h);

# Add textual content
my $text = $page->text();

# Add graphical content (paths and shapes)
my $canvas = $page->graphics();

like. it's giving the starter pack. four lines and you're already making pages. obsessed 😭

---

👑 METHODS 👑

⭐ size ⭐

# Set the page size using a common name
$page->size('letter');

# Set the page size using coordinates in points (X1, Y1, X2, Y2)
$page->size([0, 0, 612, 792]);

# Get the page coordinates in points
my @rectangle = $page->size();

When you call it with an argument, it sets the physical page size (a.k.a. the media box). Check out "Page Sizes" down below for all the possible values you can throw at it. Returns the $page object, so you can chain it, slay.

Call it with no arguments and it hands you back the coordinates of the rectangle that encloses the physical page size. 🎀

The size method is a convenient shortcut for setting the PDF's media box when you don't need print-related page boundaries. Fr fr, it's exactly equivalent to this:

# Set
$page = $page->boundaries(media => $size);

# Get
@rectangle = $page->boundaries->{'media'}->@*;

---

🦋 boundaries 🦋

# Set
$page->boundaries(
    media => '13x19',
    bleed => [0.75 * 72, 0.75 * 72, 12.25 * 72, 18.25 * 72],
    trim  => 0.25 * 72,
);

# Get
%boundaries = $page->boundaries();
($x1, $y1, $x2, $y2) = $page->boundaries('trim');

Call it with a hash containing one or more page boundary definitions and it sets or replaces all the prepress page boundaries. Returns the $page object. 💜

Call it with no arguments and it gives you the current page boundaries. Call it with one argument and you get back the coordinates for that specific page boundary. chef's kiss.

🎀 Page Boundaries 🎀

PDF defines five page boundaries. When you're making PDFs for print shops, you'll most commonly use just the media box and the trim box. Traditional print shops may also use the bleed box when they're adding printer's marks and other info. periodt.

• media

The media box defines the boundaries of the physical medium the page is going to be printed on. It may include any extended area surrounding the finished page for bleed, printing marks, or other such purposes. The default value is a US letter page (8.5" x 11"). 💌

• crop

The crop box defines the region to which the contents of the page shall be clipped (cropped) when displayed or printed. The default value is the page's media box.

This is a historical page boundary. You'll likely want to set the bleed and/or trim boxes instead. ngl, crop is kinda the vintage one 🙈

• bleed

The bleed box defines the region to which the contents of the page shall be clipped when output in a production environment. This may include any extra bleed area needed to accommodate the physical limitations of cutting, folding, and trimming equipment. The actual printed page (media box) may include printing marks that fall outside the bleed box. The default value is the page's crop box.

• trim

The trim box defines the intended dimensions of the finished page after trimming. It may be smaller than the media box to allow for production-related content, such as printing instructions, cut marks, or color bars. The default value is the page's crop box.

• art

The art box defines the extent of the page's meaningful content (including potential white space) as intended by the page's creator. The default value is the page's crop box.

🌈 Page Sizes 🌈

PDF page sizes are stored as rectangle coordinates. But for convenience, PDF::API2 also supports a bunch of aliases and shortcuts that are way more human-friendly. bestie-friendly, even 💅

Here are all the formats you can use:

• a standard paper size

$page->boundaries(media => 'A4');

Aliases for the most common paper sizes are built in (case-insensitive).

US: Letter, Legal, Ledger, Tabloid

Metric: 4A0, 2A0, A0 - A6, 4B0, 2B0, and B0 - B6

• a "WxH" string in inches

$page->boundaries(media => '8.5x11');

Many US paper sizes are commonly identified by their size in inches rather than by a particular name. These can be passed as strings with the width and height separated by an "x".

Examples: "4x6", "12x18", "8.5x11"

• a number (in points) representing a reduction from the next-larger box

# Note: There are 72 points per inch
$page->boundaries(media => '12x18', trim => 0.5 * 72);

# Equivalent
$page->boundaries(media => [0,        0,        12   * 72, 18   * 72],
                  trim  => [0.5 * 72, 0.5 * 72, 11.5 * 72, 17.5 * 72]);

This example shows a 12" x 18" physical sheet that will be reduced to a final size of 11" x 17" by trimming 0.5" from each edge. The smaller boundary is assumed to be centered on the larger one. 🎯

The "next-larger box" follows this order, stopping at the first defined value:

art -> trim -> bleed -> media

crop -> media

This option isn't available for the media box, since it is by definition the largest boundary. no exceptions bestie 🫶

• [$width, $height] in points

$page->boundaries(media => [8.5 * 72, 11 * 7.2]);

For other page or boundary sizes, the width and height (in points) can be given directly as an array.

• [$x1, $y1, $x2, $y2] in points

$page->boundaries(media => [0, 0, 8.5 * 72, 11 * 72]);

Finally, the raw coordinates of the bottom-left and top-right corners of a rectangle can be specified.

---

🔥 rotation 🔥

$page = $page->rotation($degrees);

Rotates the page clockwise when it's displayed or printed. $degrees has to be a multiple of 90, and it may be negative for counter-clockwise rotation. 💫

The coordinate system follows the page rotation. In other words, after rotating the page 180 degrees, [0, 0] will be in the top right corner of the page rather than the bottom left, X will increase to the right, and Y will increase downward. yes it's weird. yes it's correct.

To create a landscape page without moving the origin, use "size". 🌸

---

🎨 graphics 🎨

my $canvas = $page->graphics(%options);

Returns a PDF::API2::Content object for drawing paths and shapes. this is where the main character energy comes out ✨

The following options are available:

• prepend (boolean) — If true, place the drawing at the beginning of the page's content stream instead of the end.
• compress (boolean) — Manually specify whether the drawing instructions should be compressed. If unspecified, the PDF's compression setting will be used, which is on by default.

---

💌 text 💌

my $text = $page->text(%options);

Returns a PDF::API2::Content object for including textual content.

The options are the same as the "graphics" method. 👑

---

🖼️ object 🖼️

$page = $page->object($object, $x, $y, $scale_x, $scale_y);

Places an image or other external object (a.k.a. XObject) on the page in the specified location.

If $x and $y are omitted, the object will be placed at "[0, 0]".

For images, $scale_x and $scale_y represent the width and height of the image on the page in points. If $scale_x is omitted, it will default to 72 pixels per inch. If $scale_y is omitted, the image will be scaled proportionally based on the image dimensions.

For other external objects, the scale is a multiplier, where 1 (the default) represents 100% (i.e. no change).

If the object to be placed depends on a coordinate transformation (e.g. rotation or skew), first create a content object using "graphics", then call "object" in PDF::API2::Content after making the appropriate transformations.

---

🎀 annotation 🎀

my $annotation = $page->annotation();

Returns a new PDF::API2::Annotation object. 🫶

---

🧚 MIGRATION 🧚

See "MIGRATION" in PDF::API2 for an overview. lowkey important, don't skip it bestie.

• gfx — Replace with "graphics".
• rotate — Replace with "rotation".
• mediabox, get_mediabox — Replace with "size" if not in a print shop environment, or "boundaries" if more complex page boundaries are needed.

If using page size aliases (e.g. "letter" or "A4"), check the Page Sizes section to ensure that the alias you're using is still supported (you'll get an error if it isn't). 😭

• cropbox, bleedbox, trimbox, artbox, get_cropbox, get_bleedbox, get_trimbox, get_artbox — Replace with "boundaries".

---

and that's the whole page, bestie!! 🦋💖 this doc shipped as part of PDF::API2::Page(3), built for perl v5.42.0 and dated 2025-09-01. go make some iconic PDFs, no cap. 💅✨🌈