PHPackages                             raincreativelab/shackles - 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. raincreativelab/shackles

ActiveLibrary[Image & Media](/categories/media)

raincreativelab/shackles
========================

Rule Based Image Processor for PHP

34PHP

Since Mar 5Pushed 11y ago1 watchersCompare

[ Source](https://github.com/raincreativelab/shackles)[ Packagist](https://packagist.org/packages/raincreativelab/shackles)[ RSS](/packages/raincreativelab-shackles/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

**Documentation work in progress**
----------------------------------

[](#documentation-work-in-progress)

SHACKLES
========

[](#shackles)

What is Shackles?
-----------------

[](#what-is-shackles)

Shackle is a chainable, rule-based image processing library for PHP. Simply put, it makes complex image processing damn simple and easy.

**A straight-forward example:**

The following code will duplicate the original photo, crop at 400 x 300 pixel, then convert the whole thing into grayscale.

```
// Create a new chain
$chain = new Chain();
$chain->setRules([
    new Duplicate(),
    new Crop([
        "width"  => 400,
        "height" => 300
    ]),
    new Grayscale()
]);

// Create a new runner
$runner = ChainBuilder::newRunner([
    "source" => "/path/to/my/image/directory",
    "format" => "gs-{NAME}-{###}-{W}x{H}"
]);

// Run the chain and apply to the image
$runner
    ->process("image.jpg", 100) // 100 is the JPG output quality
    ->run($chain);

// The following code will return the following image:
// gs-image-15A-400x300.jpg
// The '15A' is a random string chain
```

How Shackles work?
------------------

[](#how-shackles-work)

To better understand how Shackles do its thing, here are some basic terminologies we will be using for clarity and consistency.

#### Rule

[](#rule)

is the basic unit of work. It contains how the image will be processed. There are 4 common rules:

- [Resize](#resize)
- [Duplicate](#duplicate)
- [Crop](#crop)
- [Convert Image to Grayscale](#grayscale)

The name of the rule clearly defines what it does and what you would expect for it to do. You can create define your own rules that you can attach to Shackle.

**You might want to know more about:**[Rules](#rule), [Creating your own Rule](#create-rule)

#### Chain

[](#chain)

are group of rules you chain to perform series of actions to your image. The order of each rule depends on how it is plugged in to the chain.

**Learn how to:**[Create a Chain](#chain)

#### Runner

[](#runner)

runs the chain of rules you set. The runner accepts the image you want to process and use the chain of rules on how the target image will be processed.

**Learn how to:**[Run your Chain](#runner), [Chain Builder](#chain-builder), [Storing your chain](#chain-serializer), [Running Chain from String](#string-to-chain)

Why use Shackles?
-----------------

[](#why-use-shackles)

Shackles is just one of the components we use in our CMS. This component specifically handles one thing only - Image Processing.

But because we want to share this to people that they might find it useful, we decided to make it a standalone component for people to integrate and use.

#### Use case

[](#use-case)

There are scenarios that an image needs to be processed in a series of steps. That steps can vary from resizing it, cropping it to produce thumbnails and sometimes, there is a need to produce multiple versions of your thumbnails in different aspect ratio. I know that there are other libraries out there to do just that or you might have something that you created your self. Well, this kind of scenario is the thing Shackle is solving.

Shackle's decouple the processing and breaks them into a series of reusable, chainable rules that you can use, configure to solve different scenarios in image processing. Because of its simple design, and API, extending the component is simple and straight forward.

[You can always check the example above](#example)

Rule
----

[](#rule-1)

Rule is the basic unit of work that defines how image will be processed or manipulated.

Any rule used by Shackle extends the `shackles\Rule` abstract class. The abstract class requires the implementing class to implement the

```
/**
 * This is a custom method that will be used
 * to process the image.
 *
 * @param Image $image Image to process
 *
 * @return void
 */
abstract protected function processImage(Image $image);
```

The following method signature should define how the image will be processed or manipulated.

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity41

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.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2261391?v=4)[raincreativelab](/maintainers/raincreativelab)[@raincreativelab](https://github.com/raincreativelab)

---

Top Contributors

[![raincreativelab](https://avatars.githubusercontent.com/u/2261391?v=4)](https://github.com/raincreativelab "raincreativelab (5 commits)")

### Embed Badge

![Health badge](/badges/raincreativelab-shackles/health.svg)

```
[![Health](https://phpackages.com/badges/raincreativelab-shackles/health.svg)](https://phpackages.com/packages/raincreativelab-shackles)
```

###  Alternatives

[char0n/ffmpeg-php

PHP wrapper for FFmpeg application

495240.6k1](/packages/char0n-ffmpeg-php)[goat1000/svggraph

Generates SVG graphs

135911.1k3](/packages/goat1000-svggraph)[gravatarphp/gravatar

Gravatar URL builder which is most commonly called as a Gravatar library

16653.6k2](/packages/gravatarphp-gravatar)[rsoury/wp-imgix

Rewrites WordPress image URLs to use ImgIX

167.2k](/packages/rsoury-wp-imgix)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)