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: 1 year ago
Size: 14,274 bytes


Class file image Download

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


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.


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
  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.


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.


      readme.txt               this file
      <licenses>               licenses

    images/                    images directory, to use in test (empty)
    log/                       log file directory (empty)

      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


imageHandler operates in three modes:

   Will send header
    'Content-Disposition: attachment; filename="<name>"'
   and force the web browser to open a 'save file' box

   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).


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'.


imageHandler offers two public methods (and 21 private...).

The isResizable method returns resizeability or not.


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.


imageHandler::Operate( image, props )

                      Input argument
  image                     {string}
                      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)

*)   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


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



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'..
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.


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.


You can separately test the 'imageHandler.php' from a web browser:
and add opt. arguments at the end.
(replace 'image.php' by image path and file name).


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!


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.

For more information send a message to info at phpclasses dot org.