scale()
public function scale(float $scale): void
Description
Scales a loaded image by a percentage, adjusting both width and height proportionally to maintain the aspect ratio. This method provides an intuitive way to resize images relative to their current size rather than specifying absolute dimensions.
Load First, Then Scale: This method requires an image to be loaded first using load() or upload(). Calling scale() without a loaded image will throw an Exception with the message "No image is loaded to scale."
Parameters
| Parameter |
Type |
Description |
Default |
Required |
| $scale |
float |
The percentage to scale the image. 100 = original size, <100 = reduce, >100 = enlarge. |
N/A |
Yes |
Understanding Scale Values
The $scale parameter works as a percentage of the original dimensions:
- 100: Keeps the original size (no change)
- 50: Reduces to half size (50% of original)
- 25: Reduces to quarter size (25% of original)
- 200: Doubles the size (200% of original)
- 150: Increases by 50% (150% of original)
Relative vs. Absolute Sizing: Use scale() when you want to resize relative to the current size (e.g., "make it 50% smaller"). Use resize_to_width() or resize_to_height() when you need specific pixel dimensions. The scale() method is particularly useful when processing images of varying sizes with a consistent reduction or enlargement factor.
Return Value
| Type |
Description |
| void |
This method does not return a value. It modifies the loaded image resource in place. |
Example #1
The code sample below demonstrates the most basic use of scale().
// Load an image
$this->image->load('modules/gallery/photos/photo.jpg');
// Scale to 50% of original size
$this->image->scale(50);
// Save the scaled image
$this->image->save('modules/gallery/photos/photo_half.jpg');
Proportional Scaling: The scale() method maintains aspect ratio automatically by applying the same percentage to both width and height. A scale value of 50 reduces a 2000x1000 image to 1000x500, maintaining the original 2:1 ratio perfectly.
Example #2
The example above shows how to create quick preview images at a fixed percentage of original size.
public function generate_preview(): void {
$photo_id = segment(3, 'int');
// Get photo record
$photo = $this->db->get_where($photo_id, 'photos');
if ($photo === false) {
redirect('photos/not_found');
}
$source_path = 'modules/gallery/originals/' . $photo->filename;
if (!$this->file->exists($source_path)) {
redirect('photos/file_missing');
}
// Load the original
$this->image->load($source_path);
// Create preview at 30% of original size
$this->image->scale(30);
// Ensure preview directory exists
$preview_dir = 'modules/gallery/previews';
if (!$this->file->exists($preview_dir)) {
$this->file->create_directory($preview_dir, 0755);
}
// Save the preview
$output_path = $preview_dir . '/' . $photo->filename;
$this->image->save($output_path, 85);
$this->image->destroy();
// Update photo record
$update_data = [
'preview_path' => $output_path,
'preview_created_at' => date('Y-m-d H:i:s')
];
$this->model->update($photo_id, $update_data, 'photos');
set_flashdata('Preview generated at 30% of original size');
redirect('gallery/view/' . $photo_id);
}
Percentage-Based Workflow: Using scale() is ideal when you want consistent relative sizing across images of different dimensions. A 30% preview works equally well for a 4000x3000 original (creating 1200x900) and a 2000x1500 original (creating 600x450), maintaining proportions in both cases.
Example #3
The example above demonstrates creating multiple scaled versions from a single source.
public function generate_scaled_variants(): void {
$image_id = segment(3, 'int');
// Get image record
$image = $this->db->get_where($image_id, 'images');
if ($image === false) {
redirect('images/not_found');
}
$source_path = 'modules/gallery/originals/' . $image->filename;
if (!$this->file->exists($source_path)) {
redirect('images/file_missing');
}
// Define scale percentages for different use cases
$scale_variants = [
'large' => 75, // 75% of original
'medium' => 50, // Half size
'small' => 30, // 30% of original
'thumbnail' => 15 // 15% of original
];
foreach ($scale_variants as $variant_name => $scale_percentage) {
// Load source fresh for each variant
$this->image->load($source_path);
// Scale by percentage
$this->image->scale($scale_percentage);
// Ensure variant directory exists
$output_dir = 'modules/gallery/scaled/' . $variant_name;
if (!$this->file->exists($output_dir)) {
$this->file->create_directory($output_dir, 0755);
}
// Save the scaled variant
$output_path = $output_dir . '/' . $image->filename;
$this->image->save($output_path, 85);
$this->image->destroy();
}
set_flashdata('Scaled variants generated successfully');
redirect('gallery/view/' . $image_id);
}
Multi-Scale Generation: Creating multiple percentage-based versions is straightforward with scale(). This approach works regardless of the source image dimensions, making it ideal for user-generated content where you can't predict original sizes but want consistent relative scaling across all images.
Example #4
The example above shows using scale() for progressive quality reduction in image optimisation.
public function optimise_for_web(): void {
$product_id = segment(3, 'int');
// Get product record
$product = $this->db->get_where($product_id, 'products');
if ($product === false) {
redirect('products/not_found');
}
$source_path = 'modules/products/originals/' . $product->image_filename;
if (!$this->file->exists($source_path)) {
redirect('products/image_missing');
}
// Load and check original dimensions
$this->image->load($source_path);
$original_width = $this->image->get_width();
$original_height = $this->image->get_height();
$this->image->destroy();
// Only optimise if image is large enough
if ($original_width < 1000 && $original_height < 1000) {
set_flashdata('Image is already optimised for web');
redirect('products/view/' . $product_id);
}
// Create web-optimised versions
$web_configs = [
'hero' => ['scale' => 60, 'compression' => 85],
'gallery' => ['scale' => 40, 'compression' => 80],
'thumbnail' => ['scale' => 20, 'compression' => 75]
];
foreach ($web_configs as $type => $config) {
// Load source
$this->image->load($source_path);
// Scale down
$this->image->scale($config['scale']);
// Ensure directory exists
$output_dir = 'modules/products/web/' . $type;
if (!$this->file->exists($output_dir)) {
$this->file->create_directory($output_dir, 0755);
}
// Save with appropriate compression
$output_path = $output_dir . '/' . $product->image_filename;
$this->image->save($output_path, $config['compression']);
$this->image->destroy();
}
set_flashdata('Product images optimised for web delivery');
redirect('products/view/' . $product_id);
}
Web Optimisation Strategy: Combining scale() with varying compression levels provides excellent file size reduction whilst maintaining acceptable quality. For example, a 60% scale with 85% compression can reduce file size by 80% or more, dramatically improving page load times without noticeable quality loss for web display.
Avoiding Upscaling: Be cautious when using scale values greater than 100, as enlarging images reduces quality through interpolation. If you need larger images, start with higher-resolution sources. The scale() method does not prevent upscaling, so validate dimensions before scaling if quality is critical.