## Apache Zeta Components Manual :: File Source for analyzer.php

## Source for file analyzer.php

Documentation is available at analyzer.php

1. <?php
2. /**
3. * File containing the ezcImageAnalyzer class.
4. *
5. * Licensed to the Apache Software Foundation (ASF) under one
6. * or more contributor license agreements. See the NOTICE file
7. * distributed with this work for additional information
8. * regarding copyright ownership. The ASF licenses this file
9. * to you under the Apache License, Version 2.0 (the
10. * "License"); you may not use this file except in compliance
11. * with the License. You may obtain a copy of the License at
12. *
13. * http://www.apache.org/licenses/LICENSE-2.0
14. *
15. * Unless required by applicable law or agreed to in writing,
16. * software distributed under the License is distributed on an
17. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18. * KIND, either express or implied. See the License for the
19. * specific language governing permissions and limitations
20. * under the License.
21. *
22. * @package ImageAnalysis
23. * @version //autogentag//
24. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
25. * @filesource
26. */
28. /**
29. * Class to retreive information about a given image file.
30. * This class scans the specified image file and leaves the information
31. * available through the public property {@link ezcImageAnalyzer::$data}.
32. * The information available depends on the handlers used by the
33. * ezcImageAnalyzer and the type of image you select. In case the
34. * ezcImageAnalyzer does not find a suitable handler to analyze an image,
35. * it will throw a {@link ezcImageAnalyzerFileNotProcessableException}.
36. *
37. * In this package the following handlers are available (in their priority
38. * order):
39. * - {@link ezcImageAnalyzerImagemagickHandler}, which uses the ImageMagick
40. * binary "identify" to collect information about an image.
41. * - {@link ezcImageAnalyzerPhpHandler}, which relies on the GD extension and
42. * is capable of using the exif extension to determine additional data.
43. *
44. * For detailed information on the data provided by these handlers,
45. * their capabilities on analyzing images and their speciallties, please
46. * take a look at their documentation. For general information on handlers,
47. * look at {@link ezcImageAnalyzerHandler},
48. * {@link ezcImageAnalyzer::getHandlerClasses()} and
49. * {@link ezcImageAnalyzer::setHandlerClasses()}.
50. *
51. * A simple example.
52. * <code>
53. * // Analyzation of the MIME type is done during creation.
54. * $image = new ezcImageAnalyzer( dirname( __FILE__ ).'/toby.jpg' );
55. *
56. * if ( $image->mime == 'image/tiff' || $image->mime == 'image/jpeg' )
57. * {
58. * // Analyzation of further image data is done during access of the data
59. * echo 'Photo taken on '.date( 'Y/m/d, H:i', $image->data->date ).".\n";
60. * }
61. * elseif ( $mime !== false )
62. * {
63. * echo "Format was detected as {$mime}.\n";
64. * }
65. * else
66. * {
67. * echo "Unknown photo format.\n";
68. * }
69. * </code>
70. *
71. * If you want to manipulate the handlers used by ezcImageAnalyzer, you can do
72. * this globally like this:
73. * <code>
74. * // Retreive the predefined handler classes
75. * $originalHandlers = ezcImageAnalyzer::getHandlerClasses();
76. * foreach ( $handlerClasses as $id => $handlerClass )
77. * {
78. * // Unset the ezcImageAnalyzerPhpHandler (do not use that anymore!)
79. * if ( $handlerClass === 'ezcImageAnalyzerPhpHandler' )
80. * {
81. * unset( $handlerClasses[$id] );
82. * }
83. * }
84. * // Set the new collection of handler classes.
85. * ezcImageAnalyzer::setHandlerClasses( $handlerClasses );
86. *
87. * // Somewhere else in the code... This now tries to use your handler in the
88. * // first place
89. * $image = new ezcImageAnalyzer( '/var/cache/images/toby.jpg' );
90. * </code>
91. *
92. * Or you can define your own handler classes to be used (beware, those must
93. * either be already loaded or load automatically on access).
94. * <code>
95. * // Define your onw handler class to be used in the first place and fall back on
96. * // ImageMagick, if necessary.
97. * $handlerClasses = array( 'MyOwnHandlerClass', 'ezcImageAnalyzerImagemagickHandler' );
98. * ezcImageAnalyzer::setHandlerClasses( $handlerClasses );
99. *
100. * // Somewehre else in the code... This now tries to use your handler in the
101. * // first place
102. * $image = new ezcImageAnalyzer( '/var/cache/images/toby.jpg' );
103. * </code>
104. *
105. * @property-read string $mime
106. * The MIME type of the image.
107. * @property-read ezcImageAnalyzerData $data
108. * Extended data about the image.
109. *
110. * @package ImageAnalysis
111. * @version //autogentag//
112. */
113. class ezcImageAnalyzer
114. {
115. /**
116. * The path of the file to analyze.
117. *
118. * @var string
119. */
120. protected $filePath ;
122. /**
123. * Determines whether the image file has been analyzed or not.
124. * This is used internally.
125. *
126. * @var bool
127. */
128. protected $isAnalyzed ;
130. /**
131. * Container to hold the properties
132. *
133. * @var array(string=>mixed)
134. */
135. protected $properties ;
137. /**
138. * Collection of known handler classes. Classes are ordered by priority.
139. *
140. * @var array(string=>mixed)
141. */
142. protected static $knownHandlers = array(
143. 'ezcImageAnalyzerPhpHandler' => array(),
144. 'ezcImageAnalyzerImagemagickHandler' => array(),
145. );
147. /**
148. * Available handler classes and their options.
149. *
150. * @var array
151. */
152. protected static $availableHandlers;
154. /**
155. * Create an image analyzer for the specified file.
156. *
157. * @throws ezcBaseFilePermissionException
158. * If image file is not readable.
159. * @throws ezcBaseFileNotFoundException
160. * If image file does not exist.
161. * @throws ezcImageAnalyzerFileNotProcessableException
162. * If the file could not be processed.
163. * @param string $file The file to analyze.
164. */
165. public function __construct ( $file )
166. {
167. if ( ! file_exists ( $file ) || ! is_file ( $file ) )
168. {
169. throw new ezcBaseFileNotFoundException ( $file );
170. }
171. if ( ! is_readable ( $file ) )
172. {
173. throw new ezcBaseFilePermissionException ( $file, ezcBaseFileException ::READ );
174. }
175. $this-> filePath = $file;
176. $this-> isAnalyzed = false;
178. $this-> checkHandlers ();
180. $this-> analyzeType ();
181. }
183. /**
184. * Check all known handlers for availability.
185. *
186. * This method checks all registered handler classes for if the they are
187. * available (using {@link ezcImageAnalyzerHandler::isAvailable()}).
188. *
189. * @throws ezcImageAnalyzerInvalidHandlerException
190. * If a registered handler class does not exist
191. * or does not inherit from {@link ezcImageAnalyzerHandler}.
192. */
193. protected function checkHandlers ()
194. {
195. if ( isset( ezcImageAnalyzer ::$availableHandlers ) && is_array( ezcImageAnalyzer ::$availableHandlers ) )
196. {
197. return;
198. }
199. ezcImageAnalyzer::$availableHandlers = array();
200. foreach ( ezcImageAnalyzer::$knownHandlers as $handlerClass => $options )
201. {
202. if ( !ezcBaseFeatures::classExists( $handlerClass ) || ! is_subclass_of ( $handlerClass, 'ezcImageAnalyzerHandler' ) )
203. {
204. throw new ezcImageAnalyzerInvalidHandlerException ( $handlerClass );
205. }
206. $handler = new $handlerClass( $options );
207. if ( $handler->isAvailable() )
208. {
209. ezcImageAnalyzer ::$availableHandlers[] = clone( $handler );
210. }
211. }
212. }
214. /**
215. * Returns an array of known handler classes.
216. *
217. * This method returns an array of available handler classes. The array is
218. * indexed by the handler names, which are assigned to an array of options
219. * set for this handler.
220. *
221. * @return array(string=>array(string=>string)) Handlers and options.
222. */
223. public static function getHandlerClasses ()
224. {
225. return ezcImageAnalyzer::$knownHandlers;
226. }
228. /**
229. * Set the array of known handlers.
230. *
231. * Sets the available handlers. The array submitted must be indexed by
232. * the handler classes names (attention: handler classes must extend
233. * ezcImageAnalyzerHandler), assigned to an array of options for this
234. * handler. Most handlers don't have any options. Which options a handler
235. * may accept depends on the handler implementation.
236. *
237. * @param array(string=>array(string=>string)) $handlerClasses Handlers
238. * and options.
239. */
240. public static function setHandlerClasses ( array $handlerClasses )
241. {
242. ezcImageAnalyzer::$knownHandlers = $handlerClasses;
243. ezcImageAnalyzer::$availableHandlers = null;
244. }
246. /**
247. /**
248. * Sets the property $name to $value.
249. *
250. * @throws ezcBasePropertyNotFoundException
251. * If the property does not exist.
252. * @throws ezcBasePropertyPermissionException
253. * If the property cannot be modified.
254. * @param string $name
255. * @param mixed $value
256. * @ignore
257. */
258. public function __set( $name, $value )
259. {
260. switch ( $name )
261. {
262. case 'mime':
263. case 'data':
264. throw new ezcBasePropertyPermissionException( $name, ezcBasePropertyPermissionException ::READ );
265. default:
266. throw new ezcBasePropertyNotFoundException ( $name );
267. }
268. }
270. /**
271. * Returns the property $name.
272. *
273. * @throws ezcBasePropertyNotFoundException
274. * If the property does not exist.
275. * @param string $name Name of the property to access.
276. * @return mixed Value of the desired property.
277. * @ignore
278. */
279. public function __get( $name )
280. {
281. switch ( $name )
282. {
283. case 'mime':
284. return $this-> properties ['mime'];
285. case 'data':
286. if ( !$this-> isAnalyzed )
287. {
288. $this-> analyzeImage ();
289. }
290. return $this-> properties [$name];
291. default:
292. throw new ezcBasePropertyNotFoundException ( $name );
293. }
294. }
296. /**
297. * Checks if the property $name exist and returns the result.
298. *
299. * @param string $name
300. * @return bool
301. * @ignore
302. */
303. public function __isset( $name )
304. {
305. switch ( $name )
306. {
307. case 'mime':
308. case 'data':
309. return true;
310. default:
311. return false;
312. }
313. }
315. /**
316. * Analyze the image file's MIME type.
317. * This method triggers a handler to analyze the MIME type of the given image file.
318. *
319. * @throws ezcImageAnalyzerFileNotProcessableException
320. * If the no handler is capable to analyze the given image file.
321. */
322. public function analyzeType ()
323. {
324. if ( ! is_array ( ezcImageAnalyzer ::$availableHandlers ) )
325. {
326. $this-> checkHandlers ();
327. }
328. foreach ( ezcImageAnalyzer::$availableHandlers as $handler )
329. {
330. if ( ( $mime = $handler->analyzeType( $this-> filePath ) ) !== false )
331. {
332. $this-> properties ['mime'] = $mime;
333. return;
334. }
335. }
336. throw new ezcImageAnalyzerFileNotProcessableException ( $this-> filePath , "Could not determine MIME type of file." );
337. }
339. /**
340. * Analyze the image file.
341. *
342. * This method triggers a handler to analyze the given image file for more data.
343. *
344. * @throws ezcImageAnalyzerFileNotProcessableException
345. * If the no handler is capable to analyze the given image file.
346. * @throws ezcBaseFileIoException
347. * If an error occurs while the file is read.
348. */
349. public function analyzeImage ()
350. {
351. if ( ! is_array ( ezcImageAnalyzer ::$availableHandlers ) )
352. {
353. $this-> checkHandlers ();
354. }
355. if ( !isset( $this-> properties ['mime'] ) )
356. {
357. $this-> analyzeType ();
358. }
359. foreach ( ezcImageAnalyzer::$availableHandlers as $handler )
360. {
361. if ( $handler->canAnalyze( $this-> properties ['mime'] ) )
362. {
363. $this-> properties ['data'] = $handler->analyzeImage( $this-> filePath );
364. $this-> isAnalyzed = true;
365. return;
366. }
367. }
368. throw new ezcImageAnalyzerFileNotProcessableException ( $this-> filePath , "No handler found to analyze MIME type '{$this->mime}'.

" );
- }
- }
Documentation generated by phpDocumentor 1.4.3