Download the PHP package prowebber/pure_image without Composer
On this page you can find all versions of the php package prowebber/pure_image. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download prowebber/pure_image
More information about prowebber/pure_image
Files in prowebber/pure_image
Package pure_image
Short Description A simple PHP image formatting script
License GPL-3.0-or-later
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package pure_image
Pure Image
A PHP-only script that makes it easier to automatically compress, resize, and crop images. This uses the native functions within PHP and PHP GD to compress and resize the images. Below are the main benefits of Pure Image:
- Handles image type conversions (e.g. convert .png to .jpg)
- Maintains the original image's aspect ratio while scaling down
- Detects & fixes images that have an aspect ratio which cannot be divided evenly to fit the specified width/height.
- Generates a hash fingerprint for each image to use for detecting duplicates
General
Installation
Install using composer: composer require prowebber/pure_image
Requirements
The following requirements must be met before using:
- PHP >=7.3
- PHP GD (https://www.php.net/manual/en/book.image.php)
Supported Images
Pure Image can read, write, and convert between the following image formats:
- Gif (.gif)
- Jpeg (.jpg, .jpeg)
- Png (.png)
Basic Usage
Pure Image is easy to use and only requires 4 steps:
- A call to init Pure Image
- Specify the source image you want to compress and/or resize
- Specify the output image and compression settings
- Save the images
Step 1) Instantiating Pure Image
Step 2) Specify a Source Image
Pure Image requires a source image for all operations. You can do this by specifying the full path to the image you want to compress/resize.
Step 3) Specify an Output Image
This is where you specify the resizing method, the name and location of the output image, and additional params if needed.
Step 4) Run Pure Image
The final step is running the script. This will perform all actions and save the compressed/resized image to the location you specified in step 3.
Common Settings
Resize Options/Methods
| Method | Description |
|---|---|
compress |
Don't resize the image; compress only |
cover |
Shrink the image so the width and height are the exact dimensions specified. The final image may be cropped. |
fit |
Shrink the image so both the width and height fit within the dimensions specified |
scale |
Scale the image to a specified width or height. Keep aspect ratio. |
hash |
Generate a perceptual image hash and return the hash and the bit value of the image for detecting similar images |
Image Compression/Quality
The image compression is specified on a scale of 0 to 5, with 1 being the lest compression (largest filesize/best quality)
and 5 being the most compressed (smallest filesize/poorest quality). If you leave the compression
setting blank or set it to 0, the script will fallback to its default value. \
| Level | Description | Quality | Jpeg Equivalent | PNG Equivalent |
|---|---|---|---|---|
| 0 | Default / fallback | 65 | 6 | |
| 1 | Least compression | Best | 75 | 0 |
| 2 | Low compression | Good | 65 | 2 |
| 3 | Moderate compression | Decent | 55 | 4 |
| 4 | High compression | Low | 45 | 6 |
| 5 | Highest compression | Poor | 35 | 8 |
Pure Image Methods
Below are the different ways Pure Image can format the output image:
- Compress - Only compress the image. Do not scale or resize.
- Cover - Resize and crop the output image so it is the exact width and height specified.
- Fit - Resize the output image so it will fit inside the dimensions specified while maintaining aspect ratio.
- Scale - Create an image with the specified width or height. Keep the aspect ratio.
Compress
Compress the image. Do not scale or resize the output image.
Options You can use these options on all types of methods.
| Param | Type | Required | Description |
|---|---|---|---|
| 'save_path' | string | Yes | The absolute path of the output file. |
| 'quality' | int | Optional | The desired compression/quality level. See Compression Settings |
| 'output_type' | string | Optional | (jpg|png|gif) The type of image you want this converted to or saved as. (Uses the filetype of the source image if not specified) |
| 'image_id' | string | Optional | Allows you to specify a unique ID for each image (output array and error array will reference this ID when called) |
Example Request
Cover
The image is resized to the exact width and height specified. The image will be cropped if the original aspect ratio cannot be kept at the specified size.
Options
| Param | Type | Required | Description |
|---|---|---|---|
| 'width' | int | Yes | The maximum width (px) of the image after resized |
| 'height' | int | Yes | The maximum height (px) of the image after resized |
| 'save_path' | string | Yes | The absolute path of the output file. |
| 'quality' | int | Optional | The desired compression/quality level. See Compression Settings |
| 'output_type' | string | Optional | (jpg|png|gif) The type of image you want this converted to or saved as. (Uses the filetype of the source image if not specified) |
Example Request
Fit
The image is resized so both the width and height will fit inside the dimensions specified. The output image will maintain the original aspect ratio.
Options
| Param | Type | Required | Description |
|---|---|---|---|
| 'width' | int | Yes | The maximum width (px) of the image after resized |
| 'height' | int | Yes | The maximum height (px) of the image after resized |
| 'save_path' | string | Yes | The absolute path of the output file. |
| 'quality' | int|null | Optional | The desired compression/quality level. See Compression Settings |
| 'output_type' | string | Optional | (jpg|png|gif) The type of image you want this converted to or saved as. (Uses the filetype of the source image if not specified) |
Example Code
Scale
Scale the image by its width or height. The final image will be the exact width or height specified and will keep its original aspect ratio.
Options
| Param | Type | Required | Description |
|---|---|---|---|
| 'width' | int | Maybe | The maximum width (px) of the image after resized |
| 'height' | int | Maybe | The maximum height (px) of the image after resized |
| 'save_path' | string | Yes | The absolute path of the output file. |
| 'quality' | int | Optional | The desired compression/quality level. See Compression Settings |
| 'output_type' | string | Optional | (jpg|png|gif) The type of image you want this converted to or saved as. (Uses the filetype of the source image if not specified) |
Example Request
Hash
The hash feature is used to create a unique hash for each image that makes it easy to detect duplicate images in a database. All hashes have the following features:
- Generates a 64 character fingerprint you can compare other images against
- Two different hashing algorithms are used (Average and Difference)
- All images are rotated so mirrored images with have the same hash value
Notes
- PHP does not support unsigned BigInts, so you will need to convert the fingerprint hashes to hex or decimals within your script
- You can save the hash image (if desired), but it is not necessary as the fingerprint represents the image exactly
- Each digit in the fingerprint represents a specific pixel in the image. 0 = x0,y0, and 63 = x7,y7
Average Fingerprint
Creates a hash based on the average brightness of the image.
- Visit each pixel (in order)
- Compare the brightness of the current pixel to the average brightness of the entire image
- If the current pixel is darker than average, give the current pixel a value of
1 - If the current pixel is lighter than average, give the current pixel a value of
0
- If the current pixel is darker than average, give the current pixel a value of
- When completed, you will have a 64 character binary string of 0's and 1's
Difference Fingerprint
Creates a hash based off the brightness of the previous pixel.
- Visit each pixel (in order)
- Compare the brightness of the current pixel to the brightness of the previous pixel
- If the current pixel is brighter, give the current pixel a value of
1 - If the previous pixel is brighter, give the current pixel a value of
0
- If the current pixel is brighter, give the current pixel a value of
- When completed, you will have a 64 character binary string of 0's and 1's
This is used to generate a hash of the image to help detect similar images that are being compressed. The hash will do the following:
- Create a black and white 16px x 16px variation of the image
- Rotate the images identically so flipped/rotated variants will be discovered
- Generate a 64 bit binary value of the image
- Use the binary value to create a hex and big int value
Database Storage You can store the image hashes in a database. Below is an example of a MySQL table to store the hashes:
| Field | Type | Notes |
|---|---|---|
img_id |
int | Auto-incrementing image ID |
total_bits |
tinyint | Contains the total 1 values in the binary string |
img_hash |
bigint UNSIGNED | Stores the hash value as an integer |
Issues
- PHP does not support unsigned BigInt values
- If the image bit value is larger than a BigInt, it will be an invalid hash
- The best workaround is to use the bit value and have MySQL convert it to the BitInt hash
- More SQL tips to come
Hash Logic Used
Advanced
Creating Multiple Output Images
You can create multiple output images by making additional calls to the $pimage->out method with the
desired params. When you are ready to create the images, just call the $pimage->save->images() method
and it will create all the images.
Custom Settings
Below are settings you can set and/or change dynamically. \
Max Allowed Image Size
This sets the maximum allowed size (in bytes) that a source image can be. If this image size is
exceeded an error will be thrown.
Getting Output Result
After the images have been created you can fetch the output result/response with the following method call:
This will return a array with details for each image processed. If you specified a unique ID for each
image, the response array will be keyed by that ID. If you did not specify an ID for each image the
response array start at 0 and will increment for each additional image output. So requesting $result[0] will
return the debug info for that image.
Errors
Pure Image id designed to catch all errors before generating any output images. If an error is detected it
will store the error message and return false. Below are different ways to check errors: \
Errors by ID \ These are the error codes (and errors) Pure Image checks.
| err_id | Error Message |
|---|---|
| 1 | The source image was not found or does not exist |
| 2 | The mime is not supported |
| 3 | Only the width or height can be specified with the scale method, but both are set |
| 4 | You cannot set the maximum image size to a non-integer value |
| 5 | The image filetype is not supported |
| 6 | The image file size exceeds the specified limit |
| 7 | The output height cannot be taller than the source image |
| 8 | The output width cannot be wider than the source image |
| 9 | You cannot start using a custom image ID after pImage assigned incremental IDs |
| 10 | You must specify an ID for each image when using custom IDs |
| 11 | Another image has already been assigned this ID. Each image must have a unique ID |
Check if any errors exist \
The following will return TRUE if there are no errors; FALSE if errors exist.
Echo errors to the screen \ If any errors exist, this will echo/dump them to the screen.
`
Return an array of errors \ If any errors exist, this will return an associative array of the errors. The key/index will be the MD5 value of the error message.
`
Return detailed array of errors \ You can return a detailed array of errors (keyed by the image ID) by using the following method call:
`
This will return an array with the following syntax: Each $err_id is outlined in the table above.
Debug
You can see debug info by running the following command which will dump all the debug info to the screen.
Debug Description \ Below is an overview of the information output when debugging.
Usage Examples
Example 1
This is the complete process currently used in production to add images.
