Clotho
742e53a9e3
- Add comprehensive FINDINGS.md documenting: - Environment assessment (PHP 8.3.6, missing extensions) - Test suite results (197 tests passing, 11.6% coverage) - Code quality analysis (Pint ✅, PHPStan Level 1 ✅) - Architecture patterns (event-driven, frontages, L1 packages) - Test coverage gaps by package - Security observations and risks - Dependency concerns (PHP version mismatch with psalm) - Add detailed TODO.md with phased improvement plan: - Phase 1: Fix failing tests ✅ COMPLETE - Phase 2: Increase coverage to 80%+ (446 hours) - Phase 3: Increase PHPStan to level 6+ (73 hours) - Phase 4: Security review (113 hours) - Total effort: 632 hours (~16 weeks) All tests passing (197/197), zero lint issues, zero static analysis errors at current configuration. Critical gaps identified in CDN, Media, SEO, Storage, and Config packages. Co-Authored-By: Clotho <clotho@lthn.ai>
551 lines
13 KiB
Markdown
551 lines
13 KiB
Markdown
# 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.
|