auto-alt-text / src / App / Domain / ValueObjects / AltText.php

AltText.php in Auto Alt Text trunk, at src/App/Domain/ValueObjects/AltText.php

153 lines 3.5 KB

Raw Download Zip

1	<?php
2
3	namespace AATXT\App\Domain\ValueObjects;
4
5	use InvalidArgumentException;
6
7	/**
8	* Value Object representing alt text for an image.
9	*
10	* This immutable object ensures that alt text values are properly
11	* validated and constrained to reasonable lengths for SEO purposes.
12	*/
13	final class AltText
14	{
15	/**
16	* Maximum recommended length for alt text (SEO best practice)
17	*/
18	public const MAX_LENGTH = 125;
19
20	/**
21	* The alt text value
22	*
23	* @var string
24	*/
25	private $value;
26
27	/**
28	* Private constructor to enforce factory method usage.
29	*
30	* @param string $value The alt text
31	*/
32	private function __construct(string $value)
33	{
34	$this->value = trim($value);
35	}
36
37	/**
38	* Create an AltText from a string value.
39	*
40	* @param string $value The alt text string
41	* @return self
42	*/
43	public static function fromString(string $value): self
44	{
45	return new self($value);
46	}
47
48	/**
49	* Create an empty AltText.
50	*
51	* @return self
52	*/
53	public static function empty(): self
54	{
55	return new self('');
56	}
57
58	/**
59	* Get the string value of the alt text.
60	*
61	* @return string
62	*/
63	public function toString(): string
64	{
65	return $this->value;
66	}
67
68	/**
69	* Create a new AltText truncated to the specified length.
70	*
71	* If the alt text is already shorter than the specified length,
72	* returns the same instance.
73	*
74	* @param int $length Maximum length (defaults to MAX_LENGTH)
75	* @return self New truncated AltText instance
76	* @throws InvalidArgumentException If length is not positive
77	*/
78	public function truncate(int $length = self::MAX_LENGTH): self
79	{
80	if ($length <= 0) {
81	throw new InvalidArgumentException(
82	sprintf('Truncate length must be positive, got: %d', $length)
83	);
84	}
85
86	if (mb_strlen($this->value) <= $length) {
87	return $this;
88	}
89
90	// Truncate at word boundary if possible
91	$truncated = mb_substr($this->value, 0, $length);
92	$lastSpace = mb_strrpos($truncated, ' ');
93
94	if ($lastSpace !== false && $lastSpace > $length * 0.8) {
95	// Only truncate at word boundary if we're not losing too much text
96	$truncated = mb_substr($truncated, 0, $lastSpace);
97	}
98
99	return new self($truncated);
100	}
101
102	/**
103	* Check if the alt text is empty.
104	*
105	* @return bool True if empty or whitespace-only
106	*/
107	public function isEmpty(): bool
108	{
109	return $this->value === '';
110	}
111
112	/**
113	* Check if the alt text exceeds the recommended maximum length.
114	*
115	* @return bool True if exceeds MAX_LENGTH
116	*/
117	public function exceedsMaxLength(): bool
118	{
119	return mb_strlen($this->value) > self::MAX_LENGTH;
120	}
121
122	/**
123	* Get the length of the alt text.
124	*
125	* @return int Character count
126	*/
127	public function length(): int
128	{
129	return mb_strlen($this->value);
130	}
131
132	/**
133	* Check if this AltText equals another AltText.
134	*
135	* @param AltText $other The other AltText to compare
136	* @return bool True if equal, false otherwise
137	*/
138	public function equals(AltText $other): bool
139	{
140	return $this->value === $other->value;
141	}
142
143	/**
144	* String representation.
145	*
146	* @return string
147	*/
148	public function __toString(): string
149	{
150	return $this->value;
151	}
152	}
153