core/php-admin
8
0
Fork 0
Code Issues 12 Pull requests Projects Releases Packages Wiki Activity Actions

roadmap: php-admin production readiness checklist #19

New issue
Closed
opened 2026-02-20 02:43:17 +00:00 by Clotho · 1 comment
Clotho commented 2026-02-20 02:43:17 +00:00
Member
Copy link

Overview

Comprehensive roadmap for bringing php-admin to production-ready state.

This roadmap aggregates all findings from automated codebase scan (issue #3) into actionable categories.

🔴 Critical Priority

Type Safety (Issues #5, #6)

  • Add declare(strict_types=1) to 20+ PHP files (#5)
  • Add missing return type hints to 18+ methods (#6)
  • Add missing parameter type hints to query scopes

Impact: Prevents type coercion bugs, improves IDE support

Security - Error Handling (Issues #9, #10, #11)

  • Add error handling to Settings modal methods (#9)
    • updateProfile() - wrap in try-catch
    • updatePreferences() - use DB transactions
    • updatePassword() - add session regeneration
    • requestAccountDeletion() - handle mail failures
  • Add error handling to PlatformUser modal (#10)
    • saveTier() - catch ValueError from enum cast
    • exportUserData() - handle large datasets
    • Log invalid tab attempts (security)
  • Add error handling to SearchProviderRegistry (#11)
    • Graceful degradation when provider fails
    • Error logging for debugging

Impact: Prevents crashes, data loss, improves reliability

🟠 High Priority

Test Coverage (Issues #7, #8)

  • Add tests for 30+ admin modal components (#7)
    • PlatformUser - tier changes, exports, provisioning
    • ServiceManager - CRUD operations
    • WaitlistManager - export, filtering
    • Settings - profile, password, preferences, deletion
    • 25+ other modal components
  • Add unit tests for Model methods (#8)
    • Service model - metadata methods, finders
    • HoneypotHit model - scopes, stats, detection

Impact: Prevents regressions, enables confident refactoring

Security - Rate Limiting & Validation (Issues #12, #13, #14)

  • Add rate limiting to admin actions (#12)
    • Tier changes: 10/minute
    • Profile updates: 20/minute
    • Password changes: 5/minute
    • Data exports: 5/minute
    • Deletion requests: 3/minute
  • Improve TeapotController security (#13)
    • Switch to whitelist-based header sanitization
    • Fix IPv6 localhost detection (::ffff:127.0.0.1)
    • Validate referer URLs
  • Validate JSON metadata fields (#14)
    • Add size limits to Service.metadata (64KB)
    • Limit HoneypotHit.headers count (50 max)
    • Validate metadata keys in setMeta()

Impact: Prevents abuse, DoS, data exfiltration

Stub Implementations (Issues #15, #16, #17)

  • Implement or remove 2FA methods (#15)
    • Decision needed: Native 2FA vs external provider
    • If keeping: implement QR codes, recovery codes, verification
    • If removing: remove UI and stub methods
  • Implement or remove BoostPurchase (#16)
    • Decision needed: Blesta integration vs external payment
    • Add URL validation before redirect
  • Remove empty register() methods (#17)
    • Cleanup: src/Mod/Hub/Boot.php
    • Cleanup: src/Website/Hub/Boot.php

Impact: Removes dead code, clarifies feature status

Documentation (Issue #18)

  • Add PHPDoc to 40+ public methods (#18)
    • PlatformUser methods (15+)
    • Settings methods (10+)
    • ServiceManager, WaitlistManager methods
    • Search algorithm documentation
    • Model scope and static method docs
    • Form component @property annotations

Impact: Improves maintainability, onboarding, IDE support

🟡 Medium Priority

Code Quality

  • Fix PHPStan level 5 errors (from TODO.md)
    • Property type declarations
    • Array shape types
  • Standardize component prop naming (from TODO.md)
    • Audit can/cannot/canAny consistency
    • Add prop validation

Performance

  • Optimize search indexing (from TODO.md)
    • Add search result caching
    • Implement debounced search
    • Profile query performance
  • Optimize menu rendering (from TODO.md)
    • Cache menu structure
    • Lazy load menu icons

🟢 Low Priority / Future Features

From TODO.md:

  • Feature: Data Tables Component (6-8 hours)
  • Feature: Dashboard Widgets (8-10 hours)
  • Feature: Notification Center (6-8 hours)
  • Enhancement: Form Builder (8-10 hours)
  • Enhancement: Activity Feed Component (4-5 hours)
  • Enhancement: File Manager (10-12 hours)
  • Enhancement: Theme Customizer (6-8 hours)
  • Enhancement: Keyboard Shortcuts (4-5 hours)

📊 Summary Statistics

Issues Created from Scan

Category Critical High Medium Low Total
Type Safety 2 0 0 0 2
Security 0 3 3 0 6
Testing 0 2 0 0 2
Error Handling 0 3 0 0 3
Stubs/TODOs 0 3 0 0 3
Documentation 0 1 0 0 1
TOTAL 2 12 3 0 17

Files Analyzed

  • Source files: 102 PHP files
  • Test files: 7 test files
  • Test coverage: ~30% (modal components largely untested)

Key Findings

  • ✅ Strong foundation: Search, forms, menu, layout systems well-tested
  • ⚠️ Missing tests: 30+ modal components lack coverage
  • ⚠️ Type safety: 20+ files missing strict_types, 18+ methods missing return types
  • ⚠️ Error handling: Critical admin operations lack error handling
  • ⚠️ Security: No rate limiting, some validation gaps
  • ⚠️ Stubs: 2FA and BoostPurchase incomplete features exposed to users

🎯 Recommended Approach

Phase 1: Critical Fixes (1-2 days)

  1. Add declare(strict_types=1) to all files (#5)
  2. Add return type hints (#6)
  3. Add error handling to Settings/PlatformUser (#9, #10)
  4. Add SearchProviderRegistry error handling (#11)

Phase 2: Security Hardening (2-3 days)

  1. Implement rate limiting (#12)
  2. Improve TeapotController security (#13)
  3. Add JSON metadata validation (#14)

Phase 3: Stub Resolution (1-2 days)

  1. Decide on 2FA approach and implement/remove (#15)
  2. Decide on BoostPurchase and implement/remove (#16)
  3. Remove empty register() methods (#17)

Phase 4: Testing & Documentation (3-5 days)

  1. Add modal component tests (#7)
  2. Add model unit tests (#8)
  3. Add PHPDoc to public methods (#18)

Phase 5: Future Enhancements (as needed)

  1. Data tables, widgets, notifications (from TODO.md)

Total estimated effort: 7-12 days to production-ready

Related Issues

  • #3 - Discovery scan (parent task)
  • #5 - Add strict_types declarations
  • #6 - Add return type hints
  • #7 - Test admin modal components
  • #8 - Test model methods
  • #9 - Error handling: Settings
  • #10 - Error handling: PlatformUser
  • #11 - Error handling: SearchProviderRegistry
  • #12 - Security: Rate limiting
  • #13 - Security: TeapotController
  • #14 - Security: Metadata validation
  • #15 - Stub: 2FA methods
  • #16 - Stub: BoostPurchase
  • #17 - Refactor: Empty register() methods
  • #18 - Documentation: PHPDoc

Discovered by

Automatic codebase scan (issue #3) - February 2026

## Overview Comprehensive roadmap for bringing php-admin to production-ready state. This roadmap aggregates all findings from automated codebase scan (issue #3) into actionable categories. --- ## 🔴 Critical Priority ### Type Safety (Issues #5, #6) - [ ] Add `declare(strict_types=1)` to 20+ PHP files (#5) - [ ] Add missing return type hints to 18+ methods (#6) - [ ] Add missing parameter type hints to query scopes **Impact:** Prevents type coercion bugs, improves IDE support ### Security - Error Handling (Issues #9, #10, #11) - [ ] Add error handling to Settings modal methods (#9) - [ ] updateProfile() - wrap in try-catch - [ ] updatePreferences() - use DB transactions - [ ] updatePassword() - add session regeneration - [ ] requestAccountDeletion() - handle mail failures - [ ] Add error handling to PlatformUser modal (#10) - [ ] saveTier() - catch ValueError from enum cast - [ ] exportUserData() - handle large datasets - [ ] Log invalid tab attempts (security) - [ ] Add error handling to SearchProviderRegistry (#11) - [ ] Graceful degradation when provider fails - [ ] Error logging for debugging **Impact:** Prevents crashes, data loss, improves reliability --- ## 🟠 High Priority ### Test Coverage (Issues #7, #8) - [ ] Add tests for 30+ admin modal components (#7) - [ ] PlatformUser - tier changes, exports, provisioning - [ ] ServiceManager - CRUD operations - [ ] WaitlistManager - export, filtering - [ ] Settings - profile, password, preferences, deletion - [ ] 25+ other modal components - [ ] Add unit tests for Model methods (#8) - [ ] Service model - metadata methods, finders - [ ] HoneypotHit model - scopes, stats, detection **Impact:** Prevents regressions, enables confident refactoring ### Security - Rate Limiting & Validation (Issues #12, #13, #14) - [ ] Add rate limiting to admin actions (#12) - [ ] Tier changes: 10/minute - [ ] Profile updates: 20/minute - [ ] Password changes: 5/minute - [ ] Data exports: 5/minute - [ ] Deletion requests: 3/minute - [ ] Improve TeapotController security (#13) - [ ] Switch to whitelist-based header sanitization - [ ] Fix IPv6 localhost detection (::ffff:127.0.0.1) - [ ] Validate referer URLs - [ ] Validate JSON metadata fields (#14) - [ ] Add size limits to Service.metadata (64KB) - [ ] Limit HoneypotHit.headers count (50 max) - [ ] Validate metadata keys in setMeta() **Impact:** Prevents abuse, DoS, data exfiltration ### Stub Implementations (Issues #15, #16, #17) - [ ] Implement or remove 2FA methods (#15) - **Decision needed:** Native 2FA vs external provider - If keeping: implement QR codes, recovery codes, verification - If removing: remove UI and stub methods - [ ] Implement or remove BoostPurchase (#16) - **Decision needed:** Blesta integration vs external payment - Add URL validation before redirect - [ ] Remove empty register() methods (#17) - Cleanup: src/Mod/Hub/Boot.php - Cleanup: src/Website/Hub/Boot.php **Impact:** Removes dead code, clarifies feature status ### Documentation (Issue #18) - [ ] Add PHPDoc to 40+ public methods (#18) - [ ] PlatformUser methods (15+) - [ ] Settings methods (10+) - [ ] ServiceManager, WaitlistManager methods - [ ] Search algorithm documentation - [ ] Model scope and static method docs - [ ] Form component @property annotations **Impact:** Improves maintainability, onboarding, IDE support --- ## 🟡 Medium Priority ### Code Quality - [ ] Fix PHPStan level 5 errors (from TODO.md) - [ ] Property type declarations - [ ] Array shape types - [ ] Standardize component prop naming (from TODO.md) - [ ] Audit can/cannot/canAny consistency - [ ] Add prop validation ### Performance - [ ] Optimize search indexing (from TODO.md) - [ ] Add search result caching - [ ] Implement debounced search - [ ] Profile query performance - [ ] Optimize menu rendering (from TODO.md) - [ ] Cache menu structure - [ ] Lazy load menu icons --- ## 🟢 Low Priority / Future Features From TODO.md: - [ ] Feature: Data Tables Component (6-8 hours) - [ ] Feature: Dashboard Widgets (8-10 hours) - [ ] Feature: Notification Center (6-8 hours) - [ ] Enhancement: Form Builder (8-10 hours) - [ ] Enhancement: Activity Feed Component (4-5 hours) - [ ] Enhancement: File Manager (10-12 hours) - [ ] Enhancement: Theme Customizer (6-8 hours) - [ ] Enhancement: Keyboard Shortcuts (4-5 hours) --- ## 📊 Summary Statistics ### Issues Created from Scan | Category | Critical | High | Medium | Low | Total | |----------|----------|------|--------|--------|-------| | Type Safety | 2 | 0 | 0 | 0 | **2** | | Security | 0 | 3 | 3 | 0 | **6** | | Testing | 0 | 2 | 0 | 0 | **2** | | Error Handling | 0 | 3 | 0 | 0 | **3** | | Stubs/TODOs | 0 | 3 | 0 | 0 | **3** | | Documentation | 0 | 1 | 0 | 0 | **1** | | **TOTAL** | **2** | **12** | **3** | **0** | **17** | ### Files Analyzed - **Source files:** 102 PHP files - **Test files:** 7 test files - **Test coverage:** ~30% (modal components largely untested) ### Key Findings - ✅ **Strong foundation:** Search, forms, menu, layout systems well-tested - ⚠️ **Missing tests:** 30+ modal components lack coverage - ⚠️ **Type safety:** 20+ files missing strict_types, 18+ methods missing return types - ⚠️ **Error handling:** Critical admin operations lack error handling - ⚠️ **Security:** No rate limiting, some validation gaps - ⚠️ **Stubs:** 2FA and BoostPurchase incomplete features exposed to users --- ## 🎯 Recommended Approach ### Phase 1: Critical Fixes (1-2 days) 1. Add `declare(strict_types=1)` to all files (#5) 2. Add return type hints (#6) 3. Add error handling to Settings/PlatformUser (#9, #10) 4. Add SearchProviderRegistry error handling (#11) ### Phase 2: Security Hardening (2-3 days) 5. Implement rate limiting (#12) 6. Improve TeapotController security (#13) 7. Add JSON metadata validation (#14) ### Phase 3: Stub Resolution (1-2 days) 8. Decide on 2FA approach and implement/remove (#15) 9. Decide on BoostPurchase and implement/remove (#16) 10. Remove empty register() methods (#17) ### Phase 4: Testing & Documentation (3-5 days) 11. Add modal component tests (#7) 12. Add model unit tests (#8) 13. Add PHPDoc to public methods (#18) ### Phase 5: Future Enhancements (as needed) 14. Data tables, widgets, notifications (from TODO.md) **Total estimated effort:** 7-12 days to production-ready --- ## Related Issues - #3 - Discovery scan (parent task) - #5 - Add strict_types declarations - #6 - Add return type hints - #7 - Test admin modal components - #8 - Test model methods - #9 - Error handling: Settings - #10 - Error handling: PlatformUser - #11 - Error handling: SearchProviderRegistry - #12 - Security: Rate limiting - #13 - Security: TeapotController - #14 - Security: Metadata validation - #15 - Stub: 2FA methods - #16 - Stub: BoostPurchase - #17 - Refactor: Empty register() methods - #18 - Documentation: PHPDoc --- ## Discovered by Automatic codebase scan (issue #3) - February 2026
Clotho added the
review
discovery
 labels 2026-02-20 02:43:17 +00:00
Charon added
PHP
P3
 and removed
review
discovery
 labels 2026-02-20 12:16:53 +00:00
Charon commented 2026-02-20 12:17:50 +00:00
Member
Copy link

Closing roadmap tracker — individual issues are labelled and triaged. Track progress via P1/P2/P3 labels.

— Charon

Closing roadmap tracker — individual issues are labelled and triaged. Track progress via P1/P2/P3 labels. — Charon
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
security/validate-json-metadata
security/improve-teapot-sanitization
security/rate-limit-admin-actions
dev
No results found.
Labels
Clear labels   
P1

Priority 1 - Critical

  
P2

Priority 2 - Important

  
P3

Priority 3 - Nice to have

  
PHP

PHP codebase

  
agent-ready

   
bug

Bug fix

  
clotho

Assigned to Clotho AI agent

  
discovery

Auto-discovered by agent

  
docs

Documentation

  
epic

   
refactor

Code quality refactoring

  
review

Needs human review

  
security

Security hardening

  
testing

Test coverage

  
athena

Assign to Athena AI agent (M3 Ultra)

  
athena-gemini

Dispatch to Gemini CLI on M3 Ultra

  
audit

Code audit task

  
clotho

Assign to Clotho AI agent for processing

  
clotho-gemini

Dispatch to Gemini CLI on darbs (AU)

  
codex

Dispatch to Codex CLI on gateway for analysis

  
darbs-claude

Dispatch to Claude on darbs (AU)

  
security

Security review task

  
wiki

Documentation/wiki update

No labels
P1
P2
P3
PHP
agent-ready
bug
clotho
discovery
docs
epic
refactor
review
security
testing
athena
athena-gemini
audit
clotho
clotho-gemini
codex
darbs-claude
security
wiki
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: core/php-admin#19
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?