4 * PEL: PHP Exif Library.
5 * A library with support for reading and
6 * writing all Exif headers in JPEG and TIFF images using PHP.
8 * Copyright (C) 2004, 2005, 2006 Martin Geisler.
10 * This program is free software; you can redistribute it and/or modify
11 * it under the terms of the GNU General Public License as published by
12 * the Free Software Foundation; either version 2 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
20 * You should have received a copy of the GNU General Public License
21 * along with this program in the file COPYING; if not, write to the
22 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
23 * Boston, MA 02110-1301 USA
25 namespace lsolesen\pel;
28 * Classes for dealing with Exif entries.
30 * This file defines two exception classes and the abstract class
31 * {@link PelEntry} which provides the basic methods that all Exif
32 * entries will have. All Exif entries will be represented by
33 * descendants of the {@link PelEntry} class --- the class itself is
34 * abstract and so it cannot be instantiated.
36 * @author Martin Geisler <mgeisler@users.sourceforge.net>
37 * @license http://www.gnu.org/licenses/gpl.html GNU General Public
43 * Common ancestor class of all {@link PelIfd} entries.
45 * As this class is abstract you cannot instantiate objects from it.
46 * It only serves as a common ancestor to define the methods common to
47 * all entries. The most important methods are {@link getValue()} and
48 * {@link setValue()}, both of which is abstract in this class. The
49 * descendants will give concrete implementations for them.
51 * If you have some data coming from an image (some raw bytes), then
52 * the static method {@link newFromData()} is helpful --- it will look
53 * at the data and give you a proper decendent of {@link PelEntry}
56 * If you instead want to have an entry for some data which take the
57 * form of an integer, a string, a byte, or some other PHP type, then
58 * don't use this class. You should instead create an object of the
59 * right subclass ({@link PelEntryShort} for short integers, {@link
60 * PelEntryAscii} for strings, and so on) directly.
62 * @author Martin Geisler <mgeisler@users.sourceforge.net>
65 abstract class PelEntry
69 * Type of IFD containing this tag.
71 * This must be one of the constants defined in {@link PelIfd}:
72 * {@link PelIfd::IFD0} for the main image IFD, {@link PelIfd::IFD1}
73 * for the thumbnail image IFD, {@link PelIfd::EXIF} for the Exif
74 * sub-IFD, {@link PelIfd::GPS} for the GPS sub-IFD, or {@link
75 * PelIfd::INTEROPERABILITY} for the interoperability sub-IFD.
82 * The bytes representing this entry.
84 * Subclasses must either override {@link getBytes()} or, if
85 * possible, maintain this property so that it always contains a
86 * true representation of the entry.
90 protected $bytes = '';
93 * The {@link PelTag} of this entry.
100 * The {@link PelFormat} of this entry.
107 * The number of components of this entry.
111 protected $components;
114 * Return the tag of this entry.
116 * @return PelTag the tag of this entry.
118 public function getTag()
124 * Return the type of IFD which holds this entry.
126 * @return int one of the constants defined in {@link PelIfd}:
127 * {@link PelIfd::IFD0} for the main image IFD, {@link PelIfd::IFD1}
128 * for the thumbnail image IFD, {@link PelIfd::EXIF} for the Exif
129 * sub-IFD, {@link PelIfd::GPS} for the GPS sub-IFD, or {@link
130 * PelIfd::INTEROPERABILITY} for the interoperability sub-IFD.
132 public function getIfdType()
134 return $this->ifd_type;
138 * Update the IFD type.
141 * int must be one of the constants defined in {@link
142 * PelIfd}: {@link PelIfd::IFD0} for the main image IFD, {@link
143 * PelIfd::IFD1} for the thumbnail image IFD, {@link PelIfd::EXIF}
144 * for the Exif sub-IFD, {@link PelIfd::GPS} for the GPS sub-IFD, or
145 * {@link PelIfd::INTEROPERABILITY} for the interoperability
148 public function setIfdType($type)
150 $this->ifd_type = $type;
154 * Return the format of this entry.
156 * @return PelFormat the format of this entry.
158 public function getFormat()
160 return $this->format;
164 * Return the number of components of this entry.
166 * @return int the number of components of this entry.
168 public function getComponents()
170 return $this->components;
174 * Turn this entry into bytes.
177 * PelByteOrder the desired byte order, which must be either
178 * {@link Convert::LITTLE_ENDIAN} or {@link Convert::BIG_ENDIAN}.
180 * @return string bytes representing this entry.
182 public function getBytes($o)
188 * Get the value of this entry as text.
190 * The value will be returned in a format suitable for presentation,
191 * e.g., rationals will be returned as 'x/y', ASCII strings will be
192 * returned as themselves etc.
195 * boolean some values can be returned in a long or more
196 * brief form, and this parameter controls that.
198 * @return string the value as text.
200 abstract public function getText($brief = false);
203 * Get the value of this entry.
205 * The value returned will generally be the same as the one supplied
206 * to the constructor or with {@link setValue()}. For a formatted
207 * version of the value, one should use {@link getText()} instead.
209 * @return mixed the unformatted value.
211 abstract public function getValue();
214 * Set the value of this entry.
216 * The value should be in the same format as for the constructor.
219 * mixed the new value.
224 public function setValue($value)
227 * This (fake) abstract method is here to make it possible for the
228 * documentation to refer to PelEntry::setValue().
229 * It cannot declared abstract in the proper PHP way, for then PHP
230 * wont allow subclasses to define it with two arguments (which is
231 * what PelEntryCopyright does).
233 throw new PelException('setValue() is abstract.');
237 * Turn this entry into a string.
239 * @return string a string representation of this entry. This is
240 * mostly for debugging.
242 public function __toString()
244 $str = Pel::fmt(" Tag: 0x%04X (%s)\n", $this->tag, PelTag::getName($this->ifd_type, $this->tag));
245 $str .= Pel::fmt(" Format : %d (%s)\n", $this->format, PelFormat::getName($this->format));
246 $str .= Pel::fmt(" Components: %d\n", $this->components);
247 if ($this->getTag() != PelTag::MAKER_NOTE && $this->getTag() != PelTag::PRINT_IM) {
248 $str .= Pel::fmt(" Value : %s\n", print_r($this->getValue(), true));
250 $str .= Pel::fmt(" Text : %s\n", $this->getText());