about.page

---
title: Image
description: Image manipulation using GD library.
icon: 'M19,19H5V5H19M19,3H5A2,2 0 0,0 3,5V19A2,2 0 0,0 5,21H19A2,2 0 0,0 21,19V5A2,2 0 0,0 19,3M13.96,12.29L11.21,15.83L9.25,13.47L6.5,17H17.5L13.96,12.29Z'
color: '#153522'
author: Taufik Nurrohman
type: Markdown
version: 2.4.1
...

This extension provides various API to work with BMP, GIF, JPEG, PNG and WEBP images.

### Usage

#### Create Image

Create a new image from a file path, an external URL or a Base64 URL:

~~~ .php
// Create image from file
$blob = new Image('.\path\to\image.png');

// Create image from remote URL
$blob = new Image('http://127.0.0.1/path/to/image.png');

// Create image from Base64 URL
$blob = new Image('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAy…');
~~~

#### Read Image Dimension

Read current image width and height:

~~~ .php
$width = $blob->width;
$height = $blob->height;
~~~

#### Read Image Type

Read current image MIME type:

~~~ .php
$type = $blob->type;
~~~

#### Resize Image

Resize image to an absolute width and height:

~~~ .php
$width = 100;
$height = 50;
$blob->resize($width); // Is the same as `->resize($width, $width)`
$blob->resize($width, $height);
~~~

#### Scale Image

Resize image width and height relative to the current image width and height:

~~~ .php
$blob->scale(50); // 50% of current image dimension
$blob->scale(200); // 200% of current image dimension
~~~

#### Fit Image

Resize image and make sure that the new width and height will not overflow the maximum width and height:

~~~ .php
$max_width = 100;
$max_height = 100;

$blob->fit($max_width, $max_height);
~~~

#### Crop and Resize Image

Resize and crop image to the center:

~~~ .php
$width = 100;
$height = 100;

$blob->crop($width); // Is the same as `->crop($width, $width)`
$blob->crop($width, $height);
~~~

#### Crop Image without Resize

Crop image with custom X and Y coordinate:

~~~ .php
$left = 20;
$top = 20;
$width = 100;
$height = 100;

$blob->crop($left, $top, $width, $height);
~~~

#### Save Image

Store the modified image blob to a file:

~~~ .php
// Method 1
file_put_contents('.\path\to\image.png', (string) $blob);
file_put_contents('.\path\to\image.png', $blob->blob(null, 50)); // Set image quality to 50%

// Method 2
$blob->blob('.\path\to\image.png');
$blob->blob('.\path\to\image.png', 50); // Set image quality to 50%
~~~

#### Render Image

Render image to the browser window as a file:

~~~ .php
status(200);
type($blob->type);

echo $blob;
~~~

~~~ .php
status(200);
type($blob->type);

echo $blob->blob(null, 50); // Set image quality to 50%
~~~

Load image from file cache if available:

~~~ .php
status(200);
type($blob->type);

if (is_file($file = '.\path\to\image.png')) {
    echo file_get_contents($file);
} else {
    echo $blob->blob($file);
}
~~~

### Image Folder

A special folder to store image files will be created automatically by this extension located at `.\lot\image`. You can
store important image files exclusively there. These files will not be directly accessible using the original address as
the files in the `.\lot\asset` folder. You need to use the proxy link feature to be able to access these files. A
built-in image proxy link feature is available and it allows public access by default:

~~~ .txt
http://127.0.0.1/image/autumn.jpg → http://127.0.0.1/lot/image/autumn.jpg
http://127.0.0.1/image/a/b/c/autumn.jpg → http://127.0.0.1/lot/image/a/b/c/autumn.jpg
~~~

You can add hooks to the route to restrict access to certain image files based on certain conditions:

~~~ .php
Hook::set('route.image', function ($content, $path) {
    // Disable public image access stored in `.\lot\image\me` folder
    if (str_starts_with($path, '/me/')) {
        status(403);
        type('text/plain');
        return 'Access denied.';
    }
    // Disable public image access stored in `.\lot\image\us` folder unless the user is logged-in
    if (str_starts_with($path, '/us/') && !Is::user()) {
        status(403);
        type('text/plain');
        return 'Access denied.';
    }
    return $content;
});
~~~

### Page Image Data

This extension also add `image` and `images` property to the current `$page` object. The `image` property will contain
the first image URL found in the current page content, and `images` property will contain list of images URL found in
the current page content. This extension will skip the parsing process if you have been set the `image` and `images`
property values explicitly in the page header:

~~~ .html.php
<?php foreach ($pages as $page): ?>
  <article>
    <?php if ($image = $page->image(72, 72)): ?>
      <img alt="" src="<?= $image; ?>">
    <?php endif; ?>
  </article>
<?php endforeach; ?>
~~~