feat: atualizar documentação dos middlewares com descrições e informações de versão

Author: CAFernandes

README.md

@@ -15,7 +15,7 @@
 
 **PivotPHP** é um microframework moderno, leve e seguro, inspirado no Express.js, para construir APIs e aplicações web de alta performance em PHP. Ideal para validação de conceitos, estudos e desenvolvimento de aplicações que exigem produtividade, arquitetura desacoplada e extensibilidade real.
 
-- **Alta Performance**: 1.32M+ ops/sec total throughput, 837K ops/sec JSON processing, 505K ops/sec small JSON, apenas 1.61MB memory footprint (v1.1.1 Revolutionary JSON Edition).
+- **Performance Competitiva**: 6,227 req/sec em ambiente Docker controlado (3º lugar em validação comparativa), 837K ops/sec JSON processing interno, 505K ops/sec small JSON, apenas 1.61MB memory footprint (v1.1.1 Revolutionary JSON Edition).
 - **Arquitetura Moderna**: DI Container, Service Providers, Event System, Extension System e PSR-15.
 - **Segurança**: Middlewares robustos para CSRF, XSS, Rate Limiting, JWT, API Key e mais.
 - **Extensível**: Sistema de plugins, hooks, providers e integração PSR-14.
@@ -210,7 +210,7 @@ $app->get('/api/users', function($req, $res) {
     $users = User::all(); // 1000+ usuários
 
     // Automaticamente usa pooling para datasets grandes
-    return $res->json($users); // 505K ops/sec (pequenos), 119K ops/sec (médios), 214K ops/sec (grandes)
+    return $res->json($users); // 505K ops/sec (pequenos), 119K ops/sec (médios), 214K ops/sec (grandes) - Benchmarks internos
 });
 
 // Controle manual para casos específicos
@@ -240,7 +240,7 @@ echo "Operations: {$stats['total_operations']}";
 **Características da Otimização JSON:**
 - ✅ **Detecção automática** - ativa pooling para arrays 10+ elementos, objetos 5+ propriedades
 - ✅ **Fallback inteligente** - dados pequenos usam `json_encode()` tradicional
-- ✅ **505K ops/sec** (pequenos), **119K ops/sec** (médios), **214K ops/sec** (grandes) em testes validados
+- ✅ **505K ops/sec** (pequenos), **119K ops/sec** (médios), **214K ops/sec** (grandes) em benchmarks internos
 - ✅ **100% reuso** de buffers em cenários de alta frequência
 - ✅ **Zero configuração** - funciona automaticamente com código existente
 - ✅ **Monitoramento integrado** - estatísticas detalhadas para otimização

src/Middleware/Http/ErrorMiddleware.php

@@ -12,6 +12,15 @@
 use PivotPHP\Core\Http\Psr7\Stream;
 use Throwable;
 
+/**
+ * Error Handling Middleware
+ *
+ * Catches and handles exceptions that occur during request processing,
+ * providing appropriate error responses and logging.
+ *
+ * @package PivotPHP\Core\Middleware\Http
+ * @since 1.1.2
+ */
 class ErrorMiddleware implements MiddlewareInterface
 {
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface

src/Middleware/Performance/CacheMiddleware.php

@@ -9,6 +9,15 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * Cache Middleware
+ *
+ * Provides HTTP response caching to improve application performance
+ * by storing and serving cached responses for repeated requests.
+ *
+ * @package PivotPHP\Core\Middleware\Performance
+ * @since 1.1.2
+ */
 class CacheMiddleware implements MiddlewareInterface
 {
     private int $ttl;

src/Middleware/Security/CsrfMiddleware.php

@@ -11,6 +11,15 @@
 use PivotPHP\Core\Http\Psr7\Response;
 use PivotPHP\Core\Http\Psr7\Stream;
 
+/**
+ * CSRF Protection Middleware
+ *
+ * Provides Cross-Site Request Forgery (CSRF) protection by validating
+ * tokens in form submissions and AJAX requests.
+ *
+ * @package PivotPHP\Core\Middleware\Security
+ * @since 1.1.2
+ */
 class CsrfMiddleware implements MiddlewareInterface
 {
     private string $fieldName;

src/Middleware/Security/SecurityHeadersMiddleware.php

@@ -9,8 +9,24 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * Security Headers Middleware
+ *
+ * Adds essential security headers to HTTP responses including
+ * X-Frame-Options, X-Content-Type-Options, and X-XSS-Protection.
+ *
+ * @package PivotPHP\Core\Middleware\Security
+ * @since 1.1.2
+ */
 class SecurityHeadersMiddleware implements MiddlewareInterface
 {
+    /**
+     * Process the request and add security headers to the response
+     *
+     * @param ServerRequestInterface $request The incoming request
+     * @param RequestHandlerInterface $handler The request handler
+     * @return ResponseInterface The response with security headers
+     */
     public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
     {
         $response = $handler->handle($request);
@@ -20,6 +36,12 @@ public function process(ServerRequestInterface $request, RequestHandlerInterface
             ->withHeader('X-XSS-Protection', '1; mode=block');
     }
 
+    /**
+     * Create a new instance of the middleware
+     *
+     * @param array $options Configuration options (currently unused)
+     * @return self New middleware instance
+     */
     public static function create(array $options = []): self
     {
         return new self();

src/Middleware/Security/XssMiddleware.php

@@ -9,6 +9,15 @@
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
+/**
+ * XSS Protection Middleware
+ *
+ * Provides protection against Cross-Site Scripting (XSS) attacks by
+ * sanitizing request input and adding appropriate security headers.
+ *
+ * @package PivotPHP\Core\Middleware\Security
+ * @since 1.1.2
+ */
 class XssMiddleware implements MiddlewareInterface
 {
     private string $allowedTags;