Tutorials/image handling changes

= Image handling changes since 4.5.1 =

4.5.1 shop version comes with improved image handling. Since now images are not generated by image URL getters, but on demand by separate PHP process. Image uploading by "admin" is unchanged, but what happens after that - now works different. Regular image getters, like oxArticle::getIconUrl, now does not generate images, it just checks for master image availability and returns image url. No more picture generation/processing is done by getters. When you upload new image using „admin“, file is stored in related "out/pictures/master" folder. All work is done later by "oxdynimggenerator" script, defined in ".htaccess" file.

= .htaccess =

In case requested image was not found (usually this happens when you upload new master image as as a source for other product images) special ".htaccess" instructions calls script which generates and stores requested image. ".htaccess" file is now appended with new instructions:

When generator is called it:


 * checks if requested path is valid;
 * extracts master image path and checks if master image is available;
 * creates requested folders structure (if needed);
 * generates requested image from master source;
 * in case of any error "HTTP/1.0 404 Not Found" header is send and "nopic.jpg" is outputted to browser;

As mentioned before image URL getters no longer generates requested image, so server load by single PHP instance is reduced. New approach leads to code changes, as some of methods are deprecated or not used at all.

= Code changes =

For info about changes in code follow this link Possibly you may have your own implementation of custom image getters similar to oxArticle::getIconUrl or oxArticle::getThumbnailUrl, which now may not be compatible with new image folder structure. So here is an example how to implement your custom image url getter:

/** * Returns article thumbnail picture url * * @return string */ public function getCustomProductImageUrl { // master image file name $sImgName = "imagename.jpg"; // master image folder; this folders must be in "out/pictures/master/" $sDirname = "product/custom/"; // config parameter keeping image size info $sSize = $this-&gt;getConfig-&gt;getConfigParam( 'aDetailImageSizes' ); // picture handler will check if master image exists and will return URL for image return oxPictureHandler::getInstance-&gt;getProductPicUrl( $sDirname, $sImgName, $sSize, 0 ); }

Extending new image handler
Image handler class is an exception from standard oxid implementation as it works separatelly from standard framework due to performance reasons, does not extend oxSuperConfig and so on. But still you may want to extend its features by adding custom functionality. So here is instructions on how to proceed.

1. edit ".htaccess" file and change name of rewrite rule handler "getimg.php" file to e.g. "custgetimg.php"; 2. create empty "custgetimg.php" file in "core/utils" folder; 3. open newly created file and start extending:

// Checks if instance name getter does not exist if ( !function_exists( "getGeneratorInstanceName" ) ) { /** * Returns image generator instance name * * @return string */ function getGeneratorInstanceName {  return "customdynimggenerator"; } } require_once "../oxdynimggenerator.php"; class customdynimggenerator extends oxdynimggenerator { // your own functions.. } require_once "getimg.php";

= Backwards compatibility =

In case you cannot update your shop image handling (due to third party modules or so), you can use "oxpichandler" module, which enables backward compatability with old image structure and also has all deprecated functions you may need. Follow install instructions written in module package.

Get the module here: http://www.oxid-esales.com/forum/attachment.php?attachmentid=891&amp;d=1317385573

= Changes in folder structure =

If you are not satisfied with PHP functions which generate images, you can use any alternative solution for image preparation. Processed images are stored on server (we also support external image storage servers) special folders. So here is a short overview how images folder structure was changed. Old "out/pictures" folder structure:

New "out/pictures" folder structure:

As you can see, the new folder structure is more clear and self explaining. Also, now picture file names do not contain suffixes like "_ico", "_th", which previously defined the purpose of file. The name of the generated file is the same as master the image file name. Now the folder name fully defines its purpose. The special folder named "generated" contains pictures automatically generated by "oxdynimggenerator.php" and partially mirrors the "master" folder structure. Deepest folder, like "380_340_75", defines generated image size and quality parameters - "width_height_quality", thus allowing easy customization and change in image size parameters, related to your template theme, or even share pictures between them. Also you should know, that deletion of "generated" folder contents is fully safe, because the image generator script will (re)generate pictures automatically on demand.

= Updating =

The new shop release comes with an update script, which, on regular conditions, automatically relocates images to the new directory structure. Please carefully execute the "updateApp" application to have an up-to-date image directory structure. Do not forget to make an images backup before executing the update application.

A few notices for those, who update their shop.

Getters
In previous versions (&lt;4.0.0) product/categories/vendors/manufacturers image urls were formatted directly in templates like this:

DON'T do it like this any more, because the new image handling concept implements totally a different path structure. You must remember and use these getters:

'''General rule - use these native getters as often as possible! In case you miss something - write your own as a module!'''

Running update application
Current update is quite complex and requires care and user knowledge. As always you will need (S)FTP client to upload update package, backup image files and change permissions of affected files/folders. During the update process you may get some error messages, so this guide will help you to fix the problems and successfully complete update process.

The main task of the update to 4.5.1 is to relocate image files to create clear hierarchy of files/folders (please have a look at chapter "Changes in folder structure "). Before starting update process its highly recommended to:

1. backup images located at "/out/pictures/"; 2. set permissions to "/out/pictures/" folder, its subfolders and files to "0777"; 3. set permissions to "/.htaccess" to "0777"; 4. check if your web server supports ".htaccess" instructions (usually its supported if standard shop works with default SEO).

After you complete these tasks you are ready for the update. Execute the update application by opening "http://[shopurl]/updateApp/". After the update "/out/pictures/" the folder will look messy and you will have to do additional cleanup manually. Open "/out/pictures/" folder and you will see something like:

\-1 |... |-12 |-icon |-generated |-master | \-1 | |... |  |-12 | |-category | |-manufacturer | |-product | |-vendor | |-wrapping |-promo |-wysiwigpro |-z1 |... |-z12

Please review "1"-"12", "z1"-"z12", "icon", "master\1"-"master\12" folders - if you do no find any file which must be kept in these folders you are free to delete them.

Still during update you may get some error messages so here is short overview about them and possible solutions

Can not create folder/Unable to write to folder/Unable to create folder
- check if "/out/pictures/" folder permissions are set to "0777" or similiar; - check if PHPs safe mode is ON, in case it does not allow files/folder creation - disable it.

Unable to update ".htaccess" file
- check if your shop contains ".htaccess" file; - check of file permissions are set to "0777";

Unable to get config value for [variable name]
Normally this warning should not appear. In case you are getting this message - your shop configuration may be broken or some configuration values are missing and image relocation task can only be partially completed. If some config values are missing, on first site start after update picture handler will try to regenerate missing images. If after update is finished images are displayed, you can ignore missing config values warning, in other case please contact our support.

After the update you see no or broken images in your shop
- check if your ".htaccess" file contains these lines (must be inserted between &lt;IfModule mod_rewrite.c&gt;&lt;/IfModule&gt; tags):

RewriteCond %{REQUEST_URI} (\/out\/pictures\/) RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule (\.jpe?g|\.gif|\.png|\.svg)$ getimg.php

- check if your server supports ".htaccess" instructions; - check if "/out/", "/out/pictures/" don't contain other ".htaccess" files disabling the rewrite rules; - set permission on files/folders in "/out/pictures/". Recommended value "0777";

After the update you see "nopic.jpg" instead of the original picture or you see lower quality images then previously
This may show that update process did not successfully moved related images, please contact our support.

In case nothing helps you can always restore backuped image files and enable old style image handling by installing "oxpichandler" module (read previous chapter about it).