Index

  1. Installation
  2. Getting Started
  3. Memory Usage
  4. Readers and Writers
  5. The Document Class
  6. Metadata
  7. Pages
  8. Canvas
  9. Page Layout and Mode
  10. Viewer Preferences
  11. Document Outline
  12. Page Labels
  13. Actions
  14. Destinations
  15. Annotations
  16. Embedded File Streams
  17. Colors and Color Spaces
  18. Page Formats and Boundaries
    1. Introduction
    2. Page Formats
    3. Page Boundaries
    4. Compare or Check for a Specific Format
    5. Get the Orientation of a Page
  19. Standard and Public Key Encryption
  20. Fonts and Encodings
  21. Corrupted Documents
  22. Reader Enabled Documents
  23. Refactor Old SetaPDF Code
  24. API Reference

Page Formats and Boundaries Handling page formats and boundary boxes

Table of Contents

  1. Introduction
    1. Page Formats
      1. Page Boundaries
        1. Compare or Check for a Specific Format
          1. Get the Orientation of a Page

            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

            © 2024 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)