Генерація PDF у сімействі бібліотек FPDF

FPDF — це клас PHP, який дозволяє створювати файли PDF за допомогою чистого PHP, тобто без використання бібліотеки PDFlib.
F на початку імені проекта FPDF означає Free: ви можете використовувати його для будь-якого використання та змінювати відповідно до своїх потреб.

  • Офіційний сайт проекту // //www.fpdf.org
    • tFPDF modified version of FPDF that adds UTF-8 support

Споріднений проект: mPDF is a PHP library which generates PDF files from UTF-8 encoded HTML

+ PDFB Library - Barcodes in Dynamic PDFs https://chir.ag/projects/pdfb/

Введение

FPDF реализует высокоуровневые функции:

  • Choice of measure unit, page format and margins
  • Page header and footer management
  • Automatic page break
  • Automatic line break and text justification
  • Image support (JPEG, PNG and GIF)
  • Colors
  • Links
  • TrueType, Type1 and encoding support
  • Page compression

Библиотека FPDF реализована в объектном стиле. Она позволяет создавать объекты класса FPDF, наполнять их текстовым и графическим содержание и выводить итоговый pdf-документ в поток или файл.

Минимальный жизненный цикл fpdf-документа включает:

  • Создание объекта документа
  • Установка шрифта вывода
  • Создание страницы
  • Вывод содержания на страницу
  • Вывод документа

Документ

Основные и обязательные параметры fpdf-документ устанавливает в конструкторе объекта. Другие дополнительные свойства устанавливаются с помощью методов:

  • __construct([string orientation [, string unit [, mixed size]]]) конструктор позволяет определить размер страницы, ориентацию и единицы измерения для всех методов (кроме размеров шрифта).
    • orientation
      • 'P' or Portrait (Default)
      • 'L' or Landscape
    • unit User unit. Possible values are:
      • 'mm' миллиметры (по умолчанию)
      • 'pt' point
      • 'cm' centimeter
      • 'in' inch A point equals 1/72 of inch, that is to say about 0.35 mm (an inch being 2.54 cm). This is a very common unit in typography; font sizes are expressed in that unit.
    • size The size used for pages. It can be either one of the following values (case insensitive):
      • 'A3', 'A4, 'A5, 'Letter, 'Legal' стандартные размеры
      • [ width, height ] массив определяющий нестандартный размер

Метаданные и представление

Метаданные документа используются для !!! но не отражаются в самом документе.

  • SetTitle(string title [, boolean isUTF8]) устанавливает мета-заголовок документа
    • title строка заголовка
    • isUTF8 по умолчанию false определяет кодировку заголовка ISO-8859-1,  true определяет UTF-8
  • SetAuthor(string author [, boolean isUTF8]) Defines the author of the document
    • author строка автора
    • isUTF8 флаг кодировки
  • SetCreator(string creator [, boolean isUTF8]) Defines the creator of the document. This is typically the name of the application that generates the PDF.
    • creator строка создателя документа
    • isUTF8 флаг кодировки
  • SetSubject(string subject [, boolean isUTF8]) Defines the subject of the document
    • subject строка темы документа
    • isUTF8 флаг кодировки
  • SetKeywords(string keywords [, boolean isUTF8]) Associates keywords with the document, generally in the form 'keyword1 keyword2 ...'
    • keywords список ключевых слов
    • isUTF8 флаг кодировки

Вывод документа

Вывод документа происходит в только финале использования fpdf-объекта, однако метод вывода , как и конструктор, применяются в любом случае, поэтом по значимости метод вывода занимает второе место:

  • string Output([string dest [, string name [, boolean isUTF8]]]) выводит документ в указанный поток . Метод сначала вызывает Close(), если необходимо завершить документ.
    • dest Destination where to send the document. It can be one of the following:
      • 'I' (по умолчанию) отправляет документ в поток, который передается браузеру для просмотра
      • 'D' аналогичен 'I', но задает принудительно режим загрузки файла, имя файла задается параметром name
      • 'F' сохраняет документ в файл, с именем заданным в name (может включать путь)
      • 'S' возвращает документ как строку
    • name задает имя файла для всех типов dest , кроме 'S' ( по умолчанию 'doc.pdf')
    • isUTF8 устанавливает кодировку параметра name для dest равного 'I' или 'D'
      • false (по умолчанию) устанавливает кодировку ISO-8859-1, true устанавливает UTF-8

Опции вывода

  • SetDisplayMode(mixed zoom [, string layout])
    предустанавливает способ отображения документа. Уровень масштабирования может быть установлен: страницы могут отображаться полностью на экране, занимать всю ширину окна, использовать реальный размер, масштабироваться с помощью определенного коэффициента масштабирования или использовать средство просмотра по умолчанию (настраивается в меню «Настройки» Adobe Reader). Макет страницы также может быть указан: один сразу, непрерывное отображение, две колонки или по умолчанию для просмотра..

    • zoom
      The zoom to use. It can be one of the following string values:

      • fullpage: displays the entire page on screen
      • fullwidth: uses maximum width of window
      • real: uses real size (equivalent to 100% zoom)
      • default: uses viewer default mode
        or a number indicating the zooming factor to use.
    • layout The page layout. Possible values are:
      • single: displays one page at once
      • continuous: displays pages continuously
      • two: displays two pages on two columns
      • default: uses viewer default mode
        Default value is default.
  • SetCompression(boolean compress) устанавливает режим сжатия страниц с помощью zlib расширения; режим не требуется устанавливать специально, т.к. он включается автоматически, если zlib обнаружено

 

Страницы

Вывод содержания документа выполняется на страницы, каждая может иметь собственный размер, ориентацию и поворот. Первую страницу необходимо добавить в документ явно, последующие могут добавляться автоматически или тоже явно.

  • AddPage([string orientation [, mixed size [, int rotation]]]) добавляет новую страницу в документ. Если страница уже существует, сначала вызывается метод Footer() для вывода нижнего колонтитула. Затем добавляется страница, текущая позиция устанавливается в верхний левый угол в соответствии с левым и верхним полями, и вызывается Header() для отображения заголовка.
    Добавляет новую страницу в документ. Если страница уже существует, сначала вызывается метод Footer() для вывода нижнего колонтитула. Затем добавляется страница, текущая позиция устанавливается в верхний левый угол в соответствии с левым и верхним полями, и вызывается Header() для отображения заголовка.

    • orientation
      Page orientation. Possible values are (case insensitive):

      • P or Portrait
        L or Landscape
        The default value is the one passed to the constructor.
    • size
      Page size. It can be either one of the following values (case insensitive):

      • A3
        A4
        A5
        Letter
        Legal
      • or an array containing the width and the height (expressed in user unit).
        The default value is the one passed to the constructor.
    • rotation
      Angle by which to rotate the page. It must be a multiple of 90; positive values mean clockwise rotation. The default value is 0.
  • boolean AcceptPageBreak() Всякий раз, когда выполняется условие разрыва страницы, вызывается метод, и разрыв выдается или нет в зависимости от возвращаемого значения. Реализация по умолчанию возвращает значение в соответствии с режимом, выбранным функцией SetAutoPageBreak(). Этот метод вызывается автоматически и не должен вызываться непосредственно приложением.
  • int PageNo() метод возвращает текущий номер страницы
  • float GetPageWidth() возвращает ширину текущей страницы
  • float GetPageHeight() возвращает высоту текущей страницы

Шрифты

Вывод текста на страницу может осуществляться  или одним из стандартных шрифтов (в кодировке Windows cp1252) или шрифтом TTF,  который был добавлен в документ. Перед выводом текста следует обязательно установить шрифт в качестве текущего.

  • SetFont(string family [, string style [, float size]]) задает шрифт, используемый для вывода строк символов
    • family Family font. It can be either a name defined by AddFont() or one of the standard families (case insensitive):
      • Courier (fixed-width)
      • Helvetica or Arial (synonymous; sans serif)
      • Times (serif)
      • Symbol (symbolic)
      • ZapfDingbats (symbolic)
        It is also possible to pass an empty string. In that case, the current family is kept.
        style
      • Также можно передать пустую строку. В этом случае текущая семья сохраняется.
    • Font style. Possible values are (case insensitive):
      • empty string: regular
      • B: bold
      • I: italic
      • U: underline
        or any combination. The default value is regular. Bold and italic styles do not apply to Symbol and ZapfDingbats.
        size
    • Font size in points.
      The default value is the current size. If no size has been specified since the beginning of the document, the value is 12.
  • SetFontSize(float size) Defines the size of the current font.
    • size размер шрифта в поинтах (points)
  • AddFont(string family [, string style [, string file]]) Импортирует шрифт TrueType, OpenType или Type1 и делает его доступным. Сначала необходимо создать файл определения шрифта с помощью утилиты MakeFont. Файл определения (и сам файл шрифта при встраивании) должен присутствовать в каталоге шрифтов. Если он не найден, возникает ошибка "Could not include font definition file" is raised
    • family
      Font family. The name can be chosen arbitrarily. If it is a standard family name, it will override the corresponding font.
    • style
      Font style. Possible values are (case insensitive):

      • empty string: regular
      • B: bold
        I: italic
        BI or IB: bold italic
        The default value is regular.
    • file имя файла определения шрифта, по умолчанию имя строится из семейства и стиля в нижнем регистре без пробела

Примечание: файлы определения шрифта должны быть доступны. Их последовательно ищут в:

  • Каталог, определенный константой FPDF_FONTPATH ​​(если эта константа определена)
  • Каталог шрифтов, расположенный в том же каталоге, что и fpdf.php (если он существует)

define('FPDF_FONTPATH','./');

//

mm (мм) = 3.8px
cm (см) = 38px
in (дюйм) = 96px = 2.54cm
pt (типографский пункт) = 4/3 px

  • //

tFPDF

Оригинальная библиотека FPDF не поддерживает UTF, поэтому официально существует модифицированная версия tFPDF, в которую добавлена ​​поддержка шрифтов TTF с кодировкой UTF-8. Версия tFPDF способна встраивать в документ только необходимые части шрифта, что существенно уменьшает конечный размер документа.

Дополнительным требованиями tFPDF является добавление папки unifont в папку font, где следует разместить файлы шрифтов TTF. Рекомендуется, но не обязательно сделать папку unifont доступной для записи (CHMOD 755 или 644) для кэширования метрик шрифтов при первом использовании шрифта, но при перемещении папки шрифтов кэш-файлы .cw и .mtx необходимо обязательно удалить.

При вызове метода AddFont()  в четвертом параметре следует передавать true

 

Вывод строк

Вывод текстовых строк на страницу напоминает работу матричных принтеров с печатающей кареткой. Такой вывод основан на понятии текущей позиции, которая характеризуется горизонтальной координатой (абсциссой) и вертикальной (ординатой) на текущей странице. Каждый текстовый вывод начинается от текущей позиции, которая после завершения вывода устанавливается в новое положение на той же или следующей странице.

Базовая линия в типографике
Базовая линия (4)

Вывод возможен только в допустимые позиции на странице, которыми можно управлять. Положение позиции на странице можно определять и изменять, также можно определить номер текущей страницы, но изменить текущую страницу нельзя (но это не точно).

С точки зрения типографики текущая позиция определяет положение базовой линии шрифта, т.е. символы первой строки будут располагаться выше

Существует четыре метода для вывода строки, которые отличаются влиянием на вывод полей и поведением текущей позиции

  • Write(float h, string txt [, mixed link]) метод выводит текст от текущей позиции, при достижении правой границы или символа \n происходит перенос строки, и текст продолжается от левой границы; после завершения текущая позиция остается в конце текста
    • h Line height.
    • txt String to print.
    • link URL or identifier returned by AddLink()
  • Cell(float w [, float h [, string txt [, mixed border [, int ln [, string align [, boolean fill [, mixed link]]]]]]]) выводит прямоугольную ячейку с цветом фона и строкой символов; верхний левый угол ячейки соответствует текущей позиции; текст выводится в одну строку с заданным типом выравнивания; вывод ячейки смещает текущую позицию вправо на ширину ячейки и вниз на ее высоту; можно поставить ссылку на текст; если включен автоматический разрыв страницы и ячейка выходит за пределы, перед выводом выполняется разрыв страницы
    • w Cell width. If 0, the cell extends up to the right margin.
    • h Cell height. Default value: 0.
    • txt String to print. Default value: empty string.
    • border Indicates if borders must be drawn around the cell. The value can be either a number:
      • 0 по умолчанию не выводит рамку
      • 1 заключает ячейку в рамку
      • строка символов границ рамки (в любом порядке):
        • L выводит левую границу рамки
        • T выводит верхнюю границу рамки
        • R выводит правую границу рамки
        • B выводит нижнюю границу рамки
    • ln устанавливает тип положения текущей позиции после вывода строки:
      • 0 по умолчанию справа от !!!
      • 1 to the beginning of the next line
      • 2 below
        Putting 1 is equivalent to putting 0 and calling Ln() just after. Default value: 0.
    • align Allows to center or align the text. Possible values are:
      • L or empty string: left align (default value)
      • C center
      • R right align
    • fill Indicates if the cell background must be painted (true) or transparent (false). Default value: false.
    • link URL or identifier returned by AddLink().
  • MultiCell(float w, float h, string txt [, mixed border [, string align [, boolean fill]]])
    выводит текст с автоматическим переносом строк при достижении границы ячейки или спецсимволе '\n'; выводится столько ячеек, сколько необходимо, одна под другой; доступны все виды горизонтального выравнивания; границы. Тюремный блок можно обрамить, а фон покрасить.

    • w Width of cells. If 0, they extend up to the right margin of the page.
    • h Height of cells.
    • txt String to print.
    • order Indicates if borders must be drawn around the cell. The value can be either a number:
      • 0 по умолчанию не выводит рамку
      • 1 заключает ячейку в рамку
      • строка символов границ рамки (в любом порядке):
        • L выводит левую границу рамки
        • T выводит верхнюю границу рамки
        • R выводит правую границу рамки
        • B выводит нижнюю границу рамки
    • align
      Sets the text alignment. Possible values are:

      • L left alignment
      • C center
      • R right alignment
      • J justification (default value)
    • fill (Default: false) выводит ячейку без фона, при true применяет background
  • Text(float x, float y, string txt)  выводит в заданную позицию строку символов, при этом текущая позиция не изменяется; не выполняет перенос строк, игнорируя и поля  и символ \n; метод позволяет разместить строку точно на странице и не считается типичным.

Текущая позиция

// Работа с позицией выполняется в единицах заданных параметром unit конструктора объекта документа.

  • Ln([float h]) выполняет завершение строки, при этом абсцисса текущей позиции возвращается к минимальному значению, а ордината увеличивается на величину заданную параметром
    • h высота разрыва (по умолчанию равна высоте последней напечатанной ячейки)
  • float GetX() возвращает абсциссу текущей позиции
  • float GetY() возвращает ординату текущей позиции
  • SetXY(float x, float y) устанавливает новую абсциссу и ординату текущей позиции от левого и верхнего краев страницы, отрицательные значения задают соответственно от правого и нижнего краев
  • SetX(float x) устанавливает новую абсциссу текущей позиции от левого края страницы, отрицательное значение задает от правого края
  • SetY(float у) устанавливает новую ординату текущей позиции от верхнего края страницы, отрицательное значение задает от нижнего края
  • SetLeftMargin(float margin)
    устанавливает величину левого поля, по сути устанавливает ограничение на минимальное значение абсциссы текущей позиции
  • SetRightMargin(float margin) устанавливает величину правого поля, по сути устанавливает ограничение на максимальное значение абсциссы текущей позиции
  • SetTopMargin(float margin)
  • SetMargins(float left, float top [, float right]) Defines the left, top and right margins. By default, they equal 1 cm. Call this method to change them
  • SetAutoPageBreak(boolean auto [, float margin]) включает или отключает режим автоматического разрыва страниц. При включении вторым параметром является расстояние от нижней части страницы, определяющее предел срабатывания. По умолчанию режим включен и поле равно 20mm
    • auto Boolean indicating if mode should be on or off
    • margin Distance from the bottom of the page
  • float GetStringWidth(string s) Returns the length of a string in user unit. A font must be selected.
    • s The string whose length is to be computed.

//

  • int AddLink() Creates a new internal link and returns its identifier. An internal link is a clickable area which directs to another place within the document.
    The identifier can then be passed to Cell(), Write(), Image() or Link(). The destination is defined with SetLink().

//

Оформление

//

  • SetTextColor(int r [, int g, int b]) Defines the color used for text. It can be expressed in RGB components or gray scale. The method can be called before the first page is created and the value is retained from page to page
    • r If g et b are given, red component; if not, indicates the gray level. Value between 0 and 255
    • g Green component (between 0 and 255)
    • b Blue component (between 0 and 255)
  • SetLineWidth(float width)
    Description
    Defines the line width. By default, the value equals 0.2 mm. The method can be called before the first page is created and the value is retained from page to page.
    Parameters
    width
    The width.
  • SetDrawColor(int r [, int g, int b])
    Description
    Defines the color used for all drawing operations (lines, rectangles and cell borders). It can be expressed in RGB components or gray scale. The method can be called before the first page is created and the value is retained from page to page.
    Parameters
    r
    If g et b are given, red component; if not, indicates the gray level. Value between 0 and 255.
    g
    Green component (between 0 and 255).
    b
    Blue component (between 0 and 255).

Графика

//

Line(float x1, float y1, float x2, float y2) //

SetLineWidth(float width) //

SetDrawColor(int r [, int g, int b]) //

SetFillColor(int r [, int g, int b]) //

Rect(float x, float y, float w, float h [, string style]) //

Картинки

//

Image(string file [, float x [, float y [, float w [, float h [, string type [, mixed link]]]]]])
Puts an image. The size it will take on the page can be specified in different ways:
explicit width and height (expressed in user unit or dpi)
one explicit dimension, the other being calculated automatically in order to keep the original proportions
no explicit dimension, in which case the image is put at 96 dpi
Supported formats are JPEG, PNG and GIF. The GD extension is required for GIF.

For JPEGs, all flavors are allowed:
gray scales
true colors (24 bits)
CMYK (32 bits)
For PNGs, are allowed:
gray scales on at most 8 bits (256 levels)
indexed colors
true colors (24 bits)
For GIFs: in case of an animated GIF, only the first frame is displayed.

Transparency is supported.

The format can be specified explicitly or inferred from the file extension.

It is possible to put a link on the image.

Remark: if an image is used several times, only one copy is embedded in the file.

Колонтитулы

Для вывода верхнего и/или нижнего колонтитула (Header/Footer) необходимо определить новый класс наследованием от FPDF и определить в нем методы Header() и Footer(), которые будут вызываться автоматически при создании каждой страницы. Смотри официальный пример //www.fpdf.org/en/tutorial

Header()
This method is used to render the page header. It is automatically called by AddPage() and should not be called directly by the application. The implementation in FPDF is empty, so you have to subclass it and override the method if you want a specific processing.

Footer()
This method is used to render the page footer. It is automatically called by AddPage() and Close() and should not be called directly by the application. The implementation in FPDF is empty, so you have to subclass it and override the method if you want a specific processing.

//

Расширения

Существует несколько десятков расширений функциональности FPDF представленных на официальной сайте проекта //www.fpdf.org/en/script/
Актуальность расширений поддерживается.

Free PDF Document Importer /FPDI

FPDI — это набор классов PHP, упрощающих разработчикам чтение страниц из существующих PDF-документов и использование их в качестве шаблонов в FPDF, разработанном Olivier Plathey. Помимо копии FPDF, FPDI не требует никаких специальных расширений PHP //www.setasign.com/products/fpdi/about/

Tag-based formatting /WriteTag

Расширение добавляет классу методы, которые определяют и обрабатывают стилевые теги в выводимых строках. Теги дают возможность отображать несколько абзацев внутри фрейма, устанавливать стили шрифта, начертания (жирный, курсив, подчеркивание), размера и цвета символов в произвольном фрагменте выводимой строки //www.fpdf.org/en/script/script23.php

  • SetStyle($tag, $family, $style, $size, $color, $indent=-1, $bullet='')
  • WriteTag($w, $h, $txt, $border=0, $align="J", $fill=false, $padding=0)

Под капотом

Некоторые заметки о внутреннем устройстве объекта FPDF помогут понять и эффективно использовать:

  • Свойство pages объекта FPDF является индексированным массивом страниц, каждая из которых является String из строк разделенных \n. Строки дописываются на страницу методом _out($s), если объект находится в состоянии формирования ($this->state==2).
  • Свойство $this->buffer является string-содержанием конечного документа, который метод Output() отправляет в обертке, заданной параметром dest. Добавляются buffer строками методом _put($s).

 

Куча

// методы с неизученным действием

AliasNbPages([string alias])
Description
Defines an alias for the total number of pages. It will be substituted as the document is closed.
Parameters
alias
The alias. Default value: {nb}.

Источники

Online PDF converter //2pdf.com/convert-pdf-to-xml/

 

Leave a Reply