Code Coverage for /Users/ericduran/Sites/drupal/drupal/core/lib/Drupal/Core/ImageToolkit/ImageToolkitInterface.php

	Code Coverage
	Classes and Traits		Functions and Methods				Lines
Total	100.00% covered (success)	0 / 0	100.00% covered (success)	100.00%	0 / 0	CRAP	100.00% covered (success)	100.00%	0 / 0

1	<?php
2
3	/**
4	* @file
5	* Contains \Drupal\Core\ImageToolkit\ImageToolkitInterface.
6	*/
7
8	namespace Drupal\Core\ImageToolkit;
9
10	use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
11	use Drupal\Core\Plugin\PluginFormInterface;
12	use Drupal\Component\Plugin\PluginInspectionInterface;
13
14	/**
15	* @defgroup image Image toolkits
16	* @{
17	* Functions for image file manipulations.
18	*
19	* Drupal's image toolkits provide an abstraction layer for common image file
20	* manipulations like scaling, cropping, and rotating. The abstraction frees
21	* module authors from the need to support multiple image libraries, and it
22	* allows site administrators to choose the library that's best for them.
23	*
24	* PHP includes the GD library by default so a GD toolkit is installed with
25	* Drupal. Other toolkits like ImageMagick are available from contrib modules.
26	* GD works well for small images, but using it with larger files may cause PHP
27	* to run out of memory. In contrast the ImageMagick library does not suffer
28	* from this problem, but it requires the ISP to have installed additional
29	* software.
30	*
31	* Image toolkits are discovered using the Plugin system using
32	* \Drupal\Core\ImageToolkit\ImageToolkitManager. The toolkit must then be
33	* enabled using the admin/config/media/image-toolkit form.
34	*
35	* Only one toolkit may be selected at a time. If a module author wishes to call
36	* a specific toolkit they can check that it is installed by calling
37	* \Drupal\Core\ImageToolkit\ImageToolkitManager::getAvailableToolkits(), and
38	* then calling its functions directly.
39	*/
40
41	/**
42	* Defines an interface for image toolkits.
43	*
44	* An image toolkit provides common image file manipulations like scaling,
45	* cropping, and rotating.
46	*
47	* @see \Drupal\Core\ImageToolkit\Annotation\ImageToolkit
48	* @see \Drupal\Core\ImageToolkit\ImageToolkitBase
49	* @see \Drupal\Core\ImageToolkit\ImageToolkitManager
50	* @see plugin_api
51	*/
52	interface ImageToolkitInterface extends ContainerFactoryPluginInterface, PluginInspectionInterface, PluginFormInterface {
53
54	/**
55	* Sets the source path of the image file.
56	*
57	* @param string $source
58	* The source path of the image file.
59	*
60	* @return \Drupal\Core\ImageToolkit\ImageToolkitInterface
61	* An instance of the current toolkit object.
62	*
63	* @throws \BadMethodCallException
64	* After being set initially, the source image cannot be changed.
65	*/
66	public function setSource($source);
67
68	/**
69	* Gets the source path of the image file.
70	*
71	* @return string
72	* The source path of the image file, or an empty string if the source is
73	* not set.
74	*/
75	public function getSource();
76
77	/**
78	* Checks if the image is valid.
79	*
80	* @return bool
81	* TRUE if the image toolkit is currently handling a valid image, FALSE
82	* otherwise.
83	*/
84	public function isValid();
85
86	/**
87	* Writes an image resource to a destination file.
88	*
89	* @param string $destination
90	* A string file URI or path where the image should be saved.
91	*
92	* @return bool
93	* TRUE on success, FALSE on failure.
94	*/
95	public function save($destination);
96
97	/**
98	* Determines if a file contains a valid image.
99	*
100	* Drupal supports GIF, JPG and PNG file formats when used with the GD
101	* toolkit, and may support others, depending on which toolkits are
102	* installed.
103	*
104	* @return bool
105	* TRUE if the file could be found and is an image, FALSE otherwise.
106	*/
107	public function parseFile();
108
109	/**
110	* Returns the height of the image.
111	*
112	* @return int\|null
113	* The height of the image, or NULL if the image is invalid.
114	*/
115	public function getHeight();
116
117	/**
118	* Returns the width of the image.
119	*
120	* @return int\|null
121	* The width of the image, or NULL if the image is invalid.
122	*/
123	public function getWidth();
124
125	/**
126	* Returns the MIME type of the image file.
127	*
128	* @return string
129	* The MIME type of the image file, or an empty string if the image is
130	* invalid.
131	*/
132	public function getMimeType();
133
134	/**
135	* Gets toolkit requirements in a format suitable for hook_requirements().
136	*
137	* @return array
138	* An associative requirements array as is returned by hook_requirements().
139	* If the toolkit claims no requirements to the system, returns an empty
140	* array. The array can have arbitrary keys and they do not have to be
141	* prefixed by e.g. the module name or toolkit ID, as the system will make
142	* the keys globally unique.
143	*
144	* @see hook_requirements()
145	*/
146	public function getRequirements();
147
148	/**
149	* Verifies that the Image Toolkit is set up correctly.
150	*
151	* @return bool
152	* TRUE if the toolkit is available on this machine, FALSE otherwise.
153	*/
154	public static function isAvailable();
155
156	/**
157	* Returns a list of image file extensions supported by the toolkit.
158	*
159	* @return array
160	* An array of supported image file extensions (e.g. png/jpeg/gif).
161	*/
162	public static function getSupportedExtensions();
163
164	/**
165	* Applies a toolkit operation to an image.
166	*
167	* @param string $operation
168	* The toolkit operation to be processed.
169	* @param array $arguments
170	* An associative array of arguments to be passed to the toolkit
171	* operation, e.g. array('width' => 50, 'height' => 100,
172	* 'upscale' => TRUE).
173	*
174	* @return bool
175	* TRUE if the operation was performed successfully, FALSE otherwise.
176	*/
177	public function apply($operation, array $arguments = array());
178
179	}