3 <refname>Frequently Asked Questions (FAQ)</refname>
4 <refpurpose>Quick answers to common questions</refpurpose>
10 <firstname>Martin</firstname>
11 <surname>Geisler</surname>
13 {@link mailto:mgeisler@users.sourceforge.net
14 mgeisler@users.sourceforge.net}
21 <refsect1 id="{@id pel-acronym}">
23 <title>What does PEL stand for?</title>
25 <para>PEL is an acronym for "PHP Exif Library". Sound simple
26 enough, doesn't it?</para>
28 <para>But did you realise that PEL is an acronym consisting of two
29 acronyms, one of which is recursive! So "PEL" actually stands for
30 "PHP Hypertext Preprocessor Exchangeable image file format Library".
35 <refsect1 id="{@id exif-vs-exif}">
37 <title>What's the business with EXIF vs. Exif?</title>
39 <para>Well, since Exif is an acronym for "Exchangeable image file
40 format" and thus you would expect it to be spelled "EXIF", just like
41 "JPEG" which is an acronym for Joint Photographic Experts
44 <para>But the Exif standards spell Exif as "Exif" and so does PEL,
45 at least since version 0.9. But should they ever decide to update
46 their acronym to "EXIF" then PEL will revert... Luckily it does not
47 affect the acronym PEL itself :-)</para>
52 <refsect1 id="{@id why-php5}">
53 <title>Why does PEL require PHP version 5?</title>
55 <para>The support for object-oriented programming was completely
56 overhauled with the introduction of PHP 5 in July 2004. The changes
57 included both semantic changes and syntaxtical changes to the PHP
60 <para>The semantic change was the use of object references per
61 default. This change means that when you do</para>
63 <programlisting role="php">
65 $object_a = $ifd->getEntry(PelTag::IMAGE_DESCRIPTION);
66 $object_a->setValue('This is my new description.');
67 $object_b = $ifd->getEntry(PelTag::IMAGE_DESCRIPTION);
71 <para>then <literal>$object_a</literal> and
72 <literal>$object_b</literal> will both reference <emphasis>the
73 same</emphasis> element. In particular, you will see that
74 <literal>$object_b->getValue()</literal> returns the string just
75 stored in <literal>$object_a</literal> (since they are the same
76 object). With PHP 4 you would have gotten two different objects,
77 which is generally not what you want.</para>
79 <para>The syntaxtical changes from PHP 5 to PHP 4 include the
80 addition of access modifiers to object fields (the private,
81 protected, and public keywords), object constants, constructors
82 named <literal>__construct()</literal>, interfaces and abstract
83 classes, and exceptions. PEL uses all these new features to the
84 fullest, which means that PHP 4 doesn't understand the code.</para>
86 <para>If your provider is still using PHP 4, then you should ask
87 them to upgrade. PHP 5 has been declared stable since July 2004 and
88 all major PHP applications ({@link http://www.wordpress.org
89 WordPress}, {@link http://gallery.menalto.com/ Gallery},
90 {@link http://phpwiki.sourceforge.net/ PhpWiki},
91 {@link http://www.phpmyadmin.net/ phpMyAdmin}, etc...), have been
92 upgraded to work with PHP 5, so an upgrade should not bring you any
93 problems, just more features and better performance.</para>
98 <refsect1 id="{@id fatal-php4-errors}">
100 <title>Why do I get fatal errors from PHP?</title>
102 <para>If you get a fatal error when trying to use PEL, then your
103 installation of PHP might be too old. PEL requires PHP version 5.
104 Please see the question "{@tutorial faq.pkg#why-php5}" for more
110 <refsect1 id="{@id call-on-non-object}">
111 <title>What does "<literal>Call to a member function
112 <function>f</function> on a non-object</literal>" (where
113 <function>f</function> is <literal>getTiff()</literal> or
114 <literal>setValue()</literal>) mean?</title>
116 <para>This is the error PHP gives when you call a method on a
117 variable which is not an object.</para>
119 <para>PEL uses objects to represent the entire structure of a JPEG
120 image, and many of the methods defined on those objects return other
121 objects. In particular, the method {@link PelJpeg::getExif()}
122 returns a {@link PelExif} object and {@link PelIfd::getEntry()}
123 returns a {@link PelEntry} object.</para>
125 <para>But both methods can return <literal>null</literal> if no such
126 section or entry exist. The correct way to use them is thus
127 something along the lines of:</para>
129 <programlisting role="php">
131 $exif = $jpeg->getExif();
133 $tiff = $exif->getTiff();
134 /* Do something with the TIFF data. */
136 /* Sorry --- no Exif data found. */
141 <para>The same principle applies to the return values of
142 {@link PelIfd::getEntry()} and all other methods which return
148 <refsect1 id="{@id IPTC-entries}">
150 <title>Does PEL handle IPTC entries?</title>
152 <para>No, PEL only deals with Exif data, and no such extension is
153 planned. Try taking at look at the
154 {@link http://www.ozhiker.com/electronics/pjmt/ PHP JPEG Metadata
155 Toolkit} which should handle IPTC along with a huge number of other
156 metadata formats.</para>
161 <refsect1 id="{@id missing-Gettext}">
163 <title>Why does Gettext not work?</title>
165 <para>PEL uses Gettext for localization, and thus your system must
166 fulfill a few requirements:</para>
171 <para>PHP must have support for the
172 {@link http://www.php.net/manual/en/ref.gettext.php Gettext
173 extension}. Most installations of PHP already has this, but
174 please double-check with <function>
175 {@link http://www.php.net/manual/en/function.phpinfo.php
176 phpinfo}</function> before asking for help on the
181 <para>The system must be setup to generate locales for the
182 languages into which PEL has been translated. Again, most
183 commercial webhosts would have their systems configured to deal
184 with all locales, but if you're installing PEL on your own
185 server you'll probably have to reconfigure it.</para>
187 <para>How to configure the locales differ from system to system.
188 With the {@link http://www.debian.net/ Debian GNU/Linux}
189 distribution you should run</para>
192 dpkg-reconfigure locales
195 <para>and then select all locales that you want your system to
198 <para>Restart your webserver after changing the locale setup to
199 make the changes effective.</para>
208 <refsect1 id="{@id error-handling}">
210 <title>How to deal with broken images?</title>
212 <para>By default PEL will try to load as much from an image as
213 possible and continue dispite any errors found. The Exif standard
214 mandates certain formats and lengths for some entries, and sometimes
215 these requirements are violated.</para>
217 <para>The strictness of PEL is controlled by the the method
218 {@link Pel::setStrictParsing()}. The default is non-strict parsing.
219 In this mode, PEL will not throw exceptions for parse errors but
220 instead store them for later inspection via the
221 {@link Pel::getExceptions()} method.</para>
223 <para>With an argument of <literal>true</literal> to
224 {@link Pel::setStrictParsing()} you make PEL throw exceptions upon
227 <para>This may all sound very complex, but it is actually fairly
228 simple for most uses: have PEL load your images in non-strict mode
229 and check for errors afterwards, if necessary.</para>
231 <para>Please note that even if PEL is in non-strict mode it might
232 throw exceptions while parsing an image, for example if the image
233 cannot be recognized a JPEG or TIFF image. So it is always
234 necessary to wrap calls to PEL in a try-catch block.</para>
239 <refsect1 id="{@id commercial-use}">
241 <title>Can I use PEL for a commercial application?</title>
243 <para>Yes, no problem as long as you do not distribute your
244 application under another license than the GNU GPL.</para>
246 <para>As you should know, PEL is licensed to you under the
247 conditions of the GNU GPL. The license deals
248 <emphasis>only</emphasis> with the distribution of PEL and any
249 derivative works based on PEL, the license has nothing to say over
250 how you may use PEL.</para>
252 <para>So if you do not distribute your code, then you can use it for
253 whatever you want, including writing a website (commercial or not)
254 that integrates PEL. Please see
255 {@link http://www.gnu.org/licenses/gpl-faq.html#GPLRequireSourcePostedPublic
256 this question} in the GPL FAQ.</para>
261 <refsect1 id="{@id unanswered-question}">
263 <title>My question is not answered here!</title>
265 <para>Please ask your questions on the
266 {@link http://lists.sourceforge.net/lists/listinfo/pel-devel PEL
267 Development List}. If an answer is found, then the FAQ will be