documentation/manual/en/module_specs/Zend_Pdf-Properties.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.pdf.info">
   4     <!-- @todo review and revise upon completion of refactoring -->
   5     <title>Document Info and Metadata</title>
   6
   7     <para>
   8         A <acronym>PDF</acronym> document may include general information such as the document's
   9         title, author, and creation and modification dates.
  10     </para>
  11
  12     <para>
  13         Historically this information is stored using special Info structure. This structure
  14         is available for read and writing as an associative array using <code>properties</code>
  15         public property of <classname>Zend_Pdf</classname> objects:
  16
  17         <programlisting language="php"><![CDATA[
  18 $pdf = Zend_Pdf::load($pdfPath);
  19
  20 echo $pdf->properties['Title'] . "\n";
  21 echo $pdf->properties['Author'] . "\n";
  22
  23 $pdf->properties['Title'] = 'New Title.';
  24 $pdf->save($pdfPath);
  25 ]]></programlisting>
  26     </para>
  27
  28     <para>
  29         The following keys are defined by <acronym>PDF</acronym> v1.4 (Acrobat 5) standard:
  30
  31         <itemizedlist>
  32             <listitem>
  33                 <para>
  34                     <emphasis>Title</emphasis> - string, optional, the document's title.
  35                 </para>
  36             </listitem>
  37
  38             <listitem>
  39                 <para>
  40                     <emphasis>Author</emphasis> - string, optional, the name of the person who
  41                     created the document.
  42                 </para>
  43             </listitem>
  44
  45             <listitem>
  46                 <para>
  47                     <emphasis>Subject</emphasis> - string, optional, the subject of the document.
  48                 </para>
  49             </listitem>
  50
  51             <listitem>
  52                 <para>
  53                     <emphasis>Keywords</emphasis> - string, optional, keywords associated with the
  54                     document.
  55                 </para>
  56             </listitem>
  57
  58             <listitem>
  59                 <para>
  60                     <emphasis>Creator</emphasis> - string, optional, if the document was converted
  61                     to <acronym>PDF</acronym> from another format, the name of the application (for
  62                     example, Adobe FrameMaker®) that created the original document from which it was
  63                     converted.
  64                 </para>
  65             </listitem>
  66
  67             <listitem>
  68                 <para>
  69                     <emphasis>Producer</emphasis> - string, optional, if the document was converted
  70                     to <acronym>PDF</acronym> from another format, the name of the application (for
  71                     example, Acrobat Distiller) that converted it to <acronym>PDF</acronym>..
  72                 </para>
  73             </listitem>
  74
  75             <listitem>
  76                 <para>
  77                     <emphasis>CreationDate</emphasis> - string, optional, the date and time the
  78                     document was created, in the following form: "D:YYYYMMDDHHmmSSOHH'mm'", where:
  79
  80                     <itemizedlist>
  81                         <listitem>
  82                             <para>
  83                                 <emphasis>YYYY</emphasis> is the year.
  84                             </para>
  85                         </listitem>
  86
  87                         <listitem>
  88                             <para>
  89                                 <emphasis>MM</emphasis> is the month.
  90                             </para>
  91                         </listitem>
  92
  93                         <listitem>
  94                             <para>
  95                                 <emphasis>DD</emphasis> is the day (01–31).
  96                             </para>
  97                         </listitem>
  98
  99                         <listitem>
 100                             <para>
 101                                 <emphasis>HH</emphasis> is the hour (00–23).
 102                             </para>
 103                         </listitem>
 104
 105                         <listitem>
 106                             <para>
 107                                 <emphasis>mm</emphasis>is the minute (00–59).
 108                             </para>
 109                         </listitem>
 110
 111                         <listitem>
 112                             <para>
 113                                 <emphasis>SS</emphasis> is the second (00–59).
 114                             </para>
 115                         </listitem>
 116
 117                         <listitem>
 118                             <para>
 119                                 <emphasis>O</emphasis> is the relationship of local time to
 120                                 Universal Time (UT), denoted by one of the characters +, −, or Z
 121                                 (see below).
 122                             </para>
 123                         </listitem>
 124
 125                         <listitem>
 126                             <para>
 127                                 <emphasis>HH</emphasis> followed by ' is the absolute value of the
 128                                 offset from UT in hours (00–23).
 129                             </para>
 130                         </listitem>
 131
 132                         <listitem>
 133                             <para>
 134                                 <emphasis>mm</emphasis> followed by ' is the absolute value of the
 135                                 offset from UT in minutes (00–59).
 136                             </para>
 137                         </listitem>
 138                     </itemizedlist>
 139
 140                     The apostrophe character (') after HH and mm is part of the syntax. All fields
 141                     after the year are optional. (The prefix D:, although also optional, is strongly
 142                     recommended.) The default values for MM and DD are both 01; all other numerical
 143                     fields default to zero values. A plus sign (+) as the value of the O field
 144                     signifies that local time is later than UT, a minus sign (−) that local time is
 145                     earlier than UT, and the letter Z that local time is equal to UT. If no UT
 146                     information is specified, the relationship of the specified time to UT is
 147                     considered to be unknown. Whether or not the time zone is known, the rest of the
 148                     date should be specified in local time.
 149                 </para>
 150
 151                 <para>
 152                     For example, December 23, 1998, at 7:52 PM, U.S. Pacific Standard Time, is
 153                     represented by the string "D:199812231952−08'00'".
 154                 </para>
 155             </listitem>
 156
 157             <listitem>
 158                 <para>
 159                     <emphasis>ModDate</emphasis> - string, optional, the date and time the document
 160                     was most recently modified, in the same form as
 161                     <emphasis>CreationDate</emphasis>.
 162                 </para>
 163             </listitem>
 164
 165             <listitem>
 166                 <para>
 167                     <emphasis>Trapped</emphasis> - boolean, optional, indicates whether the document
 168                     has been modified to include trapping information.
 169
 170                     <itemizedlist>
 171                         <listitem>
 172                             <para>
 173                                 <emphasis><constant>TRUE</constant></emphasis> - The document has
 174                                 been fully trapped; no further trapping is needed.
 175                             </para>
 176                         </listitem>
 177
 178                         <listitem>
 179                             <para>
 180                                 <emphasis><constant>FALSE</constant></emphasis> - The document has
 181                                 not yet been trapped; any desired trapping must still be done.
 182                             </para>
 183                         </listitem>
 184
 185                         <listitem>
 186                             <para>
 187                                 <emphasis><constant>NULL</constant></emphasis> - Either it is
 188                                 unknown whether the document has been trapped or it has been partly
 189                                 but not yet fully trapped; some additional trapping may still be
 190                                 needed.
 191                             </para>
 192                         </listitem>
 193                     </itemizedlist>
 194                 </para>
 195             </listitem>
 196         </itemizedlist>
 197     </para>
 198
 199     <para>
 200         Since <acronym>PDF</acronym> v 1.6 metadata can be stored in the special
 201         <acronym>XML</acronym> document attached to the <acronym>PDF</acronym> (XMP - <ulink
 202             url="http://www.adobe.com/products/xmp/">Extensible Metadata Platform</ulink>).
 203     </para>
 204
 205     <para>
 206         This XML document can be retrieved and attached to the PDF with
 207         <methodname>Zend_Pdf::getMetadata()</methodname> and
 208         <methodname>Zend_Pdf::setMetadata($metadata)</methodname> methods:
 209
 210         <programlisting language="php"><![CDATA[
 211 $pdf = Zend_Pdf::load($pdfPath);
 212 $metadata = $pdf->getMetadata();
 213 $metadataDOM = new DOMDocument();
 214 $metadataDOM->loadXML($metadata);
 215
 216 $xpath = new DOMXPath($metadataDOM);
 217 $pdfPreffixNamespaceURI = $xpath->query('/rdf:RDF/rdf:Description')
 218                                 ->item(0)
 219                                 ->lookupNamespaceURI('pdf');
 220 $xpath->registerNamespace('pdf', $pdfPreffixNamespaceURI);
 221
 222 $titleNode = $xpath->query('/rdf:RDF/rdf:Description/pdf:Title')->item(0);
 223 $title = $titleNode->nodeValue;
 224 ...
 225
 226 $titleNode->nodeValue = 'New title';
 227 $pdf->setMetadata($metadataDOM->saveXML());
 228 $pdf->save($pdfPath);
 229 ]]></programlisting>
 230     </para>
 231
 232     <para>
 233         Common document properties are duplicated in the Info structure and Metadata document (if
 234         presented). It's user application responsibility now to keep them synchronized.
 235     </para>
 236 </sect1>
 237 <!--
 238 vim:se ts=4 sw=4 et:
 239 -->