php-framework/FINDINGS.md

FINDINGS: Core PHP Framework Assessment

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

Executive Summary

The Core PHP Framework is in good baseline health with solid fundamentals but significant test coverage gaps. The codebase demonstrates mature architectural patterns with event-driven module loading and lazy instantiation. Quality metrics show zero current failures but identify substantial technical debt in test coverage and static analysis configuration.

Health Score: 6.5/10

Strengths:

• ✅ All 197 tests passing (100% pass rate)
• ✅ Zero lint violations (Pint)
• ✅ Zero static analysis errors (PHPStan Level 1)
• ✅ Modern architecture (event-driven, lazy loading)
• ✅ Good code formatting standards

Weaknesses:

• ⚠️ Low test coverage: 11.6% (63/542 files)
• ⚠️ PHPStan running at minimum level (1 of 9)
• ⚠️ Critical packages completely untested (CDN, Media, SEO, Storage)
• ⚠️ Many error categories ignored in static analysis
• ⚠️ PHP version mismatch (8.3.6 vs 8.3.16+ required by psalm)

---

1. Environment Assessment

1.1 Initial State

Branch: dev (origin/dev) Git Status: Clean working tree Composer Lock: Missing (regenerated during install)

1.2 PHP Environment

Version: PHP 8.3.6 Missing Extensions (initial):

• ext-dom
• ext-curl
• ext-xml
• ext-mbstring
• ext-zip
• ext-sqlite3
• ext-gd

Resolution: All extensions installed successfully via apt-get.

Issue Identified: PHP 8.3.6 is below the minimum required by `vimeo/psalm` (requires ~8.3.16). This is a Ubuntu package repository limitation - 8.3.6 is the latest available in Ubuntu 24.04 stable repositories.

Workaround Applied: Used `--ignore-platform-req=php` to complete installation.

Recommendation: Either:

1. Remove or relax psalm version constraint, OR
2. Use PHP PPA for newer 8.3.x versions, OR
3. Document this as a known limitation for Ubuntu 24.04 LTS environments

1.3 Composer Dependencies

Status: ✅ Installed successfully Total Packages: 176 (lock file created) Framework Version: Laravel 12.52.0 PHPUnit Version: 11.5.55 PHPStan Version: 2.1.39 Psalm Version: 6.15.1

Security: Roave security-advisories already integrated ✅

---

2. Test Suite Assessment

2.1 Test Execution Results

Command: `vendor/bin/phpunit --testdox` Result: ✅ PASS

Statistics:

• Tests: 197
• Assertions: 393
• Failures: 0
• Errors: 0
• Warnings: 1 (code coverage driver not available)
• Time: 1.176 seconds
• Memory: 50.50 MB

2.2 Test Distribution

Feature Tests (tests/Feature/):

• Activity Log Service: 14 tests
• Admin Menu Registry: 12 tests
• Event Audit Log: 10 tests
• Input: 4 tests
• Lazy Module Listener: 10 tests
• Lifecycle Event Provider: 9 tests
• Lifecycle Events: 21 tests
• Logs Activity Trait: 12 tests
• Module Registry: 12 tests
• Module Scanner: 16 tests
• Pro: 16 tests
• Sanitiser: 26 tests
• Seeder Discovery: 16 tests
• Seeder Registry: 15 tests

Co-located Tests:

• src/Core/Bouncer/Tests/: 3 test files
• src/Core/Config/Tests/: 1 test file
• src/Core/Front/Tests/: 1 test file
• src/Core/Input/Tests/: 1 test file
• src/Core/Service/Tests/: 3 test files
• src/Mod/Trees/Tests/: 9 test files

2.3 Test Quality Observations

Positive Patterns:

• Comprehensive assertions (average 2 per test)
• Good use of test doubles and mocking
• Feature tests use Orchestra Testbench correctly
• Tests follow AAA pattern (Arrange, Act, Assert)
• Good test naming (descriptive, readable)

Missing Coverage:

• No tests for critical business logic (CDN, Media, SEO)
• No integration tests for cross-module workflows
• No performance tests for caching/optimisation
• Limited error path testing
• No security-specific test suite

---

3. Code Quality Assessment

3.1 Laravel Pint (Linter)

Command: `vendor/bin/pint --test` Result: ✅ PASS

Output: `{"result":"pass"}`

Analysis: Codebase adheres perfectly to Laravel Pint's PSR-12 based coding standards. No formatting issues detected.

3.2 PHPStan (Static Analysis)

Command: `vendor/bin/phpstan analyse --memory-limit=512M` Result: ✅ PASS (with caveats)

Configuration (phpstan.neon):

level: 1  # Lowest level (0-9 available)
paths:
  - src

Errors: 0 (at level 1)

Files Analysed: 515

Critical Concerns:

3.2.1 Ignored Error Categories

ignoreErrors:
  - '#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

Analysis: These ignored categories mask potentially serious issues:

• `new static` usage may hide LSP violations
• `env()` calls outside config violate Laravel best practices
• Unused traits may indicate dead code
• Deprecated function usage needs tracking
• Missing class/method references may break at runtime

Risk Level: Medium - these could hide real bugs

3.2.2 Excluded Paths

excludePaths:
  - 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

Analysis: Test directories are appropriately excluded, but:

• `src/Core/Activity` exclusion is concerning (production code)
• `src/Mod/Trees` exclusion may hide issues in the best-tested module

Recommendation: Review Activity package exclusion reason, consider removing Trees exclusion.

3.3 PHPStan Level Analysis

Current Level: 1 (out of 9)

What Level 1 Checks:

• Basic unknown classes
• Unknown functions
• Unknown methods on `$this`
• Wrong number of arguments passed to methods

What's NOT Checked (Levels 2-9):

• Unknown properties
• Unknown magic methods
• Possibly undefined variables
• Unknown array keys
• Unreachable code
• Type checking
• Strict type checking
• Mixed type restrictions
• Strict rules

Impact: Running at level 1 provides minimal type safety. Critical type errors, null pointer issues, and unreachable code remain undetected.

---

4. Architecture Patterns Discovered

4.1 Event-Driven Module Loading

Pattern: Modules declare interest in lifecycle events via static `$listens` arrays and are only instantiated when those events fire.

Implementation:

LifecycleEventProvider::register()
  └── ModuleScanner::scan()        # Finds Boot.php with $listens
  └── ModuleRegistry::register()   # Wires LazyModuleListener for each event

Benefits:

• Web requests don't load admin modules
• API requests don't load web modules
• Lazy instantiation reduces memory footprint
• Clear separation of concerns

Quality: ✅ Well-designed, modern Laravel approach

4.2 Frontages System

Pattern: ServiceProviders in `src/Core/Front/` fire context-specific lifecycle events.

Frontages Discovered:

Frontage	Event	Middleware	Context
Web	`WebRoutesRegistering`	`web`	Public routes
Admin	`AdminPanelBooting`	`admin`	Admin panel
Api	`ApiRoutesRegistering`	`api`	REST endpoints
Client	`ClientRoutesRegistering`	`client`	Authenticated SaaS
Cli	`ConsoleBooting`	-	Artisan commands
Mcp	`McpToolsRegistering`	-	MCP tool handlers

Quality: ✅ Excellent separation of concerns, enables selective module loading

4.3 L1 Package Structure

Pattern: Subdirectories under `src/Core/` are self-contained packages with:

• Own Boot.php (module entry point)
• Own migrations
• Own tests (co-located)
• Own views

Packages Identified:

• Activity (8 files) - Activity logging wrapper for spatie/laravel-activitylog
• Bouncer (14 files) - Security blocking/redirects
• Cdn (20 files) - CDN integration (BunnyCDN, Flux)
• Config (36 files) - Dynamic configuration system
• Front (266 files) - Frontage system + Blade components
• Lang (15 files) - Translation system
• Media (23 files) - Media handling with thumbnails
• Search (7 files) - Search functionality
• Seo (19 files) - SEO utilities (OG images, sitemaps)
• Storage (9 files) - Cache resilience, circuit breakers

Quality: ✅ Good modular organisation, follows Laravel package conventions

4.4 Actions Pattern

Pattern: Single-purpose business logic classes with static `run()` helper.

Example:

class CreateOrder
{
    use Action;

    public function __construct(private OrderService $orders) {}

    public function handle(User $user, array $data): Order
    {
        return $this->orders->create($user, $data);
    }
}

// Usage: CreateOrder::run($user, $validated);

Quality: ✅ Clean, testable, follows command pattern

4.5 Seeder Ordering System

Pattern: Seeders use PHP attributes for dependency ordering.

Attributes:

• `#[SeederPriority(50)]` - Lower runs first
• `#[SeederAfter(OtherSeeder::class)]` - Dependency ordering
• `#[SeederBefore(OtherSeeder::class)]` - Reverse dependency

Quality: ✅ Elegant solution to seeder ordering problem, prevents circular dependencies

4.6 HLCRF Layout System

Pattern: Data-driven layouts with five regions (Header, Left, Content, Right, Footer).

Usage:

$page = Layout::make('HCF')  // Header-Content-Footer
    ->h(view('header'))
    ->c($content)
    ->f(view('footer'));

Variants: C, HCF, HLCF, HLCRF

Quality: ✅ Flexible, declarative layout system

---

5. Test Coverage Analysis

5.1 Overall Statistics

Total PHP Files: 542 Test Files: 63 Coverage: 11.6%

Breakdown:

• Core packages: 327 files, 9 tests (2.8%)
• Mod/Trees: 19 files, 9 tests (47.4%)
• Other: 196 files, 45 tests (22.9%)

5.2 Zero Coverage Packages (Critical Risk)

CDN Package (20 files, 0%)

Business Impact: HIGH - Infrastructure for global asset delivery

Untested Components:

• `BunnyCdnService.php` - BunnyCDN API integration
• `FluxCdnService.php` - FluxCDN integration
• `StorageOffload.php` - Asset offloading logic
• Console commands: PushAssetCommand, MigrateAssetsCommand
• Middleware: RewriteCdnUrls, RedirectToCdn

Risk: CDN failures could cause widespread asset delivery issues. No automated validation of:

• API authentication
• File upload/sync logic
• URL rewriting correctness
• Failover behaviour

---

Media Package (23 files, 0%)

Business Impact: HIGH - User uploads, image processing

Untested Components:

• `ImageOptimizer.php` - Image compression/optimisation
• Video thumbnail generation
• Image resizing pipeline
• Temporary file management
• Media conversion queue jobs

Risk: Image processing bugs could corrupt user uploads, cause data loss, or create security vulnerabilities (malicious file uploads).

---

SEO Package (19 files, 0%)

Business Impact: HIGH - Search engine visibility, social sharing

Untested Components:

• OG image generation
• Schema.org structured data validation
• Sitemap generation
• Meta tag controllers

Risk: SEO bugs directly impact business visibility and traffic. Broken OG images harm social media sharing. Invalid schema.org markup reduces search rankings.

---

Storage Package (9 files, 0%)

Business Impact: HIGH - Performance, reliability

Untested Components:

• `ResilientRedisStore.php` - Redis failover logic
• `TieredCache.php` - Multi-tier caching
• Circuit breaker pattern implementation
• Cache warming system

Risk: Cache failures could cascade to database overload. Circuit breaker bugs could prevent recovery from transient failures. No validation of failover logic.

---

Config System (36 files, 3%)

Business Impact: MEDIUM - Dynamic configuration

Untested Components:

• `ConfigService.php` - Config CRUD operations
• `ConfigResolver.php` - Config value resolution
• Console commands (8 commands)
• Models: ConfigKey, ConfigValue, ConfigProfile, ConfigVersion

Risk: Configuration bugs could break multi-tenancy, prevent feature flag changes, or corrupt config state.

---

5.3 Partial Coverage Packages

Bouncer (14 files, 21%)

Current Tests: 3 Missing Tests: 11 Components: Security blocking, IP filtering, user agent detection

Front Package (266 files, 0.4%)

Current Tests: 1 (device detection) Note: Contains many Blade view components that may not require unit tests Strategy: Focus on feature tests for key user flows instead of testing every component

Service Package (9 files, 33%)

Current Tests: 3 Missing Tests: 6 Components: Core framework services

---

5.4 Well-Tested Reference: Trees Module

Coverage: 47% (9 tests for 19 files)

Test Structure:

• `TreePlantingTest.php` - Feature test for planting functionality
• `TreeReferralTest.php` - Feature test for referral system
• `TreeApiTest.php` - API endpoint tests
• `TreeQueueTest.php` - Queue job tests
• `AgentDetectionTest.php` - User agent detection

Quality Observations:

• Well-structured feature tests
• Good use of factories and seeders
• Comprehensive assertions
• Tests both happy path and error cases

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

---

6. Dependency Concerns

6.1 PHP Version Mismatch

Issue: `vimeo/psalm ^6.14` requires PHP ~8.3.16+ Environment: PHP 8.3.6 (Ubuntu 24.04 LTS latest) Impact: Cannot update psalm without PHP upgrade Workaround: Using `--ignore-platform-req=php`

Options:

1. Use Ondřej Surý PPA for PHP 8.3.16+
2. Relax psalm version constraint
3. Remove psalm in favour of PHPStan-only approach
4. Accept platform requirement override

6.2 Missing Curl Extension Warning

Warning: "Composer is operating significantly slower than normal because you do not have the PHP curl extension enabled." Resolution: Installed `php8.3-curl` Impact: Fixed after installation

6.3 Missing Unzip Warning

Warning: "As there is no 'unzip' nor '7z' command installed zip files are being unpacked using the PHP zip extension." Impact: Minor - may cause invalid corrupted archive reports, loses UNIX permissions Recommendation: Install `unzip` package

6.4 Code Coverage Driver

Warning: "No code coverage driver available" Impact: Cannot generate coverage reports Resolution: Install Xdebug or PCOV extension Priority: Medium (needed for Phase 2 coverage assessment)

---

7. Quality Issues Identified

7.1 Critical

1. CDN Package Untested - High business risk
2. Media Processing Untested - Data loss risk, security risk
3. SEO System Untested - Business visibility risk
4. Storage/Caching Untested - Reliability risk

7.2 High

5. Config System Undertested - 1 test for 36 files
6. PHPStan Level Too Low - Minimal type checking at level 1
7. Many Error Categories Ignored - Masks potential bugs
8. PHP Version Mismatch - Psalm incompatibility

7.3 Medium

9. Front Package Undertested - 266 files, 1 test (many are Blade components)
10. Bouncer Package Partially Tested - Security component needs full coverage
11. Code Coverage Tooling Missing - Cannot measure actual coverage percentage
12. Activity Package Excluded from PHPStan - Production code not analysed

7.4 Low

13. Missing Unzip Utility - Minor performance impact
14. Helper Functions Untested - 16 utility files
15. Search Functionality Untested - 7 files
16. Language/Translation Untested - 15 files

---

8. Security Observations

8.1 Positive Findings

✅ Input Sanitisation: `Sanitiser.php` has comprehensive tests (26 tests)

• Strips null bytes
• Strips control characters
• Preserves safe characters (newlines, tabs)
• Unicode normalisation
• Nested array handling

✅ Security Advisories: Roave security-advisories integrated in composer.json

✅ Activity Logging: `LogsActivityTrait` tested (12 tests) for audit trail

8.2 Security Gaps Requiring Review

⚠️ File Upload Handling (Media package): Zero tests

• No validation of file type checking
• No validation of malicious file detection
• No validation of path traversal prevention

⚠️ CDN Security (Cdn package): Zero tests

• No validation of signed URL generation
• No validation of token authentication
• No validation of access control

⚠️ Bouncer/Gate (Security package): 21% coverage

• Incomplete testing of authorisation logic
• No tests for privilege escalation prevention
• No tests for IP blocking/filtering edge cases

⚠️ Encryption (Crypt package): Zero tests

• No validation of encryption algorithm usage
• No validation of key management
• No validation of secure random generation

⚠️ Headers/CORS (Headers package): Zero tests

• No validation of CSP configuration
• No validation of CORS rules
• No validation of security headers

8.3 Security Recommendations

Immediate Actions:

1. Test file upload validation and sanitisation (Phase 4A.2)
2. Test authorisation logic in Bouncer/Gate (Phase 4B.1)
3. Review encryption implementation (Phase 4C.1)

Future Actions: 4. Security audit of CDN access controls 5. Penetration testing of file upload endpoints 6. Review of all `env()` calls outside config (currently ignored by PHPStan)

---

9. Architecture Quality Assessment

9.1 Strengths

✅ Event-Driven Design: Excellent separation of concerns ✅ Lazy Loading: Modules only loaded when needed ✅ Frontage System: Clean context separation (Web/Admin/API/etc) ✅ L1 Package Structure: Self-contained, modular, follows Laravel conventions ✅ Actions Pattern: Testable, single-responsibility business logic ✅ Seeder Ordering: Elegant dependency management with attributes ✅ HLCRF Layouts: Flexible, declarative layout system

9.2 Concerns

⚠️ Front Package Size: 266 files (49% of codebase) in single package

• May benefit from further subdivision
• Many are Blade components (acceptable)
• Consider extracting major subsystems

⚠️ Test Co-location: Inconsistent approach

• Some packages use `Tests/` subdirectory (good)
• Some have no tests at all
• Main `tests/` directory duplicates structure
• Recommendation: Standardise on co-located tests

⚠️ Activity Package Excluded: Production code excluded from PHPStan

• Review exclusion reason
• Consider fixing issues instead of excluding

---

10. Compliance & Standards

10.1 Coding Standards

✅ PSR-12: Full compliance via Laravel Pint ✅ UK English: Specified in CLAUDE.md (colour, organisation, centre) ✅ Strict Types: `declare(strict_types=1);` required per CLAUDE.md ✅ Type Hints: All parameters and return types required per CLAUDE.md ✅ License: EUPL-1.2 specified in composer.json

10.2 Laravel Standards

✅ Service Providers: Properly structured ✅ Facades: Not overused (good) ✅ Eloquent Models: Follow conventions ✅ Migrations: Present in L1 packages ✅ Orchestra Testbench: Correctly integrated

10.3 Testing Standards

✅ PHPUnit 11: Latest version ✅ Test Naming: Descriptive, follows conventions ✅ Test Structure: AAA pattern (Arrange, Act, Assert) ⚠️ Coverage: Only 11.6% (below industry standard 80%)

---

11. Performance Considerations

11.1 Positive Patterns

✅ Lazy Module Loading: Reduces memory footprint ✅ Resilient Redis Store: Failover support for cache ✅ Tiered Caching: Multi-level cache strategy ✅ Circuit Breaker: Prevents cascade failures ✅ CDN Integration: Offloads static assets

11.2 Performance Risks (Untested)

⚠️ Cache Failover Logic: No tests for `ResilientRedisStore` ⚠️ Circuit Breaker: No tests for circuit breaker pattern ⚠️ Image Optimisation: No tests for `ImageOptimizer` ⚠️ CDN Offload: No tests for `StorageOffload`

Impact: Performance optimisations may have bugs that cause:

• Cache stampedes
• Database overload during cache failures
• Image processing bottlenecks
• CDN sync failures

Recommendation: Prioritise testing Storage and Media packages in Phase 2A.

---

12. Recommendations Summary

12.1 Immediate Actions (Week 1)

1. ✅ Install code coverage driver (Xdebug or PCOV)
2. ✅ Install unzip utility (`sudo apt-get install unzip`)
3. ✅ Resolve PHP version mismatch (choose one approach from 6.1)
4. ✅ Baseline documentation (commit TODO.md and FINDINGS.md)

12.2 Phase 2 Priorities (Weeks 2-7)

Critical Packages (Phase 2A - 210 hours):

1. CDN Package (40 hours)
2. Config System (60 hours)
3. Media Processing (45 hours)
4. SEO System (35 hours)
5. Storage/Caching (30 hours)

Success Criteria:

• All critical packages have 80%+ test coverage
• Business logic fully validated
• Security vulnerabilities identified and tested

12.3 Phase 3 Priorities (Weeks 8-9)

PHPStan Improvements (73 hours):

1. Incrementally increase to level 6
2. Remove ignored error categories
3. Remove excluded paths (except tests)
4. Enable strict type checking

Success Criteria:

• PHPStan level 6+ with zero errors
• No ignored categories
• Production code not excluded

12.4 Phase 4 Priorities (Weeks 10-12)

Security Review (113 hours):

1. Input validation and file uploads (35 hours)
2. Authentication and authorisation (25 hours)
3. Encryption and data security (20 hours)
4. Infrastructure security (18 hours)
5. Dependency audit (15 hours)

Success Criteria:

• Security audit report completed
• Zero high-severity vulnerabilities
• All inputs validated
• Encryption properly implemented

---

13. Risk Assessment

13.1 High Risk

Risk	Impact	Likelihood	Mitigation
CDN failures cause asset delivery issues	High	Medium	Test CDN package (Phase 2A.1)
Image processing corrupts uploads	High	Medium	Test Media package (Phase 2A.3)
Cache failures cause DB overload	High	Low	Test Storage package (Phase 2A.5)
File upload security vulnerabilities	High	Medium	Security review (Phase 4A.2)
Authorisation bypasses	High	Low	Test Bouncer + review (Phase 4B)

13.2 Medium Risk

Risk	Impact	Likelihood	Mitigation
SEO bugs reduce search visibility	Medium	Medium	Test SEO package (Phase 2A.4)
Config errors break multi-tenancy	Medium	Low	Test Config package (Phase 2A.2)
Type errors at runtime	Medium	Medium	Increase PHPStan level (Phase 3)
Dependency vulnerabilities	Medium	Low	Regular audits (Phase 4E)

13.3 Low Risk

Risk	Impact	Likelihood	Mitigation
Helper function bugs	Low	Low	Test helpers (Phase 2B.2)
Search functionality bugs	Low	Low	Test search (Phase 2B.3)
Translation bugs	Low	Low	Test i18n (Phase 2B.4)

---

14. Conclusion

The Core PHP Framework demonstrates mature architectural design with event-driven module loading, lazy instantiation, and well-structured L1 packages. The code quality is high with zero lint violations and clean formatting.

However, significant technical debt exists in test coverage (11.6%) and static analysis configuration (PHPStan level 1). Critical business packages (CDN, Media, SEO, Storage) have zero test coverage, creating high risk for production deployments.

The 16-week improvement plan outlined in TODO.md provides a realistic roadmap to:

1. Achieve 80%+ test coverage
2. Increase PHPStan to level 6+
3. Complete security review
4. Address all high and medium risks

The framework has solid foundations and with focused effort on test coverage and security review, can achieve production-grade quality standards.

Overall Assessment: Good potential, requires investment in testing and security validation.

---

Appendix A: File Count by Package

Package	PHP Files	Test Files	Coverage %
Front	266	1	0.4%
Config	36	1	2.8%
Media	23	0	0%
CDN	20	0	0%
Seo	19	0	0%
Mod/Trees	19	9	47.4%
Events	16	0	0%
Helpers	16	0	0%
Lang	15	0	0%
Bouncer	14	3	21.4%
Headers	11	0	0%
Storage	9	0	0%
Service	9	3	33.3%
Activity	8	0	0%
Console	7	0	0%
Database	7	0	0%
Search	7	0	0%
Mail	5	0	0%
Input	2	1	50%
Crypt	2	0	0%
Rules	2	0	0%
TOTAL	542	63	11.6%

---

Appendix B: Environment Details

Operating System: Ubuntu 24.04 LTS (Noble) Kernel: Linux 6.8.0-100-generic PHP: 8.3.6 (cli) Composer: 2.x Git: Installed Node: 22.x (via nodesource) Docker: Available

PHP Extensions Installed:

• dom, curl, xml, mbstring, zip, sqlite3, gd
• calendar, ctype, exif, ffi, fileinfo, ftp
• gettext, iconv, phar, posix, readline, shmop
• sockets, sysvmsg, sysvsem, sysvshm, tokenizer

PHP Extensions Missing:

• xdebug (for code coverage)
• pcov (alternative for code coverage)

---

End of Assessment Report