Commit inicial, se subio el proyecto

This commit is contained in:
Gabriel
2026-09-23 17:20:43 -06:00
commit 943dc06127
7470 changed files with 2641057 additions and 0 deletions
@@ -0,0 +1,128 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common;
use JsonSerializable;
use stdClass;
use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface;
use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface;
use WordPress\AiClient\Common\Exception\InvalidArgumentException;
/**
* Abstract base class for all Data Value Objects in the AI Client.
*
* This abstract class consolidates the common functionality needed by all
* data transfer objects:
* - Array transformation for data manipulation
* - JSON schema support for validation and documentation
* - JSON serialization with proper empty object handling
*
* All DTOs in the AI Client should extend this class to ensure
* consistent behavior across the codebase.
*
* @since 0.1.0
*
* @template TArrayShape of array<string, mixed>
* @implements WithArrayTransformationInterface<TArrayShape>
*/
abstract class AbstractDataTransferObject implements WithArrayTransformationInterface, WithJsonSchemaInterface, JsonSerializable
{
/**
* Validates that required keys exist in the array data.
*
* @since 0.1.0
*
* @param array<mixed> $data The array data to validate.
* @param string[] $requiredKeys The keys that must be present.
* @throws InvalidArgumentException If any required key is missing.
*/
protected static function validateFromArrayData(array $data, array $requiredKeys): void
{
$missingKeys = [];
foreach ($requiredKeys as $key) {
if (!array_key_exists($key, $data)) {
$missingKeys[] = $key;
}
}
if (!empty($missingKeys)) {
throw new InvalidArgumentException(sprintf('%s::fromArray() missing required keys: %s', static::class, implode(', ', $missingKeys)));
}
}
/**
* {@inheritDoc}
*
* @since 0.1.0
*/
public static function isArrayShape(array $array): bool
{
try {
/** @var TArrayShape $array */
static::fromArray($array);
return \true;
} catch (InvalidArgumentException $e) {
return \false;
}
}
/**
* Converts the object to a JSON-serializable format.
*
* This method uses the toArray() method and then processes the result
* based on the JSON schema to ensure proper object representation for
* empty arrays.
*
* @since 0.1.0
*
* @return mixed The JSON-serializable representation.
*/
#[\ReturnTypeWillChange]
public function jsonSerialize()
{
$data = $this->toArray();
$schema = static::getJsonSchema();
return $this->convertEmptyArraysToObjects($data, $schema);
}
/**
* Recursively converts empty arrays to stdClass objects where the schema expects objects.
*
* @since 0.1.0
*
* @param mixed $data The data to process.
* @param array<mixed, mixed> $schema The JSON schema for the data.
* @return mixed The processed data.
*/
private function convertEmptyArraysToObjects($data, array $schema)
{
// If data is an empty array and schema expects object, convert to stdClass
if (is_array($data) && empty($data) && isset($schema['type']) && $schema['type'] === 'object') {
return new stdClass();
}
// If data is an array with content, recursively process nested structures
if (is_array($data)) {
// Handle object properties
if (isset($schema['properties']) && is_array($schema['properties'])) {
foreach ($data as $key => $value) {
if (isset($schema['properties'][$key]) && is_array($schema['properties'][$key])) {
$data[$key] = $this->convertEmptyArraysToObjects($value, $schema['properties'][$key]);
}
}
}
// Handle array items
if (isset($schema['items']) && is_array($schema['items'])) {
foreach ($data as $index => $item) {
$data[$index] = $this->convertEmptyArraysToObjects($item, $schema['items']);
}
}
// Handle oneOf/anyOf schemas - just use the first one
foreach (['oneOf', 'anyOf'] as $keyword) {
if (isset($schema[$keyword]) && is_array($schema[$keyword])) {
foreach ($schema[$keyword] as $possibleSchema) {
if (is_array($possibleSchema)) {
return $this->convertEmptyArraysToObjects($data, $possibleSchema);
}
}
}
}
}
return $data;
}
}
@@ -0,0 +1,349 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common;
use BadMethodCallException;
use JsonSerializable;
use ReflectionClass;
use WordPress\AiClient\Common\Exception\InvalidArgumentException;
use WordPress\AiClient\Common\Exception\RuntimeException;
/**
* Abstract base class for enum-like behavior in PHP 7.4.
*
* This class provides enum-like functionality for PHP versions that don't support native enums.
* Child classes should define uppercase snake_case constants for enum values.
*
* @example
* class PersonEnum extends AbstractEnum {
* public const FIRST_NAME = 'first';
* public const LAST_NAME = 'last';
* }
*
* // Usage:
* $enum = PersonEnum::from('first'); // Creates instance with value 'first'
* $enum = PersonEnum::tryFrom('invalid'); // Returns null
* $enum = PersonEnum::firstName(); // Creates instance with value 'first'
* $enum->name; // 'FIRST_NAME'
* $enum->value; // 'first'
* $enum->equals('first'); // Returns true
* $enum->is(PersonEnum::firstName()); // Returns true
* PersonEnum::cases(); // Returns array of all enum instances
*
* @property-read string $value The value of the enum instance.
* @property-read string $name The name of the enum constant.
*
* @since 0.1.0
*/
abstract class AbstractEnum implements JsonSerializable
{
/**
* @var string The value of the enum instance.
*/
private string $value;
/**
* @var string The name of the enum constant.
*/
private string $name;
/**
* @var array<string, array<string, string>> Cache for reflection data.
*/
private static array $cache = [];
/**
* @var array<string, array<string, self>> Cache for enum instances.
*/
private static array $instances = [];
/**
* Constructor is private to ensure instances are created through static methods.
*
* @since 0.1.0
*
* @param string $value The enum value.
* @param string $name The constant name.
*/
final private function __construct(string $value, string $name)
{
$this->value = $value;
$this->name = $name;
}
/**
* Provides read-only access to properties.
*
* @since 0.1.0
*
* @param string $property The property name.
* @return mixed The property value.
* @throws BadMethodCallException If property doesn't exist.
*/
final public function __get(string $property)
{
if ($property === 'value' || $property === 'name') {
return $this->{$property};
}
throw new BadMethodCallException(sprintf('Property %s::%s does not exist', static::class, $property));
}
/**
* Prevents property modification.
*
* @since 0.1.0
*
* @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
{
throw new BadMethodCallException(sprintf('Cannot modify property %s::%s - enum properties are read-only', static::class, $property));
}
/**
* Creates an enum instance from a value, throws exception if invalid.
*
* @since 0.1.0
*
* @param string $value The enum value.
* @return static The enum instance.
* @throws InvalidArgumentException If the value is not valid.
*/
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', $value, static::class));
}
return $instance;
}
/**
* Tries to create an enum instance from a value, returns null if invalid.
*
* @since 0.1.0
*
* @param string $value The enum value.
* @return static|null The enum instance or null.
*/
final public static function tryFrom(string $value): ?self
{
$constants = static::getConstants();
foreach ($constants as $name => $constantValue) {
if ($constantValue === $value) {
return self::getInstance($constantValue, $name);
}
}
return null;
}
/**
* Gets all enum cases.
*
* @since 0.1.0
*
* @return static[] Array of all enum instances.
*/
final public static function cases(): array
{
$cases = [];
$constants = static::getConstants();
foreach ($constants as $name => $value) {
$cases[] = self::getInstance($value, $name);
}
return $cases;
}
/**
* Checks if this enum has the same value as the given value.
*
* @since 0.1.0
*
* @param string|self $other The value or enum to compare.
* @return bool True if values are equal.
*/
final public function equals($other): bool
{
if ($other instanceof self) {
return $this->is($other);
}
return $this->value === $other;
}
/**
* Checks if this enum is the same instance type and value as another enum.
*
* @since 0.1.0
*
* @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
}
/**
* Gets all valid values for this enum.
*
* @since 0.1.0
*
* @return string[] List of all enum values.
*/
final public static function getValues(): array
{
return array_values(static::getConstants());
}
/**
* Checks if a value is valid for this enum.
*
* @since 0.1.0
*
* @param string $value The value to check.
* @return bool True if value is valid.
*/
final public static function isValidValue(string $value): bool
{
return in_array($value, self::getValues(), \true);
}
/**
* Gets or creates a singleton instance for the given value and name.
*
* @since 0.1.0
*
* @param string $value The enum value.
* @param string $name The constant name.
* @return static The enum instance.
*/
private static function getInstance(string $value, string $name): self
{
$className = static::class;
if (!isset(self::$instances[$className])) {
self::$instances[$className] = [];
}
if (!isset(self::$instances[$className][$name])) {
$instance = new $className($value, $name);
self::$instances[$className][$name] = $instance;
}
/** @var static */
return self::$instances[$className][$name];
}
/**
* Gets all constants for this enum class.
*
* @since 0.1.0
*
* @return array<string, string> Map of constant names to values.
* @throws RuntimeException If invalid constant found.
*/
final protected static function getConstants(): array
{
$className = static::class;
if (!isset(self::$cache[$className])) {
self::$cache[$className] = static::determineClassEnumerations($className);
}
return self::$cache[$className];
}
/**
* Determines the class enumerations by reflecting on class constants.
*
* This method can be overridden by subclasses to customize how
* enumerations are determined (e.g., to add dynamic constants).
*
* @since 0.1.0
*
* @param class-string $className The fully qualified class name.
* @return array<string, string> Map of constant names to values.
* @throws RuntimeException If invalid constant found.
*/
protected static function determineClassEnumerations(string $className): array
{
$reflection = new ReflectionClass($className);
$constants = $reflection->getConstants();
// Validate all constants
$enumConstants = [];
foreach ($constants as $name => $value) {
// Check if constant name follows uppercase snake_case pattern
if (!preg_match('/^[A-Z][A-Z0-9_]*$/', $name)) {
throw new RuntimeException(sprintf('Invalid enum constant name "%s" in %s. Constants must be UPPER_SNAKE_CASE.', $name, $className));
}
// Check if value is valid type
if (!is_string($value)) {
throw new RuntimeException(sprintf('Invalid enum value type for constant %s::%s. ' . 'Only string values are allowed, %s given.', $className, $name, gettype($value)));
}
$enumConstants[$name] = $value;
}
return $enumConstants;
}
/**
* Handles dynamic method calls for enum checking.
*
* @since 0.1.0
*
* @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
{
// Handle is* methods
if (str_starts_with($name, 'is')) {
$constantName = self::camelCaseToConstant(substr($name, 2));
$constants = static::getConstants();
if (isset($constants[$constantName])) {
return $this->value === $constants[$constantName];
}
}
throw new BadMethodCallException(sprintf('Method %s::%s does not exist', static::class, $name));
}
/**
* Handles static method calls for enum creation.
*
* @since 0.1.0
*
* @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
{
$constantName = self::camelCaseToConstant($name);
$constants = static::getConstants();
if (isset($constants[$constantName])) {
return self::getInstance($constants[$constantName], $constantName);
}
throw new BadMethodCallException(sprintf('Method %s::%s does not exist', static::class, $name));
}
/**
* Converts camelCase to CONSTANT_CASE.
*
* @since 0.1.0
*
* @param string $camelCase The camelCase string.
* @return string The CONSTANT_CASE version.
*/
private static function camelCaseToConstant(string $camelCase): string
{
$snakeCase = preg_replace('/([a-z])([A-Z])/', '$1_$2', $camelCase);
if ($snakeCase === null) {
return strtoupper($camelCase);
}
return strtoupper($snakeCase);
}
/**
* Returns string representation of the enum.
*
* @since 0.1.0
*
* @return string The enum value.
*/
final public function __toString(): string
{
return $this->value;
}
/**
* Converts the enum to a JSON-serializable format.
*
* @since 0.1.0
*
* @return string The enum value.
*/
#[\ReturnTypeWillChange]
public function jsonSerialize()
{
return $this->value;
}
}
@@ -0,0 +1,17 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Contracts;
use Throwable;
/**
* Base interface for all AI Client exceptions.
*
* This interface allows callers to catch all AI Client specific exceptions
* with a single catch statement.
*
* @since 0.2.0
*/
interface AiClientExceptionInterface extends Throwable
{
}
@@ -0,0 +1,21 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Contracts;
/**
* Interface for objects that cache data.
*
* @since 0.4.0
*/
interface CachesDataInterface
{
/**
* Invalidates all caches managed by this object.
*
* @since 0.4.0
*
* @return void
*/
public function invalidateCaches(): void;
}
@@ -0,0 +1,42 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Contracts;
/**
* Interface for objects that support array transformation.
*
* @since 0.1.0
*
* @template TArrayShape of array<string, mixed>
*/
interface WithArrayTransformationInterface
{
/**
* Converts the object to an array representation.
*
* @since 0.1.0
*
* @return TArrayShape The array representation.
*/
public function toArray(): array;
/**
* Creates an instance from array data.
*
* @since 0.1.0
*
* @param TArrayShape $array The array data.
* @return self<TArrayShape> The created instance.
*/
public static function fromArray(array $array): self;
/**
* Checks if the array is a valid shape for this object.
*
* @since 0.1.0
*
* @param array<mixed> $array The array to check.
* @return bool True if the array is a valid shape.
* @phpstan-assert-if-true TArrayShape $array
*/
public static function isArrayShape(array $array): bool;
}
@@ -0,0 +1,24 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Contracts;
/**
* Interface for objects that can provide their JSON schema representation.
*
* This interface is implemented by DTOs to provide a consistent way to retrieve
* their JSON schema for validation and serialization purposes.
*
* @since 0.1.0
*/
interface WithJsonSchemaInterface
{
/**
* Gets the JSON schema representation of the object.
*
* @since 0.1.0
*
* @return array<string, mixed> The JSON schema as an associative array.
*/
public static function getJsonSchema(): array;
}
@@ -0,0 +1,17 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Exception;
use WordPress\AiClient\Common\Contracts\AiClientExceptionInterface;
/**
* Exception thrown when an invalid argument is provided.
*
* This extends PHP's built-in InvalidArgumentException while implementing
* the AI Client exception interface for consistent catch handling.
*
* @since 0.2.0
*/
class InvalidArgumentException extends \InvalidArgumentException implements AiClientExceptionInterface
{
}
@@ -0,0 +1,17 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Exception;
use WordPress\AiClient\Common\Contracts\AiClientExceptionInterface;
/**
* Exception thrown for runtime errors.
*
* This extends PHP's built-in RuntimeException while implementing
* the AI Client exception interface for consistent catch handling.
*
* @since 0.2.0
*/
class RuntimeException extends \RuntimeException implements AiClientExceptionInterface
{
}
@@ -0,0 +1,50 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Exception;
/**
* Exception thrown when a token limit is reached during prompt fulfillment.
*
* Providers should throw this exception when the token usage for a request
* exceeds the allowed limit, whether that is the model's context window
* or a configured maximum.
*
* @since 1.0.0
*/
class TokenLimitReachedException extends \WordPress\AiClient\Common\Exception\RuntimeException
{
/**
* The token limit that was reached, if known.
*
* @since 1.0.0
*
* @var int|null
*/
private $maxTokens;
/**
* Creates a new TokenLimitReachedException.
*
* @since 1.0.0
*
* @param string $message The exception message.
* @param int|null $maxTokens The token limit that was reached, if known.
* @param \Throwable|null $previous The previous throwable used for exception chaining.
*/
public function __construct(string $message = '', ?int $maxTokens = null, ?\Throwable $previous = null)
{
parent::__construct($message, 0, $previous);
$this->maxTokens = $maxTokens;
}
/**
* Returns the token limit that was reached, if known.
*
* @since 1.0.0
*
* @return int|null The token limit, or null if not provided.
*/
public function getMaxTokens(): ?int
{
return $this->maxTokens;
}
}
@@ -0,0 +1,162 @@
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Common\Traits;
use WordPress\AiClient\AiClient;
/**
* Trait for objects that cache data using PSR-16 cache with in-memory fallback.
*
* When a PSR-16 cache is configured via AiClient::setCache(), data is stored persistently.
* Otherwise, data is cached in-memory for the duration of the request.
*
* @since 0.4.0
*/
trait WithDataCachingTrait
{
/**
* In-memory cache used when no PSR-16 cache is configured.
*
* @since 0.4.0
*
* @var array<string, mixed>
*/
private array $localCache = [];
/**
* Gets the cache key suffixes managed by this object.
*
* @since 0.4.0
*
* @return list<string> The cache key suffixes.
*/
abstract protected function getCachedKeys(): array;
/**
* Gets the base cache key for this object.
*
* The base cache key is used as a prefix for all cache keys managed by this object.
* It should be unique to the implementing class to avoid cache key collisions.
*
* @since 0.4.0
*
* @return string The base cache key.
*/
abstract protected function getBaseCacheKey(): string;
/**
* Checks if a value exists in the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @return bool True if the value exists in cache, false otherwise.
*/
protected function hasCache(string $key): bool
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->has($fullKey);
}
return array_key_exists($fullKey, $this->localCache);
}
/**
* Gets a value from the cache, or computes and caches it if not present.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @param callable $callback The callback to compute the value if not cached.
* @param int|\DateInterval|null $ttl The TTL for the cache entry, or null for default.
* Ignored for local cache.
* @return mixed The cached or computed value.
*/
protected function cached(string $key, callable $callback, $ttl = null)
{
if ($this->hasCache($key)) {
return $this->getCache($key);
}
$value = $callback();
$this->setCache($key, $value, $ttl);
return $value;
}
/**
* Gets a value from the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @param mixed $default The default value to return if the key does not exist.
* @return mixed The cached value or the default value if not found.
*/
protected function getCache(string $key, $default = null)
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->get($fullKey, $default);
}
return $this->localCache[$fullKey] ?? $default;
}
/**
* Sets a value in the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @param mixed $value The value to cache.
* @param int|\DateInterval|null $ttl The TTL for the cache entry, or null for default. Ignored for local cache.
* @return bool True on success, false on failure.
*/
protected function setCache(string $key, $value, $ttl = null): bool
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->set($fullKey, $value, $ttl);
}
$this->localCache[$fullKey] = $value;
return \true;
}
/**
* Invalidates all caches managed by this object.
*
* @since 0.4.0
*
* @return void
*/
public function invalidateCaches(): void
{
foreach ($this->getCachedKeys() as $key) {
$this->clearCache($key);
}
}
/**
* Clears a value from the cache.
*
* @since 0.4.0
*
* @param string $key The cache key suffix (will be appended to the base key).
* @return bool True on success, false on failure.
*/
protected function clearCache(string $key): bool
{
$fullKey = $this->buildCacheKey($key);
$cache = AiClient::getCache();
if ($cache !== null) {
return $cache->delete($fullKey);
}
unset($this->localCache[$fullKey]);
return \true;
}
/**
* Builds the full cache key by combining the base key with the suffix.
*
* @since 0.4.0
*
* @param string $key The cache key suffix.
* @return string The full cache key.
*/
private function buildCacheKey(string $key): string
{
return $this->getBaseCacheKey() . '_' . $key;
}
}