Options

Immutable configuration value objects for loading, saving, and text rendering.

---

LoadOptions

Options controlling how an image is loaded from disk or buffer. Immutable — use with* methods to derive variants.

final class LoadOptions

Constructor

public function __construct(
    public readonly ?int $page = null,
    public readonly ?int $n = null,
    public readonly bool $autoRotate = true,
    public readonly ?int $shrink = null,
    public readonly ?float $scale = null,
)

Properties

Property	Type	Default	Description
$page	?int	null	Page number to load (for multipage formats like TIFF)
$n	?int	null	Number of pages to load
$autoRotate	bool	true	Whether to auto-rotate based on EXIF orientation
$shrink	?int	null	Shrink-on-load factor (integer downscale)
$scale	?float	null	Scale-on-load factor (float downscale)

Static Methods

default()

Creates a LoadOptions with all defaults.

public static function default(): self

Mutator Methods

Each returns a new instance with the modified property.

withPage()

Set the page (zero-based) to load for multi-page formats.

public function withPage(int $page): self

withN()

Set the number of pages to load.

public function withN(int $n): self

withAutoRotate()

Enable or disable auto-rotation based on EXIF orientation.

public function withAutoRotate(bool $autoRotate): self

withShrink()

Set the shrink-on-load factor (integer downscale).

public function withShrink(int $factor): self

withScale()

Set the scale-on-load factor (float downscale).

public function withScale(float $scale): self

Internal Methods

toVipsOptions()

Convert to a VIPS-compatible options array.

public function toVipsOptions(): array

Returns: Associative array for VIPS newFromFile / newFromBuffer options.

Usage

use PhpMlKit\Opal\Image;
use PhpMlKit\Opal\LoadOptions;

// Default loading
$img = Image::fromFile('photo.jpg');

// Load second page of a TIFF
$options = (new LoadOptions())->withPage(1);
$tiffPage = Image::fromFile('multi-page.tif', $options);

// Load with shrink-on-load (faster thumbnails)
$options = LoadOptions::default()
    ->withShrink(2)
    ->withAutoRotate(false);
$img = Image::fromFile('large.jpg', $options);

---

SaveOptions

Options controlling how an image is saved. Format-specific. Use one of the static factory methods to get a pre-configured instance.

final class SaveOptions

Static Factory Methods

jpeg()

public static function jpeg(
    int $quality = 85,
    bool $strip = true,
    bool $progressive = false,
): self

Parameter	Type	Default	Description
$quality	int	85	JPEG quality (0–100)
$strip	bool	true	Remove metadata
$progressive	bool	false	Enable progressive JPEG

png()

public static function png(
    int $compression = 6,
    bool $strip = true,
    bool $interlace = false,
): self

Parameter	Type	Default	Description
$compression	int	6	PNG compression level (0–9)
$strip	bool	true	Remove metadata
$interlace	bool	false	Enable Adam7 interlacing

webp()

public static function webp(
    int $quality = 80,
    bool $lossless = false,
    bool $strip = true,
): self

Parameter	Type	Default	Description
$quality	int	80	WebP quality (0–100)
$lossless	bool	false	Enable lossless compression
$strip	bool	true	Remove metadata

tiff()

public static function tiff(int $quality = 75, bool $strip = false): self

Parameter	Type	Default	Description
$quality	int	75	TIFF quality
$strip	bool	false	Remove metadata

avif()

public static function avif(int $quality = 50, int $speed = 5): self

Parameter	Type	Default	Description
$quality	int	50	AVIF quality (0–100)
$speed	int	5	Encoding speed (0=slow/best, 8=fast/worst)

heif()

public static function heif(int $quality = 50): self

Parameter	Type	Default	Description
$quality	int	50	HEIF quality (0–100)

Mutator Methods

withQuality()

Set the encoding quality (0–100).

public function withQuality(int $quality): self

withStrip()

Set whether to strip metadata on save.

public function withStrip(bool $strip): self

Internal Methods

toVipsOptions()

Convert to a VIPS-compatible options array.

public function toVipsOptions(): array

Usage

use PhpMlKit\Opal\Image;
use PhpMlKit\Opal\SaveOptions;

$img = Image::fromFile('input.jpg');

// Save as JPEG with high quality
$img->toFile('output.jpg', SaveOptions::jpeg(quality: 95));

// Save as lossless WebP
$img->toFile('output.webp', SaveOptions::webp(lossless: true));

// Encode to PNG buffer with custom compression
$png = $img->toBuffer(
    ImageFormat::PNG,
    SaveOptions::png(compression: 9, interlace: true)
);

---

TextOptions

Options controlling how text is rendered. Immutable — use with* methods to derive variants.

final class TextOptions

Constructor

public function __construct(
    public readonly ?string $font = null,
    public readonly ?string $fontFile = null,
    public readonly ?int $fontSize = null,
    public readonly ?int $width = null,
    public readonly ?int $height = null,
    public readonly ?string $align = null,
    public readonly ?bool $justify = null,
    public readonly ?int $dpi = null,
    public readonly ?bool $rgba = null,
    public readonly ?int $spacing = null,
    public readonly ?string $wrap = null,
)

Properties

Property	Type	Default	Description
$font	?string	null	Font family name (e.g. 'sans-serif', 'serif', 'monospace')
$fontFile	?string	null	Path to a custom font file
$fontSize	?int	12	Font size in points
$width	?int	null	Maximum width in pixels for text wrapping
$height	?int	null	Maximum height in pixels
$align	?string	null	Text alignment ('left', 'centre', 'right')
$justify	?bool	null	Whether to justify text
$dpi	?int	null	Rendering resolution in DPI
$rgba	?bool	null	Whether to render as RGBA
$spacing	?int	null	Line spacing in points
$wrap	?string	null	Wrapping mode ('word', 'char', 'word-char')

Static Methods

default()

public static function default(): self

Creates a TextOptions with font size 12 and all other values as null.

Mutator Methods

Each returns a new instance with the modified property.

withFont()

Set the font family or Pango font description.

public function withFont(string $font): self

withFontfile()

Set a custom font file path (.ttf or .otf).

public function withFontFile(string $fontFile): self

withFontSize()

Set the font size in points.

public function withFontSize(int $fontSize): self

withWidth()

Set the maximum text block width in pixels.

public function withWidth(int $width): self

withHeight()

Set the maximum text block height in pixels.

public function withHeight(int $height): self

withAlign()

Set alignment: 'left', 'centre', or 'right'.

public function withAlign(string $align): self

withJustify()

Enable or disable text justification.

public function withJustify(bool $justify): self

withDpi()

Set rendering resolution in DPI.

public function withDpi(int $dpi): self

withRgba()

Enable RGBA rendering for transparent backgrounds.

public function withRgba(bool $rgba = true): self

withSpacing()

Set line spacing in points.

public function withSpacing(int $spacing): self

withWrap()

Set wrapping mode: 'word', 'char', or 'word-char'.

public function withWrap(string $wrap): self

Internal Methods

toVipsOptions()

Convert to a VIPS-compatible options array.

public function toVipsOptions(): array

Returns: Associative array for VIPS text operation options.

Usage

use PhpMlKit\Opal\Image;
use PhpMlKit\Opal\TextOptions;

// Create a text image with defaults
$textImg = Image::text('Hello World');

// Custom text rendering
$options = TextOptions::default()
    ->withFont('sans-serif')
    ->withFontSize(48)
    ->withWidth(800)
    ->withAlign('centre')
    ->withDpi(300);

$textImg = Image::text('Hello World', $options);

// Draw text onto an existing image
$img = Image::fromFile('photo.jpg');
$img = $img->drawText('Hello', 100, 200, color: Color::white(), options: $options);