это всего-лишь шпаргалка для самого себя…
Представим, что у вас есть проект, базирующийся на фреймворке Codeigniter, и вам кровь из носу нужно, чтобы он мог создавать PDF-файлы. Когда у меня возникла такая задача, то выбор мой пал на библиотеку dompdf. И все написанное ниже — это просто краткий конспект действий по ее (библиотеки) установке и интеграции (как говорят в кино — «основано на реальных событиях» 🙂 ).
Вводные
Коль уж проект на Codeigniter-е имеется, то, полагаю, и сервер, где он размещен, тоже есть в наличии. А на сервере том, как минимум, присутствуют Apache и PHP (а может даже и MySQL?!). Все это установлено, настроено и отлично работает, взаимодействуя друг с другом. Да и сам проект уже делает все, что должен, вот только PDF-ов там и не хватает!.. У вас ведь именно так все и есть на самом деле? Ну ОК, тогда поехали дальше…
В одном из тестов (уж не помню, на каком релизе и которого из дистрибутивов) мне пришлось доустановить пакет zlibc. В остальных случаях проверка показала, что таковой уже был установлен в системе. В принципе, ничего страшного не произойдет, если вы в консоли введете команду:
sudo apt-get install zlibc
И если пакета в системе не было, то ОС-ь установит его, а если был — то просто сообщит, что такой уже имеется. Но зато в дальнейшем у вас уж точно не будет затыков по причине его отсутствия…
И последнее уточнение — лично я использовал Codeigniter 3-й версии.
Подготовка — установка composer
На самом деле, на сайте composer-а все расписано — и как его качать, и как его ставить, и даже насыпан кучкой набор консольных команд для этого. Лично я из них выбрал лишь первые две — одну для загрузки файла с сервера:
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
…и вторую — для проверки целостности загруженного файла:
php -r "if (hash_file('sha384', 'composer-setup.php') === '756890a4488ce9024fc62c56153228907f1545c228516cbf63f885e036d37e9a59d27d63f46af1d4d07ee0f76181c7d3') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
ВАЖНО! По поводу второй команды должен сразу предупредить — она БЫЛА АКТУАЛЬНА на тот момент, когда я проделывал описываемые тут манипуляции (так как она подходит лишь для конкретной версии composer-а, а именно — 2.0.9). Причина заключается в том, что непосредственно в самой команде указан тот эталонный хеш, с которым будет сверяться хеш файла, скачанного вами из интернета. И как только версия composer-а на сайте изменится, то поменяется и хеш! Поэтому, вторую команду в момент выполнения вами этих действий КОПИРУЙТЕ С САЙТА composer-а (с актуальным хешем)!
Ели проверка хеша завершилась успешно (сообщением «Installer verified»), то пришло время выполнить непосредственно саму установку composer-а. Вот такая команда:
php composer-setup.php --install-dir=/bin --filename=composer
… установит его в папку /bin, а сам бинарник назовет именем «composer» (благодаря чему, в дальнейшем вы сможете вызывать его, просто набирав это слово как команду в консоли, и при этом, ввод пути к файлу и пр. «шаманские танцы» — будут излишними).
Установка библиотеки dompdf в проект
Начнем с зависимостей. Есть ряд обязательных пакетов-зависимостей, которые нужно установить в системе, иначе библиотека dompdf работать не будет. Для этого введите команду:
sudo apt-get install php-xml php-gd php-mbstring
Кроме того, в документации к dompdf предлагается установить НЕОБЯЗАТЕЛЬНЫЕ (дополнительные) пакеты php-gmagick и php-imagick, цель которых — ускорение обработки графики. По поводу именно этой парочки могу лишь сказать, что во первых, у меня в некоторых случаях в списке «стандартных» пакетов отсутствовал какой-нибудь из них, если же вдруг оказывалось, что присутствовали оба, то тогда они конфликтовали между собой, а главное — я так и не увидел реального ускорения процедуры создания PDF-файлов после установки (любого из них). Правда, может у меня графика была никакая, и ускорять там реально было нечего?! Короче говоря, вы можете ввести команду для установки сразу обоих пакетов, и посмотреть на реакцию вашей системы (что поставится, что не поставится, проверить — а будет ли реальное ускорение, и т.д., и т.п.):
sudo apt-get install php-gmagick php-imagick
Если оба сразу не устанавливаются, ставьте по одному. Ну а если нет желания, то можете и не устанавливать их вовсе…
Чтобы установить сам dompdf, во первых, перейдите в папку applications вашего Codeigniter-проекта. После чего просто введите команду:
sudo composer require dompdf/dompdf
Composer поругается, что вы пытаетесь запускать его от имени root-а, предложит почитать наставления по этому поводу, и спросит, хотите ли вы продолжать дальше? Нажимаете кнопку «y» на клавиатуре, и плавно наблюдаете, как происходит установка библиотеки. Подтверждением того, что все ОК, является отсутствие сообщений, подсвеченных красным фоном. Если же сообщения об ошибках имеются — изучаете их, устраняете причины, повторяете установку dompdf заново.
По итогу, в папке applications должна будет появиться папка vendor (если ее там не было ранее), а уже в ней — папка c библиотекой dompdf и парочкой других, которые composer установит как «зависимости».
Использование dompdf в проекте
Во первых, перейдите в папку application/config вашего проекта. В ней вам нужно найти и отредактировать файл config.php. Цель редактирования — «глобально» включить в Codeigniter-е использование composer-а (за это отвечает параметр composer_autoload, поэтому, найдите и измените его). После редактирования строка с параметром должна выглядеть следующим образом:
$config['composer_autoload'] = TRUE;
Во вторых, предлагаю создать в Codeigniter-е дополнительную «библиотеку», которая и будет генерить PDF-файлы (лично я считаю этот вариант более удобным в случаях, когда процедуру нужно вызывать из целой кучи разных контроллеров). Для этого перейдите в папку application/libraries и создайте в ней НОВЫЙ файл Pdfgenerator.php с таким содержанием:
<?php
defined('BASEPATH') OR exit('No direct script access allowed');
use Dompdf\Dompdf;
class Pdfgenerator {
public function generate($html, $filename = '', $stream = TRUE, $paper = 'A4', $orientation = "portrait")
{
$dompdf = new DOMPDF();
$dompdf->set_option('enable_remote', TRUE);
$dompdf->set_option('dpi','79');
$dompdf->set_option('enable_html5_parser',TRUE);
$dompdf->loadHtml($html);
$dompdf->setPaper($paper,$orientation);
$dompdf->render();
$dompdf->stream($filename.".pdf", array("Attachment" => !$stream));
}
}
(Если пожелаете использовать другое имя файла, то учтите, что во первых, оно должно начинаться с заглавной буквы, во вторых, в вышеприведенном коде имя класса должно совпадать с именем файла (без расширения «.php»), и в третьих — не забудьте изменить имя вызываемой библиотеки в коде показанном ниже).
Пару слов по поводу самого содержимого этого файла. В основном, он мало чем отличается от множества иных вариантов, которых предостаточно в интернете. Просто в нем прописано несколько параметров, которые были нужны лично мне. И часть из них можно указывать прямо при вызове функции.
Первым делом, я хотел бы заострить ваше внимание на одном из них (т.к. в свое время самому пришлось искать его). Причина заключалась в том, что мне нужно было в PDF включать файлы (CSS-стили и картинки) из «внешних» (по отношению к dompdf) папок. И вот именно данный параметр помог мне «подчинить» библиотеку моим пожеланиям:
$dompdf->set_option('enable_remote', TRUE);
Второй параметр, который, полагаю, тоже нуждается в пояснении — это переменная $stream. Меняя ее значение (возможные варианты — TRUE и FALSE), вы будете управлять поведением браузера касательно сформированного PDF-ника — либо он будет сразу же открываться в браузере, либо браузер будет каждый раз спрашивать вас, что с ним делать (сохранять, открывать в приложении, и т.д. и т.п.)…
И наконец, о непосредственном использовании всего этого безобразия. В тех контроллерах, где вам нужно сформировать и вывести PDF-файл, вставляете такой код:
$html=$this->load->view('my_doc_print',$data, TRUE);
$this->load->library('pdfgenerator');
$this->pdfgenerator->generate($html,'pdf_name',FALSE,'A4','portrait');
Первая строка вызывает view, который собственно и формирует тот HTML-документ, который должен быть преобразован в PDF. Тут все сравнительно стандартно, за исключением третьего параметра — TRUE. Его использование приводит к тому, что сформированная веб-страница не выводится в браузер, а возвращается в переменную $html.
Вторая трока — стандартное подключение библиотеки. Если ранее вы имя файла Pdfgenerator.php поменяли на свое собственное, то и в этой строке, и в третьей, не забудьте изменить его (только тут вписывайте имя уже с маленькой буквы!).
И третья строка — вызов самой функции формирования PDF-документа. Ей передается до пяти параметров (нумерация слева направо):
- Тот самый HTML-документ для преобразования в PDF;
- Имя будущего PDF-файла (без расширения);
- Упоминавшееся выше «поведение» (открывать PDF-файл сразу или спрашивать пользователя). Этот параметр имеет свое «дефолтное» значение в самой функции, поэтому может не указываться;
- Размер бумаги. Этот параметр имеет свое «дефолтное» значение (A4) в самой функции, поэтому может не указываться;
- Ориентация страницы в документе. Этот параметр имеет свое «дефолтное» значение (портрет) в самой функции, поэтому может не указываться;
Кастомные шрифты в dompdf (кириллица и т.п.)
Сюрприз может поджидать тех, кто захочет использовать в документе кириллицу (либо иные национальные наборы символов). Входящие в комплект dompdf шрифты их не поддерживают. Поэтому, нужно будет как-то «досыпать» туда своих. Лично мне показалось, что проще всего будет импортировать подходящие TTF-шрифты с требующимся набором символов.
Когда-то раньше в числе прочего в библиотеке dompdf присутствовал специальный файл — load_font.php, который предназначался именно для этих целей. Но на данном этапе его среди прочих не оказалось, и мне пришлось его скачивать отдельно.
Для этого идем на страницу утилит библиотеки dompdf, и там находим нужный файл. В принципе, вы можете попробовать использовать приведенную ниже команду, но на всякий случай напоминаю — ссылки в интернете имеют свойство меняться с годами. Хотя, попробовать-то можно 🙂 .
Для начала, перейдите в папку application/vendor вашего проекта (именно в ней и нужно разместить скачиваемый файл). И там уже введите такую команду:
wget https://raw.githubusercontent.com/dompdf/utils/master/load_font.php
Затем в полученном файле необходимо отредактировать значение одного параметра. Откройте файл в редакторе, найдите в нем такую строку:
require_once "vendor/autoload.php";
…и измените ее, чтобы в итоге стало так:
require_once 'autoload.php';
На всякий случай, обращаю внимание, что указанный в параметре файл (autoload.php) должен находиться в той же папке, что и load_font.php. Именно поэтому выше было сказано, что файл load_font.php нужно сохранять в папку application/vendor (как раз там по умолчанию и «живет» autoload.php после описанных выше манипуляций composer-а).
В эту же папку копируете и TTF-файлы со шрифтами. Команда позволяет добавить в dompdf разные «начертания» шрифта. Именно с этой целью лично я и скопировал в проект сразу четыре файла: CALIBRI.TTF («обычный шрифт»), CALIBRIB.TTF («жирный шрифт»), CALIBRII.TTF («наклонный шрифт») и CALIBRIZ.TTF («жирный наклонный шрифт»). После чего ввел команду:
php load_font.php calibri CALIBRI.TTF CALIBRIB.TTF CALIBRII.TTF CALIBRIZ.TTF
В ней я указал (произвольное) имя для нового «семейства» шрифтов (calibri), а затем перечислил (в нужном порядке) все четыре файла с различными «начертаниями» шрифта.
Ну и напоследок, пример того, как в CSS формируемого HTML-документа (будущего PDF-файла) указать использование только что добавленного в dompdf нового семейства шрифтов (calibri):
*{
font-family:"calibri";
}