mPDF Manual – mPDF functions

AddPageByArray()

(mPDF >= 5.0)

AddPageByArray — Add a new page using an array of parameters

Description

void AddPageByArray ([ array $arr ])

Add a new page to the document using an array of parameters which are all optional.

The parameter type can specify certain conditions which determine how many pages are added. If writing a DOUBLE-SIDED document, a conditional page-break ('type' => "E" or "O") will add a new page only if required to make the current page match the type (i.e. ODD or EVEN); a page-break with 'type' => "NEXT-ODD" or "NEXT-EVEN" will add one or two pages as required to make the current page match the type (i.e. ODD or EVEN).

Number of pages added:

'type' SINGLE-SIDED DOUBLE-SIDED

Currently ODD page


Currently EVEN page
BLANK 1 1 1

'O' or 'ODD'

0 0 1

'E' or 'EVEN'

0 1 0

'NEXT-ODD'

1 2 1

'NEXT-EVEN'

1 1 2

Parameters

orientation => L|P

This attribute specifies the orientation of the new page.

BLANK or omitted leaves the current orientation unchanged

Values (case-insensitive)

'L' or 'landscape'
Landscape
'P' or 'portrait'
Portrait
type => E|O|even|odd|next-odd|next-even

If type is specified as 'E' or 'O' when writing a DOUBLE-SIDED document, the page-break is conditional; a new page will only be added if necessary to meet the specified condition. 

If type is specified as 'NEXT-ODD' or 'NEXT-EVEN' when writing a DOUBLE-SIDED document, either one or two pages are added as necessary to meet the specified condition.

If not writing a DOUBLE-SIDED document, a page-break 'type' => "E" or "O" will be ignored.

BLANK or omitted will force a new page unconditionally.

Values (case-insensitive)

'O' or 'ODD'
Add a new page if required to make current page an ODD one.
'E' or 'EVEN'
Add a new page if required to make current page an EVEN one.
'NEXT-ODD'
Add one or two pages as required to make the current page ODD.
'NEXT-EVEN'
Add one or two pages as required to make the current page EVEN.
resetpagenum => 1 - ∞

Sets/resets the document page number to resetpagenum starting on the new page. (The value must be a positive integer).

BLANK or omitted or 0 leaves the current page number sequence unchanged.

pagenumstyle => 1|A|a|I|i

Sets/resets the page numbering style (values as for lists)

BLANK or omitted leaves the current page number style unchanged.

Values (case-sensitive)

'1'
Decimal - 1,2,3,4…
'A'
Alpha uppercase - A,B,C,D…
'a'
Alpha lowercase - a,b,c,d…
'I'
Roman uppercase - I, II, III, IV…
'i'
Roman lowercase - i, ii, iii, iv…
suppress => on|off|1|0

'suppress' => 'on' will suppress document page numbers from the new page onwards (until 'suppress' => 'off' is used)

BLANK or omitted leaves the current condition unchanged.

Values (case-insensitive)

1 or 'on'
Suppress (hide) page numbers from the new page forwards.
0 or 'off'
Show page numbers from the new page forwards.
margin-left
margin-right
margin-top
margin-bottom
margin-header
margin-footer

Sets the page margins from the new page forwards.

All values should be specified as LENGTH in millimetres.

If you are writing a DOUBLE-SIDED document, the margin values will be used for ODD pages; left and right margins will be mirrored for EVEN pages.

BLANK or omitted leaves the current margin unchanged. NB 0 (zero) will set the margin to zero.

odd-header-name
even-header-name
odd-footer-name
even-footer-name

Selects a header or footer by name to use from the new page forwards. The header/footer must already have been defined using:

If you are writing a SINGLE-SIDED document, the values for ODD will be used for all pages, and values for EVEN will be ignored.

BLANK or omitted leaves the header/footer unchanged. NB BLANK will not unset the header. Set odd-header-value to -1 to turn the header off.

odd-header-value
even-header-value
odd-footer-value
even-footer-value

Specify whether to show or hide the named header or footer from the new page forwards. The header/footer must already have been defined using:

If you are writing a SINGLE-SIDED document, the values for ODD will be used for all pages, and values for EVEN will be ignored.

BLANK or omitted or 0 leaves the header/footer state unchanged.

Values (case-insensitive)

1 or 'on'
Start using the selected header/footer from the new page onwards.
-1 or 'off'
Start the selected header from the new page onwards.
pageselector

Select a named CSS @page.

BLANK or omitted or leaves the CSS page unchanged.

See Using @page for more information

sheet-size

sheet-size can be specified either as:

  • a pre-defined page size,
  • or as an array of width and height in millimetres e.g. array(210, 297).

Default: BLANK - makes no change to the current sheet-size

Values (case-insensitive)

  • 'A0' - 'A10', 'B0' - 'B10', 'C0' - 'C10'
  • '4A0', '2A0', 'RA0' - 'RA4', 'SRA0' - 'SRA4'
  • 'Letter', 'Legal', 'Executive', 'Folio'
  • 'Demy', 'Royal'
  • 'A' (Type A paperback 111x178mm)
  • 'B' (Type B paperback 128x198mm)

All of the above values can be suffixed with '-L' to force a Landscape page orientation document e.g. 'A4-L'

Note: If you use the array() form for sheet-size, then you must:

  • specify the width less than the height i.e. the dimensions of the page in portrait orientation;
  • and explicitly define the orientation as 'L' or 'P'

Changelog

Version Description
5.0 Function was added.
5.4 Alternative parameter names added

Alternative parameter names

type condition
margin-left mgl
margin-right mgr
margin-top mgt
margin-bottom mgb
margin-header mgh
margin-footer mgf
odd-header-name ohname
even-header-name ehname
odd-footer-name ofname
even-footer-name efname
odd-header-value ohvalue
even-header-value ehvalue
odd-footer-value ofvalue
even-footer-value efvalue
pageselector pagesel
sheet-size newformat

Examples

Example #1

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->WriteHTML('Your Introduction');

$mpdf->AddPage();
$mpdf->WriteHTML('Your Book text');

Example #2 - Resetting page numbering with a new style

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->useOddEven = 1;
$mpdf->AddPageByArray(array(
    'resetpagenum' => '1',
    'pagenumstyle' => 'i',
    'suppress' => 'on',
));
$mpdf->WriteHTML('Your Book text');


Example #3 - Defining new margins and page orientation

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->WriteHTML('Your Introduction');

$mpdf->AddPageByArray(array(
    'orientation' => 'L',
    'mgl' => '50',
    'mgr' => '50',
    'mgt' => '50',
    'mgb' => '50',
    'mgh' => '10',
    'mgf' => '10',
));
$mpdf->WriteHTML('Your Book text');

Example #4 - Changing headers/footers

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->useOddEven = 1;
$mpdf->defHeaderByName(
    'myHeader', 
    array (
        'L' => array (),
        'R' => array (),
        'C' => array (
            'content' => 'Chapter 2', 
            'font-style' => 'B', 
            'font-family' => 'serif'
        ),
        'line' => 1,
    )
);
$mpdf->defHTMLHeaderByName(
    'myHeader2',
    '<div style="text-align: center; font-weight: bold;">Chapter 2</div>'
);
$mpdf->WriteHTML('Your Introduction');

// Selects new headers for ODD and EVEN pages to use from the new page onwards
// Note the html_ prefix before the named HTML header
$mpdf->AddPageByArray(array(
    'condition' => 'NEXT-ODD',
    'ohname' => 'myHeader',
    'ehname' => 'html_myHeader2',
    'ohvalue' => 1,
    'ehvalue' => 1,
));
$mpdf->WriteHTML('Your Book text');

// Turns all headers/footers off from new page onwards
$mpdf->AddPage(
    '','NEXT-ODD','','','','','','','','','',
    '','','','',
    -1,-1,-1,-1
);
$mpdf->AddPageByArray(array(
    'condition' => 'NEXT-ODD',
    'ohvalue' => -1,
    'ehvalue' => -1,
    'ofvalue' => -1,
    'efvalue' => -1,
));
$mpdf->WriteHTML('End section of book with no headers');

Example #5 - Blank template as example

<?php
$mpdf = new \Mpdf\Mpdf();

$mpdf->WriteHTML('Introduction');

$mpdf->AddPageByArray(array(
    'orientation' => '',
    'condition' => '',
    'resetpagenum' => '',
    'pagenumstyle' => '',
    'suppress' => '',
    'mgl' => '',
    'mgr' => '',
    'mgt' => '',
    'mgb' => '',
    'mgh' => '',
    'mgf' => '',
    'ohname' => '',
    'ehname' => '',
    'ofname' => '',
    'efname' => '',
    'ohvalue' => 0,
    'ehvalue' => 0,
    'ofvalue' => 0,
    'efvalue' => 0,
    'pagesel' => '',
    'newformat' => '',
));
$mpdf->WriteHTML('Chapter 1 ...');

$mpdf->Output();

Notes

See Also

  • <pagebreak> - Custom HTML tag - equivalent to AddPage() or AddPageByArray()
Fork me on GitHub