core/php-framework
8
0
Fork 0
Code Issues 2 Pull requests Projects Releases Packages Wiki Activity Actions
php-framework/TODO.md
Clotho 742e53a9e3 docs(#2): add phase 0 assessment findings and TODO 
- 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>
2026-02-20 02:02:26 +00:00

13 KiB
Raw Blame History

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.