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: 

const string SetaPDF_Core_PageFormats::A3 = 'a3'

Page format constant

const string SetaPDF_Core_PageFormats::A4 = 'a4'

Page format constant

const string SetaPDF_Core_PageFormats::A5 = 'a5'

Page format constant

const string SetaPDF_Core_PageFormats::LEGAL = 'legal'

Page format constant

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: 

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

Landscape orientation

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
static public array SetaPDF_Core_PageFormats::getFormat ( string|array $format [, string $orientation = self::ORIENTATION_PORTRAIT ] )

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: 

const string SetaPDF_Core_PageBoundaries::ART_BOX = '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
const string SetaPDF_Core_PageBoundaries::BLEED_BOX = '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
const string SetaPDF_Core_PageBoundaries::CROP_BOX = '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
const string SetaPDF_Core_PageBoundaries::MEDIA_BOX = '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
const string SetaPDF_Core_PageBoundaries::TRIM_BOX = '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
static public boolean SetaPDF_Core_PageBoundaries::isValidName ( string $name )

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
static public boolean|string 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 ] )

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.