Comparable enum (#20)

* feat: comparable enum

* test: comparable enum

* ci: php-cs-fixer in repository scope

* chore: add `Comparable` usage in README

* ci: globally use `php-cs-fixer`

* improve Comparable logic

* test more PHP versions in CI

* update ci job name

* remove class name quoting in exceptions to match PHP behavior

* migrate pest config

* add comment to test

---------

Co-authored-by: Samuel Štancl <samuel@archte.ch>
Co-authored-by: Samuel Štancl <samuel.stancl@gmail.com>

tests/Pest.php

@@ -1,6 +1,6 @@
 <?php
 
-use ArchTech\Enums\{InvokableCases, Options, Names, Values, From, Metadata};
+use ArchTech\Enums\{Comparable, InvokableCases, Options, Names, Values, From, Metadata};
 use ArchTech\Enums\Meta\Meta;
 use ArchTech\Enums\Meta\MetaProperty;
 
@@ -36,7 +36,7 @@ class Instructions extends MetaProperty
 #[Meta(Color::class, Desc::class)] // variadic syntax
 enum Status: int
 {
-    use InvokableCases, Options, Names, Values, From, Metadata;
+    use InvokableCases, Options, Names, Values, From, Metadata, Comparable;
 
     #[Color('orange')] #[Desc('Incomplete task')]
     case PENDING = 0;
@@ -49,7 +49,7 @@ enum Status: int
 #[Meta([Color::class, Desc::class, Instructions::class])] // array
 enum Role
 {
-    use InvokableCases, Options, Names, Values, From, Metadata;
+    use InvokableCases, Options, Names, Values, From, Metadata, Comparable;
 
     #[Color('indigo')]
     #[Desc('Administrator')]

tests/Pest/ComparableTest.php

@@ -0,0 +1,44 @@
+<?php
+
+test('the is method checks for equality', function () {
+    expect(Status::PENDING->is(Status::PENDING))->toBeTrue();
+    expect(Status::PENDING->is(Status::DONE))->toBeFalse();
+    expect(Role::ADMIN->is(Role::ADMIN))->toBeTrue();
+
+    expect(Role::ADMIN->is(Role::GUEST))->toBeFalse();
+    expect(Role::ADMIN->is('admin'))->toBeFalse();
+});
+
+it('the isNot method checks for inequality', function () {
+    expect(Status::PENDING->isNot(Status::DONE))->toBeTrue();
+    expect(Status::PENDING->isNot(Status::PENDING))->toBeFalse();
+    expect(Status::PENDING->isNot(Role::ADMIN))->toBeTrue();
+    expect(Role::ADMIN->isNot(Role::GUEST))->toBeTrue();
+
+    expect(Role::ADMIN->isNot(Role::ADMIN))->toBeFalse();
+    expect(Role::ADMIN->isNot('admin'))->toBeTrue();
+});
+
+it('the in method checks for presence in an array', function () {
+    expect(Status::PENDING->in([Status::PENDING, Status::DONE]))->toBeTrue();
+    expect(Role::ADMIN->in([Role::ADMIN]))->toBeTrue();
+
+    expect(Status::PENDING->in([Status::DONE]))->toBeFalse();
+    expect(Status::PENDING->in([Role::ADMIN, Role::GUEST]))->toBeFalse();
+});
+
+it('the not in method checks for absence in an array', function () {
+    expect(Status::PENDING->notIn([Status::DONE]))->toBeTrue();
+    expect(Role::ADMIN->notIn([Role::GUEST]))->toBeTrue();
+
+    expect(Status::PENDING->notIn([Status::PENDING, Status::DONE]))->toBeFalse();
+    expect(Role::ADMIN->notIn([Role::ADMIN, Role::GUEST]))->toBeFalse();
+});
+
+test('the in and notIn methods work with Laravel collections', function () {
+    expect(Status::PENDING->in(collect([Status::PENDING, Status::DONE])))->toBeTrue();
+    expect(Role::ADMIN->in(collect([Status::PENDING, Role::GUEST])))->toBeFalse();
+
+    expect(Status::DONE->notIn(collect([Status::PENDING])))->toBeTrue();
+    expect(Role::ADMIN->notIn(collect([Role::ADMIN, Status::PENDING])))->toBeFalse();
+});

tests/Pest/FromTest.php

@@ -4,9 +4,12 @@ it('does not override the default BackedEnum from method')
     ->expect(Status::from(0))
     ->toBe(Status::PENDING);
 
+// Shortened exception message due to inconsistency between PHP 8.1 and 8.2+
+// 8.1:  2 is not a valid backing value for enum "Status"
+// 8.2+: 2 is not a valid backing value for enum Status
 it('does not override the default BackedEnum from method with errors', function () {
     Status::from(2);
-})->throws(ValueError::class, '2 is not a valid backing value for enum "Status"');
+})->throws(ValueError::class, '2 is not a valid backing value for enum');
 
 it('does not override the default BackedEnum tryFrom method')
     ->expect(Status::tryFrom(1))
@@ -22,7 +25,7 @@ it('can select a case by name with from() for pure enums')
 
 it('throws a value error when selecting a non-existent case with from() for pure enums', function () {
     Role::from('NOBODY');
-})->throws(ValueError::class, '"NOBODY" is not a valid name for enum "Role"');
+})->throws(ValueError::class, '"NOBODY" is not a valid name for enum Role');
 
 it('can select a case by name with tryFrom() for pure enums')
     ->expect(Role::tryFrom('GUEST'))
@@ -38,7 +41,7 @@ it('can select a case by name with fromName() for pure enums')
 
 it('throws a value error when selecting a non-existent case by name with fromName() for pure enums', function () {
     Role::fromName('NOBODY');
-})->throws(ValueError::class, '"NOBODY" is not a valid name for enum "Role"');
+})->throws(ValueError::class, '"NOBODY" is not a valid name for enum Role');
 
 it('can select a case by name with tryFromName() for pure enums')
     ->expect(Role::tryFromName('GUEST'))
@@ -54,7 +57,7 @@ it('can select a case by name with fromName() for backed enums')
 
 it('throws a value error when selecting a non-existent case by name with fromName() for backed enums', function () {
     Status::fromName('NOTHING');
-})->throws(ValueError::class, '"NOTHING" is not a valid name for enum "Status"');
+})->throws(ValueError::class, '"NOTHING" is not a valid name for enum Status');
 
 it('can select a case by name with tryFromName() for backed enums')
     ->expect(Status::tryFromName('DONE'))