PDFlib HOWTO - FAQ

$Id: faq.html,v 1.63 2009-01-27 06:53:10 cz Exp $

パッケージ関連
- Perl での PDFlib のインストール方法は？
ライセンス関係
- 開発環境と本番環境が存在する場合、ライセンスは両環境に必要？
- ライセンスに関するエラーが表示される
- Apache(PHP)において、環境変数 PDFLIBLICENSEFILE でライセンスファイルを設定したい
技術関係
- PDFlib+PDI で取り込んだ PDF ファイルの総ページ数を求めるには？
- 透明テキストの出力方法は？
- 白紙の PDF が出力される
- PDF_begin_document()等の viewerpreferences オプションの指定方法は？
- PDFlib で作成した PDF が Acrobat Reader 4.0や5.0で開けない
- テキストフローで日本語を利用するには？
- PDFlib ブロックで複数行を指定するには？
- 一つのPDFlib ブロック内でフォントや文字等を変更するには？
- 注釈等、オプションを日本語で指定するには
- 機種依存文字の表示方法
- C 言語での PDF_get_buffer()の使用方法
- PDF ブロックで、文字列を左詰め、右詰め、中央揃え等で表示するには
- 外字エディタで作成した外字の出力方法
- 複数のPDFファイルの合成方法
- Perl 版 PPS での日本語表示
- .TTC ファイルのフォントの指定方法
- テキストフローの文字列の均等割付
- 色設定を CMYK にしたい
- PDFlib で文字を修飾(太字や下線など）したい
これってバグ？
- PHP でサンプルを実行するとエラーが出力されます
- Windows 用の PHP で、外部ファイルを読み込めない
- PDFlib で生成した PDF ファイルを Acrobat 8 で印刷しようとするとエラーが出ます
よくあるエラーメッセージとその原因

パッケージ関係

Perl での PDFlib のインストール方法は？

必要なことは @INC モジュールのサーチパスに pdflib_pl.so と pdflib_pl.pm をコピーしてあげるだけです。まず下記を実行して、パスを探します。

# perl -e 'use Config; print $Config{sitearchexp};'

RedHat 系は /usr/lib/perl5/site_perl/5.6.1/i386-linux に、Debian 系は /usr/local/share/perl/5.6.1 にコピーすることになるかと思います(Perl 5.6.1 の場合)。

# cp perl56/pdflib_pl.so /usr/lib/perl5/site_perl/5.6.1/i386-linux/
# cp pdflib_pl.pm /usr/lib/perl5/site_perl/5.6.1/i386-linux/

これでインストールは完了です。サンプルファイルを「perl hello.pl」などのようにして実行し、PDF が正常に生成されることを確認してみてください。

▲目次

ライセンス関係

開発環境と本番環境が存在する場合、ライセンスは両環境に必要？

開発環境と本番環境とで一瞬でも同時に同一ライセンスを指定している瞬間がある場合は、別々のライセンスが必要です。例えば開発環境で開発を行ない、本番環境を設定して本番環境でテストするような場合、開発環境からライセンスキーを削除してからではないと、本番環境にライセンスキーを設定することはできません。

ただ、ライセンスキーが無くても www.pdflib.com というロゴが表示されるだけなので、そのような状況の場合にはそもそも開発環境にライセンスキーは不要ではないでしょうか？

ライセンスに関するエラーが表示される

SMPマシンで、下記のようなエラーが表示されてしまう場合、必要なライセンス数が足りていません(PDFlib 7 からは物理CPU数にかかわらず必要ライセンス数は１台に付き１つなので、このエラーは出ないはずです）。

Fatal error: PDFlib error [1994] PDF_begin_page: Found 2 CPUs - license covers only 1 in /var/www/htdocs/test.php on line 5

PDFlib は CPU ライセンスのため、PDFlib を使用するマシンの CPU 数が2つであれば2ライセンス、4CPUマシンであれば4ライセンスが必要となります。ライセンスキーの追加は、不足しているライセンスキーを購入して、1CPU用ライセンスキー2つを合わせて2CPU構成のサーバで利用することは出来ますか？の手順通りライセンスファイルを作成します。

Apache(PHP)において、環境変数 PDFLIBLICENSEFILE でライセンスファイルを設定したい

まずは PDF_set_parameter() APIを使用して PDFLIBLICENSEFILE を設定し、ライセンスファイルの内容が正常かどうかを確認しましょう。ライセンスファイルの内容は下記のようになります（xxxxxxxxxx-xxxxxxxxxx や yyyyyyyyyy-yyyyyyyyyy の部分は、実際のライセンスキーを指定します。指定するライセンスキーが一つの場合、当然「PDFlib 7.0.0」の行は一行だけです）。

PDFlib license file 1.0
PDFlib 7.0.0 xxxxxxxxxx-xxxxxxxxxx
PDFlib 7.0.0 yyyyyyyyyy-yyyyyyyyyy

PDFlib とはまったく関係なく環境変数の普通の話ではありますが、環境変数 PDFLIBLICENSEFILE は Apache を起動するプロセスの環境変数ではなく、Apache の環境変数として指定する必要があります。つまり、

# export PDFLIBLICENSEFILE=/tmp/licensefile
# /etc/init.d/httpd start

と実行しても環境変数 PDFLIBLICENSEFILE は Apache には設定されていない(引き継がれていない）ため、これではうまくいきません。一番簡単な解決方法は、/etc/init.d/httpd ファイルに export 行を書いてしまうことだと思われます。

以下は httpd ファイルの変更例です。

start() {
    echo -n $"Starting $prog: "

    # この行を追加します。
    export PDFLIBLICENSEFILE=/tmp/licensefile

    daemon $httpd `moduleargs` $OPTIONS
    RETVAL=$?
    echo
    [ $RETVAL = 0 ] && touch /var/lock/subsys/httpd
    return $RETVAL
}

▲目次

技術関係

PDFlib+PDI で取り込んだ PDF ファイルの総ページ数を求めるには？

PDF_get_pdi_value() を key に '/Root/Pages/Count' を指定して呼び出しましょう。下記のように呼び出せば OK です($doc は PDF_open_pdi()の、$pageはPDF_open_pdi_page()のリターン値です)。

PDF_get_pdi_value($p, '/Root/Pages/Count', $doc, $page, 0);

透明テキストの出力方法は？

PDFlibおよびPDF仕様にはテキストレンダリングモードという概念があります。その中に「不可視」という属性があるため、textrendering を不可視設定するだけで、以後の文字列を不可視で出力することができます。

PDF_set_value($p, "textrendering", 3);
PDF_show($p, "あいうえお");	// 不可視

PDF_set_value($p, "textrendering", 0);
PDF_continue_text($p, "かきくけこ");	// 可視

ただしフリーソフトウェアなど、テキストレンダリングモードを解釈しない PDF ビューワの場合には、もしかしたら不可視にならない可能性があります。

白紙の PDF が出力される

多くの場合、IE のバグによるものです。サンプルでは正常に実行できるのに、自分で作ったプログラムではうまくいかない(PDF が出力されない)場合、サンプルのようにヘッダをちゃんと出力しているかどうか確認する必要があります。

header("Content-type: application/pdf");
header("Content-Length: 長さ");
header("Content-Disposition: inline; filename=PDFファイル名.pdf");

もし上記を追加しても駄目な場合、PHPでセッションを利用していると、クライアントがIEの場合のみ「(生成したPDFのURL名)が取得できません」といったエラーダイアログが表示され、正しくPDF表示ができませんや、header を参考にして、「Pragma: no-cache」「Expires: 0」「Cache-Control: must-revalidate, post-check=0, pre-check=0」といったヘッダを出力してみてください。PHP における説明ですが、他の言語でも共通の箇所は多いです。

PDF_begin_document()等の viewerpreferences オプションの指定方法は？

下記のようになります。なおスペースのかわりに「=」で指定することもできます(個人的にはこっちの方が好みです)。

PDF_begin_document($p, "", "viewerpreferences {hidemenubar=true hidetoolbar=true}");

# こう書いても OK
PDF_begin_document($p, "", "viewerpreferences={hidemenubar=true hidetoolbar=true}");

PDFlib で作成した PDF が Acrobat Reader 4.0や5.0で開けない

普段意識しないかもしれませんが PDF にはバージョンがあります。PDFlib 6　各製品はデフォルトで PDF バージョン 1.5 で PDF を出力します。また PDFlib 7 各製品はデフォルトで PDF バージョン 1.6 で PDF を出力します。

PDF 1.7 は Acrobat 8 以降、PDF 1.6 は Acrobat 7 以降、PDF 1.5 は Acrobat 6 以降、PDF 1.4 は Acrobat 5 以降、PDF 1.3 は Acrobat 4 以降でしか開くことはできません。PDF のバージョンを変更するには下記のように、PDF_new()関数でPDFオブジェクト生成後に設定するか、あるいは PDF_begin_document()のcompatibilityオプションで指定します。

$p = PDF_new()
PDF_set_parameter($p, "compatibility", "1.4"); # Acrobat 5 以降で開ける
PDF_begin_document($p, "", "compatibility=1.4")

テキストフローで日本語を利用するには？

テキストフローで日本語を利用する場合、エンコーディングとして Unicode を使用する必要があります。具体的には encoding オプションとして、

標準CJKフォント(HeiseiKakuGo-W5やHeiseiMin-W3等)の場合は「UniJIS-UCS2-H」
カスタムフォント(TrueTypeフォントやOpenTypeフォント)の場合は「unicode」

を指定することになります。サンプルコードとして、textflow_sample.php (PDFlib 7 用) (PDFlib 6 用) を用意しました。生成される PDF は textflow_sample.pdf です。

PDFlib ブロックで複数行を指定するには？

PDFlib ブロックで複数行のテキストを利用する場合には、PDFlib ブロックのプロパティで[テキスト]タブの[textflow]を true に設定し、テキストフローを利用する必要があります。

あとは PDF_fill_textblock()に文字列を指定するだけです。ブロックの横幅に入りきらない行は自動的に改行されますが、明示的に改行する場合は「\n」を指定します。

$text = "あ\nいう\nえおか\nきくけこ\nさしすせそ\nたちつてとなにぬねのはひふへほ";

PDF_fill_textblock($p, $page, "testblock", mb_convert_encoding($text, "UTF-8", "EUC-JP"), 
  "fontname {HeiseiKakuGo-W5} pdiwarning true encoding UniJIS-UCS2-H textformat utf8");

一つのPDFlib ブロック内でフォントや文字等を変更するには？

textflow を true に設定した PDFlib ブロックの場合、テキストフローのインラインオプションリストを利用することにより、一つのブロック内でフォント等の設定を変更することができます。

実際の指定方法は下記のようになります。インラインオプションごとに encoding を指定し、かつ PDF_fill_textblock()のオプションでもエンコーディングを指定しないとエラーとなるので注意してください。

$org = "<fontsize=10 fontname=HeiseiKakuGo-W5 encoding=UniJIS-UCS2-H>サンプル1<fontsize=30" . 
    "fontname=HeiseiMin-W3 encoding=UniJIS-UCS2-H>サンプル2";

PDF_set_parameter($p, "textformat", "utf8");
$org = "\xEF\xBB\xBF" . mb_convert_encoding($org, "UTF-8", "EUC-JP");
PDF_fill_textblock($p, $page, "org", $org, "encoding=UniJIS-UCS2-H");

注釈等、オプションを日本語で指定するには

日本語マニュアルの P.102「4.5.4 Unicode 非対応言語での文字列処理」の「オプションリストの文字列」にある通り、各関数の引数は UTF-8 で指定する必要があります(UTF-8 BOM をお忘れ無く)。そのため、例えば注釈に日本語を設定するために PDF_create_annotation() 関数を呼び出す時などには、下記のように UTF-8 で指定する必要があります(PDFlib 7 からは EUC-H や 90ms-RKSJ-H 等、Unicode 以外の CJK CMap で指定することも可能となりました )。

$contents = '注釈注釈注釈';
$contents = "\xEF\xBB\xBF" . mb_convert_encoding($contents, 'UTF-8', 'EUC-JP');
PDF_create_annotation($p, 100, 100, 500, 500, 'Text', 'contents='.$contents);

Solaris 8 など、UTF-8 に直接文字コードを変換できない環境の場合には、PDFlib の PDF_utf16_to_utf8()関数を利用することにより、UTF-16 から UTF-8 へ変換することができます(UTF-16 の場合、BOM は FFFE(Intel x86 などのリトルエンディアン環境の場合)もしくは FEFF(PowerPC などのビッグエンディアン環境の場合）です）。

$contents = '注釈注釈注釈';
$contents = "\xFF\xFE" . mb_convert_encoding($contents, 'UTF-16', 'EUC-JP');
$contents_utf8 = PDF_utf16_to_utf8($p, $contents);
PDF_create_annotation($p, 100, 100, 500, 500, 'Text', 'contents='.$contents_utf8);

もちろんタイトルや作成者も指定可能です。

$author = '鈴木一郎';
$author = "\xEF\xBB\xBF" . mb_convert_encoding($author, 'UTF-8', 'EUC-JP');
PDF_set_info($p, "Author", $author);

機種依存文字の表示方法

文字コードの世界では、厳密な意味では「機種依存文字」というものは存在しません。例えば Windows で機種依存文字とされている○に1「①」という文字や、はしごたか「髙」は Microsoft コードページ932(CP932)に含まれており、この文字セットは PDF では 90ms-RKSJ-H という CMap を指定することで扱うことができます。

なお 90ms-RKSJ-H は当然 Shift-JIS なので、Linux などでは EUC から変換する必要があります（PHP の場合、文字によっては変換先エンコードは SJIS-win と指定する必要があるかもしれません）。

$font = PDF_load_font($p, "KozGoPro-Medium", "90ms-RKSJ-H", "");
PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);

$str = "あ①髙お";
$str = mb_convert_encoding($str, 'Shift-JIS', 'EUC-JP');
PDF_show($p, $str);

PDF ブロックで、文字列を左詰め、右詰め、中央揃え等で表示するには

PDFlib ブロックでテキストフローを使うのが一番簡単だと思います。PDFlib ブロックのプロパティで、[テキスト]の「textflow」を true に設定します。文字の配置は alignment プロパティでも設定できますし、（もちろん）プログラムから設定することもできます。

サンプルコードは sample_textflow.php, テンプレートPDF ファイルは 560-0201_textflow.pdf で、生成される PDF は textflow_sample.pdf です。PDF_fill_textblock()関数のオプションの textformat 引数は auto ではなく utf8 等、渡す文字列の文字コードを指定する必要がありますので注意してください。

サンプルを実行しても文字が表示されない場合には、使用している PDFlib ブロックプラグインと PDFlib が最新バージョンかどうかを確認してください。PDFlib ブロックプラグイン 2.1.0 で作成した PDF ファイルは PDFlib 6.0.2 以降じゃないと扱えません。

外字エディタで作成した外字の出力方法

カスタムフォントの利用方法とほぼ同じで、フォントを読み込み、出力文字として外字の文字コードを指定するぐらいです。

サンプルコードは gaiji.php(PDFlib 7用)(PDFlib 6用) にあります。

テンプレートPDF ファイルは 560-0201.pdf, サンプルで作成した外字フォントファイルは EUDC.TTE で、生成される PDF は gaiji.pdf です。カスタムフォントの場合、エンコーディングは Unicode の必要があります。外字領域の文字コードを変換する場合には変換元のエンコーディングとして SJIS-win を指定する必要があるので注意してください。

サンプルプログラムの実行方法は、外字エディタ(eudcedit.exe)で作成した外字フォント(外字エディタで作成した外字フォントは C:\windows\fonts\EUDC.TTE として保存されます)を /tmp にコピーし、gaiji.php と 560-0201.pdf を同じディレクトリに配置して実行するだけです。

なお PDF_setfont()を呼び出した後は、設定したフォントで文字が出力されます。そのため、結果として当該フォント(外字フォント)の文字セットに無い文字は出力されません。

外字および出力しようとする文字を全て含んだフォントを用意し、そのフォントを PDF_setfont()関数で設定して出力
プログラム側で出力する文字およびその文字に設定するフォントを判断し、文字種ごとに必要に応じて PDF_setfont()関数を呼び出してフォントの切り替えを行う(外字の場合のみフォントを切り替え)

のどちらかにより対処する必要があります。

複数のPDFファイルの合成方法

下記メソッドを繰り返し呼び出すだけです。非常に簡単です。hello.php を元にした、複数PDFファイルを結合するサンプルプログラムは join.php です。

PDF_open_pdi_document()
PDF_open_pdi_page()
PDF_begin_page_ext()
PDF_fit_pdi_page()
PDF_end_page_ext()
PDF_close_pdi_page()
PDF_close_pdi_document()

Perl 版 PPS での日本語表示

PDFlib 6 のアーカイブファイル同梱の businesscard.pl をベースに、日本語を表示するための簡単な処理を追加したプログラムの Perl 版(businesscard.pl)です。

プログラム内の文字コードは SJIS ですので、Linux や Solaris 等の Unix 系 OS で実行する場合はプログラムの文字コードを EUC にして、Jcode::convert()に渡す $from の値を 'euc-jp' に書き換えてください(ファイルの文字コードと Jcode::convert()の引数があっていないと、おそらく出力された文字が文字化けするので注意してください）。

.TTC ファイル内のフォントの指定方法

msgothic.ttc 等のように拡張子が .ttc のファイルは、複数の TrueType フォント(*.TTF)ファイルを一つにまとめたフォントファイルです。各フォントの名前を直接指定することもできますが、最も簡単な方法は下記のように .TTC ファイル内の各フォントを番号で指定しまうことです。「msgothic」や「msmincho」は変数名のようなものなので、ユニークな英数字であれば特に何でもかまいません。

PDF_set_parameter($p, "FontOutline", "msgothic=/tmp/msgothic.ttc");
PDF_set_parameter($p, "FontOutline", "msmincho=/tmp/msmincho.ttc");

// msmincho の1番目のフォントの場合
$font = PDF_load_font($p, "msmincho:0", "unicode", "embedding");

// msgothic の3番目のフォントの場合
$font = PDF_load_font($p, "msmincho:2", "unicode", "embedding");

PDFlib ブロックに指定する場合、下記のようになります(encode=unicode であることに注意）。

PDF_set_parameter($p, "FontOutline", "hogehoge=msgothic.ttc");
PDF_fill_textblock($p, $page, "org", $org, 
  "fontname hogehoge:1 fontsize 20 encoding unicode textformat utf8");

テキストフローの文字列の均等割付

日中韓文字の場合には下記オプションを指定することで、いい感じの表示になります。

hyphenchar=none alignment=justify lastalignment=justify adjustmethod=spread spreadlimit=10000%

なお alignment=justify のみ設定している場合、テキストフローの設定範囲内に文字列が収まる場合には alignment=left と同等の表示となりますので注意が必要です。

色設定を CMYK にしたい

PDF_load_iccprofile()関数でICCプロファイルを読み込むことで、設定可能です。Japan Color 2001 Coated など、国内で使われているICCプロファイルは Adobe ICCプロファイルからダウンロードできます。

下記は、Adobe からダウンロードした ICCプロファイル(Japan Color 2001 Coated)を読み込み、CMYK に設定している例です。

define('PATH_ICC', '/usr/local/pdflib7/resource/icc/AdobeICCProfiles_jp');

$p = PDF_new();
if (PDF_begin_document($p, "", "") == 0) { die("Error: " . PDF_get_errmsg($p)); }

PDF_set_parameter($p, "SearchPath", PATH_ICC);

PDF_begin_page_ext($p, 1000, 1000, "");

$icchandle = PDF_load_iccprofile($p, "JapanColor2001Coated", "usage=iccbased");
if ($icchandle == 0) {
  echo PDF_get_errmsg($p);
 exit;
}
PDF_set_value($p, "setcolor:iccprofilecmyk", $icchandle );
PDF_setcolor($p, "fill", "iccbasedcmyk", 0,1,0,0);

PDFlib で文字を修飾(太字や下線など）したい

PDFlib で文字をイタリックや太字にする場合、PDF_load_font()の fontstyle オプションを指定することで実現可能です(テキストフローの場合、PDF_create_textflow()関数で指定)

指定できるオプションは、日本語マニュアル(リファレンス)のP.42「表3.4 PDF_load_font()のオプション」にあります。

またアンダーラインは、set_parameter()メソッドで underline に true を設定することで、指定可能です(テキストフローの場合は、下線を指定する文字列をタグで囲みます)。

▲目次

これってバグ？

PHP でサンプルを実行するとエラーが出力されます

FreeBSD4.5 や一部の環境において、PHP で PDFlib を実行すると下記のようなエラーが表示される環境があります(xxxxx は関数名等)。

/usr/libexec/ld-elf.so.1: /usr/local/php4/lib/php/libpdf_php.so: Undefinedsymbol "xxxxx"

これはライブラリの一部に非互換性があるから発生しているもののようです。対策は簡単で、DSO 版の pdflib を自前でビルドしてしまうことです。手順は DSO 版 PDFlib の自前ビルドを参照してください。

Windows 用の PHP で、外部ファイルを読み込めない

Windows 用の PHP では、PHP 側の機能制限により PDFlib で相対パスを使用することはできません。そのため雛形 PDF や画像等を読み込む場合には、PDF_open_pdi()等、外部ファイルを読み込む関数を呼び出す前に下記のように SearchPath を設定する必要があります(パスに相対パスを指定することはできません)。

PDFlib 同梱のサンプルプログラムにおいても、SearchPath を下記の例のように絶対パスに変更してやらないとエラーとなるので注意しましょう。

$searchpath = "c:/Apache Group/Apache/htdocs/560-0201.pdf";
PDF_set_parameter($p, "SearchPath", $searchpath);

PDFlib で生成した PDF ファイルを Acrobat 8 で印刷しようとするとエラーが出ます

ライセンスキーを設定していない（www.pdflib.com というロゴが出力されている) PDFlib で生成した PDF ファイルを Acrobat 8 で印刷しようとすると、「印刷ジョブを開始できません。プリンタは利用可能ですか？」（画像１）と表示され、OKを押下すると「描画エラーが発生しました。」（画像２）と表示された後に、「www.pdflib.com」というロゴが無い状態で印刷されるという現象が確認されています。

これは PDFlib ML(英語) の Printing errors when printing pdftest sample にも説明がありますが、「www.pdflib.com」というロゴにも使用されている Type 3 フォントを非PostScriptプリンタに出力した時の、Acrobat Reader 8 のバグによるものです。この現象はPostScriptプリンタに出力した場合や、他のフォントの場合には発生しません(また Acrobat Reader 7 以下でも発生しません）。

通常 Type 3 フォントを使うことはほとんど無く、また、ライセンスキーを購入すれば Type 3 フォントを使用している「www.pdflib.com」というロゴを消せるため実使用上にはまったく問題ありませんが、Acrobat Reader 8 は挙動が変わった箇所も多いため、個人的にはあまりお薦めしません。また PDF の解釈が Acrobat Reader 7 以前と少し変わり、特に PDF 仕様からすると少し変な PDF を読み込んだ際の表示結果が異なっているため、PDF 仕様に正しく準拠していない PDF を出力する製品では注意が必要です(PDFlib ではそういうことはありません）。

▲目次

よくあるエラーメッセージとその原因

Fatal error: Uncaught exception 'PDFlibException' with message 'Font 'KozMinProVI-Regular' with
encoding 'EUC-H': Couldn't open CMap file 'EUC-H' for reading (file not found)'

PDFlib/PDI/PPS 7 以降で、CMap を設定していない時に発生するエラーです。CMap やフォントについてやサンプルコードを参考に、CMap を設定するようにしてください。

Fatal error:  Uncaught exception 'PDFlibException' with message 'License does not cover PDI and 
PDFlib Personalization Server (PPS)'

PDFlib のライセンスキーで PDFlib+PDI か PPS の機能、あるいは PDFlib+PDI のライセンスキーで PPS の機能を使おうとした時のエラーです。PDFlib/PDI/PPS 製品の違いについてを参考に、必要な機能を持つ製品にアップグレードしてください。

PDFlib exception occurred in hello sample: [1986] set_parameter: Invalid license key

無効なライセンスキーが指定された、あるいは旧バージョンのライセンスキーを指定した場合のエラーです。正しいライセンスキーを指定してください。

▲目次

<< PDFlib HOWTO に戻る

▲目次