# TODO: Core PHP Framework Quality Improvement Plan

**Repository**: core/php-framework
**Branch**: dev
**Assessment Date**: 2026-02-20
**Agent**: Clotho

## Executive Summary

The framework is in **good baseline health**:
- ✅ All 197 tests pass
- ✅ Zero lint issues (Pint)
- ✅ Zero static analysis errors (PHPStan Level 1)
- ⚠️ Test coverage: 11.6% (63 test files / 542 PHP files)
- ⚠️ PHPStan running at Level 1 (lowest)

## Phase 1: Fix Failing Tests

**Status**: ✅ COMPLETE

All 197 tests pass successfully:
- 197 tests, 393 assertions
- No failures, no errors
- 1 PHPUnit warning (code coverage driver not available)

**Action Items**: None required - all tests passing.

---

## Phase 2: Increase Coverage to 80%+

**Current Coverage**: 11.6% (63/542 files)
**Target Coverage**: 80% (434 files need tests)
**Priority**: High

### Phase 2A: Critical Business Packages (Priority 1)

These packages are business-critical and require immediate test coverage:

#### 2A.1 CDN Package (20 files, 0% coverage)
**Impact**: Infrastructure for asset delivery
**Files**:
- \`src/Core/Cdn/Services/BunnyCdnService.php\`
- \`src/Core/Cdn/Services/FluxCdnService.php\`
- \`src/Core/Cdn/Services/StorageOffload.php\`
- \`src/Core/Cdn/Console/\` (4 commands)
- \`src/Core/Cdn/Middleware/\` (2 middleware)

**Test Types Needed**:
- Unit tests for services
- Integration tests for storage offload
- Feature tests for console commands
- HTTP tests for middleware

**Estimated Effort**: 40 hours
**Files to Create**: \`src/Core/Cdn/Tests/Feature/\`, \`src/Core/Cdn/Tests/Unit/\`

---

#### 2A.2 Config System (36 files, 3% coverage)
**Impact**: Core configuration management
**Current**: 1 test file for 36 files
**Files**:
- \`src/Core/Config/Services/ConfigService.php\`
- \`src/Core/Config/Services/ConfigResolver.php\`
- \`src/Core/Config/Models/\` (4 models)
- \`src/Core/Config/Console/\` (8 commands)

**Test Types Needed**:
- Unit tests for ConfigService and ConfigResolver
- Model tests for ConfigKey, ConfigValue, ConfigProfile, ConfigVersion
- Feature tests for console commands
- Integration tests for config resolution

**Estimated Effort**: 60 hours
**Files to Create**: Expand \`src/Core/Config/Tests/\`

---

#### 2A.3 Media/Image Processing (23 files, 0% coverage)
**Impact**: Content handling and user uploads
**Files**:
- \`src/Core/Media/Image/ImageOptimizer.php\`
- \`src/Core/Media/Conversion/\` (5 files)
- \`src/Core/Media/Thumbnail/\` (4 files)
- \`src/Core/Media/Temp/\` (2 files)

**Test Types Needed**:
- Unit tests for image optimisation
- Integration tests for conversion pipeline
- Feature tests for thumbnail generation
- Unit tests for temporary file handling

**Estimated Effort**: 45 hours
**Files to Create**: \`src/Core/Media/Tests/Feature/\`, \`src/Core/Media/Tests/Unit/\`

---

#### 2A.4 SEO System (19 files, 0% coverage)
**Impact**: Business visibility and search rankings
**Files**:
- \`src/Core/Seo/OgImage/\` (4 files)
- \`src/Core/Seo/Schema/\` (5 files)
- \`src/Core/Seo/Sitemap/\` (3 files)

**Test Types Needed**:
- Unit tests for OG image generation
- Unit tests for schema validation
- Integration tests for sitemap generation
- HTTP tests for controllers

**Estimated Effort**: 35 hours
**Files to Create**: \`src/Core/Seo/Tests/Feature/\`, \`src/Core/Seo/Tests/Unit/\`

---

#### 2A.5 Storage/Caching (9 files, 0% coverage)
**Impact**: Performance and reliability
**Files**:
- \`src/Core/Storage/Cache/ResilientRedisStore.php\`
- \`src/Core/Storage/Cache/TieredCache.php\`
- \`src/Core/Storage/CircuitBreaker/\` (3 files)

**Test Types Needed**:
- Unit tests for resilient Redis store
- Integration tests for tiered caching
- Unit tests for circuit breaker pattern
- Performance tests for cache warming

**Estimated Effort**: 30 hours
**Files to Create**: \`src/Core/Storage/Tests/Feature/\`, \`src/Core/Storage/Tests/Unit/\`

---

### Phase 2B: Infrastructure Packages (Priority 2)

#### 2B.1 Activity Logging (8 files, 0% coverage)
**Impact**: Audit trail and compliance
**Estimated Effort**: 15 hours

#### 2B.2 Helpers (16 files, 0% coverage)
**Impact**: Widely used utility functions
**Estimated Effort**: 25 hours

#### 2B.3 Search (7 files, 0% coverage)
**Impact**: User-facing functionality
**Estimated Effort**: 15 hours

#### 2B.4 Language/Translation (15 files, 0% coverage)
**Impact**: i18n support
**Estimated Effort**: 20 hours

#### 2B.5 Events System (16 files, 0% coverage)
**Impact**: Core lifecycle events
**Estimated Effort**: 25 hours

---

### Phase 2C: Supporting Components (Priority 3)

#### 2C.1 Headers/Security (11 files, 0% coverage)
**Estimated Effort**: 18 hours

#### 2C.2 Console Commands (7 files, 0% coverage)
**Estimated Effort**: 12 hours

#### 2C.3 Database/Seeders (7 files, 0% coverage)
**Estimated Effort**: 12 hours

#### 2C.4 Mail System (5 files, 0% coverage)
**Estimated Effort**: 10 hours

#### 2C.5 Validation Rules (2 files, 0% coverage)
**Estimated Effort**: 5 hours

#### 2C.6 Encryption/Crypt (2 files, 0% coverage)
**Estimated Effort**: 5 hours

---

### Phase 2D: Improve Existing Coverage

#### 2D.1 Bouncer (14 files, 21% coverage)
**Current**: 3 test files
**Target**: 11 more test files
**Estimated Effort**: 20 hours

#### 2D.2 Front Package (266 files, 0.4% coverage)
**Note**: Many are Blade components that may not need unit tests
**Strategy**: Focus on feature tests for key flows
**Estimated Effort**: 40 hours (selective testing)

#### 2D.3 Input (2 files, 50% coverage)
**Current**: 1 test file
**Target**: 1 more test file
**Estimated Effort**: 2 hours

#### 2D.4 Service (9 files, 33% coverage)
**Current**: 3 test files
**Target**: 6 more test files
**Estimated Effort**: 12 hours

---

### Phase 2 Summary

**Total Estimated Effort**: 446 hours (~11 weeks at 40 hrs/week)

**Recommended Approach**:
1. Start with Phase 2A (critical packages) - 210 hours
2. Move to Phase 2B (infrastructure) - 100 hours
3. Complete Phase 2C (supporting) - 62 hours
4. Finish with Phase 2D (improve existing) - 74 hours

**Success Metrics**:
- Achieve 80%+ test coverage
- All critical business logic covered
- Integration tests for key workflows
- Performance tests for caching/optimisation

---

## Phase 3: Fix All PHPStan Errors

**Current Level**: 1 (lowest)
**Current Errors**: 0
**Target Level**: 6+ (recommended for production)
**Priority**: Medium

### Phase 3A: Gradually Increase PHPStan Level

#### 3A.1 Run PHPStan at Level 2
**Action**: Update \`phpstan.neon\` to \`level: 2\` and fix errors
**Estimated Errors**: 50-100 (typical for level increase)
**Estimated Effort**: 10 hours

#### 3A.2 Run PHPStan at Level 3
**Action**: Update to \`level: 3\` and fix errors
**Estimated Errors**: 30-60
**Estimated Effort**: 8 hours

#### 3A.3 Run PHPStan at Level 4
**Action**: Update to \`level: 4\` and fix errors
**Estimated Errors**: 20-40
**Estimated Effort**: 8 hours

#### 3A.4 Run PHPStan at Level 5
**Action**: Update to \`level: 5\` and fix errors
**Estimated Errors**: 15-30
**Estimated Effort**: 10 hours

#### 3A.5 Run PHPStan at Level 6+
**Action**: Update to \`level: 6\` or higher and fix errors
**Estimated Errors**: 10-25
**Estimated Effort**: 12 hours

---

### Phase 3B: Remove Ignored Error Categories

**Current Ignored Errors**:
\`\`\`
- '#Unsafe usage of new static#'
- '#env\\(\\).*outside of the config directory#'
- identifier: larastan.noEnvCallsOutsideOfConfig
- identifier: trait.unused
- identifier: class.notFound
- identifier: function.deprecated
- identifier: method.notFound
\`\`\`

**Action Items**:
1. Review each ignored category
2. Fix underlying issues
3. Remove from ignore list
4. Re-enable strict checking

**Estimated Effort**: 15 hours

---

### Phase 3C: Remove Excluded Paths

**Current Excluded Paths**:
\`\`\`
- src/Core/Activity
- src/Core/Config/Tests
- src/Core/Input/Tests
- src/Core/Tests
- src/Core/Bouncer/Tests
- src/Core/Bouncer/Gate/Tests
- src/Core/Service/Tests
- src/Core/Front/Tests
- src/Mod/Trees
\`\`\`

**Action**: Remove exclusions and fix errors in excluded paths
**Estimated Effort**: 10 hours

---

### Phase 3 Summary

**Total Estimated Effort**: 73 hours (~2 weeks)

**Recommended Approach**:
1. Complete Phase 2A (critical test coverage) first
2. Incrementally increase PHPStan levels
3. Fix errors at each level before proceeding
4. Remove ignored categories and exclusions last

**Success Metrics**:
- PHPStan Level 6+ with zero errors
- No ignored error categories
- No excluded paths
- Strict type checking enabled

---

## Phase 4: Security Review

**Priority**: High
**Prerequisites**: Phase 2A complete (critical packages tested)

### Phase 4A: Input Validation & Sanitisation

#### 4A.1 Review Input Handling
**Files to Review**:
- \`src/Core/Input/Sanitiser.php\` ✅ (has tests)
- All controllers and form requests
- API endpoints

**Security Checks**:
- XSS prevention
- SQL injection prevention
- Command injection prevention
- Path traversal prevention
- Mass assignment protection

**Estimated Effort**: 20 hours

---

#### 4A.2 Review File Upload Handling
**Files to Review**:
- \`src/Core/Media/\` (all file handling)
- Upload controllers
- Storage configuration

**Security Checks**:
- File type validation
- File size limits
- Malicious file detection
- Storage path security
- CDN upload security

**Estimated Effort**: 15 hours

---

### Phase 4B: Authentication & Authorisation

#### 4B.1 Review Bouncer/Gate System
**Files to Review**:
- \`src/Core/Bouncer/\` (all files)
- \`src/Core/Bouncer/Gate/\` (all files)

**Security Checks**:
- Authorisation logic correctness
- Privilege escalation prevention
- Session security
- CSRF protection

**Estimated Effort**: 15 hours

---

#### 4B.2 Review Authentication Flows
**Files to Review**:
- Login controllers
- Password reset flows
- API authentication

**Security Checks**:
- Brute force protection
- Password strength requirements
- Token expiration
- Multi-factor authentication support

**Estimated Effort**: 10 hours

---

### Phase 4C: Data Security

#### 4C.1 Review Encryption
**Files to Review**:
- \`src/Core/Crypt/\` (all files)
- Any encrypted data storage

**Security Checks**:
- Encryption algorithm strength
- Key management
- Secure random generation
- No hardcoded secrets

**Estimated Effort**: 8 hours

---

#### 4C.2 Review Data Exposure
**Files to Review**:
- API responses
- Error messages
- Log files
- Debug output

**Security Checks**:
- No sensitive data in logs
- No stack traces in production
- API response sanitisation
- Database query obfuscation

**Estimated Effort**: 12 hours

---

### Phase 4D: Infrastructure Security

#### 4D.1 Review Headers & CORS
**Files to Review**:
- \`src/Core/Headers/\` (all files)
- CORS middleware
- CSP configuration

**Security Checks**:
- Security headers present
- CSP properly configured
- CORS restrictions
- XSS protection headers

**Estimated Effort**: 8 hours

---

#### 4D.2 Review CDN Security
**Files to Review**:
- \`src/Core/Cdn/\` (all files)

**Security Checks**:
- Signed URLs for private assets
- Token validation
- Rate limiting
- Hotlink protection

**Estimated Effort**: 10 hours

---

### Phase 4E: Dependency Security

#### 4E.1 Review Composer Dependencies
**Action**: Run \`composer audit\` and review
**Files**: \`composer.json\`, \`composer.lock\`

**Security Checks**:
- Known vulnerabilities in dependencies
- Outdated packages
- Security advisories
- Roave security-advisories integration ✅ (already present)

**Estimated Effort**: 5 hours

---

#### 4E.2 Update Vulnerable Dependencies
**Action**: Update packages with known vulnerabilities
**Estimated Effort**: 10 hours

---

### Phase 4 Summary

**Total Estimated Effort**: 113 hours (~3 weeks)

**Recommended Approach**:
1. Start with Phase 4A (input validation) - critical
2. Move to Phase 4B (auth/authz) - high priority
3. Complete Phase 4C (data security)
4. Review Phase 4D (infrastructure)
5. Finish with Phase 4E (dependencies)

**Success Metrics**:
- All inputs validated and sanitised
- No authorisation bypasses
- Encryption properly implemented
- Security headers configured
- Zero high-severity vulnerabilities
- Security audit report created

---

## Phase 5: Performance Optimisation (Future)

**Priority**: Low
**Prerequisites**: Phases 1-4 complete

### Potential Areas:
- Cache optimisation (already has resilient Redis)
- Query optimisation
- Asset optimisation
- CDN configuration tuning
- Database indexing review

**Estimated Effort**: TBD (requires profiling first)

---

## Appendix: Reference Implementation

The **Trees Module** (\`src/Mod/Trees/\`) serves as an excellent reference for test implementation:
- **Coverage**: 47% (9 tests for 19 files)
- **Test Types**: Feature tests, API tests, queue tests, integration tests
- **Pattern**: Co-located tests in \`Tests/Feature/\` directory
- **Quality**: Well-structured, comprehensive assertions

**Recommendation**: Use Trees module as template when implementing tests for Core packages.

---

## Summary Timeline

| Phase | Effort | Duration | Priority |
|-------|--------|----------|----------|
| Phase 1 | 0 hrs | ✅ Complete | High |
| Phase 2A | 210 hrs | 5-6 weeks | High |
| Phase 2B | 100 hrs | 2-3 weeks | Medium |
| Phase 2C | 62 hrs | 1-2 weeks | Medium |
| Phase 2D | 74 hrs | 2 weeks | Low |
| Phase 3 | 73 hrs | 2 weeks | Medium |
| Phase 4 | 113 hrs | 3 weeks | High |
| **Total** | **632 hrs** | **~16 weeks** | - |

**Recommended Execution Order**:
1. Phase 2A (Critical coverage) - 6 weeks
2. Phase 4A-4B (Critical security) - 2 weeks
3. Phase 3 (PHPStan improvements) - 2 weeks
4. Phase 2B-2D (Complete coverage) - 5 weeks
5. Phase 4C-4E (Complete security) - 1 week

**Total Realistic Timeline**: ~16 weeks (4 months) with one full-time developer.