Download the PHP package marceli-to/image-cache without Composer

Image Cache

A simple image caching package for Laravel using Intervention Image v3.

Installation

Prerequisites

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• Composer

Basic Installation

You can install the package via composer:

Post-Installation Setup

1. Publish the configuration file:

This will create a config/image-cache.php file where you can configure:

• Cache path
• Cache lifetime
• Image search paths
• Available templates
• Route configuration

2. Configure your filesystem:

Ensure your Laravel filesystem is properly configured for storing cached images. By default, this package uses the public disk. Update your .env file and config/filesystems.php as needed:

Then create the symbolic link to make the storage publicly accessible:

3. Service Provider Registration:

The package uses Laravel's auto-discovery feature to register the service provider and facade automatically. If you have disabled auto-discovery, add the following to your config/app.php:

4. Create cache directory:

The package will attempt to create the cache directory automatically, but you may need to ensure proper permissions:

Intervention Image v3 Compatibility

This package is built for Intervention Image v3, which has a significantly different API compared to v2. If you're upgrading from a package that used Intervention Image v2, please note these key differences:

• The v3 API uses interfaces like ImageInterface and ModifierInterface
• Image manipulation methods return a new image instance rather than modifying the original
• The driver system has changed (GD is used by default in this package)

For more details on Intervention Image v3, please refer to the official documentation.

Configuration

Publish the configuration file:

This will create a config/image-cache.php file where you can configure:

• Cache path
• Cache lifetime
• Image search paths
• Available templates
• Route configuration

Features

Modern PHP Type Declarations

The package uses modern PHP 7.4+ type declarations throughout the codebase for improved code quality and IDE support:

• Parameter type hints for all method parameters
• Return type declarations for all methods
• Property type declarations for class properties

Robust Error Handling

The package includes comprehensive error handling:

• Proper exception handling with try/catch blocks
• Detailed logging using Laravel's Log facade
• Appropriate HTTP responses for different error scenarios
• Specific exception types for different error conditions

Input Validation

All user inputs are thoroughly validated:

• Filename validation to prevent directory traversal attacks
• Template validation to ensure templates exist
• Parameter validation for dimensions, coordinates, and ratios
• Sanitization of all inputs before processing

Usage

Basic Usage

In a Controller

In Views

The package automatically registers the necessary routes, so you can use it directly in your views:

The URL format for standard templates is:

The URL format for crop with maxSize is:

The URL format for crop with dimensions is:

Where:

• template: One of the templates defined in your config (e.g., 'large', 'small', 'thumbnail')
• filename: The name of the image file to process
• maxSize: (Optional) Maximum size for the output image
• maxWidth: (Optional) Maximum width for the output image
• maxHeight: (Optional) Maximum height for the output image
• coords: (Optional) Comma-separated string in the format width,height,x,y for cropping
• ratio: (Optional) Aspect ratio in the format width x height (e.g., '16x9')

Important notes about inputs:

• Filenames must contain only alphanumeric characters, underscores, hyphens, slashes, and dots
• File extensions must be one of: jpg, jpeg, png, gif, webp
• Coordinates must be in the format width,height,x,y with all values being positive integers
• Ratio must be in the format width x height with both values being positive integers
• Maximum dimensions must be positive integers and within the configured limits

Custom Controller

If you prefer to use your own controller, you can disable the automatic route registration in the config file:

Then create your own route and controller:

Programmatic Usage

You can also use the package programmatically:

Clearing the Cache

You can clear the cache using the provided Artisan command:

Or programmatically:

Custom Templates

You can create your own templates by:

1. Creating a class that implements Intervention\Image\Interfaces\ModifierInterface
2. Adding the template to your config file

Example template class:

Then add it to your config:

Error Handling

The package includes comprehensive error handling:

Exception Types

• InvalidArgumentException: Thrown when input validation fails
• RuntimeException: Thrown when file operations or image processing fails
• Exception: Caught for any unexpected errors

Logging

All errors and warnings are logged using Laravel's Log facade:

• Warning level: Input validation failures, image not found
• Error level: File operation failures, image processing errors

HTTP Responses

The package returns appropriate HTTP responses:

• 400 Bad Request: For invalid inputs
• 404 Not Found: When images can't be found
• 500 Server Error: For unexpected errors

Security

The package includes several security features:

• Path Sanitization: Prevents directory traversal attacks
• Input Validation: Validates all user inputs before processing
• File Extension Validation: Only allows specific image file extensions
• Error Message Sanitization: Ensures error messages don't expose sensitive information

License

The MIT License (MIT). Please see License File for more information.