Page Formats and Boundaries Handling page formats and boundary boxes

Introduction

To allow flexible and easy working with page formats and page boundaries the SetaPDF-Core component offers specific helper classes for them.

These helper classes will offer constants and static methods to simplify common tasks.

Page Formats

The class SetaPDF_Core_PageFormats will offer following predefined page formats through class constants: 

public const string SetaPDF_Core_PageFormats::A3 = 'a3'

Page format constant

public const string SetaPDF_Core_PageFormats::A4 = 'a4'

Page format constant

public const string SetaPDF_Core_PageFormats::A5 = 'a5'

Page format constant

public const string SetaPDF_Core_PageFormats::LEGAL = 'legal'

Page format constant

public const string SetaPDF_Core_PageFormats::LETTER = 'letter'

Page format constant

A page format in combination with an orientation will define the width and height of a page. Following constants for orientation values are available: 

public const string SetaPDF_Core_PageFormats::ORIENTATION_AUTO = 'auto'

If this orientation is used the 0 key will be the width while 1 will hold the height

public const string SetaPDF_Core_PageFormats::ORIENTATION_LANDSCAPE = 'landscape'

Landscape orientation

public const string SetaPDF_Core_PageFormats::ORIENTATION_PORTRAIT = 'portrait'

Portrait orientation

To create a normalized format by these constants or by an own format definition the class offers a static method, which will take care of size and orientation. The SetaPDF_Core_PageFormats::getFormat() method will mostly be used internally but it may give you an easy way to handle page formats in a normalized way :

Description
public static SetaPDF_Core_PageFormats::getFormat (
string|array $format [, string $orientation = SetaPDF_Core_PageFormats::ORIENTATION_PORTRAIT ]
): array

Returns a normalized format by a page format name or by an array.

Parameters
$format : string|array

The format as an array with 2 values or a pre-defined format constant

$orientation : string

The orientation

Return Values

Array where the keys '0' and 'width' are the width and keys '1' and 'height' are the height.

Exceptions

Throws InvalidArgumentException

Page Boundaries

A PDF page may define up to five separate boundaries that all define a boundary for a specific medium or region on that medium. Such boundaries are needed to distinguish between an intermediate medium and a finished medium. The boundaries are defined as class constants in the SetaPDF-Core component: 

public const string SetaPDF_Core_PageBoundaries::ART_BOX = 'ArtBox'

ArtBox

The art box defines the extent of the page’s meaningful content (including potential white space) as intended by the page’s creator.

See
  • PDF 32000-1:2008 - 14.11.2 Page Boundaries
public const string SetaPDF_Core_PageBoundaries::BLEED_BOX = 'BleedBox'

BleedBox

The bleed box defines the region to which the contents of the page shall be clipped when output in a production environment.

See
  • PDF 32000-1:2008 - 14.11.2 Page Boundaries
public const string SetaPDF_Core_PageBoundaries::CROP_BOX = 'CropBox'

CropBox

The crop box defines the region to which the contents of the page shall be clipped (cropped) when displayed or printed.

See
  • PDF 32000-1:2008 - 14.11.2 Page Boundaries
public const string SetaPDF_Core_PageBoundaries::MEDIA_BOX = 'MediaBox'

MediaBox

The media box defines the boundaries of the physical medium on which the page is to be printed.

See
  • PDF 32000-1:2008 - 14.11.2 Page Boundaries
public const string SetaPDF_Core_PageBoundaries::TRIM_BOX = 'TrimBox'

TrimBox

The trim box defines the intended dimensions of the finished page after trimming.

See
  • PDF 32000-1:2008 - 14.11.2 Page Boundaries

More details about the different page boundaries are available in the PDF specification PDF 32000-1:2008 - 14.11.2 Page Boundaries.

To check a string variable for a valid boundary name the class offers the isValidName() method:

Description
public static SetaPDF_Core_PageBoundaries::isValidName (
string $name
): boolean

Checks if a name is a valid page boundary name.

Parameters
$name : string

The boundary name

Return Values

A boolean value whether the name is valid or not.

The boundary boxes of a page are accessable via a SetaPDF_Core_Document_Page instance. 

Compare or Check for a Specific Format

To check an existing page or rectangle against a predefined format (like A4 or Letter) looks like an easy job but becomes tricky when you notice that different PDF creators use different values for the same formats. Some round up or down in their convertion from e.g. mm to points or simply round to full integers while others round the values to two digits.

We integrated a simple helper method that allows you to compare formats by using a difference threshold: 

Description
public static SetaPDF_Core_PageFormats::is (
string|array $format, array|SetaPDF_Core_Document_Page|SetaPDF_Core_DataStructure_Rectangle|SetaPDF_Core_Geometry_Rectangle $rect [, int|float $threshold = 1 ]
): boolean|string

Checks if a rectangle is approximately the same size as a given format.

Parameters
$format : string|array

The format as an array or as one of the defined page formats

$rect : array|SetaPDF_Core_Document_Page|SetaPDF_Core_DataStructure_Rectangle|SetaPDF_Core_Geometry_Rectangle

The rectangle or the page that needs to be compared

$threshold : int|float

The allowed difference between the rectangle and the format

Return Values

false or a string containing the matched orientation.

Get the Orientation of a Page

Sometimes it is very handy to get the orientation by a width and height value. At the end it is a simple if/else case but we prepared this in a simple helper method for you:

Description
public static SetaPDF_Core_PageFormats::getOrientation (
int|float $width, int|float $height
): string

Returns the orientation using width and height.

Parameters
$width : int|float
 
$height : int|float
 
Return Values

See SetaPDF_Core_PageFormats::ORIENTATION_XXX constants