docs: Add usage examples to cache attributes

- Add practical examples to HttpCache, Cacheable, Purge, Refresh
- Add class-level examples to DonutCache and CacheableResponse
- Show URI template placeholders usage in Purge/Refresh
- Demonstrate CDN cache configuration patterns in HttpCache

Author: koriym

src-annotation/Cacheable.php

@@ -13,6 +13,18 @@
  * For event-driven cache invalidation based on resource dependencies, use
  * #[CacheableResponse] or #[DonutCache] instead.
  *
+ * Example:
+ * ```php
+ * // Cache for 1 hour
+ * #[Cacheable(expirySecond: 3600)]
+ *
+ * // Cache with predefined expiry preset
+ * #[Cacheable(expiry: 'short')]  // short, medium, long, never
+ *
+ * // Cache until specific time from body field
+ * #[Cacheable(expiryAt: 'expires_at')]
+ * ```
+ *
  * Interceptors bound:
  * - CacheInterceptor (onGet methods)
  * - CommandInterceptor (onPut/onPatch/onDelete methods)

src-annotation/CacheableResponse.php

@@ -16,6 +16,18 @@
  * The entire response is cached and receives an ETag for conditional requests,
  * enabling 304 (Not Modified) responses to reduce network transfer costs.
  *
+ * Example:
+ * ```php
+ * #[CacheableResponse]
+ * class Article extends ResourceObject
+ * {
+ *     public function onGet(int $id): static
+ *
+ *     #[RefreshCache]
+ *     public function onDelete(int $id): static
+ * }
+ * ```
+ *
  * Interceptors bound:
  * - DonutCacheableResponseInterceptor (onGet methods when applied to class)
  * - DonutCommandInterceptor (onPut/onPatch/onDelete methods when applied to class)

src-annotation/DonutCache.php

@@ -15,6 +15,16 @@
  * which uses TTL-based expiration, this enables tag-based invalidation. Only
  * cacheable portions are stored; no ETag is generated for the entire response.
  *
+ * Example:
+ * ```php
+ * #[DonutCache]
+ * class BlogPosting extends ResourceObject
+ * {
+ *     #[Embed(rel: 'comment', src: 'app://self/comments')]
+ *     public function onGet(int $id): static
+ * }
+ * ```
+ *
  * Interceptors bound:
  * - DonutCacheInterceptor (onGet methods when applied to class, or any method when applied to method)
  *

src-annotation/HttpCache.php

@@ -15,6 +15,18 @@
  *
  * Builds a complex Cache-Control header
  *
+ * Example:
+ * ```php
+ * // CDN cache for 1 hour, browser cache for 5 minutes
+ * #[HttpCache(maxAge: 300, sMaxAge: 3600)]
+ *
+ * // Private cache with revalidation
+ * #[HttpCache(isPrivate: true, mustRevalidate: true, maxAge: 60)]
+ *
+ * // No caching (use NoHttpCache instead for simplicity)
+ * #[HttpCache(noCache: true, noStore: true)]
+ * ```
+ *
  * Interceptors bound:
  * - HttpCacheInterceptor (onGet methods)
  *

src-annotation/Purge.php

@@ -9,6 +9,13 @@
 /**
  * Purges cache for specified URI after command execution
  *
+ * Example:
+ * ```php
+ * #[Purge(uri: 'app://self/user/profile?user_id={id}')]
+ * #[Purge(uri: 'app://self/user/friend?user_id={id}')]
+ * public function onDelete(int $id): static
+ * ```
+ *
  * Interceptors bound:
  * - RefreshInterceptor (when applied to non-Cacheable classes)
  * - CommandInterceptor (when applied to Cacheable classes)

src-annotation/Refresh.php

@@ -9,6 +9,12 @@
 /**
  * Refreshes cache for specified URI after command execution
  *
+ * Example:
+ * ```php
+ * #[Refresh(uri: 'app://self/user/profile?user_id={id}')]
+ * public function onPut(int $id, string $name): static
+ * ```
+ *
  * Interceptors bound:
  * - RefreshInterceptor (when applied to non-Cacheable classes)
  * - CommandInterceptor (when applied to Cacheable classes)