Merge branch 'next' into develop

Author: olivervogel

.gitattributes

@@ -12,3 +12,5 @@
 /phpstan.dist.neon  export-ignore
 /docker-compose.yml export-ignore
 /Dockerfile         export-ignore
+/entrypoint.sh      export-ignore
+/AGENTS.md          export-ignore

.github/workflows/run-tests.yml

@@ -8,8 +8,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php: [ '8.1', '8.2', '8.3', '8.4', '8.5' ]
-        imagemagick: [ '6.9.13-25', '7.1.1-47' ]
+        php: [ '8.3', '8.4', '8.5' ]
+        imagemagick: [ '6.9.13-40', '7.1.2-15' ]
+        imagick: [ '3.8.1' ]
 
     name: PHP ${{ matrix.php }} - ImageMagick ${{ matrix.imagemagick }}
 

AGENTS.md

@@ -0,0 +1,122 @@
+# Intervention Image Agent Guide
+
+This document provides a guide for software engineering agents working on the Intervention Image codebase.
+
+## 1. Project Overview
+
+Intervention Image is a PHP image manipulation library. It provides an expressive, fluent interface to create, edit, and compose images. The library supports both the GD library and Imagick as underlying drivers.
+
+The source code is located in the `src` directory, and the project follows the PSR-4 autoloading standard.
+
+## 2. Development Environment
+
+The project uses Composer to manage dependencies. These dependencies are installed automatically when using the Docker development environment.
+
+## 3. Build, Lint, and Test Commands
+
+The following commands are used to ensure code quality and correctness.
+
+### 3.1. Testing (PHPUnit)
+
+The project uses PHPUnit for unit and feature testing.
+
+- **Run all tests:**
+  ```bash
+  docker compose run --rm tests
+  ```
+
+- **Run a single test file:**
+  To run a specific test file, provide the path to the file.
+  ```bash
+  docker compose run --rm tests tests/Unit/ImageManagerTest.php
+  ```
+
+- **Run a single test method:**
+  Use the `--filter` option to run a specific test method by its name.
+  ```bash
+  docker compose run --rm tests tests/Unit/ImageManagerTest.php --filter testMethodName
+  ```
+
+- **Check test coverage:**
+  ```bash
+  docker compose run --rm coverage
+  ```
+
+### 3.2. Static Analysis (PHPStan)
+
+PHPStan is used for static analysis to find potential bugs.
+
+- **Run static analysis:**
+  ```bash
+  docker compose run --rm analysis
+  ```
+
+### 3.3. Coding Standards (PHP CodeSniffer)
+
+The project adheres to the PSR-12 coding standard with additional rules. PHP CodeSniffer is used to enforce these standards.
+
+- **Check for coding standard violations:**
+  ```bash
+  docker compose run --rm standards
+  ```
+
+## 4. Code Style and Conventions
+
+Consistency is key. Adhere to the following guidelines when writing code.
+
+### 4.1. Formatting
+
+- **PSR-12:** The primary coding standard is PSR-12.
+- **Indentation:** Use 4 spaces for indentation, not tabs.
+- **Line Endings:** Use Unix-style line endings (LF).
+- **Strict Types:** All PHP files must start with `declare(strict_types=1);`.
+- **Class Structure:** Follow the ordering defined in `phpcs.xml.dist`:
+    1. `uses`
+    2. `enum cases`
+    3. `constants`
+    4. `static properties`
+    5. `properties`
+    6. `constructor`
+    7. `static constructors`
+    8. `methods`
+    9. `magic methods`
+
+### 4.2. Naming Conventions
+
+- **Classes:** `PascalCase`.
+- **Methods:** `camelCase`.
+- **Variables:** `camelCase`.
+- **Constants:** `UPPER_CASE` with underscore separators.
+- **File Names:** File names must match the class name they contain (e.g., `MyClass.php` for `class MyClass`).
+
+### 4.3. Imports
+
+- **One class per `use` statement:** Do not group multiple classes in a single `use` statement.
+- **No leading backslash:** `use` statements must not start with a backslash.
+- **Order:** `use` statements should be ordered alphabetically. Unused imports must be removed.
+
+### 4.4. Types and Type Hinting
+
+- **Strict Typing:** All code should be strictly typed.
+- **Parameter Types:** All method parameters must have a type hint.
+- **Return Types:** All methods must have a return type hint.
+- **Property Types:** All class properties must have a type hint.
+- **Nullable Types:** Use nullable types (`?TypeName`) when a `null` value is explicitly allowed.
+
+### 4.5. Error Handling
+
+- Exceptions should be used for error handling.
+- When catching exceptions, be as specific as possible. Avoid catching generic `\Exception` or `\Throwable`.
+- Exception messages should be clear and descriptive.
+
+### 4.6. PHPDoc (DocBlocks)
+
+- PHPDoc blocks are required for all classes, properties, and methods.
+- Follow the annotation order defined in `phpcs.xml.dist`.
+- Use DocBlocks to provide context and explain complex logic. Do not restate the obvious from the code signature.
+
+## 5. Branching and Commits
+
+- **Branching:** Create new branches from the `develop` branch. Name branches descriptively (e.g., `feature/new-filter`, `bugfix/fix-resize-issue`).
+- **Commits:** Write clear and concise commit messages. The first line should be a short summary (max 50 chars). A more detailed explanation can follow after a blank line. Always write the message in imperative and do NOT use any useless prefixes like "chore" or other.
+- **Pull Requests:** Target the `develop` branch for all pull requests. Ensure all checks (tests, linting, analysis) are passing before submitting.

Dockerfile

@@ -1,28 +1,53 @@
-FROM php:8.1-cli
+FROM php:8.3-cli
 
-# install dependencies
+ARG IMAGEMAGICK_VERSION=7.1.2-15
+
+# install dependencies for building ImageMagick and PHP extensions
 RUN apt update \
         && apt install -y \
-            libmagickwand-dev \
-            libwebp-dev \
+            libjpeg-dev \
+            libgif-dev \
+            libtiff-dev \
             libpng-dev \
+            libwebp-dev \
             libavif-dev \
+            libheif-dev \
+            libraqm-dev \
+            libopenjp2-7-dev \
+            liblcms2-dev \
             git \
             zip \
-        && pecl install imagick \
+            curl \
+            xz-utils \
+        && apt-get clean
+
+# build and install ImageMagick from source
+RUN curl -o /tmp/ImageMagick.tar.xz -sL \
+        "https://imagemagick.org/archive/releases/ImageMagick-${IMAGEMAGICK_VERSION}.tar.xz" \
+        && cd /tmp \
+        && tar xf ImageMagick.tar.xz \
+        && cd "ImageMagick-${IMAGEMAGICK_VERSION}" \
+        && ./configure \
+        && make -j$(nproc) \
+        && make install \
+        && ldconfig \
+        && cd / \
+        && rm -rf /tmp/ImageMagick*
+
+# install PHP extensions
+RUN pecl install imagick \
         && pecl install xdebug \
         && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp --with-avif \
         && docker-php-ext-enable \
             imagick \
             xdebug \
         && docker-php-ext-install \
             gd \
-            exif \
-        && apt-get clean
+            exif
 
 # install composer
 COPY --from=composer /usr/bin/composer /usr/bin/composer
 
-# install composer dependencies
-COPY composer.json composer.lock ./
-RUN composer install
+# setup entrypoint
+COPY entrypoint.sh /usr/local/bin/entrypoint.sh
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

composer.json

@@ -19,12 +19,12 @@
         }
     ],
     "require": {
-        "php": "^8.1",
+        "php": "^8.3",
         "ext-mbstring": "*",
-        "intervention/gif": "^4.2"
+        "intervention/gif": "^5"
     },
     "require-dev": {
-        "phpunit/phpunit": "^10.0 || ^11.0 || ^12.0",
+        "phpunit/phpunit": "^12.0",
         "mockery/mockery": "^1.6",
         "phpstan/phpstan": "^2.1",
         "squizlabs/php_codesniffer": "^4",

docker-compose.yml

@@ -2,26 +2,26 @@ services:
   tests:
     build: ./
     working_dir: /project
-    entrypoint: ["./vendor/bin/phpunit"]
+    entrypoint: ["/usr/local/bin/entrypoint.sh", "./vendor/bin/phpunit"]
     volumes:
       - ./:/project
   coverage:
     build: ./
     working_dir: /project
-    entrypoint: ["./vendor/bin/phpunit", "--coverage-text"]
+    entrypoint: ["/usr/local/bin/entrypoint.sh", "./vendor/bin/phpunit", "--coverage-text"]
     volumes:
       - ./:/project
     environment:
       - XDEBUG_MODE=coverage
   analysis:
     build: ./
     working_dir: /project
-    entrypoint: ["./vendor/bin/phpstan", "analyze", "--memory-limit=512M"]
+    entrypoint: ["/usr/local/bin/entrypoint.sh", "./vendor/bin/phpstan", "analyze", "--memory-limit=512M"]
     volumes:
       - ./:/project
   standards:
     build: ./
     working_dir: /project
-    entrypoint: ["./vendor/bin/phpcs"]
+    entrypoint: ["/usr/local/bin/entrypoint.sh", "./vendor/bin/phpcs"]
     volumes:
       - ./:/project

entrypoint.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+set -e
+
+composer install --quiet
+
+exec "$@"

phpstan.dist.neon

@@ -2,15 +2,3 @@ parameters:
     level: 6
     paths:
         - src
-    reportUnmatchedIgnoredErrors: false
-    ignoreErrors:
-        - 
-            identifier: unset.possiblyHookedProperty
-    exceptions:
-        check:
-            missingCheckedExceptionInThrows: true
-        uncheckedExceptionClasses:
-            - ImagickException
-            - ImagickDrawException
-            - ImagickPixelException
-            - Error

phpunit.dist.xml

@@ -9,6 +9,9 @@
     cacheDirectory=".phpunit.cache" 
     colors="true" 
     displayDetailsOnTestsThatTriggerNotices="true"
+    displayDetailsOnTestsThatTriggerDeprecations="true"
+    displayDetailsOnPhpunitDeprecations="true"
+    displayDetailsOnTestsThatTriggerWarnings="true"
     processIsolation="false" 
     stopOnFailure="false">
   <testsuites>

readme.md

@@ -8,51 +8,51 @@
 
 Intervention Image is a **PHP image processing library** that provides a simple
 and expressive way to create, edit, and compose images. It comes with a universal
-interface for the two most popular PHP image manipulation extensions. You can
-choose between the GD library or Imagick as the base layer for all operations.
+interface for the popular PHP image manipulation extensions. You can
+choose between the GD library, Imagick or libvips as the base layer for all operations.
 
-- Simple interface for common image editing tasks
-- Interchangeable driver architecture
-- Support for animated images
+- Fluent interface for common image editing tasks
+- Interchangeable driver architecture with support for **GD, Imagick and libvips**
+- Support for animated images with all drivers
 - Framework-agnostic
-- PSR-12 compliant
 
 ## Installation
 
-You can easily install this library using [Composer](https://getcomposer.org).
-Simply request the package with the following command:
+Install this library using [Composer](https://getcomposer.org). Simply request the package with the following command:
 
 ```bash
 composer require intervention/image
 ```
 
 ## Getting Started
 
-Learn the [basics](https://image.intervention.io/v3/basics/instantiation/) on
-how to use Intervention Image and more with the [official
-documentation](https://image.intervention.io/v3/).
+Learn the [basics](https://image.intervention.io/v4/basics/instantiation/) on
+how to use Intervention Image and more with the [official documentation](https://image.intervention.io/v4/).
 
 ## Code Examples
 
 ```php
 use Intervention\Image\ImageManager;
+use Intervention\Image\Drivers\Gd\Driver as GdDriver;
+use Intervention\Image\Alignment;
+use Intervention\Image\Color;
+use Intervention\Image\Format;
+use Intervention\Image\Fraction;
 
-// create image manager with desired driver
-$manager = new ImageManager(
-    new Intervention\Image\Drivers\Gd\Driver()
-);
+// create image manager instance using the preferred driver
+$manager = ImageManager::usingDriver(GdDriver::class);
 
-// open an image file
-$image = $manager->read('images/example.gif');
+// read image data from path
+$image = $manager->decodePath('images/example.webp');
 
-// resize image instance
-$image->resize(height: 300);
+// scale image by height
+$image->scale(height: 300);
 
 // insert a watermark
-$image->place('images/watermark.png');
+$image->insert('images/watermark.png', alignment: Alignment::BOTTOM_RIGHT);
 
 // encode edited image
-$encoded = $image->toJpg();
+$encoded = $image->encodeUsingFormat(Format::JPEG, quality: 65);
 
 // save encoded image
 $encoded->save('images/example.jpg');
@@ -63,9 +63,9 @@ $encoded->save('images/example.jpg');
 Before you begin with the installation make sure that your server environment
 supports the following requirements.
 
-- PHP >= 8.1
+- PHP >= 8.3
 - Mbstring PHP Extension
-- Image Processing PHP Extension
+- Image Processing PHP Extension (GD, Imagick or libvips)
 
 ## Supported Image Libraries