{"id":13404947,"url":"https://github.com/oscarotero/imagecow","last_synced_at":"2025-04-13T00:48:44.606Z","repository":{"id":2912933,"uuid":"3922453","full_name":"oscarotero/imagecow","owner":"oscarotero","description":"PHP library to manipulate and generate responsive images","archived":false,"fork":false,"pushed_at":"2021-07-21T23:27:29.000Z","size":6796,"stargazers_count":244,"open_issues_count":7,"forks_count":29,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-09T14:06:39.635Z","etag":null,"topics":["client-hints","gd","image","imagick","responsive-images"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oscarotero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-04-03T20:38:55.000Z","updated_at":"2024-12-30T05:48:46.000Z","dependencies_parsed_at":"2022-08-21T10:10:52.810Z","dependency_job_id":null,"html_url":"https://github.com/oscarotero/imagecow","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscarotero%2Fimagecow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscarotero%2Fimagecow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscarotero%2Fimagecow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oscarotero%2Fimagecow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oscarotero","download_url":"https://codeload.github.com/oscarotero/imagecow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248262421,"owners_count":21074306,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client-hints","gd","image","imagick","responsive-images"],"created_at":"2024-07-30T19:01:53.592Z","updated_at":"2025-04-13T00:48:44.581Z","avatar_url":"https://github.com/oscarotero.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"# Imagecow\n\n[![Build Status](https://travis-ci.org/oscarotero/imagecow.svg?branch=master)](https://travis-ci.org/oscarotero/imagecow)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/oscarotero/imagecow/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/oscarotero/imagecow/?branch=master)\n\nCreated by Oscar Otero \u003chttp://oscarotero.com\u003e \u003coom@oscarotero.com\u003e\n\n\n## What is Imagecow?\n\nIt's a php library to manipulate images to web.\n\n* PHP \u003e= 5.5\n* Use GD2 or Imagick libraries\n* Very simple, fast and easy to use. There is not a lot of features, just the basics: crop, resize, resizeCrop, etc.\n\nSimple usage example:\n\n```php\nuse Imagecow\\Image;\n\nImage::fromFile('my-image.gif')\n    -\u003eautoRotate()\n    -\u003eresizeCrop(300, 400, 'center', 'middle')\n    -\u003eformat('png')\n    -\u003esave('converted-image.png')\n    -\u003eshow();\n```\n\n\n## How use it?\n\n### Installation\n\nThis package is installable and autoloadable via Composer as [imagecow/imagecow](https://packagist.org/packages/imagecow/imagecow).\n\n```php\n$ composer require imagecow/imagecow\n```\n\n### Creating a Imagecow\\Image instance:\n\n```php\nuse Imagecow\\Image;\n\n//Using Imagick:\n$image = Image::fromFile('my-image.jpg', Image::LIB_IMAGICK);\n\n//Detect the available library automatically\n//(in order of preference: Imagick, Gd)\n$image = Image::fromFile('my-image.jpg');\n\n//Create an instance from a string\n$image = Image::fromString(file_get_contents('my-image.jpg'));\n```\n\n### resize\n\n`Image::resize($width, $height = 0, $cover = false)`\n\nResizes the image keeping the aspect ratio.\n\n**Note:** If the new image is bigger than the original, the image wont be resized\n\n* `$width`: The new max-width of the image. You can use percentages or numbers (pixels). If it's `0`, it will be calculated automatically using the height\n* `$height`: The new max-height of the image. As width, you can use percentages or numbers and it will be calculated automatically if it's `0`\n* `$cover`: If it's `true`, the new dimensions will cover both width and height values. It's like css's `image-size: cover`.\n\n```php\n//Assuming the original image is 1000x500\n\n$image-\u003eresize(200);                    // change to 200x100\n$image-\u003eresize(0, 200);                 // change to 400x200\n$image-\u003eresize(200, 300);               // change to 200x100\n$image-\u003eresize(2000, 2000);             // keeps 1000x500\n```\n\n### crop\n\n`Image::crop($width, $height, $x = 'center', $y = 'middle')`\n\nCrops the image:\n\n* `$width`: The width of the cropped image. It can be number (pixels) or percentage\n* `$height`: The height of the cropped image. It can be number (pixels) or percentage\n* `$x`: The horizontal offset of the crop. It can be a number (for pixels) or percentage. You can also use the keywords `left`, `center` and `right`. If it's not defined, used the value by default (`center`).\n* `$y`: The vertical offset of the crop. As with $x, it can be a number or percentage. You can also use the keywords `top`, `middle` and `bottom`. If it's not defined, used the value by default (`middle`).\n\n```php\n$image-\u003ecrop(200, 300);                 // crops to 200x300px\n$image-\u003ecrop(200, 300, 'left', 'top');  // crops to 200x300px from left and top\n$image-\u003ecrop(200, 300, 20, '50%');      // crops to 200x300px from 20px left and 50% top\n$image-\u003ecrop('50%', '50%');             // crops to half size\n```\n\n#### Automatic cropping\n\nImagecow includes some code copied from the great library [stojg/crop](https://github.com/stojg/crop) to calculate the most important parts of the image to crop and resizeCrop automatically. The available methods are:\n\n* `Image::CROP_ENTROPY` [more info](https://github.com/stojg/crop#cropentropy)\n* `Image::CROP_BALANCED` [more info](https://github.com/stojg/crop#cropbalanced)\n\nNote: **these methods are available only for Imagick**. If you use Gd, the methods fallback to \"center\", \"middle\" positions.\n\nTo use them:\n\n```php\n$image-\u003ecrop(500, 200, Image::CROP_ENTROPY);  // crops to 500x200 using the Entropy method to calculate the center point\n$image-\u003ecrop(500, 200, Image::CROP_BALANCED); // The same as above but using the Balanced method\n```\n\n### resizeCrop\n\n`Image::resizeCrop($width, $height, $x = 'center', $y = 'middle')`\n\nResizes and crops the image. See [resize](resize) and [crop](crop) for the arguments description.\n\n```php\n$image-\u003eresizeCrop(200, 300);                  //Resizes and crops to 200x300px.\n$image-\u003eresizeCrop('50%', 300);                //Resizes and crops to half width and 300px height\n$image-\u003eresizeCrop(200, 300, 'left', '100%'); //Resizes and crops to 200x300px from left and bottom\n$image-\u003eresizeCrop(200, 300, Image::CROP_BALANCED); //Resizes and crops to 200x300px using the CROP_BALANCED method\n```\n\n### rotate\n\n`Image::rotate($angle)`\n\nRotates the image\n\n* `$angle`: Rotation angle in degrees (anticlockwise)\n\n```php\n$image-\u003erotate(90); // rotates the image 90 degrees\n```\n\n### autoRotate\n\n`Image::autoRotate()`\n\nAutorotates the image according its EXIF data\n\n```php\n$image-\u003eautoRotate();\n```\n\n### opacity\n\n`Image::opacity($value)`\n\nSet the alpha channel of the image. The value must be between 0 (transparent) to 100 (opaque). Note that the image will be converted to png (if it's not already)\n\n```php\n$image-\u003eopacity(50);\n```\n\n### blur\n\n`Image::blur($loops = 4)`\n\nApplies the gaussian blur to the image. The more loops, the more the image blurs.\n\n```php\n$image-\u003eblur(8);\n```\n\n### watermark\n\n`Image::watermark($image, $x = 'right', $y = 'bottom')`\n\nApplies a image as a watermark. You can configure the position and opacity.\n\n```php\n$image = Image::fromFile('photo.jpg');\n$logo = Image::fromFile('logo.png');\n\n$logo-\u003eopacity(50);\n\n$image-\u003ewatermark($logo);\n```\n\n### format\n\n`Image::format($format)`\n\nConverts the image to other format.\n\n* `$format`: The format name. It can be \"jpg\", \"png\", \"gif\", or \"webp\"*.\n\n```php\n$image-\u003eformat('png'); // converts to png\n```\n\n*Note: `webp` format is only supported when using Imagick. [ImageMagick must be built with WEBP support](#installing-imagemagick-with-webp-support).\n\n### save\n\nSave the image to a file.\n\n* `$filename`: The filename for the saved image. If it's not defined, overwrite the file (only if has been loaded from a file).\n\n```php\n$image-\u003esave('my-new-image.png'); // save to this file\n$image-\u003esave(); // overwrite file\n```\n\n### setBackground\n\n`Image::setBackground(array $background)`\n\nSet a default background used in some transformations: for example on convert a transparent png to jpg.\n\n* `$background`: An array with the RGB value of the color\n\n```php\n$image-\u003esetBackground(array(255, 255, 255)); // set the background to white\n```\n\n### quality\n\n`Image::quality($quality)`\n\nDefines the image compression quality for jpg images\n\n* `$quality`: An integer value between 0 and 100\n\n```php\n$image-\u003equality(80); // change the quality to 80\n```\n\n### setClientHints\n\n`Image::setClientHints(array $clientHints)`\n\nDefines the client hints to fix the final size of the image and generate responsive images. The available client hints are:\n\n* `dpr` Device pixel ratio\n* `width` The final image width\n* `viewport-width` The viewport width\n\n```php\n$image-\u003esetClientHints([\n    'dpr' =\u003e 2,\n    'width' =\u003e 300,\n    'viewport-width' =\u003e 1024,\n]);\n```\n\nMore information about [client hints below](#responsive-images).\n\n### Display the image\n\nSend the HTTP header with the content-type, output the image data and die:\n\n```php\n$image-\u003eshow(); // you should see this image in your browser\n```\n\nInsert the image as base64 url:\n\n```php\necho '\u003cimg src=\"' . $image-\u003ebase64() . '\"\u003e';\n```\n\n### Get image info:\n\nThere are other functions to returns image info:\n\n* `$image-\u003egetWidth()`: Returns the image width in pixels\n* `$image-\u003egetHeight()`: Returns the image height in pixels\n* `$image-\u003egetMimeType()`: Returns the image mime-type\n* `$image-\u003egetExifData()`: Returns the EXIF data of the image\n* `$image-\u003egetString()`: Returns a string with the image content\n\n\n#### Execute multiple functions\n\nYou can execute some of these functions defined as a string. This is useful to get images transformed dinamically using variables, for example: `image.php?transform=resize,200,300|format,png`. All operations are separated by `|` and use commas for the arguments:\n\n```php\n$image-\u003etransform('resize,200,50%|format,png|crop,100,100,CROP_ENTROPY');\n\n//This is the same than:\n$image\n\t-\u003eresize(200, '50%')\n\t-\u003eformat('png')\n\t-\u003ecrop(100, 100, Image::CROP_ENTROPY);\n```\n\n### Responsive images\n\nImagecow has support for client hints, that allows to generate responsive images without using cookies or javascript code (like in 1.x version of imagecow). Client Hints is introduced by Google becoming a standard. [Here's a deep explain of how to use it](https://www.smashingmagazine.com/2016/01/leaner-responsive-images-client-hints/)\n\nNote that currently this is supported only by [chrome and opera browsers](http://caniuse.com/#feat=client-hints-dpr-width-viewport).\n\nSimple example:\n\nIn your webpage, add the following code:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003ctitle\u003eMy webpage\u003c/title\u003e\n    \u003c!-- Activate client hints --\u003e\n    \u003cmeta http-equiv=\"Accept-CH\" content=\"DPR,Width,Viewport-Width\"\u003e \n\u003c/head\u003e\n\u003cbody\u003e\n    \u003c!-- Insert a responsive image --\u003e\n    \u003cimg src=\"image.php?file=flower.jpg\u0026amp;transform=resize,1000\" sizes=\"25vw\"\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nNow, in the server side:\n\n```php\nuse Imagecow\\Image;\n\n$file = __DIR__.'/'.$_GET['file'];\n$transform = isset($_GET['transform']) ? $_GET['transform'] : null;\n\n//Create the image instance\n$image = Image::fromFile($file);\n\n//Set the client hints\n$image-\u003esetClientHints([\n    'dpr' =\u003e isset($_SERVER['HTTP_DPR']) ? $_SERVER['HTTP_DPR'] : null,\n    'width' =\u003e isset($_SERVER['HTTP_WIDTH']) ? $_SERVER['HTTP_WIDTH'] : null,\n    'viewport-width' =\u003e isset($_SERVER['HTTP_VIEWPORT_WIDTH']) ? $_SERVER['HTTP_VIEWPORT_WIDTH'] : null,\n]);\n\n//Transform the image and display the result:\n$image-\u003etransform($transform)-\u003eshow();\n```\n\n### Other utils\n\n#### IconExtractor.\n\n**Only for Imagick**. Class to extract the images from an .ico file and convert to png.\n\n```php\nuse Imagecow\\Utils\\IconExtractor;\n\n$icon = new IconExtractor('favicon.ico');\n\n//Gets the better image from the icon (quality = color_depth + (width * height))\n$image = $icon-\u003egetBetterQuality();\n\n//Do imagecow stuff\n$image-\u003eresize(100)-\u003esave('my-image.png');\n```\n\n#### SvgExtractor.\n\n**Only for Imagick** This class allows generate images from a svg file (useful for browsers that don't support svg format):\n\n```php\nuse Imagecow\\Utils\\SvgExtractor;\n\n$svg = new SvgExtractor('image.svg');\n\n//Gets the image\n$image = $svg-\u003eget();\n\n//Now you can execute the imagecow methods:\n$image-\u003eresize(200)-\u003eformat('jpg')-\u003esave('image.jpg');\n```\n\n### Installing ImageMagick with WEBP support\n#### macOS\nVia Homebrew:\n```bash\nbrew install webp\nbrew install imagemagick --with-webp\n```\n\n#### CentOS/RHEL\n```bash\nyum install libwebp-devel rpm-build\nmkdir /tmp/imagemagick\ncd /tmp/imagemagick\nyum-builddep ImageMagick -y\nyumdownloader --source ImageMagick\nrpm -ivh ImageMagick*\nsed -i '/BuildRequires:\\tghostscript-devel/a BuildRequires:\\tlibwebp-devel' /root/rpmbuild/SPECS/ImageMagick.spec\nsed -i '/Requires: pkgconfig/a Requires: libwebp' /root/rpmbuild/SPECS/ImageMagick.spec\nrpmbuild -ba /root/rpmbuild/SPECS/ImageMagick.spec\nrpm -Uvh --force /root/rpmbuild/RPMS/x86_64/ImageMagick-*.rpm\nyum-config-manager --save --setopt=updates.exclude=ImageMagick*;\n```\n\n#### Ubuntu\n```bash\nmkdir /tmp/imagemagick\ncd /tmp/imagemagick\napt-get build-dep imagemagick\napt-get install libwebp-dev devscripts\napt-get source imagemagick\ncd imagemagick-*\ndebuild -uc -us\ndpkg -i ../*magick*.deb\n```\n\n### Maintainers:\n\n* @oscarotero (creator)\n* @eusonlito (collaborator)\n* [and more...](https://github.com/oscarotero/imagecow/graphs/contributors)\n\n### Thanks to\n\nStig Lindqvist and Julien Deniau jdeniau for the [stojg/crop library](https://github.com/stojg/crop)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foscarotero%2Fimagecow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foscarotero%2Fimagecow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foscarotero%2Fimagecow/lists"}