Add BC-safe enhancements: ProviderCollection, cache, oEmbed (#83)

* Add ProviderCollection, cache support, and oEmbed discovery

- Add getProviders() method returning ProviderCollection for type-safe iteration
- Add CacheInterface with ArrayCache implementation
- Add optional PSR-16 compatible cache to UrlMatcher for persistent index
- Add OEmbedDiscovery class for auto-discovering oEmbed endpoints
- Add OEmbedResponse DTO for parsed oEmbed data
- Add comprehensive tests for all new features

* Add documentation for ProviderCollection, caching, and oEmbed

Author: dereuromark

docs/README.md

@@ -347,6 +347,145 @@ $loader = new ArrayLoader([
 $MediaEmbed->loadProvidersFromLoader($loader, reset: true);
 ```
 
+### Provider Collection
+
+Get all providers as a filterable collection:
+
+```php
+use MediaEmbed\Provider\ProviderCollection;
+
+$MediaEmbed = new MediaEmbed();
+
+// Get all providers
+$providers = $MediaEmbed->getProviders();
+echo count($providers); // e.g., 137
+
+// Filter to specific providers
+$subset = $MediaEmbed->getProviders(['youtube', 'vimeo', 'dailymotion']);
+
+// Filter by capabilities
+$withIframe = $providers->withIframeSupport();
+$withThumbnails = $providers->withThumbnailSupport();
+
+// Iterate over providers
+foreach ($providers as $slug => $config) {
+    echo $config->name . ' (' . $slug . ')' . PHP_EOL;
+}
+
+// Chain filters
+$filtered = $providers
+    ->withIframeSupport()
+    ->whitelist(['youtube', 'vimeo', 'twitch']);
+```
+
+### Caching
+
+For better performance on repeated requests, use the cache support:
+
+```php
+use MediaEmbed\Cache\ArrayCache;
+use MediaEmbed\Cache\CacheInterface;
+
+// Using the built-in ArrayCache (in-memory, single request)
+$cache = new ArrayCache();
+$MediaEmbed = new MediaEmbed();
+$matcher = $MediaEmbed->getUrlMatcher();
+$matcher->setCache($cache);
+
+// The domain index will be cached after first match
+$MediaEmbed->parseUrl('https://youtube.com/watch?v=abc');
+```
+
+For persistent caching, implement `CacheInterface` with your preferred cache backend (Redis, Memcached, filesystem, etc.):
+
+```php
+use MediaEmbed\Cache\CacheInterface;
+use Psr\SimpleCache\CacheInterface as Psr16Cache;
+
+class Psr16Adapter implements CacheInterface {
+    public function __construct(private Psr16Cache $cache) {}
+
+    public function get(string $key, mixed $default = null): mixed {
+        return $this->cache->get($key, $default);
+    }
+
+    public function set(string $key, mixed $value, ?int $ttl = null): bool {
+        return $this->cache->set($key, $value, $ttl);
+    }
+
+    public function delete(string $key): bool {
+        return $this->cache->delete($key);
+    }
+
+    public function has(string $key): bool {
+        return $this->cache->has($key);
+    }
+}
+
+// Use with any PSR-16 cache
+$cache = new Psr16Adapter($yourPsr16Cache);
+$MediaEmbed->getUrlMatcher()->setCache($cache, ttl: 3600);
+```
+
+### oEmbed Discovery
+
+For URLs not covered by built-in providers, use oEmbed auto-discovery:
+
+```php
+use MediaEmbed\OEmbed\OEmbedDiscovery;
+
+$discovery = new OEmbedDiscovery();
+
+// Auto-discover and fetch oEmbed data
+$response = $discovery->discover('https://example.com/video/123');
+
+if ($response !== null) {
+    echo $response->title;
+    echo $response->providerName;
+
+    if ($response->hasHtml()) {
+        echo $response->html; // Ready-to-use embed code
+    }
+
+    if ($response->hasThumbnail()) {
+        echo $response->thumbnailUrl;
+    }
+}
+
+// With size constraints
+$response = $discovery->discover($url, maxWidth: 640, maxHeight: 480);
+
+// Or fetch directly from a known endpoint
+$response = $discovery->fetch('https://example.com/oembed?url=...');
+```
+
+The `OEmbedResponse` provides typed access to all oEmbed fields:
+
+```php
+$response->type;           // 'video', 'photo', 'link', or 'rich'
+$response->version;        // oEmbed version (usually '1.0')
+$response->title;          // Content title
+$response->authorName;     // Author/creator name
+$response->authorUrl;      // Author URL
+$response->providerName;   // Provider name (e.g., 'YouTube')
+$response->providerUrl;    // Provider homepage
+$response->thumbnailUrl;   // Thumbnail image URL
+$response->thumbnailWidth; // Thumbnail width
+$response->thumbnailHeight;// Thumbnail height
+$response->html;           // Embed HTML (for video/rich types)
+$response->width;          // Embed width
+$response->height;         // Embed height
+$response->url;            // Source URL (for photo type)
+$response->cacheAge;       // Suggested cache duration in seconds
+
+// Type checks
+$response->isVideo();
+$response->isPhoto();
+$response->isRich();
+$response->hasHtml();
+$response->hasThumbnail();
+```
+
 ### Example with BBCode
 
 #### Parse video content upon save (db input)

src/Cache/ArrayCache.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MediaEmbed\Cache;
+
+/**
+ * Simple in-memory array cache.
+ *
+ * This cache stores values in memory for the duration of the request.
+ * Use this when you don't need persistent caching.
+ */
+final class ArrayCache implements CacheInterface {
+
+	/**
+	 * @var array<string, mixed>
+	 */
+	private array $cache = [];
+
+	/**
+	 * @inheritDoc
+	 */
+	public function get(string $key, mixed $default = null): mixed {
+		return $this->cache[$key] ?? $default;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function set(string $key, mixed $value, ?int $ttl = null): bool {
+		$this->cache[$key] = $value;
+
+		return true;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function delete(string $key): bool {
+		unset($this->cache[$key]);
+
+		return true;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function has(string $key): bool {
+		return isset($this->cache[$key]);
+	}
+
+	/**
+	 * Clear all cached values.
+	 *
+	 * @return bool
+	 */
+	public function clear(): bool {
+		$this->cache = [];
+
+		return true;
+	}
+
+}

src/Cache/CacheInterface.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MediaEmbed\Cache;
+
+/**
+ * Simple cache interface compatible with PSR-16 SimpleCache.
+ *
+ * Implementations of this interface can wrap any PSR-16 compatible cache
+ * or provide custom caching logic.
+ */
+interface CacheInterface {
+
+	/**
+	 * Fetches a value from the cache.
+	 *
+	 * @param string $key The unique key of this item in the cache.
+	 * @param mixed $default Default value to return if the key does not exist.
+	 * @return mixed The value of the item from the cache, or $default if not found.
+	 */
+	public function get(string $key, mixed $default = null): mixed;
+
+	/**
+	 * Persists data in the cache.
+	 *
+	 * @param string $key The key of the item to store.
+	 * @param mixed $value The value of the item to store.
+	 * @param int|null $ttl Optional TTL in seconds.
+	 * @return bool True on success, false on failure.
+	 */
+	public function set(string $key, mixed $value, ?int $ttl = null): bool;
+
+	/**
+	 * Delete an item from the cache by its unique key.
+	 *
+	 * @param string $key The unique cache key.
+	 * @return bool True if the item was successfully removed, false otherwise.
+	 */
+	public function delete(string $key): bool;
+
+	/**
+	 * Determines whether an item is present in the cache.
+	 *
+	 * @param string $key The cache item key.
+	 * @return bool
+	 */
+	public function has(string $key): bool;
+
+}

src/Matcher/UrlMatcher.php

@@ -4,6 +4,8 @@
 
 namespace MediaEmbed\Matcher;
 
+use MediaEmbed\Cache\CacheInterface;
+
 /**
  * URL matcher with optional domain-based caching for faster lookups.
  *
@@ -12,6 +14,12 @@
  */
 final class UrlMatcher {
 
+	/**
+	 * Cache key for the domain index.
+     * @var string
+	 */
+	private const CACHE_KEY = 'media_embed_domain_index';
+
 	/**
 	 * Domain-to-providers index for fast path matching.
 	 *
@@ -31,11 +39,25 @@ final class UrlMatcher {
 	 */
 	private bool $indexBuilt = false;
 
+	/**
+	 * Optional cache for persisting the domain index.
+	 */
+	private ?CacheInterface $cache = null;
+
+	/**
+	 * Cache TTL in seconds (default: 1 hour).
+	 */
+	private int $cacheTtl = 3600;
+
 	/**
 	 * @param array<string, array<string, mixed>> $providers Providers keyed by slug.
+	 * @param \MediaEmbed\Cache\CacheInterface|null $cache Optional cache for persisting domain index.
+	 * @param int $cacheTtl Cache TTL in seconds.
 	 */
-	public function __construct(array $providers = []) {
+	public function __construct(array $providers = [], ?CacheInterface $cache = null, int $cacheTtl = 3600) {
 		$this->providers = $providers;
+		$this->cache = $cache;
+		$this->cacheTtl = $cacheTtl;
 	}
 
 	/**
@@ -49,6 +71,25 @@ public function setProviders(array $providers) {
 		$this->indexBuilt = false;
 		$this->domainIndex = [];
 
+		// Clear cached index when providers change
+		if ($this->cache !== null) {
+			$this->cache->delete(static::CACHE_KEY);
+		}
+
+		return $this;
+	}
+
+	/**
+	 * Set the cache implementation.
+	 *
+	 * @param \MediaEmbed\Cache\CacheInterface|null $cache Cache implementation.
+	 * @param int $ttl Cache TTL in seconds.
+	 * @return $this
+	 */
+	public function setCache(?CacheInterface $cache, int $ttl = 3600) {
+		$this->cache = $cache;
+		$this->cacheTtl = $ttl;
+
 		return $this;
 	}
 
@@ -118,6 +159,17 @@ private function buildIndexIfNeeded(): void {
 			return;
 		}
 
+		// Try to load from cache first
+		if ($this->cache !== null) {
+			$cached = $this->cache->get(static::CACHE_KEY);
+			if (is_array($cached)) {
+				$this->domainIndex = $cached;
+				$this->indexBuilt = true;
+
+				return;
+			}
+		}
+
 		$this->domainIndex = [];
 
 		foreach ($this->providers as $slug => $provider) {
@@ -136,6 +188,11 @@ private function buildIndexIfNeeded(): void {
 			}
 		}
 
+		// Store in cache
+		if ($this->cache !== null) {
+			$this->cache->set(static::CACHE_KEY, $this->domainIndex, $this->cacheTtl);
+		}
+
 		$this->indexBuilt = true;
 	}
 

src/MediaEmbed.php

@@ -10,6 +10,7 @@
 use MediaEmbed\Matcher\UrlMatcher;
 use MediaEmbed\Object\MediaObject;
 use MediaEmbed\Provider\PhpFileLoader;
+use MediaEmbed\Provider\ProviderCollection;
 use MediaEmbed\Provider\ProviderConfig;
 use MediaEmbed\Provider\ProviderLoaderInterface;
 use URLify;
@@ -508,6 +509,18 @@ public function getProviderOrFail(string $alias): ProviderConfig {
 		return ProviderConfig::fromArray($host);
 	}
 
+	/**
+	 * Get all providers as a collection.
+	 *
+	 * @param array<string> $whitelist Optional list of slugs to include.
+	 * @return \MediaEmbed\Provider\ProviderCollection
+	 */
+	public function getProviders(array $whitelist = []): ProviderCollection {
+		$hosts = $this->getHosts($whitelist);
+
+		return ProviderCollection::fromArray(array_values($hosts));
+	}
+
 	/**
 	 * Add a provider using ProviderConfig DTO.
 	 *