Add TrueStandard and FalseStandard classes with tryFromString and tryFromInt methods

- Implemented `TrueStandard` and `FalseStandard` to represent literal boolean values.
- Added `tryFromString` and `tryFromInt` methods returning `Undefined` for invalid inputs.
- Updated `Usage` examples to demonstrate new methods and their behavior for both branches.
- Included comprehensive unit tests to validate `tryFromString`, `tryFromInt`, `fromString`, `fromInt`, and `__toString` behaviors.

Author: georgedeploy

src/Bool/FalseStandard.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Bool;
+
+use PhpTypedValues\Abstract\Bool\BoolType;
+use PhpTypedValues\Exception\BoolTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+use function sprintf;
+use function strtolower;
+use function trim;
+
+/**
+ * Represents a literal boolean false value.
+ *
+ * Accepts common false-like representations in factories:
+ *  - Strings: "false", "0", "no", "off", "n" (case-insensitive)
+ *  - Ints: 0
+ *
+ * @psalm-immutable
+ */
+readonly class FalseStandard extends BoolType
+{
+    protected false $value;
+
+    /**
+     * @throws BoolTypeException
+     */
+    public function __construct(bool $value)
+    {
+        if ($value !== false) {
+            throw new BoolTypeException('Expected false literal, got "true"');
+        }
+
+        $this->value = false;
+    }
+
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        try {
+            return static::fromInt($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    /**
+     * @throws BoolTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        $v = strtolower(trim($value));
+        if ($v === 'false' || $v === '0' || $v === 'no' || $v === 'off' || $v === 'n') {
+            return new static(false);
+        }
+
+        throw new BoolTypeException(sprintf('Expected string representing false, got "%s"', $value));
+    }
+
+    /**
+     * @throws BoolTypeException
+     */
+    public static function fromInt(int $value): static
+    {
+        if ($value === 0) {
+            return new static(false);
+        }
+
+        throw new BoolTypeException(sprintf('Expected int "0" for false, got "%s"', $value));
+    }
+
+    public function value(): bool
+    {
+        return $this->value;
+    }
+}

src/Bool/TrueStandard.php

@@ -0,0 +1,88 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpTypedValues\Bool;
+
+use PhpTypedValues\Abstract\Bool\BoolType;
+use PhpTypedValues\Exception\BoolTypeException;
+use PhpTypedValues\Exception\TypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+use function sprintf;
+use function strtolower;
+use function trim;
+
+/**
+ * Represents a literal boolean true value.
+ *
+ * Accepts common true-like representations in factories:
+ *  - Strings: "true", "1", "yes", "on", "y" (case-insensitive)
+ *  - Ints: 1
+ *
+ * @psalm-immutable
+ */
+readonly class TrueStandard extends BoolType
+{
+    protected bool $value;
+
+    /**
+     * @throws BoolTypeException
+     */
+    public function __construct(bool $value)
+    {
+        if ($value !== true) {
+            throw new BoolTypeException('Expected true literal, got "false"');
+        }
+
+        $this->value = true;
+    }
+
+    public static function tryFromString(string $value): static|Undefined
+    {
+        try {
+            return static::fromString($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    public static function tryFromInt(int $value): static|Undefined
+    {
+        try {
+            return static::fromInt($value);
+        } catch (TypeException) {
+            return Undefined::create();
+        }
+    }
+
+    /**
+     * @throws BoolTypeException
+     */
+    public static function fromString(string $value): static
+    {
+        $v = strtolower(trim($value));
+        if ($v === 'true' || $v === '1' || $v === 'yes' || $v === 'on' || $v === 'y') {
+            return new static(true);
+        }
+
+        throw new BoolTypeException(sprintf('Expected string representing true, got "%s"', $value));
+    }
+
+    /**
+     * @throws BoolTypeException
+     */
+    public static function fromInt(int $value): static
+    {
+        if ($value === 1) {
+            return new static(true);
+        }
+
+        throw new BoolTypeException(sprintf('Expected int "1" for true, got "%s"', $value));
+    }
+
+    public function value(): bool
+    {
+        return $this->value;
+    }
+}

src/Usage/Boolean.php

@@ -3,7 +3,10 @@
 use PhpTypedValues\Abstract\Bool\BoolTypeInterface;
 use PhpTypedValues\Bool\Alias\Boolean;
 use PhpTypedValues\Bool\BoolStandard;
+use PhpTypedValues\Bool\FalseStandard;
+use PhpTypedValues\Bool\TrueStandard;
 use PhpTypedValues\Exception\UndefinedTypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
  * Boolean.
@@ -23,6 +26,27 @@
 // Ensure interface method usage is visible to Psalm
 echo (testBool(BoolStandard::fromBool(true)) ? 'true' : 'false') . \PHP_EOL;
 
+// true/false literal usages (and try* to reference both branches for Psalm)
+$t1 = TrueStandard::tryFromString('yes');
+if (!($t1 instanceof Undefined)) {
+    echo $t1->toString() . \PHP_EOL;
+}
+
+$t2 = TrueStandard::tryFromInt(1);
+if (!($t2 instanceof Undefined)) {
+    echo $t2->toString() . \PHP_EOL;
+}
+
+$f1 = FalseStandard::tryFromString('off');
+if (!($f1 instanceof Undefined)) {
+    echo $f1->toString() . \PHP_EOL;
+}
+
+$f2 = FalseStandard::tryFromInt(0);
+if (!($f2 instanceof Undefined)) {
+    echo $f2->toString() . \PHP_EOL;
+}
+
 /**
  * Exercise BoolTypeInterface::value() for Psalm.
  */

tests/Unit/Bool/FalseStandard/FalseStandardTest.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Bool\FalseStandard;
+use PhpTypedValues\Exception\BoolTypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('constructs only with false and exposes value/toString', function (): void {
+    $f = new FalseStandard(false);
+    expect($f->value())->toBeFalse()
+        ->and($f->toString())->toBe('false')
+        ->and((string) $f)->toBe('false');
+
+    expect(fn() => new FalseStandard(true))
+        ->toThrow(BoolTypeException::class, 'Expected false literal, got "true"');
+});
+
+it('fromString accepts false-like values only', function (): void {
+    expect(FalseStandard::fromString('false')->value())->toBeFalse()
+        ->and(FalseStandard::fromString(' NO ')->value())->toBeFalse()
+        ->and(FalseStandard::fromString('off')->value())->toBeFalse()
+        ->and(FalseStandard::fromString('0')->value())->toBeFalse();
+
+    expect(fn() => FalseStandard::fromString('true'))
+        ->toThrow(BoolTypeException::class, 'Expected string representing false, got "true"');
+});
+
+it('fromInt accepts only 0', function (): void {
+    expect(FalseStandard::fromInt(0)->value())->toBeFalse();
+
+    expect(fn() => FalseStandard::fromInt(1))
+        ->toThrow(BoolTypeException::class, 'Expected int "0" for false, got "1"');
+});
+
+it('tryFromString/tryFromInt return Undefined for non-false inputs', function (): void {
+    $ok = FalseStandard::tryFromString('n');
+    $badStr = FalseStandard::tryFromString('yes');
+    $okI = FalseStandard::tryFromInt(0);
+    $badI = FalseStandard::tryFromInt(2);
+
+    expect($ok)->toBeInstanceOf(FalseStandard::class)
+        ->and($ok->value())->toBeFalse()
+        ->and($okI)->toBeInstanceOf(FalseStandard::class)
+        ->and($okI->value())->toBeFalse()
+        ->and($badStr)->toBeInstanceOf(Undefined::class)
+        ->and($badI)->toBeInstanceOf(Undefined::class);
+});

tests/Unit/Bool/TrueStandard/TrueStandardTest.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+use PhpTypedValues\Bool\TrueStandard;
+use PhpTypedValues\Exception\BoolTypeException;
+use PhpTypedValues\Undefined\Alias\Undefined;
+
+it('constructs only with true and exposes value/toString', function (): void {
+    $t = new TrueStandard(true);
+    expect($t->value())->toBeTrue()
+        ->and($t->toString())->toBe('true')
+        ->and((string) $t)->toBe('true');
+
+    expect(fn() => new TrueStandard(false))
+        ->toThrow(BoolTypeException::class, 'Expected true literal, got "false"');
+});
+
+it('fromString accepts true-like values only', function (): void {
+    expect(TrueStandard::fromString('true')->value())->toBeTrue()
+        ->and(TrueStandard::fromString(' YES ')->value())->toBeTrue()
+        ->and(TrueStandard::fromString('on')->value())->toBeTrue()
+        ->and(TrueStandard::fromString('1')->value())->toBeTrue();
+
+    expect(fn() => TrueStandard::fromString('false'))
+        ->toThrow(BoolTypeException::class, 'Expected string representing true, got "false"');
+});
+
+it('fromInt accepts only 1', function (): void {
+    expect(TrueStandard::fromInt(1)->value())->toBeTrue();
+
+    expect(fn() => TrueStandard::fromInt(0))
+        ->toThrow(BoolTypeException::class, 'Expected int "1" for true, got "0"');
+});
+
+it('tryFromString/tryFromInt return Undefined for non-true inputs', function (): void {
+    $ok = TrueStandard::tryFromString('y');
+    $badStr = TrueStandard::tryFromString('no');
+    $okI = TrueStandard::tryFromInt(1);
+    $badI = TrueStandard::tryFromInt(0);
+
+    expect($ok)->toBeInstanceOf(TrueStandard::class)
+        ->and($ok->value())->toBeTrue()
+        ->and($okI)->toBeInstanceOf(TrueStandard::class)
+        ->and($okI->value())->toBeTrue()
+        ->and($badStr)->toBeInstanceOf(Undefined::class)
+        ->and($badI)->toBeInstanceOf(Undefined::class);
+});