PHPackages darkroom/darkroom - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. darkroom/darkroom ActiveLibrary[Image & Media](/categories/media) darkroom/darkroom ================= A PHP library to transform, crop, resize and manipulate images 0.1.2(7y ago)12622[1 PRs](https://github.com/ptejada/darkroom/pulls)MITPHPPHP ^5.6 || ^7.0 Since Sep 28Pushed 7y ago1 watchersCompare [ Source](https://github.com/ptejada/darkroom)[ Packagist](https://packagist.org/packages/darkroom/darkroom)[ RSS](/packages/darkroom-darkroom/feed)WikiDiscussions master Synced 3w ago READMEChangelogDependencies (1)Versions (4)Used By (0) Darkroom ======== [](#darkroom) Darkroom is a library that facilitates simple image manipulation operations in PHP. The core functionality of the library is implemented in the form of *tools* which makes extending the image editor natural and intuitive. [![Build Status](https://camo.githubusercontent.com/6665c33c9e6ab35c2f9732ca2079706b2a291fb5a0c89d0aaae245c2c7dd07ee/68747470733a2f2f7472617669732d63692e6f72672f7074656a6164612f6461726b726f6f6d2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/ptejada/darkroom)[![StyleCI](https://camo.githubusercontent.com/aa778e57bbcad877a7e84f63b029538c86493e3c518110e656adc096516e5dde/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3131363532313233312f736869656c643f6272616e63683d6d6173746572)](https://github.styleci.io/repos/116521231)[![Maintainability](https://camo.githubusercontent.com/42290f5bb4174e34fcc819d0b4a479a0ce42820a8335ec49c61e6e758bacfa77/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f64633032633264303438653632366135356638612f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/ptejada/darkroom/maintainability)[![Test Coverage](https://camo.githubusercontent.com/dd8034e174906751e8e6085286e6961894222139a9755cd321f637610c221c89/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f64633032633264303438653632366135356638612f746573745f636f766572616765)](https://codeclimate.com/github/ptejada/darkroom/test_coverage) Requirements ============ [](#requirements) The Darkroom library has the following requirements: - PHP 5.6+ - GD Library Installation ============ [](#installation) Use composer to install the library in your project: ``` composer require darkroom/darkroom ``` Table of Contents- [Darkroom](#darkroom) - [Requirements](#requirements) - [Installation](#installation) - [Getting Started](#getting-started) - [Tools](#tools) - [Built-in tools](#built-in-tools) - [crop](#crop) - [resize](#resize) - [rotate](#rotate) - [stamp](#stamp) - [Custom tools](#custom-tools) - [The Storage](#the-storage) - [Location and naming pattern](#location-and-naming-pattern) - [Custom path generator](#custom-path-generator) - [Sending to external service](#sending-to-external-service) - [Custom Storage](#custom-storage) - [TODO](#todo) Getting Started =============== [](#getting-started) The library API is inspired by the options and actions that an image editor GUI would have. The result is a fluent and descriptive OOP driven API which replaces the long functions with a lot of arguments. There are three major components you should be aware of: The *Editor*, *Image* and *Tools*. In a nutshell, the *Editor*is use to create the *Image* object(s) and the *Tools* are the actions that manipulate the image like crop and resize. Use the editor to open an image: ``` $image = \Darkroom\Editor::open('image.jpg'); ``` Simple image crop: ``` // 400x400 viewport $image->edit()->crop()->square(400); // 400x200 viewport $image->edit()->crop()->rectagle(400, 200); ``` By default the image crop viewport will start from the top left of the image or the `x,y` position `0,0`. The position of the viewport can be specified as follows: ``` // Crop 400x400 square at position (150, 100) $image->edit()->crop()->square(400)->at(150, 100); ``` Save image to file system and get the reference: ``` // Save the image edits and get the local file path of the new image $newImagePath = $image->save()->localPath(); // Save the image edits and get the public URL of the new image $newImageUrl = $image->save()->publicUrl(); ``` To render the image to the standard output with its corresponding HTTP headers: ``` $image->render(); ``` Tools ===== [](#tools) Every image edit is handled by a `Tool`. Image edits include but are not limited to cropping, resizing placing watermarks. The library comes with built-in tools and also provides the option for custom tools to be registered Built-in tools -------------- [](#built-in-tools) All tools are accessed from the Image reference `edit()` factory. ``` $image = \Darkroom\Editor::open('image.jpg'); // The call to resize() will return an intance of \Darkroom\Tool\Resize $image->edit()->resize()->to(400); ``` ### crop [](#crop) Crop the image using a custom viewport dimension and position. **Modifiers:** - `rectangle( with, height )` - Creates rectangular viewport with specified dimensions - `square( dimension )` - Creates square viewport with specified dimension - `at( x, y )` - Position the upper left corner of the viewport. ### resize [](#resize) Resize the image to different dimensions while respecting the original aspect ratio unless the `distort` modifier is used. **Modifiers:** - `to( with, height )` - Set the dimensions of the new image. The *height* is optional. - `heightTo( height )` - Set the height of the new image. The width will be automatically calculated. - `by( percent )` - Set the dimensions of the new image using a decimal percentage where 0.5 is 50% or half the size of the original image. - `withImageFill( image )` - Use an image for the unused area if the new image has a different ratio. - `withColorFill( color )` - Use solid color for the unused area if the new image has a different aspect ratio. - `withTransparentFill()` - Makes the background of the unused area transparent. - `distort()` - Ignores the original aspect ratio and resize the image exactly to the specified dimensions. ### rotate [](#rotate) Rotate the image either left or right based on an angle. **Modifiers:** - `left( degrees )` - Rotate image to the left. - `right( degrees )` - Rotate image to the Right. - `withColorFill( color )` - Set a fill background color. - `withTransparentFill()` - Makes the background transparent. ### stamp [](#stamp) Stamp image with another position at one or more positions. Can be use to place watermarks in images. **Modifiers:** - `with( image )` - Sets the image to stamp with. - `at( x, y )` - Coordinates where to stamp the image. This modifier could be call multiple times to stamp at multiple locations - `opacity( level )` - Sets the opacity level for the stamp where 1 is opaque and 0 is transparent Custom tools ------------ [](#custom-tools) You create your own tool or recipe by implementing the `\Darkroom\Tool\Tool` interface. Alternatively you can extend `\Darkroom\Tool\AbstractTool` which already implements the interface. You may register any amount of tools used them in the same way built-in tools are used. ``` // Registers a new tool which can be accesed as 'flip' \Darkroom\Editor::registerTool('flip', '\MyApp\Image\Tool\Flip'); // Usage $image = Editor::open('my-image.jpg'); // Use new 'flip' tool $image->edit()->flip()->vertical(); $image->save(); ``` Been able to use your own custom tools is a very powerful feature. With great power comes great responsibility. `Editor::registerTool()` even allows you to overwrite built-tools with your own. The Storage =========== [](#the-storage) The library comes with a zero configuration built-in storage system. By default images will be saved in the folder `/storage/images/` located in the document root of your application. The images will be furthered organized in a monthly folder follow by a random name. Ex: `2018-09/ad57ryht-a5gf-s5hr2AWg.jpg`. The image storage if fully customizable and can even support storage to external services like AWS S3. You may access and configure the underlying storage system with `\Darkroom\Editor::config()->storage()`. Location and naming pattern --------------------------- [](#location-and-naming-pattern) Example update both the root path and the image naming pattern: ``` $store = \Darkroom\Editor::config()->storage(); // Updates where images will be stored $store->setBasePath('/var/www/path/to/public/folder/'); // Updates the default image naming pattern // The new patten will generate name a string of 16 characters $store->setPathPattern('%16'); ``` In the path pattern any letter character will be process by the PHP `date()` function and replaced with its output. Any % follow by a number represents a random string where the number is the length of the string. Ex: `%6` will generate a 6 characters long random string. The default pattern is`Y-m/%32`. Custom path generator --------------------- [](#custom-path-generator) If you need even more control over how and where the images are been stored you can configure the built-in storage with a PHP `callable` with `\Darkroom\Editor::config()->storage()->setPathGenerator(callable)`. The path generator callable receives and instance of the image been save as `\Darkroom\Image`. You may return the new absolute path where the image will be stored in the file system. ``` \Darkroom\Editor::config()->storage()->setPathGenerator(function($image, $basePath){ // Saved new images using the original name suffixed with a return $basePath . DIRECTORY_SEPRARATOR . $image->file()->name() . '_' . microtime(true); }); ``` Sending to external service --------------------------- [](#sending-to-external-service) Since the path generator has access to the Image reference it can also be used as a bridge to store the image in a separate system or storage service like AWS S3. Instead of returning a `string` for the local file system path you may return anything else like a `boolean` or a custom object and it wil be used as the return value for `Image::save()` calls. ``` // Configuration \Darkroom\Editor::config()->storage()->setPathGenerator(function($image){ $buffer = $image->renderTo(tmpfile()); // Code to upload stream to AWS S3 or other service // You can also return a reference to the external service like the URL or resource id as long as // is wrapped in an object. return true; }); // Usage Editor::open('my-image.jpg')->save(); // Returns true ``` Custom Storage -------------- [](#custom-storage) You should not include a lot of code in a `closure` to handle your custom image saving logic. If you need more room to handle saving the images consider making your own implementation of the `\Darkroom\Storage\Storage` interface. You can then register your Storage implementation in the editor. ``` // Configuration \Darkroom\Editor::config()->useStorage(new MyCustomStore); ``` TODO ==== [](#todo) - Complete the `Resize` tool fill modifiers. - Add `Rotate` tool to perform image rotation. - Implement registration system for custom tools. - Add unit test for the core functionality. ### Health Score 26 — LowBetter than 41% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity15 Limited adoption so far Community9 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 2 Last Release 2824d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/253405?v=4)[Pablo Tejada](/maintainers/ptejada)[@ptejada](https://github.com/ptejada) --- Top Contributors [![ptejada](https://avatars.githubusercontent.com/u/253405?v=4)](https://github.com/ptejada "ptejada (45 commits)") --- Tags crop-imagegd-libraryphp-librarywatermarkimagegdresizetransformcrop ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/darkroom-darkroom/health.svg) ``` [![Health](https://phpackages.com/badges/darkroom-darkroom/health.svg)](https://phpackages.com/packages/darkroom-darkroom) ``` ### Alternatives [intervention/image PHP Image Processing 14.3k203.8M2.5k](/packages/intervention-image)[sybio/image-workshop Powerful PHP class using GD library to work easily with images including layer notion (like Photoshop or GIMP) 854936.5k12](/packages/sybio-image-workshop)[jbzoo/image A PHP class that simplifies working with images 171128.5k3](/packages/jbzoo-image)[intervention/image-laravel Laravel Integration of Intervention Image 1558.1M159](/packages/intervention-image-laravel)[stefangabos/zebra_image A single-file, lightweight PHP library designed for efficient image manipulation featuring methods for modifying images and applying filters 138115.5k7](/packages/stefangabos-zebra-image)[ctessier/nova-advanced-image-field An advanced image field for Nova with cropping and resizing. 102563.4k1](/packages/ctessier-nova-advanced-image-field) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)