ndrstmr/icap-flow

State-of-the-art, async-ready ICAP client for PHP.

v1.0.0 2025-06-18 22:36 UTC

Requires

• php: >=8.3
• amphp/socket: ^2.3

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.75
• mockery/mockery: ^1.6
• pestphp/pest: ^3.8
• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^11.2

EUPL-1.2

• ndrstmr

README

icap-flow

A modern, robust, and async-ready ICAP (Internet Content Adaptation Protocol) client for PHP 8.3+.

Project Vision

This library aims to be the de-facto standard solution for PHP developers needing ICAP connectivity, focusing on quality, performance, and an excellent developer experience. For more details, see our mission charter.

Installation

composer require ndrstmr/icap-flow

Basic Usage

For most projects, the SynchronousIcapClient offers a very simple, blocking API.

$icap = SynchronousIcapClient::create();

$result = $icap->scanFile('/service', '/path/to/your/file.txt');

echo $result->isInfected()
    ? 'Virus found: ' . $result->getVirusName()
    : 'File is clean';

Advanced Usage: Asynchronous Requests

To take advantage of non-blocking I/O, interact with the IcapClient directly within an event loop:

use Revolt\EventLoop;

$icap = IcapClient::create();

EventLoop::run(function () use ($icap) {
    $future = $icap->scanFile('/service', '/path/to/your/file.txt');
    $result = $future->await();

    echo $result->isInfected()
        ? 'Virus: ' . $result->getVirusName() . PHP_EOL
        : 'File is clean' . PHP_EOL;
});

Configuration

Adjust the connection settings using the Config DTO:

use Ndrstmr\Icap\Config;

$config = new Config(
    host: 'icap.example.com',
    port: 1344,
    socketTimeout: 5.0,
    streamTimeout: 30.0,
    // Header used by the ICAP server to report infections
    virusFoundHeader: 'X-Virus-Name',
);

This object can be passed to the client factory methods.

Extensibility (Cookbook)

Preview handling uses the Strategy pattern. Custom strategies implement PreviewStrategyInterface and can be registered on the client. Detailed examples can be found in the examples/cookbook/ directory.

For Developers

Run the test suite with the following command:

composer test

Further details about the pull request workflow can be found in CONTRIBUTING.md.

License

This project is licensed under the EUPL-1.2 License. See the LICENSE file for details.

Changelog

A list of all changes can be found in CHANGELOG.md.