Merge branch 'feature/initial-enums' into feature/unit-tests

Author: JasonTheAdams

src/Common/AbstractEnum.php

@@ -35,17 +35,17 @@
 abstract class AbstractEnum
 {
     /**
-     * @var string|int The value of the enum instance
+     * @var string The value of the enum instance
      */
-    private $value;
+    private string $value;
 
     /**
      * @var string The name of the enum constant
      */
     private string $name;
 
     /**
-     * @var array<string, array<string, string|int>> Cache for reflection data
+     * @var array<string, array<string, string>> Cache for reflection data
      */
     private static array $cache = [];
 
@@ -55,25 +55,27 @@ abstract class AbstractEnum
     private static array $instances = [];
 
     /**
-     * Constructor is private to ensure instances are created through static methods
+     * Constructor is private to ensure instances are created through static methods.
      *
      * @since n.e.x.t
-     * @param string|int $value The enum value
-     * @param string $name The constant name
+     *
+     * @param string $value The enum value.
+     * @param string $name The constant name.
      */
-    final private function __construct($value, string $name)
+    final private function __construct(string $value, string $name)
     {
         $this->value = $value;
         $this->name = $name;
     }
 
     /**
-     * Magic getter to provide read-only access to properties
+     * Provides read-only access to properties.
      *
      * @since n.e.x.t
-     * @param string $property The property name
-     * @return mixed
-     * @throws BadMethodCallException If property doesn't exist
+     *
+     * @param string $property The property name.
+     * @return mixed The property value.
+     * @throws BadMethodCallException If property doesn't exist.
      */
     final public function __get(string $property)
     {
@@ -87,12 +89,13 @@ final public function __get(string $property)
     }
 
     /**
-     * Magic setter to prevent property modification
+     * Prevents property modification.
      *
      * @since n.e.x.t
-     * @param string $property The property name
-     * @param mixed $value The value to set
-     * @throws BadMethodCallException Always, as enum properties are read-only
+     *
+     * @param string $property The property name.
+     * @param mixed $value The value to set.
+     * @throws BadMethodCallException Always, as enum properties are read-only.
      */
     final public function __set(string $property, $value): void
     {
@@ -102,32 +105,34 @@ final public function __set(string $property, $value): void
     }
 
     /**
-     * Create an enum instance from a value, throws exception if invalid
+     * Creates an enum instance from a value, throws exception if invalid.
      *
      * @since n.e.x.t
-     * @param string|int $value The enum value
-     * @return static
-     * @throws InvalidArgumentException If the value is not valid
+     *
+     * @param string $value The enum value.
+     * @return static The enum instance.
+     * @throws InvalidArgumentException If the value is not valid.
      */
-    final public static function from($value): self
+    final public static function from(string $value): self
     {
         $instance = self::tryFrom($value);
         if ($instance === null) {
             throw new InvalidArgumentException(
-                sprintf('%s is not a valid backing value for enum %s', (string) $value, static::class)
+                sprintf('%s is not a valid backing value for enum %s', $value, static::class)
             );
         }
         return $instance;
     }
 
     /**
-     * Try to create an enum instance from a value, returns null if invalid
+     * Tries to create an enum instance from a value, returns null if invalid.
      *
      * @since n.e.x.t
-     * @param string|int $value The enum value
-     * @return static|null
+     *
+     * @param string $value The enum value.
+     * @return static|null The enum instance or null.
      */
-    final public static function tryFrom($value): ?self
+    final public static function tryFrom(string $value): ?self
     {
         $constants = self::getConstants();
         foreach ($constants as $name => $constantValue) {
@@ -139,10 +144,11 @@ final public static function tryFrom($value): ?self
     }
 
     /**
-     * Get all enum cases
+     * Gets all enum cases.
      *
      * @since n.e.x.t
-     * @return static[]
+     *
+     * @return static[] Array of all enum instances.
      */
     final public static function cases(): array
     {
@@ -155,11 +161,12 @@ final public static function cases(): array
     }
 
     /**
-     * Check if this enum has the same value as the given value
+     * Checks if this enum has the same value as the given value.
      *
      * @since n.e.x.t
-     * @param string|int|self $other The value or enum to compare
-     * @return bool
+     *
+     * @param string|self $other The value or enum to compare.
+     * @return bool True if values are equal.
      */
     final public function equals($other): bool
     {
@@ -171,49 +178,53 @@ final public function equals($other): bool
     }
 
     /**
-     * Check if this enum is the same instance type and value as another enum
+     * Checks if this enum is the same instance type and value as another enum.
      *
      * @since n.e.x.t
-     * @param self $other The other enum to compare
-     * @return bool
+     *
+     * @param self $other The other enum to compare.
+     * @return bool True if enums are identical.
      */
     final public function is(self $other): bool
     {
         return $this === $other; // Since we're using singletons, we can use identity comparison
     }
 
     /**
-     * Get all valid values for this enum
+     * Gets all valid values for this enum.
      *
      * @since n.e.x.t
-     * @return array<string, string|int>
+     *
+     * @return array<string, string> Map of constant names to values.
      */
     final public static function getValues(): array
     {
         return self::getConstants();
     }
 
     /**
-     * Check if a value is valid for this enum
+     * Checks if a value is valid for this enum.
      *
      * @since n.e.x.t
-     * @param string|int $value The value to check
-     * @return bool
+     *
+     * @param string $value The value to check.
+     * @return bool True if value is valid.
      */
-    final public static function isValidValue($value): bool
+    final public static function isValidValue(string $value): bool
     {
         return in_array($value, self::getValues(), true);
     }
 
     /**
-     * Get or create a singleton instance for the given value and name
+     * Gets or creates a singleton instance for the given value and name.
      *
      * @since n.e.x.t
-     * @param string|int $value The enum value
-     * @param string $name The constant name
-     * @return static
+     *
+     * @param string $value The enum value.
+     * @param string $name The constant name.
+     * @return static The enum instance.
      */
-    private static function getInstance($value, string $name): self
+    private static function getInstance(string $value, string $name): self
     {
         $className = static::class;
 
@@ -231,11 +242,12 @@ private static function getInstance($value, string $name): self
     }
 
     /**
-     * Get all constants for this enum class
+     * Gets all constants for this enum class.
      *
      * @since n.e.x.t
-     * @return array<string, string|int>
-     * @throws \RuntimeException If invalid constant found
+     *
+     * @return array<string, string> Map of constant names to values.
+     * @throws \RuntimeException If invalid constant found.
      */
     final protected static function getConstants(): array
     {
@@ -260,11 +272,11 @@ final protected static function getConstants(): array
                 }
 
                 // Check if value is valid type
-                if (!is_string($value) && !is_int($value)) {
+                if (!is_string($value)) {
                     throw new \RuntimeException(
                         sprintf(
                             'Invalid enum value type for constant %s::%s. ' .
-                            'Only string and int values are allowed, %s given.',
+                            'Only string values are allowed, %s given.',
                             $className,
                             $name,
                             gettype($value)
@@ -282,13 +294,14 @@ final protected static function getConstants(): array
     }
 
     /**
-     * Handle dynamic method calls for enum checking
+     * Handles dynamic method calls for enum checking.
      *
      * @since n.e.x.t
-     * @param string $name The method name
-     * @param array<mixed> $arguments The method arguments
-     * @return bool
-     * @throws BadMethodCallException If the method doesn't exist
+     *
+     * @param string $name The method name.
+     * @param array<mixed> $arguments The method arguments.
+     * @return bool True if the enum value matches.
+     * @throws BadMethodCallException If the method doesn't exist.
      */
     final public function __call(string $name, array $arguments): bool
     {
@@ -308,13 +321,14 @@ final public function __call(string $name, array $arguments): bool
     }
 
     /**
-     * Handle static method calls for enum creation
+     * Handles static method calls for enum creation.
      *
      * @since n.e.x.t
-     * @param string $name The method name
-     * @param array<mixed> $arguments The method arguments
-     * @return static
-     * @throws BadMethodCallException If the method doesn't exist
+     *
+     * @param string $name The method name.
+     * @param array<mixed> $arguments The method arguments.
+     * @return static The enum instance.
+     * @throws BadMethodCallException If the method doesn't exist.
      */
     final public static function __callStatic(string $name, array $arguments): self
     {
@@ -331,11 +345,12 @@ final public static function __callStatic(string $name, array $arguments): self
     }
 
     /**
-     * Convert camelCase to CONSTANT_CASE
+     * Converts camelCase to CONSTANT_CASE.
      *
      * @since n.e.x.t
-     * @param string $camelCase The camelCase string
-     * @return string The CONSTANT_CASE version
+     *
+     * @param string $camelCase The camelCase string.
+     * @return string The CONSTANT_CASE version.
      */
     private static function camelCaseToConstant(string $camelCase): string
     {
@@ -347,13 +362,14 @@ private static function camelCaseToConstant(string $camelCase): string
     }
 
     /**
-     * String representation of the enum
+     * Returns string representation of the enum.
      *
      * @since n.e.x.t
-     * @return string
+     *
+     * @return string The enum value.
      */
     final public function __toString(): string
     {
-        return (string) $this->value;
+        return $this->value;
     }
 }

src/Messages/Enums/MessagePartTypeEnum.php

@@ -7,44 +7,45 @@
 use WordPress\AiClient\Common\AbstractEnum;
 
 /**
- * Enum for message part types
+ * Enum for message part types.
  *
  * @since n.e.x.t
- * @method static self text() Create an instance for TEXT type
- * @method static self inlineFile() Create an instance for INLINE_FILE type
- * @method static self remoteFile() Create an instance for REMOTE_FILE type
- * @method static self functionCall() Create an instance for FUNCTION_CALL type
- * @method static self functionResponse() Create an instance for FUNCTION_RESPONSE type
- * @method bool isText() Check if the type is TEXT
- * @method bool isInlineFile() Check if the type is INLINE_FILE
- * @method bool isRemoteFile() Check if the type is REMOTE_FILE
- * @method bool isFunctionCall() Check if the type is FUNCTION_CALL
- * @method bool isFunctionResponse() Check if the type is FUNCTION_RESPONSE
+ *
+ * @method static self text() Creates an instance for TEXT type.
+ * @method static self inlineFile() Creates an instance for INLINE_FILE type.
+ * @method static self remoteFile() Creates an instance for REMOTE_FILE type.
+ * @method static self functionCall() Creates an instance for FUNCTION_CALL type.
+ * @method static self functionResponse() Creates an instance for FUNCTION_RESPONSE type.
+ * @method bool isText() Checks if the type is TEXT.
+ * @method bool isInlineFile() Checks if the type is INLINE_FILE.
+ * @method bool isRemoteFile() Checks if the type is REMOTE_FILE.
+ * @method bool isFunctionCall() Checks if the type is FUNCTION_CALL.
+ * @method bool isFunctionResponse() Checks if the type is FUNCTION_RESPONSE.
  */
 class MessagePartTypeEnum extends AbstractEnum
 {
     /**
-     * Text content
+     * Text content.
      */
     public const TEXT = 'text';
 
     /**
-     * Inline file content (base64 encoded)
+     * Inline file content (base64 encoded).
      */
     public const INLINE_FILE = 'inline_file';
 
     /**
-     * Remote file reference (URL)
+     * Remote file reference (URL).
      */
     public const REMOTE_FILE = 'remote_file';
 
     /**
-     * Function call request
+     * Function call request.
      */
     public const FUNCTION_CALL = 'function_call';
 
     /**
-     * Function response
+     * Function response.
      */
     public const FUNCTION_RESPONSE = 'function_response';
 }