Oihana PHP System

AspectRatio

Represents and manages a 2D aspect ratio.

This class stores a width and height pair and optionally enforces a locked aspect ratio behavior.

When the ratio is unlocked:

  • Changing the width does not affect the height.
  • Changing the height does not affect the width.
  • The internal aspect ratio is recalculated automatically.

When the ratio is locked:

  • Changing the width automatically recalculates the height.
  • Changing the height automatically recalculates the width.
  • The simplified aspect ratio captured at lock time is preserved and is not re-derived from rounded dimensions.

The aspect ratio is internally simplified using the Greatest Common Divisor (GCD).

Example:

use oihana\graphics\AspectRatio;

// Create a new unlocked aspect ratio
$ratio = new AspectRatio(1920, 1080);

echo $ratio->width  . PHP_EOL; // 1920
echo $ratio->height . PHP_EOL; // 1080
echo $ratio->ratio();          // 16:9

// Since the ratio is unlocked,
// changing the width does not affect the height.

$ratio->width = 1280;

echo $ratio->width  . PHP_EOL; // 1280
echo $ratio->height . PHP_EOL; // 1080
echo $ratio->ratio();          // 32:27

// ----------------------------------------------------------------

// Create a locked aspect ratio.

$locked = new AspectRatio(1920, 1080, true);

echo $locked->ratio(); // 16:9

// Changing the width automatically updates the height.

$locked->width = 1280;

echo $locked->width  . PHP_EOL; // 1280
echo $locked->height . PHP_EOL; // 720

// Changing the height automatically updates the width.

$locked->height = 900;

echo $locked->width  . PHP_EOL; // 1600
echo $locked->height . PHP_EOL; // 900

// ----------------------------------------------------------------

// Lock an existing ratio.

$ratio->lock();

$ratio->height = 900;

echo $ratio->width  . PHP_EOL; // 1067
echo $ratio->height . PHP_EOL; // 900
Tags
author

Oihana

copyright

Oihana

license

MIT

version
1.1.0

Table of Contents

Constants

ASPECT_HEIGHT  : string = 'aspectHeight'
The 'aspectHeight' component expression.
ASPECT_WIDTH  : string = 'aspectWidth'
The 'aspectWidth' component expression.
HEIGHT  : string = 'height'
The 'height' component expression.
LOCKED  : string = 'locked'
The 'locked' component expression.
RATIO  : string = 'ratio'
The 'ratio' component expression.
WIDTH  : string = 'width'
The 'width' component expression.

Properties

$aspectHeight  : int
Returns the simplified aspect ratio height component.
$aspectWidth  : int
Returns the simplified aspect ratio width component.
$gcd  : int
Gets the current Greatest Common Divisor (GCD).
$height  : int
Gets or sets the current height.
$locked  : bool
Indicates whether the aspect ratio is currently locked.
$width  : int
Gets or sets the current width.
$_height  : int
Current height.
$_width  : int
Current width.
$_aspH  : int
Simplified aspect ratio height component.
$_aspW  : int
Simplified aspect ratio width component.
$_gcd  : int
Greatest Common Divisor.
$_locked  : bool
Indicates whether the ratio is locked.

Methods

__construct()  : mixed
Creates a new AspectRatio instance.
__toString()  : string
Returns a string representation of the dimensions and ratio.
fromRatio()  : self
Creates an AspectRatio instance from a simplified ratio.
lock()  : $this
Locks the current aspect ratio.
ratio()  : string
Returns the simplified ratio as a string.
setHeight()  : void
Updates the height.
setWidth()  : void
Updates the width.
toArray()  : array<string, mixed>
Returns the current dimensions as an associative array.
unlock()  : $this
Unlocks the aspect ratio.
assertDimension()  : void
Validates a dimension value (non-negative).
assertPositive()  : void
Validates that an integer is strictly positive.
hasValidRatio()  : bool
Indicates whether the ratio can safely be used for proportional calculations.
recalculateRatio()  : void
Recalculates the simplified aspect ratio.
synchronizeHeight()  : void
Synchronizes the height from the current width.
synchronizeWidth()  : void
Synchronizes the width from the current height.

Constants

ASPECT_HEIGHT

The 'aspectHeight' component expression.

public string ASPECT_HEIGHT = 'aspectHeight'

ASPECT_WIDTH

The 'aspectWidth' component expression.

public string ASPECT_WIDTH = 'aspectWidth'

HEIGHT

The 'height' component expression.

public string HEIGHT = 'height'

LOCKED

The 'locked' component expression.

public string LOCKED = 'locked'

RATIO

The 'ratio' component expression.

public string RATIO = 'ratio'

WIDTH

The 'width' component expression.

public string WIDTH = 'width'

Properties

$aspectHeight read-only virtual

Returns the simplified aspect ratio height component.

public int $aspectHeight

Example:

$ratio = new AspectRatio(1920, 1080);

echo $ratio->aspectHeight; // 9
Hooks
public int get

$aspectWidth read-only virtual

Returns the simplified aspect ratio width component.

public int $aspectWidth

Example:

$ratio = new AspectRatio(1920, 1080);

echo $ratio->aspectWidth; // 16
Hooks
public int get

$gcd read-only virtual

Gets the current Greatest Common Divisor (GCD).

public int $gcd

The GCD is used internally to simplify the ratio.

When the ratio is locked, the GCD reflects the value computed at lock time and is not refreshed on subsequent dimension changes.

Example:

$ratio = new AspectRatio(1920, 1080);

echo $ratio->gcd; // 120
Hooks
public int get

$height virtual

Gets or sets the current height.

public int $height

When the aspect ratio is locked, updating the height automatically recalculates the width to preserve the current ratio.

When unlocked, the aspect ratio is recalculated instead.

Tags
throws
InvalidArgumentException

If the height is negative.

Hooks
public int get public set

$locked read-only virtual

Indicates whether the aspect ratio is currently locked.

public bool $locked

Example:

$ratio = new AspectRatio(1920, 1080, true);

echo $ratio->locked; // true
Hooks
public bool get

$width virtual

Gets or sets the current width.

public int $width

When the aspect ratio is locked, updating the width automatically recalculates the height to preserve the current ratio.

When unlocked, the aspect ratio is recalculated instead.

Tags
throws
InvalidArgumentException

If the width is negative.

Hooks
public int get public set

$_height

Current height.

protected int $_height = 0

$_aspH

Simplified aspect ratio height component.

private int $_aspH = 0

$_aspW

Simplified aspect ratio width component.

private int $_aspW = 0

$_gcd

Greatest Common Divisor.

private int $_gcd = 1

$_locked

Indicates whether the ratio is locked.

private bool $_locked = false

Methods

__construct()

Creates a new AspectRatio instance.

public __construct([int $width = 0 ][, int $height = 0 ][, bool $lock = false ]) : mixed
Parameters
$width : int = 0

The initial width.

$height : int = 0

The initial height.

$lock : bool = false

Indicates whether the ratio must be locked.

Tags
throws
InvalidArgumentException

If width or height is negative.

__toString()

Returns a string representation of the dimensions and ratio.

public __toString() : string

Example:

$ratio = new AspectRatio(1920, 1080);

echo $ratio;

// 1920x1080 (16:9)
Return values
string

fromRatio()

Creates an AspectRatio instance from a simplified ratio.

public static fromRatio(int $aspectWidth, int $aspectHeight, int $width[, bool $lock = true ]) : self

Example:

$ratio = AspectRatio::fromRatio(16, 9, 1920);

echo $ratio; // 1920x1080 (16:9)
Parameters
$aspectWidth : int

The ratio width component. Must be greater than 0.

$aspectHeight : int

The ratio height component. Must be greater than 0.

$width : int

The desired width. Must be greater than 0.

$lock : bool = true

Indicates whether the ratio should be locked.

Tags
throws
InvalidArgumentException

If any of $aspectWidth, $aspectHeight or $width is not positive.

Return values
self

lock()

Locks the current aspect ratio.

public lock() : $this

Once locked:

  • Updating the width automatically updates the height.
  • Updating the height automatically updates the width.

The current simplified ratio becomes the preserved ratio.

Return values
$this

ratio()

Returns the simplified ratio as a string.

public ratio() : string

Example:

$ratio = new AspectRatio(1920, 1080);

echo $ratio->ratio(); // 16:9
Return values
string

setHeight()

Updates the height.

public setHeight(int $height) : void

When the ratio is locked, the width is synchronized from the snapshot aspect ratio and the snapshot is preserved.

When unlocked, the aspect ratio is recalculated from the new width/height pair.

Parameters
$height : int
Tags
throws
InvalidArgumentException

If the height is negative.

setWidth()

Updates the width.

public setWidth(int $width) : void

When the ratio is locked, the height is synchronized from the snapshot aspect ratio and the snapshot is preserved.

When unlocked, the aspect ratio is recalculated from the new width/height pair.

Parameters
$width : int
Tags
throws
InvalidArgumentException

If the width is negative.

toArray()

Returns the current dimensions as an associative array.

public toArray() : array<string, mixed>

Example:

$ratio = new AspectRatio(1920, 1080);

print_r($ratio->toArray());

// [
//     'width'       => 1920,
//     'height'      => 1080,
//     'aspectWidth' => 16,
//     'aspectHeight'=> 9,
//     'ratio'       => '16:9',
//     'locked'      => false
// ]
Return values
array<string, mixed>

unlock()

Unlocks the aspect ratio.

public unlock() : $this

Once unlocked:

  • Width and height become independent.
  • The aspect ratio is recalculated after each modification.
Return values
$this

assertDimension()

Validates a dimension value (non-negative).

private assertDimension(int $value, string $name) : void
Parameters
$value : int
$name : string
Tags
throws
InvalidArgumentException

assertPositive()

Validates that an integer is strictly positive.

private static assertPositive(int $value, string $name) : void
Parameters
$value : int
$name : string
Tags
throws
InvalidArgumentException

hasValidRatio()

Indicates whether the ratio can safely be used for proportional calculations.

private hasValidRatio() : bool
Return values
bool

recalculateRatio()

Recalculates the simplified aspect ratio.

private recalculateRatio() : void

Internally updates:

  • Greatest Common Divisor (GCD)
  • Simplified width ratio
  • Simplified height ratio

synchronizeHeight()

Synchronizes the height from the current width.

private synchronizeHeight() : void

synchronizeWidth()

Synchronizes the width from the current height.

private synchronizeWidth() : void
On this page

Search results