PHPackages                             3brs/imgproxy-bundle - 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. 3brs/imgproxy-bundle

ActiveSymfony-bundle[Image & Media](/categories/media)

3brs/imgproxy-bundle
====================

Imgproxy integration for Liip Imagine Bundle - replaces image processing with imgproxy

v1.0.0(6mo ago)1148MITPHPPHP ^8

Since Oct 29Pushed 6mo agoCompare

[ Source](https://github.com/3BRS/imgproxy-bundle)[ Packagist](https://packagist.org/packages/3brs/imgproxy-bundle)[ RSS](/packages/3brs-imgproxy-bundle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (14)Versions (2)Used By (0)

 [ ![](https://camo.githubusercontent.com/bb0c16caf210bea68e0e59fc11e0844dc47097f9aeb8b388c3de5f1414d4d1c0/68747470733a2f2f33627273312e667261312e63646e2e6469676974616c6f6365616e7370616365732e636f6d2f336272732f6c6f676f2f334252532d6c6f676f2d73796c6975732d3230302e706e67) ](https://www.3brs.com)

Imgproxy Bundle for Symfony
===========================

[](#imgproxy-bundle-for-symfony)

 [ ![](https://camo.githubusercontent.com/6efdc0d5b3e0dd600466b273f5190e13c770b38000aac1e90ee1e46f1b4cc524/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f336272732f696d6770726f78792d62756e646c652e737667) ](https://packagist.org/packages/3brs/imgproxy-bundle "License") [ ![](https://camo.githubusercontent.com/28288763a1065962ff49569cb28171e99a7448ad3504febe0f84422c403d6b81/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f336272732f696d6770726f78792d62756e646c652e737667) ](https://packagist.org/packages/3brs/imgproxy-bundle "Version") [ ![](https://camo.githubusercontent.com/062fee4cbf9b91b347f8f862c36ee909df9e183f7503d73ba9542777e31a0e8b/68747470733a2f2f636972636c6563692e636f6d2f67682f334252532f696d6770726f78792d62756e646c652e7376673f7374796c653d736869656c64) ](https://circleci.com/gh/3BRS/imgproxy-bundle "Build Status")

A Symfony bundle that integrates [imgproxy](https://imgproxy.net/) with [Liip Imagine Bundle](https://github.com/liip/LiipImagineBundle), replacing on-the-fly image processing with imgproxy's powerful and performant image transformation service.

Features
--------

[](#features)

- 🚀 **Drop-in replacement** for Liip Imagine Bundle - no template changes needed
- ⚡ **High performance** - leverage imgproxy's native Go implementation
- 🔒 **Secure** - URL signing support to prevent unauthorized image transformations
- 📦 **S3/CDN ready** - works seamlessly with cloud storage
- 🎨 **Full filter support** - supports 13/17 Liip Imagine filters (76% compatibility)
- 🔧 **Static asset detection** - automatically skips webpack builds and bundles

Requirements
------------

[](#requirements)

- PHP 8.0, 8.1, 8.2, 8.3, or 8.4
- Symfony 5.4, 6.4, or 7.1
- Liip Imagine Bundle 2.x
- Running imgproxy server

Installation
------------

[](#installation)

### Step 1: Install the bundle

[](#step-1-install-the-bundle)

```
composer require 3brs/imgproxy-bundle
```

### Step 2: Register the bundle

[](#step-2-register-the-bundle)

Register the bundle in `config/bundles.php`:

```
return [
    // ...
    ThreeBRS\ImgproxyBundle\ThreeBRSImgproxyBundle::class => ['all' => true],
];
```

### Step 3: Configure imgproxy

[](#step-3-configure-imgproxy)

Create `config/packages/three_brs_imgproxy.yaml`:

```
imports:
    - { resource: "@ThreeBRSImgproxyBundle/Resources/config/packages/three_brs_imgproxy.yaml" }
```

### Step 4: Set environment variables

[](#step-4-set-environment-variables)

```
# Imgproxy server URL
IMGPROXY_URL=https://imgproxy.your-domain.com

# Source images URL (your S3/CDN endpoint)
IMGPROXY_SOURCE_URL=https://your-bucket.s3.amazonaws.com

# S3 prefix path (optional, leave empty if images are in bucket root)
IMGPROXY_SOURCE_PREFIX=media/image

# Optional: URL signing keys
IMGPROXY_KEY=your_hex_key_here
IMGPROXY_SALT=your_hex_salt_here
```

### Step 5: Update Liip Imagine configuration

[](#step-5-update-liip-imagine-configuration)

In `config/packages/liip_imagine.yaml`, change the cache resolver:

```
liip_imagine:
    resolvers:
        imgproxy:
            # Resolver is auto-configured by the bundle

    cache: imgproxy  # Change from 'default' to use imgproxy resolver

    filter_sets:
        # Your existing filter sets...
        thumbnail:
            filters:
                thumbnail: { size: [300, 200], mode: outbound }
```

### Step 6: Clear cache

[](#step-6-clear-cache)

```
php bin/console cache:clear
```

### Production deployment

[](#production-deployment)

See [imgproxy documentation](https://docs.imgproxy.net/) for Kubernetes, AWS ECS, or other deployment options.

Filter Compatibility
--------------------

[](#filter-compatibility)

### ✅ Fully Supported (13/17 filters)

[](#-fully-supported-1317-filters)

Liip Imagine FilterImgproxy EquivalentNotes`thumbnail``resize:fill` or `resize:fit`Most commonly used`resize``resize:force` + `size`Exact dimensions`scale``resize:fit` + `size`Proportional scaling`downscale``resize:fit` + `enlarge:0`Never enlarges`upscale``resize:fit` + `enlarge:1`Always enlarges`crop``resize:fill` + `size`Crop to dimensions`rotate``rotate`Angle in degrees`auto_rotate``auto_rotate:1`EXIF-based rotation`background``background` + `extend`Background color`grayscale``saturation:0`Grayscale effect`watermark``watermark`Requires URL`strip`✓Automatic`interlace`✓Automatic### ⚠️ Partially Supported

[](#️-partially-supported)

- `relative_resize` - May be imprecise (requires source dimensions)

### ❌ Not Supported

[](#-not-supported)

- `flip` - No native imgproxy support (use CSS `transform`)
- `paste` - Complex compositing not supported
- `resample` - DPI changes irrelevant for web

Usage
-----

[](#usage)

No changes to your templates are needed! All existing `imagine_filter` calls work automatically:

```
{# Works exactly as before #}

{# With responsive images #}

```

### How It Works

[](#how-it-works)

```
┌─────────────────┐
│  Twig Template  │
│  imagine_filter │
└────────┬────────┘
         │
         v
┌─────────────────────┐
│   Imgproxy Bundle   │
│  (Cache Resolver)   │
└────────┬────────────┘
         │
         v
┌─────────────────────┐      ┌──────────────┐
│  Imgproxy Server    │◄─────│  S3 / CDN    │
│  (Image Processing) │      │  (Source)    │
└────────┬────────────┘      └──────────────┘
         │
         v
┌─────────────────────┐
│   Generated URL     │
│   (Signed/Unsigned) │
└─────────────────────┘

```

**Example Generated URLs:**

```
# Without signing (development)
https://imgproxy.example.com/insecure/resize:fill:300:200/plain/s3-bucket.com/image.jpg

# With signing (production)
https://imgproxy.example.com/AbC123.../resize:fill:300:200/plain/s3-bucket.com/image.jpg

```

### Performance Benefits

[](#performance-benefits)

Using imgproxy provides significant performance improvements:

- ⚡ **Native Go Performance** - Up to 10x faster than PHP-based image processing
- 🔄 **On-the-fly Processing** - No need to pre-generate image variations
- 💾 **Reduced Storage** - Store only original images, generate variants on demand
- 🌐 **CDN Compatible** - imgproxy URLs can be cached by CDN for global distribution

Static Assets
-------------

[](#static-assets)

The bundle automatically detects and skips static assets (webpack builds, bundles):

- `/build/**` - webpack encore assets
- `/bundles/**` - Symfony bundle assets
- `/assets/**` - general static files

These are returned without imgproxy processing.

Development
-----------

[](#development)

### Setting up Development Environment

[](#setting-up-development-environment)

1. Clone the repository:

```
git clone https://github.com/3BRS/imgproxy-bundle.git
cd imgproxy-bundle
```

2. Install dependencies:

```
composer install
```

3. Start Docker environment:

```
make up
```

### Available Make Commands

[](#available-make-commands)

Run `make help` to see all available commands:

```
make install          # Install composer dependencies
make test             # Run all tests (PHPUnit + ECS + PHPStan + Deptrac)
make phpunit          # Run PHPUnit tests
make phpunit-coverage # Run tests with coverage report
make ecs              # Check code style
make ecs-fix          # Fix code style issues
make phpstan          # Run static analysis
make deptrac          # Run architecture analysis (requires PHP 8.1+)
make rector           # Check for automated refactoring opportunities
make rector-fix       # Apply automated refactorings
make audit            # Check for security vulnerabilities (optional)
make bash             # Connect to PHP container
```

Testing
-------

[](#testing)

Run the complete test suite:

```
# Run all quality checks
make test

# Or run individually
make phpunit          # Unit tests
make ecs              # Code style check
make phpstan          # Static analysis
make deptrac          # Architecture analysis (PHP 8.1+)
```

### Test Suite

[](#test-suite)

The project has comprehensive test coverage with 106 tests and 381 assertions:

```
# Run all tests
make phpunit

# Run only unit tests
make phpunit-unit

# Run only integration tests
make phpunit-integration

# Generate HTML coverage report
make phpunit-coverage

# Coverage report will be in var/coverage/index.html
```

**Test Coverage:**

- ✅ **Unit Tests** - All components (URL builder, filter converter, cache resolver)
- ✅ **Integration Tests** - Full Symfony kernel with Liip Imagine integration
- ✅ **106 tests** with **381 assertions** (100% passing)
- ✅ **Infection mutation testing** for code quality verification

### Code Modernization with Rector

[](#code-modernization-with-rector)

Rector automatically refactors code to modern PHP standards:

```
# Check for refactoring opportunities
make rector

# Apply automated improvements
make rector-fix
```

**What Rector improves:**

- ✅ Constructor property promotion (PHP 8.0+)
- ✅ Early returns for better readability
- ✅ Type declarations
- ✅ Dead code removal
- ✅ Symfony/PHPUnit best practices

**Notes:**

- Rector maintains PHP 8.0 compatibility while using modern syntax
- Rector requires PHPStan 1.x, which doesn't support PHP 8.4
- On PHP 8.4, use PHPStan 2.x instead (Rector will be unavailable)

### Security Audit

[](#security-audit)

**Note:** Security audit is primarily useful for **applications**, not libraries/bundles.

This bundle doesn't commit `composer.lock`, so the audit only checks development dependencies.

**For bundle developers:**

```
make audit  # Optional: checks dev dependencies (PHPStan, ECS, etc.)
```

**For application developers using this bundle:**

Always run security audit in your **application** to check all dependencies including this bundle:

```
# In your Symfony application
composer audit
```

The audit checks dependencies against the [PHP Security Advisories Database](https://github.com/FriendsOfPHP/security-advisories).

### Continuous Integration

[](#continuous-integration)

The project uses CircleCI to test against multiple PHP and Symfony versions:

- **PHP versions**: 8.0, 8.1, 8.2, 8.3, 8.4
- **Symfony versions**: 5.4, 6.4, 7.1
- **Dependency strategies**: `--prefer-lowest` and `--prefer-stable`

Each CI build runs:

1. **PHPUnit** - 106 tests with 381 assertions (unit + integration)
2. **ECS** - Code style checks (PSR-12)
3. **PHPStan** - Static analysis (level 8)
4. **Deptrac** - Architecture validation (PHP 8.1+ only)
5. **Rector** - Code modernization checks (PHP 8.0-8.3)
6. **Infection** - Mutation testing for code quality

**Architecture Layers:**

The project uses Deptrac to enforce clean architecture:

- **Bundle** - Main bundle class (can depend on all layers)
- **DependencyInjection** - Service configuration (can depend on Imagine)
- **Imagine** - Core business logic (independent, no external dependencies)

**Version-specific tools:**

- **PHP 8.0**: Deptrac skipped (requires PHP 8.1+)
- **PHP 8.4**: Rector skipped (PHPStan 2.x required for PHP 8.4, which conflicts with Rector 1.x)

Contributing
------------

[](#contributing)

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`make test`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Code Quality Standards

[](#code-quality-standards)

All contributions must pass our quality gates:

- **PSR-12** coding standards (enforced by ECS)
- **PHPStan level 8** static analysis
- **Deptrac** architecture validation (PHP 8.1+)
- **Rector** code modernization (optional but recommended)
- Write meaningful commit messages
- Add tests for new features

**Before submitting:**

```
make test         # Run all quality checks
make rector       # Check for refactoring opportunities
make rector-fix   # Apply automated improvements (optional)
```

License
-------

[](#license)

This project is licensed under the MIT License.

Credits
-------

[](#credits)

Developed and maintained by [3BRS](https://3brs.com)

Support
-------

[](#support)

- 🐛 [Report bugs](https://github.com/3BRS/imgproxy-bundle/issues)
- 💡 [Request features](https://github.com/3BRS/imgproxy-bundle/issues)
- 📖 [Imgproxy Documentation](https://docs.imgproxy.net/)
- 📖 [Liip Imagine Bundle Documentation](https://symfony.com/bundles/LiipImagineBundle/current/index.html)

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance66

Regular maintenance activity

Popularity16

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

201d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ab23998c28b111996e4b3357f20929d6904a97ac21724750e1dfafd6a09791e4?d=identicon)[ondrej-kuhnel](/maintainers/ondrej-kuhnel)

---

Top Contributors

[![ondrej-kuhnel](https://avatars.githubusercontent.com/u/6840281?v=4)](https://github.com/ondrej-kuhnel "ondrej-kuhnel (10 commits)")

---

Tags

symfonyimage processingSymfony Bundleliip-imagineimgproxy

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Code StyleECS

Type Coverage Yes

### Embed Badge

![Health badge](/badges/3brs-imgproxy-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/3brs-imgproxy-bundle/health.svg)](https://phpackages.com/packages/3brs-imgproxy-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[kreait/firebase-bundle

Symfony Bundle for the Firebase Admin SDK

1534.7M2](/packages/kreait-firebase-bundle)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)

PHPackages © 2026

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