feat(core): refactor to dependency injection pattern with adapter fallbacks

- Add 8 interfaces for pool/cache abstraction (PSR-11 compatible)
- Implement 10+ adapters with fallback mechanisms
- Refactor 7 core classes to use DI (Request, Response, Factory, etc)
- Add HttpPoolFacade for single entry point to pools
- Protect BC aliases with class_exists() checks
- Update phpstan.neon with necessary suppressions
- All 550 tests passing, quality checks passing
- Maintain BC until v3.0.0 when aliases will be removed

Author: CAFernandes

CLAUDE.md

@@ -199,7 +199,7 @@ pivotphp-core/
 
 3. **Middleware Pipeline** (`src/Middleware/`): PSR-15 compliant middleware system organized by responsibility
    - **Security**: `src/Middleware/Security/` - AuthMiddleware, CsrfMiddleware, XssMiddleware, SecurityHeadersMiddleware
-   - **Performance**: `src/Middleware/Performance/` - CacheMiddleware, RateLimitMiddleware  
+   - **Performance**: `src/Middleware/Performance/` - CacheMiddleware, RateLimitMiddleware
    - **HTTP**: `src/Middleware/Http/` - CorsMiddleware, ErrorMiddleware
    - **Core**: `src/Middleware/Core/` - BaseMiddleware, MiddlewareInterface
    - **Advanced**: LoadShedder, TrafficClassifier
@@ -211,7 +211,7 @@ pivotphp-core/
 5. **Performance Components**:
    - **JSON Optimization**: `JsonBufferPool`, `JsonBuffer` (v1.1.1)
    - **Pool Management**: `DynamicPoolManager` (consolidated in v1.1.2)
-   - **Memory Management**: `MemoryManager` 
+   - **Memory Management**: `MemoryManager`
    - **Performance Monitoring**: `PerformanceMonitor` (unified in v1.1.2)
    - **Distributed Coordination**: `DistributedPoolManager`
 
@@ -369,7 +369,7 @@ When creating new middleware, follow the organized structure:
 // Security middleware
 namespace PivotPHP\Core\Middleware\Security;
 
-// Performance middleware  
+// Performance middleware
 namespace PivotPHP\Core\Middleware\Performance;
 
 // HTTP protocol middleware
@@ -483,4 +483,4 @@ $app->use(new ApiDocumentationMiddleware([
 ### Architectural Foundation (v1.1.2+)
 - Organized middleware structure while maintaining full backward compatibility
 - All performance optimizations from v1.1.1 and v1.1.0 are preserved and enhanced
-- Migration to new namespace structure is recommended but optional
+- Migration to new namespace structure is recommended but optional

composer.json

@@ -66,6 +66,7 @@
         "ext-mbstring": "Required for proper string handling",
         "ext-fileinfo": "Required for file upload validation",
         "ext-apcu": "For caching middleware and performance optimization",
+        "pivotphp/performance-tools": "Separate package with advanced pooling, caching, and middleware compilation (v2.2.0+)",
         "pivotphp/cycle-orm": "Database ORM integration for PivotPHP",
         "pivotphp/reactphp": "Async runtime extension for continuous execution"
     },
@@ -75,7 +76,8 @@
         },
         "files": [
             "src/functions.php",
-            "src/aliases.php"
+            "src/aliases.php",
+            "src/aliases-performance-tools.php"
         ]
     },
     "autoload-dev": {

docs/PERFORMANCE-TOOLS-MIGRATION.md

@@ -0,0 +1,186 @@
+# Performance Tools Migration Guide
+
+## Overview
+
+A partir da versão 2.2.0, os componentes de performance do PivotPHP foram migrados para um pacote separado: **`pivotphp/performance-tools`**.
+
+Esta mudança permite:
+- ✅ **Modularização**: Performance tools como pacote independente
+- ✅ **Compatibilidade BC**: Aliases automáticos até v3.0.0
+- ✅ **Injeção de Dependências**: Interfaces e adapters para flexibilidade
+- ✅ **Manutenção**: Separação clara de responsabilidades
+
+## Migrated Components
+
+| Component | Location | New Package |
+|-----------|----------|-------------|
+| Psr7Pool | `PivotPHP\Core\Http\Pool` | `PivotPHP\PerformanceTools\Http\Psr7\Pool` |
+| PoolManager | `PivotPHP\Core\Http\Psr7\Pool` | `PivotPHP\PerformanceTools\Http\Psr7\Pool` |
+| ResponsePool | `PivotPHP\Core\Http\Psr7\Pool` | `PivotPHP\PerformanceTools\Http\Psr7\Pool` |
+| HeaderPool | `PivotPHP\Core\Http\Psr7\Pool` | `PivotPHP\PerformanceTools\Http\Psr7\Pool` |
+| EnhancedStreamPool | `PivotPHP\Core\Http\Psr7\Pool` | `PivotPHP\PerformanceTools\Http\Psr7\Pool` |
+| OperationsCache | `PivotPHP\Core\Http\Psr7\Cache` | `PivotPHP\PerformanceTools\Http\Psr7\Cache` |
+| JsonBufferPool | `PivotPHP\Core\Json\Pool` | `PivotPHP\PerformanceTools\Json\Pool` |
+| JsonBuffer | `PivotPHP\Core\Json\Pool` | `PivotPHP\PerformanceTools\Json\Pool` |
+| MiddlewarePipelineCompiler | `PivotPHP\Core\Middleware` | `PivotPHP\PerformanceTools\Middleware` |
+| SerializationCache | `PivotPHP\Core\Utils` | `PivotPHP\PerformanceTools\Utils` |
+
+## Backward Compatibility (v2.2.0 - v2.9.x)
+
+**No breaking changes!** O PivotPHP Core v2.2.0+ inclui aliases automáticos que redirecionam as classes antigas para o novo pacote.
+
+### Old Code (Still Works)
+
+```php
+use PivotPHP\Core\Http\Pool\Psr7Pool;
+use PivotPHP\Core\Http\Psr7\Pool\PoolManager;
+use PivotPHP\Core\Json\Pool\JsonBufferPool;
+
+// Funciona exatamente como antes
+$pool = Psr7Pool::getServerRequest(...);
+```
+
+### New Code (Recommended)
+
+```php
+use PivotPHP\PerformanceTools\Http\Psr7\Pool\Psr7Pool;
+use PivotPHP\PerformanceTools\Http\Psr7\Pool\PoolManager;
+use PivotPHP\PerformanceTools\Json\Pool\JsonBufferPool;
+
+// Mesmo funcionamento, namespaces claros
+$pool = Psr7Pool::getServerRequest(...);
+```
+
+## Installation
+
+### For Development/Optional Performance
+
+```bash
+# Install pivotphp/performance-tools if not already included
+composer require pivotphp/performance-tools
+```
+
+### For Production
+
+O PivotPHP Core mantém cópias injetáveis das interfaces para permitir que aplicações funcionem sem o pacote performance-tools. Para máxima performance, instale o pacote:
+
+```bash
+composer require pivotphp/performance-tools
+```
+
+## Interfaces & Adapters
+
+O Core v2.2.0 introduz interfaces e adapters para permitir injeção de dependências sem criar dependências rígidas:
+
+### Interfaces (em `src/Contracts/`)
+
+- `JsonOptimizerInterface`
+- `Psr7PoolInterface`
+- `ResponsePoolInterface`
+- `HeaderPoolInterface`
+- `StreamPoolInterface`
+- `OperationsCacheInterface`
+- `SerializationCacheInterface`
+- `MiddlewarePipelineCompilerInterface`
+
+### Adapters (em `src/Http/Adapters/`, `src/Json/Adapters/`, etc.)
+
+Os adapters implementam as interfaces e delegam para as classes do PerformanceTools quando disponíveis, ou caem de volta para implementações simples quando o pacote não está instalado.
+
+## Architecture Changes
+
+### Before (v2.1.x)
+
+```
+Core
+├── Http/Pool/Psr7Pool
+├── Http/Psr7/Pool/PoolManager
+├── Json/Pool/JsonBufferPool
+├── Middleware/MiddlewarePipelineCompiler
+└── Utils/SerializationCache
+```
+
+### After (v2.2.0+)
+
+```
+Core
+├── Contracts/ (Interfaces)
+├── Adapters/ (Delegates to PerformanceTools)
+└── aliases-performance-tools.php (BC)
+
+PerformanceTools (Separate Package)
+├── Http/Psr7/Pool/ (Psr7Pool, PoolManager, ResponsePool, etc.)
+├── Http/Psr7/Cache/ (OperationsCache)
+├── Json/Pool/ (JsonBufferPool, JsonBuffer)
+├── Middleware/ (MiddlewarePipelineCompiler)
+└── Utils/ (SerializationCache)
+```
+
+## Dependency Injection
+
+A injeção de dependências agora funciona via interfaces e adapters:
+
+### Example: Custom Psr7Pool Implementation
+
+```php
+use PivotPHP\Core\Contracts\Psr7PoolInterface;
+use PivotPHP\Core\Http\Facades\HttpPoolFacade;
+
+class CustomPool implements Psr7PoolInterface {
+    // Implementação customizada
+}
+
+// Injetar no façade
+HttpPoolFacade::setPool(new CustomPool());
+
+// Ou via PoolManager
+PoolManager::setResponsePool(...);
+PoolManager::setHeaderPool(...);
+```
+
+## Migration v2.x → v3.0.0
+
+Na v3.0.0, as aliases serão removidas. Para preparar seu código:
+
+### Step 1: Update Imports
+
+```php
+// Old
+use PivotPHP\Core\Http\Pool\Psr7Pool;
+
+// New
+use PivotPHP\PerformanceTools\Http\Psr7\Pool\Psr7Pool;
+```
+
+### Step 2: Ensure performance-tools is Installed
+
+```bash
+composer require pivotphp/performance-tools
+```
+
+### Step 3: Test Your Application
+
+```bash
+composer test
+```
+
+## Deprecation Timeline
+
+| Version | Status | Notes |
+|---------|--------|-------|
+| v2.1.x | ✅ Current | All in Core |
+| v2.2.0 - v2.9.x | ✅ Supported | Aliases available, new package recommended |
+| v3.0.0 | ⚠️ Upcoming | Aliases removed, performance-tools required |
+
+## Support
+
+For issues or questions about the migration:
+
+1. Check the [PerformanceTools documentation](../pivotphp-performance-tools/README.md)
+2. Review [Core Contracts](src/Contracts/)
+3. Open an issue on GitHub
+
+## See Also
+
+- [PerformanceTools README](../pivotphp-performance-tools/README.md)
+- [Architecture Decision Record: Performance Tools Package Separation](./docs/adr-001-performance-tools-separation.md)

RELEASE_v1.2.0.md docs/releases/v1.2.0/RELEASE_v1.2.0.mdRELEASE_v1.2.0.md renamed to docs/releases/v1.2.0/RELEASE_v1.2.0.md

@@ -1,5 +1,6 @@
 parameters:
     level: 9
+    treatPhpDocTypesAsCertain: false
     paths:
         - src
     excludePaths:
@@ -11,7 +12,11 @@ parameters:
         - '#Call to an undefined method [a-zA-Z0-9\\_]+::[a-zA-Z0-9_]+\(\)#'
         - '#Access to an undefined property [a-zA-Z0-9\\_]+::\$[a-zA-Z0-9_]+#'
         - '#Parameter \#[0-9]+ \$[a-zA-Z0-9_]+ of method [a-zA-Z0-9\\_]+::[a-zA-Z0-9_]+\(\) expects [^,]+, [^,]+ given#'
+        - '#Parameter \#[0-9]+ \$[a-zA-Z0-9_]+ of static method [a-zA-Z0-9\\_]+::[a-zA-Z0-9_]+\(\) expects [^,]+, [^,]+ given#'
         - '#Method [a-zA-Z0-9\\_]+::[a-zA-Z0-9_]+\(\) has parameter \$[a-zA-Z0-9_]+ with no value type specified in iterable type array#'
         - '#Method [a-zA-Z0-9\\_]+::[a-zA-Z0-9_]+\(\) return type has no value type specified in iterable type array#'
         - '#Property [a-zA-Z0-9\\_]+::\$[a-zA-Z0-9_]+ type has no value type specified in iterable type array#'
         - '#Call to an undefined static method Express\\Routing\\Router::(getGroupStats|warmupGroups|identifyByGroup|benchmarkGroupAccess|warmupCache)\(\)#'
+        - '#Else branch is unreachable because ternary operator condition is always#'
+        - '#Result of && is always#'
+        - '#Cannot cast mixed to string#'

phpstan.neon

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PivotPHP\Core\Contracts;
+
+/**
+ * Interface para otimização de JSON
+ *
+ * Abstrai a implementação de pooling de buffers JSON,
+ * permitindo que o core funcione sem performance-tools.
+ */
+interface JsonOptimizerInterface
+{
+    /**
+     * Codificar dados para JSON com otimização
+     *
+     * @param mixed $data Dados a codificar
+     * @param int $flags Flags de encoding
+     * @return string JSON codificado
+     */
+    public function encodeJson(mixed $data, int $flags = 0): string;
+
+    /**
+     * Verificar se deve usar otimizações
+     *
+     * @param mixed $data Dados a verificar
+     * @return bool True se deve otimizar
+     */
+    public function shouldOptimize(mixed $data): bool;
+
+    /**
+     * Obter estatísticas de uso
+     *
+     * @return array Estatísticas do optimizer
+     */
+    public function getStats(): array;
+
+    /**
+     * Aquecer cache de buffers
+     *
+     * @return void
+     */
+    public function warmUp(): void;
+
+    /**
+     * Limpar todos os caches
+     *
+     * @return void
+     */
+    public function clearCache(): void;
+}

src/Contracts/JsonOptimizerInterface.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PivotPHP\Core\Contracts;
+
+use Psr\Http\Message\ServerRequestInterface;
+use PivotPHP\Core\Http\Response;
+
+/**
+ * Interface para compilador de middleware pipeline
+ *
+ * Abstrai compilação otimizada de pipelines de middleware.
+ */
+interface MiddlewarePipelineCompilerInterface
+{
+    /**
+     * Compilar pipeline de middlewares em callable
+     *
+     * @param string $cacheKey Chave do cache
+     * @param array $middlewares Array de middlewares
+     * @return callable Pipeline compilado
+     */
+    public function compilePipeline(string $cacheKey, array $middlewares): callable;
+
+    /**
+     * Obter pipeline compilado do cache
+     *
+     * @param string $cacheKey Chave do cache
+     * @return callable|null Pipeline compilado ou null se não existe
+     */
+    public function getCompiledPipeline(string $cacheKey): ?callable;
+
+    /**
+     * Aquecer cache com padrões comuns
+     *
+     * @return void
+     */
+    public function warmUp(): void;
+
+    /**
+     * Limpar cache compilado
+     *
+     * @return void
+     */
+    public function clearCache(): void;
+
+    /**
+     * Obter estatísticas
+     *
+     * @return array
+     */
+    public function getStats(): array;
+}