Sharing here the roadmap proposed by Claude Code for modernizing Minicli while keeping 8.2 compatibility. The PR #114 has initial work on that front, removing deprecation warnings and fixing a few other details for better compatibility with PHP 8.4.

Minicli Improvement Roadmap

Based on analysis of the minicli codebase and current PHP best practices, here are recommended improvements prioritized by impact and effort.

High Priority Improvements

1. Fix Dynamic Property Deprecation

Issue: Test suite shows deprecation warning about dynamic properties in ThemeConfig

Creation of dynamic property Minicli\Output\ThemeConfig::$custom is deprecated

Action: Implement proper property declarations or use __set/__get magic methods
Impact: Fixes PHP 8.2+ compatibility warnings

2. Enhanced Type Safety

Current State: Good use of strict types, but some opportunities for improvement
Improvements:

• Add more specific return types using union types (string|null instead of mixed)
• Consider using 'never' return type for methods that always throw exceptions
• Add generic type hints where applicable (e.g., array<string, mixed>)
• Use more specific array shapes in PHPDoc

Medium Priority Enhancements

3. Modern PHP Attributes for Commands

Current: Array-based command registration
Proposed: PHP 8+ attributes for cleaner command definition

#[Command('help', description: 'Show help information')]
class HelpController extends CommandController
{
    #[Parameter('command', required: false)]
    public function handle(string $command = null): void
    {
        // Implementation
    }
}

Benefits: Better IDE support, cleaner code, self-documenting

4. Dependency Injection Improvements

Current State: Custom DI container with basic functionality
Enhancements:

• Add support for constructor property promotion
• Implement auto-wiring with type hints
• Add circular dependency detection
• Consider lazy loading for services
• Add service tagging and decoration

5. Enhanced Error Handling

Current: Basic exception hierarchy
Improvements:

• Create more specific exception types extending base exceptions
• Add error codes for programmatic handling
• Implement structured error responses with context
• Add error middleware/handlers
• Improve error messages for better UX

Lower Priority Optimizations

6. Performance Enhancements

Opportunities:

• Implement command caching to avoid filesystem scans
• Add lazy loading for themes and services
• Consider using WeakMap for object caches where appropriate
• Optimize reflection usage in DI container
• Benchmark and profile common operations

7. Developer Experience

Enhancements:

• Add PHPDoc templates for common patterns
• Implement command scaffolding/generation tools
• Add debug toolbar or profiling capabilities
• Enhanced IDE support with better type hints
• Add development helper commands

8. Modern PHP Features Adoption

Current: Already uses many modern features (enums, readonly, etc.)
Additional opportunities:

• Use match expressions where appropriate instead of switch
• Consider readonly classes for immutable data structures
• Implement enums for constants where beneficial
• Use named arguments in internal APIs
• Leverage constructor property promotion more widely

9. Testing & Quality Improvements

Current State: Good test coverage with Pest, PHPStan level 9
Enhancements:

• Add mutation testing with Pest's mutation plugin
• Implement integration tests for CLI workflows
• Add performance benchmarks
• Consider property-based testing for complex logic
• Add end-to-end CLI testing scenarios

Architecture Considerations

10. Event System

Proposal: Add a simple event dispatcher for extensibility

$app->on('command.before', fn($command) => /* log command */);
$app->on('command.after', fn($command, $result) => /* cleanup */);

Benefits: Plugin support, better separation of concerns

11. Plugin System

Goal: Create a lightweight plugin architecture for third-party extensions
Features:

• Plugin discovery and loading
• Lifecycle hooks
• Plugin configuration
• Dependency management between plugins

12. Configuration Validation

Current: Basic array-based configuration
Enhancement: Add schema validation for configuration files using modern validation libraries
Benefits: Better error messages, IDE support, documentation

Implementation Strategy

Phase 1: Foundation (High Priority)

1. Fix dynamic property deprecation
2. Enhance type safety across codebase
3. Improve error handling

Phase 2: Modernization (Medium Priority)

1. Implement PHP attributes for commands
2. Enhance DI container
3. Add event system foundation

Phase 3: Experience (Lower Priority)

1. Performance optimizations
2. Developer tooling
3. Plugin system

Phase 4: Advanced Features

1. Advanced testing strategies
2. Configuration validation
3. Extended architecture patterns

Success Metrics

• Zero deprecation warnings on PHP 8.2+
• Improved static analysis scores
• Better IDE support and developer experience
• Maintained or improved performance
• Clean, maintainable codebase
• Strong test coverage (>95%)

Notes

• All changes should maintain backward compatibility where possible
• Each improvement should include tests
• Documentation should be updated with changes
• Consider community feedback on major architectural changes
• Performance benchmarks should be established before optimizations

Generated: 2025-07-23
Based on: minicli codebase analysis and PHP 8.4 upgrade