PHP Classes

File: docs/README.txt

Recommend this page to a friend!
  Classes of Kjell-Inge Gustafsson   PHP Image Handling API   docs/README.txt   Download  
File: docs/README.txt
Role: Documentation
Content type: text/plain
Description: Documentation
Class: PHP Image Handling API
Provide an API to do image manipulation operations
Author: By
Last change:
Date: 2 years ago
Size: 14,274 bytes


Class file image Download
IMAGEHANDLER Author Kjell-Inge Gustafsson, kigkonsult <> Copyright 2015, Kjell-Inge Gustafsson kigkonsult, All rights reserved. Version 1.4 License non-commercial use: Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License ( commercial use :imageHandler141license / imageHandler14Xlicense Link Support PREFACE This document describes usage of the software imageHandler. This document, as well as refered documents, are provided by kigkonsult for informational purposes and is provided on an "as is" basis without any warranties expressed or implied. Information in this document is subject to change without notice and does not represent a commitment on the part of kigkonsult. The software described in this document is provided under a license agreement. The software may be used only in accordance with the terms of that license agreement. It is against the law to copy or use the software except as specifically allowed in the license agreement. It is the users responsibility to ensure the suitability of the software before using it. In no circumstances will kigkonsult be responsible for the use of the software, software's outcomes or results or any loss or damage of data or programs as a result of using the software. The use of the software implies acceptance of these terms. This document makes previous versions obsolete. Product names mentioned herein are or may be trademarks or registered trademarks of their respective owners. OVERVIEW imageHandler is a PHP (gd) back end class package managing crop region, resize, adapt size and convert of bmp, jpg, gif, png, xbmp and xbm image types with preserved proportions and (for gif/png) transparency. For tiff images with an embedded thumbnail, the thumbnail is returned. ImageHandler offers also availability 'on-the-fly' using a web (REST GET/PUT, json) service interface. Anonymous (source and/or output) filenames (without extension) and remote image resources are supported. The imageHandler interface is simple : the source image filename or url and the crop, (re-)size and/or adapt directives in pixels or percent of the source image size. If the crop and size arguments are set simultaneously, cropping is done before (re-)sizing. The imageHandler output mode is download - will open a 'save file'-box in browser stream - (default) usable in a 'src' statement in a HTML page, (showing a 'thumbnail') save - saves (cropped/resized) image on disk Output image type for the resized images is (default) png. Non-resizable images types are returned 'as is'. The class package includes the PHP class the PHP web service interface script an PHP 'index.php' page, usable for testing, evaluating and/or image reviewing, including a (separate) editable image crop/resize test schema. The imageHandler class and index page supports PEAR log class or equivalents. But, despite the most intense review of requirements and conditions in architecture, design and test of imageHandler, the imageHandler's ability to crop and resize an image may still depend on the image origin and the image displayability on browser capability and/or (external) viewers. Note, imageHandler focus is image cropping/resizing, not image engineering. REQUIREMENTS imageHandler is developed using PHP 5.5.20 and the PHP included gd 2.1.0. PHP must be compiled with '--enable-exif'. Windows users must have the mbstring extension enabled. When operating on (very) large images, some PHP general directives like 'memory_limit' may need to be increased ('1024M' or more) and also max_execution_time' and others. FILES imageHander/ docs/ readme.txt this file <licenses> licenses images/ images directory, to use in test (empty) log/ log file directory (empty) test/ imageHandler.css test script css imageHandler.js test script javascript index.php test script cropAndResizeTest.php imageHandler crop/resize testcases imageHandler.class.php the class file imageHandler.php the interface script OPERATION MODES imageHandler operates in three modes: download Will send header 'Content-Disposition: attachment; filename="<name>"' and force the web browser to open a 'save file' box stream Will send header 'Content-Disposition: filename="<name>"' opens the imageHandler output for display in browser usable in an HTML page like <img src="http://localhost/imageHandler/imageHandler.php?i=img.php&mw=200"> save to disk Full path to target must be given If path is not writable, imageHandler is terminated (and error logged). imageHandler is checking image type (png,gif etc) by examining image content, NOT filename extension, i.e. supporting anonymous filenames. The crop operation is controlled by four arguments: 'cx', 'cy', 'cwidth' and 'cheight' and accept values both in percent and pixels. Percent will be converted to pixels, based on the source image width and height. The 'cwidth' and 'cheight' sets the size of the cropped area. Default ('cx' and/or 'cy' are missing) a centered crop is done. The 'cx' and 'cy' arguments sets a crop start point, for 'cx' horizontal (left(=0)<->right) position and 'cy' vertical upper(=0)<->lower) position. If you want to start the crop in the left upper corner, set 'cx'=0 and 'cy'=0, next to the right lower corner, set 'cx'=99% and 'cy'=99%. The resizing operation is controlled by four (calling) arguments: 'width', 'height', 'maxwidth' and 'maxheight', accepts also values in percent and pixels (percent converted as above). If both (and only) 'width' and 'height' are set, image is reshaped and distorted. If only one ('width' or 'height') is set, image is proportionally resized. The 'maxwidth' and 'maxheight' arguments (one or both) overrides 'width' and 'height', and the resize image operation will preserve proportions according to the 'box', limited by the 'maxwidth' and/or 'maxheight' arguments. The resize operation will preserve transparency for png and most gif images. If error occurs, imageHandler is terminated (and error logged) and FALSE is returned. If image is not resizable, image is returned 'as is'. Remote images are cached locally (into a tempfile) before operation (and removed afterwords). CONFIGURATION imageHandler is default set up to work 'out-of-the-box' with operation set to 2 (stream) all (resized) output in png no logging. imageHandler::$defaultOperation = {int} // One of 1=download, 2=stream, 3=save to disk // default 2, details in 'OPERATION MODES', above. // used if missing in input imageHandler::$outputpng = {bool} // Affects resezable(!) images only // Default TRUE, all output as png // FALSE, no changed output of resized jpg/gif images imageHandler::$imageLib = {string} // Default empty // if not empty, it will prefix the image argument, below // If used, MUST be suffixed by '/' (DIRECTORY_SEPARATOR) // Usable if you don't want to show image path in public imageHandler::$filenamePrefix = {string} // prefix for created (temp/output) filenames // Default 'imageHandler_' imageHandler::$cache = {string}; // tempfile directory // Default result of PHP function 'sys_get_temp_dir()' // Log (opt, if you want to use any logging) imageHandler::$logger = {log object instance} // PEAR log object instance or equivalent // Default null imageHandler::$logprio = {int} // Default 'LOG_NOTICE' For examples, please examine 'imageHandler.php' or 'index.php'. CLASS METHODS imageHandler offers two public methods (and 21 private...). The isResizable method returns resizeability or not. Format: imageHandler::isResizable( image ) image {string} source filename (incl path*) alt. source url return (bool) TRUE if resizable return (bool) FALSE if NOT resizable *) note, imageHandler::$imageLib, above The Operate method manages the crop/(re-)size factory. Format: imageHandler::Operate( image, props ) Input argument image {string} Required source filename (incl path*) alt. source url Output management arguments, all optional props array( ['operation'] => {int}, 1=download, 2=stream (default), 3=save to disk ['name'] => {string}, Display/output (image-)name (incl path if operate = 3), is generated if missing, based on the current datetime+msec. If the 'imageHandler::$outputpng' directive is set (default TRUE), output will ha a 'png' extension. sizing arguments, se OPERATION MODES, above and remarks **/***, below ['cx'] => {mixed}, ['cy'] => {mixed}, ['cwidth'] => {mixed}, ['cheight'] => {mixed}, ['width'] => {mixed}, ['height'] => {mixed}, ['maxwidth'] => {mixed}, ['maxheight'] => {mixed}, ) return FALSE on error (and reason logged) return image on success (operate = 1/2) return TRUE on success (operate = 3) Remarks *) note, imageHandler::$imageLib, above **) values in percent (ex '50%') of source width/height or pixels (ex. '200') accepted ***) cx/cy only if cwidth and/or cheight exists INTERFACE ARGUMENTS The imageHandler interface, 'imageHandler.php', is the web (REST GET/POST, json) service. It is a configuration section in top of script. Remarks, above, are also applicable here. The interface accepts (main) json argument i / image {string} json formatted string, json object properties as below. The interface accepts the following GET/POST arguments and json (sub-)properties: short / full argument key names i / image {string} filename or url, required * o / operation {mixed} 1/'download', 2/'stream' (default), 3/'save' (to disk) n / name {string} image output (display/save) name (opt) p {mixed} bool, TRUE jpg/gif output as png (default), FALSE not TRUE also force png extension int, 1=TRUE, 0=FALSE string, '1'=TRUE, ''=FALSE settings for the resizeable image, all opt, percent or pixels ** cx {mixed} left start crop position cy {mixed} upper start crop position cw / cwidth {mixed} image crop width ch / cheight {mixed} image crop height w / width {mixed} image output width h / height {mixed} image output height mw / maxwidth {mixed} image max output width mh / maxheight {mixed} image max output height EVALUATION AND TEST index.php For evaluation and test, an 'index.php' page (together with supporting css and javascript scripts) are attached in the 'test' directory, supporting PEAR log class or equivalents. You can configure 'index.php' in top of script, image directory base url log settings ini_set( 'memory_limit'.. etc... Information for each image in the image folder are displayed with name, size, mime contenttype etc. Exif metadata are displayed, if available, using an show/hide button. The exif metadata key information in detail can be found in ''. Also imageHandler output modes can be tested. cropAndResizeTest.php For each resizeable image, an editable test case schema is available, also using a show/hide button, and used in 'index.php', testing download of cropped and/or down-/upsized images. The (more formalized) schema may also work very well as base for ad hoc and explorative tests. (Note, test images are NOT included in the package.) During the tests, keep an eye on the temp (/tmp) folder, extensive tests may fill it up. To test it in a nice way, use a 1000x1000 image (or two, one with width 1000 and another with heigt 1000) and review the output. imageHandler.php You can separately test the 'imageHandler.php' from a web browser: <serverUrl><path>/imageHandler.php?i=<imagePath> and add opt. arguments at the end. ex. http://localhost/imageHandler/imageHandler.php?i=image.php&mw=200 (replace 'image.php' by image path and file name). DONATE You can show your appreciation for our free software, and can support future development by making a donation of any size by going to "" and click the 'Donate' button. Thanks in advance! SUPPORT Use the contact page,"" for queries, improvement/development issues or professional support and development. Please note that paid support or consulting service has the highest priority. kigkonsult offer professional services for software support, design and new/re-development, customizations and adaptations of PHP and MySQL/MaridDb solutions with focus on software lifecycle management, including long term utility, robustness and maintainability.