Merge pull request #167 from bearsunday/attribute-interceptor-docs

Document cache attributes and interceptors

Author: koriym

src-annotation/Cacheable.php

@@ -6,6 +6,31 @@
 
 use Attribute;
 
+/**
+ * Marks a resource class as cacheable with TTL-based expiration
+ *
+ * Traditional time-based caching where cache expires after a specified duration.
+ * 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)
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#cacheable
+ */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class Cacheable
 {

src-annotation/CacheableResponse.php

@@ -5,14 +5,42 @@
 namespace BEAR\RepositoryModule\Annotation;
 
 use Attribute;
-use BEAR\QueryRepository\DonutCacheableResponseInterceptor;
 use BEAR\QueryRepository\DonutCacheModule;
-use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
+ * Enables event-driven cache invalidation for fully cacheable responses
+ *
+ * For content that is fundamentally static but changes predictably via resource
+ * methods (onPut, onDelete, etc.). Unlike #[Cacheable] which uses TTL-based
+ * expiration, this enables tag-based invalidation driven by resource dependencies.
+ * 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)
+ * - DonutCacheInterceptor (when applied to method)
+ *
  * @see DonutCacheModule
- * @see DonutCacheableResponseInterceptor
- * @see DonutCommandInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class CacheableResponse

src-annotation/DonutCache.php

@@ -6,12 +6,33 @@
 
 use Attribute;
 use BEAR\QueryRepository\DonutCacheModule;
-use BEAR\QueryRepository\DonutCommandInterceptor;
 
 /**
+ * Enables event-driven donut caching for resources with non-cacheable embedded content
+ *
+ * For content that is fundamentally static but changes predictably via resource
+ * methods, with some embedded resources that cannot be cached. Unlike #[Cacheable]
+ * 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)
+ *
  * @see DonutCacheModule
- * @see DonutCacheInterceptor
- * @see DonutCommandInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#donut-cache
  */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_CLASS)]
 final class DonutCache

src-annotation/HttpCache.php

@@ -15,7 +15,28 @@
  *
  * Builds a complex Cache-Control header
  *
+ * Example:
+ * ```php
+ * // Cache for 1 hour
+ * #[HttpCache(maxAge: 3600)]
+ *
+ * // Cache with revalidation when stale
+ * #[HttpCache(maxAge: 3600, mustRevalidate: true)]
+ *
+ * // Private cache (not shared cache like CDN)
+ * #[HttpCache(isPrivate: true, maxAge: 300)]
+ *
+ * // CDN cache for 1 hour, browser cache for 5 minutes
+ * #[HttpCache(maxAge: 300, sMaxAge: 3600)]
+ *
+ * // For disabling cache, use #[NoHttpCache] instead
+ * ```
+ *
+ * Interceptors bound:
+ * - HttpCacheInterceptor (onGet methods)
+ *
  * @see HttpCacheInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html
  */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class HttpCache extends AbstractCacheControl

src-annotation/NoHttpCache.php

@@ -12,7 +12,11 @@
  *
  * Simplified notation to say that you don't want anything cached
  *
+ * Interceptors bound:
+ * - HttpCacheInterceptor (onGet methods)
+ *
  * @see HttpCacheInterceptor
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html
  */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class NoHttpCache extends AbstractCacheControl

src-annotation/Purge.php

@@ -6,7 +6,27 @@
 
 use Attribute;
 
-/** @see RefreshInterceptor */
+/**
+ * Purges cache for specified URI after command execution
+ *
+ * Behavior differs based on class attributes:
+ * - **#[Cacheable] classes**: CommandInterceptor automatically binds to all
+ *   command methods (onPut/onPatch/onDelete) and processes #[Purge] annotations
+ * - **Non-Cacheable classes**: RefreshInterceptor binds only to methods explicitly
+ *   marked with #[Purge] or #[Refresh]
+ *
+ * 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
+ * {
+ *     // ...
+ * }
+ * ```
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#tag-based-cache-invalidation
+ */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
 final class Purge extends AbstractCommand
 {

src-annotation/Refresh.php

@@ -5,9 +5,27 @@
 namespace BEAR\RepositoryModule\Annotation;
 
 use Attribute;
-use BEAR\QueryRepository\RefreshInterceptor;
 
-/** @see RefreshInterceptor */
+/**
+ * Refreshes cache for specified URI after command execution
+ *
+ * Behavior differs based on class attributes:
+ * - **#[Cacheable] classes**: CommandInterceptor automatically binds to all
+ *   command methods (onPut/onPatch/onDelete) and processes #[Refresh] annotations
+ * - **Non-Cacheable classes**: RefreshInterceptor binds only to methods explicitly
+ *   marked with #[Purge] or #[Refresh]
+ *
+ * Example:
+ * ```php
+ * #[Refresh(uri: 'app://self/user/profile?user_id={id}')]
+ * public function onPut(int $id, string $name): static
+ * {
+ *     // ...
+ * }
+ * ```
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#event-driven-content
+ */
 #[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
 final class Refresh extends AbstractCommand
 {

src-annotation/RefreshCache.php

@@ -5,9 +5,15 @@
 namespace BEAR\RepositoryModule\Annotation;
 
 use Attribute;
-use BEAR\QueryRepository\DonutCommandInterceptor;
 
-/** @see DonutCommandInterceptor */
+/**
+ * Refreshes donut cache after command execution
+ *
+ * Interceptors bound:
+ * - DonutCacheInterceptor
+ *
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#cache-invalidation
+ */
 #[Attribute(Attribute::TARGET_METHOD)]
 final class RefreshCache
 {

src/CacheInterceptor.php

@@ -17,6 +17,16 @@
 
 use const E_USER_WARNING;
 
+/**
+ * Interceptor for TTL-based caching on CQRS queries with #[Cacheable]
+ *
+ * Bound to query methods (onGet) of classes marked with #[Cacheable].
+ * Retrieves cached resource state if available, otherwise executes
+ * the method and stores the result with configured TTL.
+ *
+ * @see \BEAR\RepositoryModule\Annotation\Cacheable
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#cacheable
+ */
 final readonly class CacheInterceptor implements MethodInterceptor
 {
     public function __construct(

src/CommandInterceptor.php

@@ -12,6 +12,20 @@
 use Ray\Aop\MethodInterceptor;
 use Ray\Aop\MethodInvocation;
 
+/**
+ * Interceptor for cache invalidation on CQRS commands with #[Purge] or #[Refresh]
+ *
+ * Automatically bound to all command methods (onPut/onPatch/onDelete) of #[Cacheable] classes.
+ * Processes #[Purge] and #[Refresh] annotations on these methods and executes cache
+ * invalidation after successful write operations.
+ *
+ * For non-Cacheable classes, use RefreshInterceptor instead by explicitly marking methods
+ * with #[Purge] or #[Refresh].
+ *
+ * @see \BEAR\RepositoryModule\Annotation\Purge
+ * @see \BEAR\RepositoryModule\Annotation\Refresh
+ * @see https://bearsunday.github.io/manuals/1.0/en/cache.html#tag-based-cache-invalidation
+ */
 final readonly class CommandInterceptor implements MethodInterceptor
 {
     /** @param CommandInterface[] $commands */