Full image management for WordPress: resizing, caching, output customization. Supports Jetpack Photon.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cache_img
.gitattributes
.gitignore
.htaccess
README.md
composer.json
license.txt
wp-imager.php

README.md

WP Imager v 2.7.4

WP Imager makes image management easier when it comes to manipulating, caching and customizing WordPress images. It has a pure PHP WP twin, PHP-Imager

Can be used inside or outside the loop:

  • If used inside a loop, the script will automatically retrieve an image from the post, following a priority pattern: featured image, random image attached to the post, first image found in post even if external or not attached to post.
  • If used outside the loop, for any image you want display in the template, use the $exturl param.
  • If used outside the loop, to display images based on the Post ID, then use the param $post_id.

Uses TimThumb for image resizing and caching

WPML 100% compatible

Supports WordPress Jetpack's Photon module, it automatically switches to Photon cached images' URLs, if module is on, while keeping your custom sizes and with no need to tweak or edit a thing

Caches images outside of the WordPress folders, to avoid clutter and overflowing upload folders

To-Do

  • Convert function params to array
  • Add TimThumb filters
  • Support for Jetpack's Photon filters. Maybe?

Requirements

  • PHP 5.2.x or higher
  • GD image library

Get started

  1. Place the provided cache_img folder in your site's root folder.

Make sure that cache_img/cache is writable, in case images are not displaying.

  1. Place the wp-imager.php file in your WP template.

  2. Call wp-imager.php from your functions.php

<?php include 'wp-imager.php'; ?>

If you want to have pretty img urls, then there's an extra step:

  • If you don't have an .htaccess yet, place the one provided in your site's root folder.
  • If you already have an .htaccess, then adapt it, following the one provided.

If you don't complete every step the script won't work.

Parameters

<?php wp_imager($width=null, $height=null, $crop=null, $class='', $link=false, $exturl=null, $nohtml=false, $post_id=null, $bg_color=null); ?>
Parameter Type Description & Options Default
width int Resize dimension of width (dont put 'px' after size) 100
height int Resize dimension of height (dont put 'px' after size) 100
crop int Type of cropping to perform 0 = Resize to Fit exactly specified dimensions (no cropping) 1 = Crop and resize to best fit the dimensions (default) 2 = Resize proportionally to fit entire image into specified dimensions, and add borders if required 3 = Resize proportionally adjusting size of scaled image so there are no borders gaps 1
class string class name/names to append to image NULL
link bool Wraps the image in HTML, pointing to the image's post, with title attribute filled with post's title for better SEO. Won't work with $exturl false
exturl string URL of some external/custom image (eg. http://www.mysite.com/image.jpg) NULL
nohtml bool When false, image is wrapped in its img HTML tag, with alt attribute filled with post's title for better SEO. If true, only the image url is returned false
post_id int If empty, will retrieve $post->ID from active loop, else specify the post ID you need to retrieve the img from $post->ID
bg_color int When using crop value '2' (with borders) you can customize the borders color (the canvas beneath the image). ffffff

Defaults

  • Function always returns to avoid yet another parameter, so simply echo it in your code.
  • Processed IMG's quality is always 100
  • Caching is done in a cache_img folder, in the root of your website (provided)
  • Pretty img urls are enabled by default. Adapt the .htaccess provided with the script.

Usage

Resize + default Cropping

<?php echo wp_imager(600, 350); ?>

Resize with no Cropping

<?php echo wp_imager(600, 350, 0); ?>

Resize + default Cropping + Image Class

<?php echo wp_imager(600, 350, '', 'img-responsive'); ?>

Resize + default Cropping + WP post link

<?php echo wp_imager(600, 350, '', '', true); ?>

Resize + default Cropping + custom img URL (outside the loop)

<?php echo wp_imager(600, 350, '', '', '', 'http://www.domain.com/image.jpg'); ?>

Resize + default Cropping + no html wrapper

<?php echo wp_imager(600, 350, '', '', '', '', true); ?>

Conflicting Params

Clearly there are some parameters you cannot use together and as the script is specifically made to use within WordPress, restrictions may apply.

For example:

  • $link = true and $nohtml = true dont make sense together, as you can imagine ($nohtml = true wins anyway)
  • $class won't do anything if $nohtml = true
  • $link = true and $exturl will output a broken or empty post url, if $exturl is not a post image (yes, $exturl should work also for images within WordPress but I haven't tested it yet)

Changelog

30/4/2016

  • version 2.6.5
  • Fixed minor issues with WPML compatibility
  • Overriding jpeg_quality and wp_editor_set_quality to 100
  • Added post_id param support (in previous versions)

10/12/2015

  • version 2.6
  • Added support in case there's no attachments in posts but there are images within the content
  • Added support in case after content import, attachments ID are incorrect, the script will still find the image provided it's in the current server (with same folder structure)

14/9/2016

  • version 2.7.1
  • Fixed minor bugs
  • Added 100 quality on jpg
  • Preparing for params as array
  • Preparing for TimThumb Filters

22/7/2015

  • version 2.5
  • Updated Timthumb to latest available (June 2014)
  • Change TimThumb default from timthumb-config.php
  • Added canvas color param
  • Updated htaccess rule
  • Various small improvements

6/7/2015

  • version 2.2
  • Support for Post ID (outside of loop)

7/4/2015

  • version 1.8
  • Fixes to WPML compatibility bug
  • Support for Photon

23/3/2015

  • version 1.5
  • Fixes to WPML compatibility

2/12/2014

  • added compatibility with WPML

3/2/2014

  • added $nohtml param
  • added $htaccess var
  • fixed various bugs

29/1/2014

  • release version 1.0

Credits

TimThumbs (discontinued): BinaryMoon

Author

Jany Martelli @ Shambix

License

Released under the GPL v3 License