{"id":15036557,"url":"https://github.com/gregwar/image","last_synced_at":"2025-05-14T08:08:52.677Z","repository":{"id":39615462,"uuid":"2137402","full_name":"Gregwar/Image","owner":"Gregwar","description":"A PHP library to handle images","archived":false,"fork":false,"pushed_at":"2024-09-23T15:02:03.000Z","size":2567,"stargazers_count":1006,"open_issues_count":81,"forks_count":191,"subscribers_count":44,"default_branch":"master","last_synced_at":"2025-04-09T00:30:23.931Z","etag":null,"topics":["center","crop","gd","images","php","resizes"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gregwar.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-08-01T15:29:43.000Z","updated_at":"2025-03-15T20:58:06.000Z","dependencies_parsed_at":"2023-01-30T22:46:55.388Z","dependency_job_id":"5052e37e-143d-42f2-ac7c-1526d580a349","html_url":"https://github.com/Gregwar/Image","commit_stats":{"total_commits":266,"total_committers":36,"mean_commits":7.388888888888889,"dds":0.4699248120300752,"last_synced_commit":"03edd7fc7339e6ac04f440ab592a029634b222a2"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gregwar%2FImage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gregwar%2FImage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gregwar%2FImage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gregwar%2FImage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gregwar","download_url":"https://codeload.github.com/Gregwar/Image/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101558,"owners_count":22014908,"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":["center","crop","gd","images","php","resizes"],"created_at":"2024-09-24T20:31:32.593Z","updated_at":"2025-05-14T08:08:52.628Z","avatar_url":"https://github.com/Gregwar.png","language":"PHP","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=YUXRLWHQSWS6L"],"categories":[],"sub_categories":[],"readme":"# Gregwar's Image class\n\n[![Build status](https://github.com/Gregwar/Image/actions/workflows/test.yml/badge.svg)](https://github.com/Gregwar/Image/actions/workflows/test.yml)\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=YUXRLWHQSWS6L)\n\nThe `Gregwar\\Image` class purpose is to provide a simple object-oriented images handling and caching API.\n\n# Installation\n\nWith composer :\n\n``` json\n{\n    ...\n    \"require\": {\n        \"gregwar/image\": \"2.*\"\n    }\n}\n```\n\n# Usage\n\n## Basic handling\n\nUsing methods chaining, you can open, transform and save a file in a single line:\n\n```php\n\u003c?php use Gregwar\\Image\\Image;\n\nImage::open('in.png')\n     -\u003eresize(100, 100)\n     -\u003enegate()\n     -\u003esave('out.jpg');\n```\n\nHere are the resize methods:\n\n* `resize($width, $height, $background)`: resizes the image, will preserve scale and never\n   enlarge it (background is `red` in order to understand what happens):\n\n![resize()](doc/resize.jpg)\n\n* `scaleResize($width, $height, $background)`: resizes the image, will preserve scale, can enlarge\n it (background is `red` in order to understand what happens):\n\n![scaleResize()](doc/scaleResize.jpg)\n\n* `forceResize($width, $height, $background)`: resizes the image forcing it to\n   be exactly `$width` by `$height`\n\n![forceResize()](doc/forceResize.jpg)\n\n* `cropResize($width, $height, $background)`: resizes the image preserving scale (just like `resize()`)\n  and croping the whitespaces:\n\n![cropResize()](doc/cropResize.jpg)\n\n* `zoomCrop($width, $height, $background, $xPos, $yPos)`: resize and crop the image to fit to given dimensions:\n\n![zoomCrop()](doc/zoomCrop.jpg)\n\n* In `zoomCrop()`, You can change the position of the resized image using the `$xPos` (center, left or right) and `$yPos` (center,\n  top or bottom):\n\n![zoomCrop() with yPos=top](doc/zoomCropTop.jpg)\n\nThe other methods available are:\n\n* `crop($x, $y, $w, $h)`: crops the image to a box located on coordinates $x,y and\n   which size is $w by $h\n\n* `negate()`: negates the image colors\n\n* `brighness($b)`: applies a brightness effect to the image (from -255 to +255)\n\n* `contrast($c)`: applies a contrast effect to the image (from -100 to +100)\n\n* `grayscale()`: converts the image to grayscale\n\n* `emboss()`: emboss the image\n\n* `smooth($p)`: smooth the image\n\n* `sharp()`: applies a mean removal filter on the image\n\n* `edge()`: applies an edge effect on the image\n\n* `colorize($red, $green, $blue)`: colorize the image (from -255 to +255 for each color)\n\n* `sepia()`: applies a sepia effect\n\n* `merge($image, $x, $y, $width, $height)`: merges two images\n\n* `fill($color, $x, $y)`: fills the image with the given color\n\n* `write($font, $text, $x, $y, $size, $angle, $color, $position)`: writes text over image, $position can be any of 'left', 'right', or 'center'\n\n* `rectangle($x1, $y1, $x2, $y2, $color, $filled=false)`: draws a rectangle\n\n* `rotate($angle, $background = 0xffffff)` : rotate the image to given angle\n\n* `roundedRectangle($x1, $y1, $x2, $y2, $radius, $color, $filled=false)`: draws a rounded rectangle ($radius can be anything from 0)\n\n* `line($x1, $y1, $x2, $y2, $color)`: draws a line\n\n* `ellipse($cx, $cy, $width, $height, $color, $filled=false)`: draws an ellipse\n\n* `circle($cx, $cy, $r, $color, $filled=false)`: draws a circle\n\n* `fillBackground($bg=0xffffff)`: fills the background of a transparent image to the 'bg' color\n\n* `fixOrientation()`: return the image rotated and flipped using image exif information \n\n* `applyExifOrientation(int $exif_rotation_value)`: return the image rotated and flipped using an exif rotation value \n\n* `html($title = '', $type = 'jpg')`: return the `\u003cimg ... /\u003e` tag with the cache image\n\n* `flip($flipVertical, $flipHorizontal)`: flips the image in the given directions. Both params are boolean and at least one must be true.\n\n* `inline($type = 'jpg')`: returns the HTML inlinable base64 string (see `demo/inline.php`)\n\nYou can also create image from scratch using:\n\n```php\n\u003c?php\n    Image::create(200, 100);\n```\n\nWhere 200 is the width and 100 the height\n\n## Saving the image\n\nYou can save the image to an explicit file using `save($file, $type = 'jpg', $quality = 80)`:\n\n```php\n\u003c?php\n    // ...\n    $image-\u003esave('output.jpg', 'jpg', 85);\n```\n\nYou can also get the contents of the image using `get($type = 'jpg', $quality = 80)`, which will return the binary contents of the image\n\n## Using cache\n\nEach operation above is not actually applied on the opened image, but added in an operations\narray. This operation array, the name, type and modification time of file are hashed using\n`sha1()` and the hash is used to look up for a cache file.\n\nOnce the cache directory configured, you can call the following methods:\n\n* `jpeg($quality = 80)`: lookup or create a jpeg cache file on-the-fly\n\n* `gif()`: lookup or create a gif cache file on-the-fly\n\n* `png()`: lookup or create a png cache file on-the-fly\n\n* `guess($quality = 80)`: guesses the type (use the same as input) and lookup or create a\n  cache file on-the-fly\n\n* `setPrettyName($prettyName, $prefix = true)`: sets a \"pretty\" name suffix for the file, if you want it to be more SEO-friendly.\n   for instance, if you call it \"Fancy Image\", the cache will look like something/something-fancy-image.jpg.\n   If `$prefix` is passed to `false` (default `true`), the pretty name won't have any hash prefix.\n   If you want to use non-latin1 pretty names, **behat/transliterator** package must be installed.\n\nFor instance:\n\n```php\n\u003c?php use Gregwar\\Image\\Image;\n\necho Image::open('test.png')\n          -\u003esepia()\n          -\u003ejpeg();\n\n//Outputs: cache/images/1/8/6/9/c/86e4532dbd9c073075ef08e9751fc9bc0f4.jpg\n```\n\nIf the original file and operations do not change, the hashed value will be the same and the\ncache will not be generated again.\n\nYou can use this directly in an HTML document:\n\n\n```php\n\u003c?php use Gregwar\\Image\\Image;\n\n// ...\n\u003cimg src=\"\u003c?php echo Image::open('image.jpg')-\u003eresize(150, 150)-\u003ejpeg(); ?\u003e\" /\u003e\n// ...\n```\n\nThis is powerful since if you change the original image or any of your code the cached hash\nwill change and the file will be regenerated.\n\nWriting image\n-------------\n\nYou can also create your own image on-the-fly using drawing functions:\n\n\n```php\n\u003c?php \n    $img_src = Image::create(300, 300)\n                    -\u003efill(0xffaaaa)    // Filling with a light red\n                    -\u003erectangle(0xff3333, 0, 100, 300, 200, true) // Drawing a red rectangle\n                      // Writing \"Hello $username !\" on the picture using a custom TTF font file\n                    -\u003ewrite('./fonts/CaviarDreams.ttf', 'Hello '.$username.'!', 150, 150, 20, 0, 'white', 'center')\n                    -\u003ejpeg();\n?\u003e\n\u003cimg src=\"\u003c?= $img_src  ?\u003e\" /\u003e\n```\n\n## Using fallback image\n\nIf the image file doesn't exist, you can configure a fallback image that will be used\nby the class (note that this requires the cache directory to be available).\n\nA default \"error\" image which is used is in `images/error.jpg`, you can change it with:\n\n```php\n\u003c?php\n    $img-\u003esetFallback('/path/to/my/fallback.jpg');\n```\n\n## Garbage Collect\n\nTo prevent the cache from growing forever, you can use the provided GarbageCollect class as below:\n\n```php\n\u003c?php use Gregwar\\Image\\GarbageCollect;\n\n// This could be a cron called each day @3:00AM for instance\n// Removes all the files from ../cache that are more than 30 days\n// old. A verbose output will explain which files are deleted\nGarbageCollect::dropOldFiles(__DIR__.'/../cache', 30, true);\n\n```\n\n# Development\n\n`Gregwar\\Image` is using PHP metaprogramming paradigms that makes it easy to enhance.\n\nEach function that handles the image is implemented in an *Adapter*, this is where\nall the specific actions take place.\n\nThe `Common` adapter is design to contain common abstract actions, while the\nspecific adapters (like `GD`) are designed to contain actions specific to the low\nlevel layer.\n\nYou can add your own methods by adding it in the corresponding adapter.\n\n```php\n\u003c?php\n    // In the adapter\n    private function myFilter()\n    {\n        $this-\u003enegate();\n        $this-\u003esepia();\n    }\n```\n\nWhich could be used on the Image\n\n```php\n\u003c?php\n    $image-\u003emyFilter();\n```\n\nYou can also write your own adapter which could extend one of this repository and use it by calling `setAdapter()`:\n\n```php\n\u003c?php\n    $image-\u003esetAdapter(new MyCustomAdapter);\n```\n\n# License\n\n`Gregwar\\Image` is under MIT License, please read the LICENSE file for further details.\nDo not hesitate to fork this repository and customize it !\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregwar%2Fimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregwar%2Fimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregwar%2Fimage/lists"}