|
| 1 | +# MegaOptim |
| 2 | +MegaOptim provides REST based APIs for optimizing images while keeping them almost identical to the original image but significantly reducing the image size using its advanced algorithms. |
| 3 | + |
| 4 | +The end result is to satisfy the pagespeed requirements, fast website load, less space usage, etc. |
| 5 | + |
| 6 | +This library can be installed with composer or without composer and can be used in differet use cases such as optimizing your library, optimizing the uploaded image on the go, etc. |
| 7 | + |
| 8 | +# Requirements |
| 9 | +- Api Key from MegaOptim.com |
| 10 | + |
| 11 | +# Installation |
| 12 | +### Composer |
| 13 | +You can install it with composer |
| 14 | +``` |
| 15 | +composer require megaoptim/megaoptim-php |
| 16 | +``` |
| 17 | +### Without Composer |
| 18 | +This is not recommended way. But you can require the `loadnoncomposer.php` file that will load the library without composer. |
| 19 | +```php |
| 20 | +require "megaoptim-php/loadnoncomposer.php" |
| 21 | +``` |
| 22 | + |
| 23 | +# How to Use |
| 24 | +This library has a class that will be used in 99% of the usecases and it is called ```MegaOptim\Optimizer``` and the ```run``` method is the method used for optimization. Its definition is as follows: |
| 25 | + |
| 26 | +``` |
| 27 | +public function run($resource, $args = array()) |
| 28 | +``` |
| 29 | +1. ```$resource``` - `string|array` The resources path, can be: Single image path OR Single URL OR multiple local paths OR multiple urls in array. **But not mixed array of urls and paths**. |
| 30 | +2. ```$args``` - `array` The parameters that describe how the optimization is going to be. It has few properties: |
| 31 | + * ```'keep_exif'``` - 1 OR 0 |
| 32 | + * ```'max_width'``` - Numeric px value |
| 33 | + * ```'max_height'``` - Numeric px value |
| 34 | + * ```'cmyktorgb'``` - 1 OR 0 |
| 35 | + * ```'compression'``` - intelligent (default), ultra OR lossless |
| 36 | + |
| 37 | + |
| 38 | +The ```$args``` parameter is not required and the defaults are as follows: |
| 39 | + |
| 40 | +``` |
| 41 | +[ |
| 42 | + 'keep_exif' => 0, |
| 43 | + 'max_width' => 0, |
| 44 | + 'max_height' => 0, |
| 45 | + 'cmyktorgb' => 1, |
| 46 | + 'compression' => 'intelligent', |
| 47 | +] |
| 48 | +``` |
| 49 | + |
| 50 | +To optimize single image call the ```run()``` method on some given parameters just like the following examples: |
| 51 | + |
| 52 | +## Single Local File |
| 53 | +```php |
| 54 | +use MegaOptim\Optimizer; |
| 55 | +$megaoptim = new Optimizer('your-api-key'); |
| 56 | +$response = $megaoptim->run( '/path/to/file.jpg', array( 'compression' => Optimizer::COMPRESSION_INTELLIGENT ) ); |
| 57 | +``` |
| 58 | + |
| 59 | +## Single URL |
| 60 | +```php |
| 61 | +use MegaOptim\Optimizer; |
| 62 | +$megaoptim = new Optimizer('your-api-key'); |
| 63 | +$response = $megaoptim->run( 'http://yoursite.com/some_image.jpg', array( 'compression' => Optimizer::COMPRESSION_INTELLIGENT ) ); |
| 64 | +``` |
| 65 | + |
| 66 | +## Multiple Files ( up to 5 ) |
| 67 | +```php |
| 68 | +use MegaOptim\Optimizer; |
| 69 | +$megaoptim = new Optimizer('your-api-key'); |
| 70 | +$resources = array( |
| 71 | + '/path/to/file1.jpg', |
| 72 | + '/path/to/file2.jpg', |
| 73 | + '/path/to/file3.jpg', |
| 74 | +); |
| 75 | + |
| 76 | +$response = $megaoptim->run( $resources, array( 'compression' => Optimizer::LOSSY ) ); |
| 77 | +``` |
| 78 | + |
| 79 | +## Multiple URLs ( up to 5 ) |
| 80 | +```php |
| 81 | +use MegaOptim\Optimizer; |
| 82 | +$megaoptim = new Optimizer('your-api-key'); |
| 83 | +$resources = array( |
| 84 | + 'http://somesite.com/path/to/file1.jpg', |
| 85 | + 'http://somesite.com/path/to/file2.jpg', |
| 86 | + 'http://somesite.com/path/to/file3.jpg', |
| 87 | +); |
| 88 | + |
| 89 | +$response = $megaoptim->run( $resources, array( 'compression' => Optimizer::LOSSY ) ); |
| 90 | +``` |
| 91 | + |
| 92 | + |
| 93 | +## Handling Response |
| 94 | + |
| 95 | +Once we run the optimization with `run()` method we have the instance of `MegaOptim\Http\Response` which contains all the response variables and array of optimized image objects. |
| 96 | + |
| 97 | +The contents of the ```$response``` methods are as follows: |
| 98 | + |
| 99 | +- ```$response->isSuccessful()``` - Returns boolean to determine if the optimization was successful. |
| 100 | +- ```$response->isError()``` - Returns boolean to determine if the optimization was not successful. |
| 101 | +- ```$response->getErrors()``` - Returns ```array``` with errors. |
| 102 | +- ```$response->getOptimizedFiles()``` - Returns array of ```optimized image objects``` from the class ```MegaOptim\Http\Result[]``` |
| 103 | + |
| 104 | +To get the optimized image objects and further process them we can use the `getOptimizedFiles()` method which will return array as mentioned above: |
| 105 | + |
| 106 | +```php |
| 107 | +$files = $response->getOptimizedFiles(); |
| 108 | +foreach($files as $file) { |
| 109 | + // Do something |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +We have the following properties and methods available to use for each optimized image object: |
| 114 | + |
| 115 | +- ```$file->getFileName()``` - Returns the original file name. |
| 116 | +- ```$file->getOptimizedSize()``` - Returns the new size in bytes. |
| 117 | +- ```$file->getSavedBytes()``` - Returns the total saved bytes. |
| 118 | +- ```$file->getSavedPercent()``` - Returns the total saved space in percentage. |
| 119 | +- ```$file->getUrl()``` - Returns the optimized image url. You need to download and store it on your server because it will be removed after 1 hour from MegaOptim server |
| 120 | + |
| 121 | +To save the optimized images locally we have three methods available: |
| 122 | +- ```$file->saveOverwrite()``` - Overwrites the local file with the new optimized file. **Only available when local files are being optimized, not URLs.** |
| 123 | +- ```$file->saveAsFile( $file_path )``` - Saves the optimized file in the specified file path. If the result directory doesn't exist it attempts to create it recursively. |
| 124 | +- ```$file->saveToDir( $dir_path )``` - Saves the optimized file in the specified directory path. If the result directory doesn't exist it attempts to create it recursively. |
| 125 | + |
| 126 | +```php |
| 127 | +if( !empty($files) ) { |
| 128 | + // Note: Thise are for demonstration purposes, you don't have to use it like this. |
| 129 | + // Overwrite |
| 130 | + $files[0]->saveOverwrite(); |
| 131 | + // Or save as other file |
| 132 | + $files[0]->saveAsFile('/path/to/other/file.jpg'); |
| 133 | + // Or save in some other dir with the original name |
| 134 | + $files[0]->saveToDir('/path/to/other'); |
| 135 | +} |
| 136 | + |
| 137 | +``` |
| 138 | + |
| 139 | +# TODO |
| 140 | +* Test library on different Operating Systems such as Windows. |
| 141 | + |
| 142 | +# Development |
| 143 | +If you found a bug or want to contribute to the script feel free to create pull requests to make it even better! |
| 144 | + |
| 145 | +## License |
| 146 | + |
| 147 | +``` |
| 148 | +Copyright (C) 2018 MegaOptim (https://megaoptim.com) |
| 149 | +
|
| 150 | +This file is part of MegaOptim Image Optimizer |
| 151 | +
|
| 152 | +MegaOptim Image Optimizer is free software: you can redistribute it and/or modify |
| 153 | +it under the terms of the GNU General Public License as published by |
| 154 | +the Free Software Foundation, either version 2 of the License, or |
| 155 | +(at your option) any later version. |
| 156 | +
|
| 157 | +MegaOptim Image Optimizer is distributed in the hope that it will be useful, |
| 158 | +but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 159 | +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 160 | +GNU General Public License for more details. |
| 161 | +
|
| 162 | +You should have received a copy of the GNU General Public License |
| 163 | +along with MegaOptim Image Optimizer. If not, see <https://www.gnu.org/licenses/>. |
| 164 | +``` |
| 165 | + |
| 166 | + |
| 167 | + |
| 168 | + |
| 169 | + |
0 commit comments