Image Manipulation Quick Reference
This reference lists all methods available in Trongate's Image module when calling $this->image->method_name(). Use this page as your quick lookup guide when working with images.
Note: All image operations include automatic security validation during upload to prevent malicious file uploads. The Image module automatically preserves transparency for PNG and GIF images through all operations.
Getting Images Into Memory
| Method |
Parameters |
Returns |
Description |
| included-image-upload() |
array $config |
array |
Upload a NEW image with automatic security validation, resizing, and thumbnail generation. |
| included-image-load() |
string $filename |
void |
Load an EXISTING image from disk into memory for manipulation. |
When to Use Which:
- upload() - For NEW images from user file uploads. Handles validation, security, and optional automatic resizing/thumbnails.
- load() - For EXISTING images already on disk. Perfect for batch processing, generating new sizes, or creating variations.
Upload Configuration
Configuration Array Keys
| Key |
Type |
Required |
Default |
Description |
destination |
string |
yes |
- |
Target directory path |
upload_to_module |
bool |
no |
false |
Upload to module directory |
target_module |
string |
no |
current |
Target module name |
make_rand_name |
bool |
no |
false |
Generate random filename |
max_width |
int |
no |
450 |
Maximum width (0 = no limit) |
max_height |
int |
no |
450 |
Maximum height (0 = no limit) |
thumbnail_dir |
string |
no |
'' |
Thumbnail directory |
thumbnail_max_width |
int |
no |
0 |
Thumbnail width |
thumbnail_max_height |
int |
no |
0 |
Thumbnail height |
Upload Example
$config = [
'destination' => 'products/images',
'upload_to_module' => true,
'make_rand_name' => true,
'max_width' => 1200,
'max_height' => 1200,
'thumbnail_dir' => 'products/images/thumbs',
'thumbnail_max_width' => 300,
'thumbnail_max_height' => 300
];
$file_info = $this->image->upload($config);
/* Returns:
[
'file_name' => 'img_6756d8e9a2b4f3.21.jpg',
'file_path' => '../modules/products/products/images/img_6756d8e9a2b4f3.21.jpg',
'file_type' => 'image/jpeg',
'file_size' => 245760,
'thumbnail_path' => '../modules/products/products/images/thumbs/img_6756d8e9a2b4f3.21.jpg'
]
*/
Load Example
// Load existing image from disk
$this->image->load('modules/products/images/widget.jpg');
// Now you can manipulate it
$this->image->resize_to_width(800);
$this->image->save('modules/products/images/widget_800.jpg');
Image Information
| Method |
Parameters |
Returns |
Description |
| included-image-get_width() |
none |
int |
Get width in pixels of currently loaded image. |
| included-image-get_height() |
none |
int |
Get height in pixels of currently loaded image. |
| included-image-get_header() |
none |
string |
Get MIME type for currently loaded image (e.g., 'image/jpeg'). |
Example Usage
// Load and inspect image
$this->image->load('modules/gallery/photos/landscape.jpg');
$width = $this->image->get_width(); // e.g., 1920
$height = $this->image->get_height(); // e.g., 1080
$mime = $this->image->get_header(); // 'image/jpeg'
// Calculate aspect ratio
$ratio = $width / $height; // 1.78 (16:9)
// Conditional processing
if ($ratio > 1.5) {
// Wide image - resize to width
$this->image->resize_to_width(800);
} else {
// Portrait or square - resize to height
$this->image->resize_to_height(600);
}
Image Resizing
| Method |
Parameters |
Returns |
Description |
| included-image-resize_to_width() |
int $width |
void |
Resize to specific width, height adjusts proportionally. |
| included-image-resize_to_height() |
int $height |
void |
Resize to specific height, width adjusts proportionally. |
| included-image-scale() |
float $percentage |
void |
Scale by percentage (50 = half size, 150 = 1.5× size). |
Resize Examples
// Resize to 800px wide (height adjusts)
$this->image->load('modules/gallery/photos/landscape.jpg');
$this->image->resize_to_width(800);
// Original: 2000×1500 → Result: 800×600
// Resize to 600px tall (width adjusts)
$this->image->load('modules/gallery/photos/portrait.jpg');
$this->image->resize_to_height(600);
// Original: 1200×1600 → Result: 450×600
// Scale to 50% of original
$this->image->load('modules/products/images/photo.jpg');
$this->image->scale(50);
// Original: 1920×1080 → Result: 960×540
// Scale to 150% (enlarge)
$this->image->scale(150);
// Original: 800×600 → Result: 1200×900
Image Cropping
| Method |
Parameters |
Returns |
Description |
| included-image-crop() |
int $width
int $height
string $position = 'center' |
void |
Crop to exact dimensions. Position: 'left', 'center', 'right'. |
| included-image-resize_and_crop() |
int $width
int $height |
void |
Resize then crop to fill exact dimensions perfectly. |
Crop Examples
// Simple crop (centered)
$this->image->load('modules/blog/images/wide.jpg');
$this->image->crop(800, 600);
// Crops from center
// Crop from left (preserve left side)
$this->image->crop(800, 600, 'left');
// Crop from right (preserve right side)
$this->image->crop(800, 600, 'right');
// Perfect fit (resize + crop)
$this->image->load('modules/products/images/any-size.jpg');
$this->image->resize_and_crop(400, 300);
// Always produces exactly 400×300, no stretching
Image Saving and Output
| Method |
Parameters |
Returns |
Description |
| included-image-save() |
string $filename = null
int $compression = 100
int $permissions = null |
void |
Save image to disk with optional compression and permissions. |
| included-image-output() |
bool $return = false |
string|null |
Output image to browser or return as string. |
| included-image-destroy() |
none |
void |
Free memory allocated to the image resource. |
Save and Output Examples
// Save with default quality (100)
$this->image->load('modules/gallery/photos/original.jpg');
$this->image->resize_to_width(800);
$this->image->save('modules/gallery/photos/resized.jpg');
// Save with compression (85% quality)
$this->image->save('modules/gallery/photos/compressed.jpg', 85);
// Save with custom permissions
$this->image->save('modules/documents/private/secure.jpg', 90, 0600);
// Output directly to browser
$this->image->load('modules/products/images/photo.jpg');
$this->image->resize_to_width(400);
header('Content-Type: ' . $this->image->get_header());
$this->image->output();
// Capture as binary string
$image_data = $this->image->output(true);
$base64 = base64_encode($image_data);
// Free memory when done
$this->image->destroy();
Common Patterns
Pattern 1: User Avatar Upload with Multiple Sizes
public function upload_avatar(): void {
$user_id = segment(3, 'int');
$this->validation->set_rules(
'avatar',
'Avatar',
'required|max_size[2000]|max_width[2000]|max_height[2000]'
);
if ($this->validation->run() === true) {
$config = [
'destination' => 'avatars',
'upload_to_module' => true,
'target_module' => 'users',
'make_rand_name' => true,
'max_width' => 800,
'max_height' => 800,
'thumbnail_dir' => 'avatars/thumbs',
'thumbnail_max_width' => 150,
'thumbnail_max_height' => 150
];
$file_info = $this->image->upload($config);
// Store paths in database
$data = [
'avatar_full' => $file_info['file_path'],
'avatar_thumb' => $file_info['thumbnail_path']
];
$this->model->update($user_id, $data, 'users');
set_flashdata('Avatar updated successfully!');
redirect('users/profile/' . $user_id);
} else {
$this->avatar_form($user_id);
}
}
Pattern 2: Generate Multiple Product Image Sizes
public function process_product_image(): void {
$product_id = segment(3, 'int');
// Get product
$product = $this->db->get_where($product_id, 'products');
if ($product === false) {
redirect('products/not_found');
}
$source_path = $product->original_image_path;
$sizes = [
'large' => 1200,
'medium' => 800,
'small' => 400,
'thumbnail' => 200
];
$paths = [];
foreach ($sizes as $name => $width) {
// Load original fresh for each size
$this->image->load($source_path);
$this->image->resize_to_width($width);
$output_path = str_replace('.jpg', "_{$name}.jpg", $source_path);
$this->image->save($output_path, 85);
$this->image->destroy();
$paths[$name] = $output_path;
}
// Store all paths
$data = [
'image_large' => $paths['large'],
'image_medium' => $paths['medium'],
'image_small' => $paths['small'],
'image_thumbnail' => $paths['thumbnail']
];
$this->model->update($product_id, $data, 'products');
set_flashdata('Product images generated successfully');
redirect('products/edit/' . $product_id);
}
Pattern 3: Dynamic Image Serving
public function serve(): void {
$product_id = segment(3, 'int');
$size = segment(4) ?? 'medium';
$product = $this->db->get_where($product_id, 'products');
if ($product === false) {
redirect('products/not_found');
}
// Check if original image exists
if (!$this->file->exists($product->original_image_path)) {
redirect('products/image_missing');
}
// Load original
$this->image->load($product->original_image_path);
// Resize based on size parameter
switch ($size) {
case 'large':
$this->image->resize_to_width(1200);
break;
case 'small':
$this->image->resize_to_width(400);
break;
case 'thumbnail':
$this->image->resize_and_crop(200, 200);
break;
case 'medium':
default:
$this->image->resize_to_width(800);
break;
}
// Cache for 1 week
header('Content-Type: ' . $this->image->get_header());
header('Cache-Control: public, max-age=604800');
$this->image->output();
$this->image->destroy();
}
// Usage: yoursite.com/products/serve/123/large
Pattern 4: Format Conversion
public function convert_to_webp(): void {
$product_id = segment(3, 'int');
$product = $this->db->get_where($product_id, 'products');
if ($product === false) {
redirect('products/not_found');
}
$source_path = $product->image_path;
// Check source exists
if (!$this->file->exists($source_path)) {
set_flashdata('Source image not found');
redirect('products/edit/' . $product_id);
}
// Load and convert
$this->image->load($source_path);
// Create WebP version
$webp_path = str_replace(
['.jpg', '.jpeg', '.png'],
'.webp',
$source_path
);
$this->image->save($webp_path, 85);
$this->image->destroy();
// Update database
$data = ['image_webp' => $webp_path];
$this->model->update($product_id, $data, 'products');
set_flashdata('Image converted to WebP format');
redirect('products/edit/' . $product_id);
}
Pattern 5: Conditional Processing Based on Dimensions
public function smart_resize(): void {
$photo_id = segment(3, 'int');
$photo = $this->db->get_where($photo_id, 'photos');
if ($photo === false) {
redirect('photos/not_found');
}
$image_path = $photo->original_path;
if (!$this->file->exists($image_path)) {
set_flashdata('Image file not found');
redirect('photos/manage');
}
$this->image->load($image_path);
$width = $this->image->get_width();
$height = $this->image->get_height();
$ratio = $width / $height;
if ($ratio > 1.5) {
// Wide landscape
$this->image->resize_to_width(1200);
} elseif ($ratio < 0.7) {
// Tall portrait
$this->image->resize_to_height(1200);
} else {
// Square-ish
$this->image->resize_and_crop(1000, 1000);
}
$this->image->save($image_path, 85);
$this->image->destroy();
set_flashdata('Photo optimized successfully');
redirect('photos/view/' . $photo_id);
}
Validation Rules for Image Uploads
Use these validation rules with $this->validation->set_rules():
| Rule |
Parameter |
Description |
required |
none |
Image upload is mandatory |
max_size |
KB |
Maximum file size (e.g., max_size[5000] = 5MB) |
max_width |
pixels |
Maximum image width |
max_height |
pixels |
Maximum image height |
min_width |
pixels |
Minimum image width |
min_height |
pixels |
Minimum image height |
Validation Example
// Avatar requirements: square, 100-2000px, max 2MB
$this->validation->set_rules(
'avatar',
'Profile Picture',
'required|max_size[2000]|min_width[100]|min_height[100]|max_width[2000]|max_height[2000]'
);
// Product image: flexible size, max 5MB
$this->validation->set_rules(
'product_image',
'Product Image',
'required|max_size[5000]|max_width[4000]|max_height[4000]'
);
Quality Settings Reference
| Quality |
File Size |
Visual Quality |
Best For |
| 100 |
Largest |
Maximum |
Archival, printing, source files |
| 90-95 |
Large |
Excellent |
Hero images, featured content |
| 85-90 |
Medium |
Very good |
Standard web images (recommended) |
| 75-85 |
Small |
Good |
Thumbnails, list views |
| 60-75 |
Very small |
Acceptable |
Previews, backgrounds |
| <60 |
Tiny |
Poor |
Avoid for web use |
Supported Image Formats
| Format |
Extension |
MIME Type |
Transparency |
Compression |
| JPEG |
.jpg, .jpeg |
image/jpeg |
No |
Lossy (adjustable 0-100) |
| PNG |
.png |
image/png |
Yes (alpha channel) |
Lossless |
| GIF |
.gif |
image/gif |
Yes (binary) |
Lossless (256 colors) |
| WEBP |
.webp |
image/webp |
Yes (alpha channel) |
Lossy or lossless |
File Permission Reference
| Permission |
Octal |
Description |
Use Case |
| rw-r--r-- |
0644 |
Owner writes, all read |
Public web images (recommended) |
| rw-r----- |
0640 |
Owner writes, group reads |
Semi-private images |
| rw------- |
0600 |
Owner only |
Private images, documents |
| rw-rw-r-- |
0664 |
Owner/group write, all read |
Shared editing environments |
Best Practices Summary
Image Manipulation Essentials:
- ✅ Use included-image-upload() for NEW images from users
- ✅ Use included-image-load() for EXISTING images on disk
- ✅ Always validate images before uploading (type, size, dimensions)
- ✅ Use
make_rand_name for user-uploaded images (security)
- ✅ Store complete paths from
upload() in your database
- ✅ Generate common sizes during upload, not on-demand
- ✅ Reload source with
load() when generating multiple sizes
- ✅ Use quality 85-90 for web images (balance of quality/size)
- ✅ Set appropriate permissions (0644 public, 0600 private)
- ✅ Check file existence before
load() operations
- ✅ Preserve originals and generate variants as needed
- ✅ Use
resize_to_width() for most layouts
- ✅ Use
resize_and_crop() for thumbnails and grids
- ✅ Add caching headers when serving dynamic images
- ✅ Call
destroy() when processing many images in a loop
- ✅ Use
output() for watermarks and on-the-fly generation
Quick Decision Matrix
| Task |
Method(s) |
Notes |
| Upload new image |
upload() |
Handles validation, security, optional resize/thumbnails |
| Load existing image |
load() |
For batch processing or generating new sizes |
| Create square thumbnail |
resize_and_crop() |
Perfect for avatars and icons |
| Resize for web display |
resize_to_width() |
Most common for responsive layouts |
| Reduce file size |
save() with quality 80-85 |
Good balance for web |
| Dynamic watermark |
output() |
Don't store watermarked versions |
| Convert format |
save() with new extension |
Change .jpg to .webp, etc. |
| Multiple sizes |
Loop with load() + resize + save() |
Reload source each time |
| Check dimensions first |
get_width()/get_height() |
For conditional processing |
Need More Details? Each method is fully documented in the Image Module Reference with complete parameter descriptions, return values, and exception handling.