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

## Source for file handler.php

Documentation is available at handler.php

1. <?php
2. /**
3. * This file contains the ezcImageHandler interface.
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 ImageConversion
23. * @version //autogentag//
24. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
25. * @filesource
26. */
28. /**
29. * Driver interface to access different image manipulation backends of PHP.
30. * This interface has to be implemented by a handler class in order to be
31. * used with the ImageConversion package.
32. *
33. * @see ezcImageConverter
34. *
35. * @package ImageConversion
36. * @version //autogentag//
37. */
38. abstract class ezcImageHandler
39. {
40. /**
41. * Container to hold the properties
42. *
43. * @var array(string=>mixed)
44. */
45. protected $properties ;
47. /**
48. * Settings of the handlers
49. *
50. * @var ezcImageHandlerSettings
51. */
52. protected $settings ;
54. /**
55. * Create a new image handler.
56. * Creates an image handler. This should never be done directly,
57. * but only through the manager for configuration reasons. One can
58. * get a direct reference through manager afterwards. When overwriting
59. * the constructor.
60. *
61. * @param ezcImageHandlerSettings $settings
62. * Settings for the handler.
63. */
64. public function __construct ( ezcImageHandlerSettings $settings )
65. {
66. $this-> properties ['name'] = $settings->referenceName;
67. $this-> settings = $settings;
68. }
70. /**
71. * Sets the property $name to $value.
72. *
73. * @throws ezcBasePropertyNotFoundException if the property does not exist.
74. * @throws ezcBasePropertyReadOnlyException if the property cannot be modified.
75. * @param string $name
76. * @param mixed $value
77. * @ignore
78. */
79. public function __set( $name, $value )
80. {
81. switch ( $name )
82. {
83. case 'name':
84. throw new ezcBasePropertyPermissionException ( $name, ezcBasePropertyPermissionException ::READ );
85. default:
86. throw new ezcBasePropertyNotFoundException ( $name );
87. }
88. }
90. /**
91. * Returns the property $name.
92. *
93. * @throws ezcBasePropertyNotFoundException if the property does not exist.
94. * @param string $name
95. * @return mixed
96. * @ignore
97. */
98. public function __get( $name )
99. {
100. switch ( $name )
101. {
102. case 'name':
103. return $this-> properties [$name];
104. default:
105. throw new ezcBasePropertyNotFoundException ( $name );
106. }
107. }
109. /**
110. * Checks if the property $name exist and returns the result.
111. *
112. * @param string $name
113. * @return bool
114. * @ignore
115. */
116. public function __isset( $name )
117. {
118. switch ( $name )
119. {
120. case 'name':
121. return true;
122. default:
123. return false;
124. }
125. }
127. /**
128. * Checks a file name for illegal characters.
129. * Checks if a file name contains illegal characters, which are ", ' and $.
130. *
131. * @param string $file The file name to check.
132. * @return void
133. *
134. * @throws ezcImageFileNameInvalidException
135. * If an invalid character (", ', $) is found in the file name.
136. */
137. protected function checkFileName ( $file )
138. {
139. if ( strpos ( $file, "'" ) !== false || strpos ( $file, "'" ) !== false || strpos ( $file, '$' ) !== false )
140. {
141. throw new ezcImageFileNameInvalidException ( $file );
142. }
143. }
145. /**
146. * Returns if a MIME conversion needs transparent color replacement.
147. *
148. * In case a transparency supporting MIME type (like image/png) is
149. * converted to one that does not support transparency, special steps need
150. * to be performed. This method returns if the given conversion from
151. * $inMime to $outMime is affected by this.
152. *
153. * @param string $inMime
154. * @param string $outMime
155. * @return bool
156. */
157. protected function needsTransparencyConversion ( $inMime, $outMime )
158. {
159. $transparencyMimes = array(
160. 'image/gif' => true,
161. 'image/png' => true,
162. );
163. return (
164. $outMime !== null
165. && $inMime !== $outMime
166. && isset( $transparencyMimes[$inMime] )
167. && !isset( $transparencyMimes[$outMime] )
168. );
169. }
171. /**
172. * Load an image file.
173. * Loads an image file and returns a reference to it.
174. *
175. * For developers: The use of ezcImageHandler::loadCommon() is highly
176. * recommended for the implementation of this method!
177. *
178. * @param string $file File to load.
179. * @param string $mime The MIME type of the file.
180. * @return string Reference to the file in this handler.
181. */
182. abstract public function load ( $file, $mime = null );
184. /**
185. * Save an image file.
186. * Saves a given open file. Can optionally save to a new file name.
187. * The image reference is not freed automatically, so you need to call
188. * the close() method explicitly to free the referenced data.
189. *
190. * @see ezcImageHandler::load()
191. * @see ezcImageHandler::close()
192. *
193. * @param string $image File reference created through.
194. * @param string $newFile Filename to save the image to.
195. * @param string $mime New MIME type, if differs from
196. * initial one.
197. * @param ezcImageSaveOptions $options Options for saving.
198. * @return void
199. */
200. abstract public function save ( $image, $newFile = null, $mime = null, ezcImageSaveOptions $options = null );
202. /**
203. * Close the file referenced by $image.
204. * Frees the image reference. You should call close() before.
205. *
206. * @see ezcImageHandler::load()
207. * @see ezcImageHandler::save()
208. * @param string $reference The image reference.
209. * @return void
210. */
211. abstract public function close ( $reference );
213. /**
214. * Check wether a specific MIME type is allowed as input for this handler.
215. *
216. * @param string $mime MIME type to check if it's allowed.
217. * @return bool
218. */
219. abstract public function allowsInput ( $mime );
221. /**
222. * Checks wether a specific MIME type is allowed as output for this handler.
223. *
224. * @param string $mime MIME type to check if it's allowed.
225. * @return bool
226. */
227. abstract public function allowsOutput ( $mime );
229. /**
230. * Checks if a given filter is available in this handler.
231. *
232. * @param string $name Name of the filter to check for.
233. * @return bool
234. *
235. */
236. abstract public function hasFilter ( $name );
238. /**
239. * Returns a list of filters this handler provides.
240. * The list returned is in format:
241. *
242. * <code>
243. * array(
244. * 0 => <string filtername>,
245. * 1 => <string filtername>,
246. * ...
247. * )
248. * </code>
249. *
250. * @return array(string)
251. */
252. abstract public function getFilterNames ();
254. /**
255. * Applies a filter to a given image.
256. *
257. * @internal This method is the main one, which will dispatch the
258. * filter action to the specific function of the backend.
259. *
260. * @see ezcImageHandler::load()
261. * @see ezcImageHandler::save()
262. *
263. * @param string $image Image reference to apply the filter on.
264. * @param ezcImageFilter $filter Contains which filter operation to apply.
265. * @return void
266. *
267. * @throws ezcImageFilterNotAvailableException
268. * If the desired filter does not exist.
269. * @throws ezcImageMissingFilterParameterException
270. * If a parameter for the filter is missing.
271. * @throws ezcImageFilterFailedException
272. * If the operation performed by the the filter failed.
273. * @throws ezcBaseValueException
274. * If a parameter was not within the expected range.
275. */
276. abstract public function applyFilter ( $image, ezcImageFilter $filter );
278. /**
279. * Converts an image to another MIME type.
280. *
281. * Use {@link ezcImageHandler::allowsOutput()} to determine,
282. * if the output MIME type is supported by this handler!
283. *
284. * @see ezcImageHandler::load()
285. * @see ezcImageHandler::save()
286. *
287. * @param string $image Image reference to convert.
288. * @param string $mime MIME type to convert to.
289. * @return void
290. *
291. * @throws ezcImageMimeTypeUnsupportedException
292. * If the given MIME type is not supported by the filter.
293. */
294. abstract public function convert ( $image, $mime );
295. }
296. ?>

Documentation generated by phpDocumentor 1.4.3