Hello PHP-FIG Community,
I'd like to propose a modernization enhancement to PSR-3 (Logger Interface)
that would convert the current LogLevel class with string constants to a
PHP 8.1+ backed enum while maintaining backward compatibility.
I have attached an md file to this email that mentions all the details of
the RFC.
I believe this change represents a natural evolution that enhances PSR-3
without compromising the stability and wide adoption that makes it such a
successful standard.
Thank you for your time and consideration. I look forward to the discussion.
Best regards,
Junaid Farooq
--
You received this message because you are subscribed to the Google Groups "PHP
Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/php-fig/88b6a5e1-aab5-4d4a-bb40-c9f199812665n%40googlegroups.com.
# RFC: Convert PSR-3 LogLevel to PHP 8.1+ Enum
**Author:** Junaid Farooq
**Date:** August 25, 2025
**Target:** PSR-3 Logger Interface
**Proposed Version:** 4.0.0 (Major version due to PHP version requirement change)
## Summary
This RFC proposes converting the PSR-3 `LogLevel` class with string constants to a modern PHP 8.1+ backed enum
while maintaining backward compatibility for string values and usage patterns.
## Current State
```php
class LogLevel
{
const EMERGENCY = 'emergency';
const ALERT = 'alert';
const CRITICAL = 'critical';
const ERROR = 'error';
const WARNING = 'warning';
const NOTICE = 'notice';
const INFO = 'info';
const DEBUG = 'debug';
}
```
## Proposed Change
```php
enum LogLevel: string
{
case EMERGENCY = 'emergency';
case ALERT = 'alert';
case CRITICAL = 'critical';
case ERROR = 'error';
case WARNING = 'warning';
case NOTICE = 'notice';
case INFO = 'info';
case DEBUG = 'debug';
}
```
## Motivation
### 1. Type Safety
- Enums provide compile-time type checking
- Prevents invalid log level values at the type system level
- Better static analysis support
### 2. Modern PHP Standards
- PHP 8.1+ enums are the modern approach for fixed value sets
- Aligns with contemporary PHP development practices
- Demonstrates PHP-FIG's commitment to modern language features
### 3. Developer Experience
- Enhanced IDE support with better autocomplete
- Improved refactoring capabilities
- Better debugging and inspection tools
### 4. Future-Proofing
- Enables pattern matching in future PHP versions
- Opens possibilities for additional enum methods
- Provides foundation for enhanced functionality
## Backward Compatibility Analysis
### ✅ **Compatible Usage Patterns:**
1. **Static access remains identical:**
```php
// Works with both class constants and enum cases
$level = LogLevel::ERROR;
```
2. **String values unchanged:**
```php
// Both return 'error'
echo LogLevel::ERROR; // Current: 'error', Proposed: 'error'
```
3. **String comparisons work:**
```php
// Still works
if ($level === 'error') { ... }
```
4. **Usage in LoggerTrait unchanged:**
```php
$this->log(LogLevel::ERROR, $message, $context);
```
### ⚠️ **Potentially Breaking Changes:**
1. **Type checks:**
```php
// Would break
if ($level instanceof LogLevel) { ... }
```
2. **Reflection on constants:**
```php
// Would need updating
$reflection = new ReflectionClass(LogLevel::class);
$constants = $reflection->getConstants();
```
3. **Class extension (unlikely but possible):**
```php
// Would break - but this is poor practice anyway
class CustomLogLevel extends LogLevel { ... }
```
### **Impact Assessment:**
- **Low risk:** Most usage follows `LogLevel::CONSTANT` pattern
- **Primary concern:** Reflection-based code and type checking
- **Ecosystem scan needed:** Analysis of major logging libraries
## PHP Version Requirements
**Current:** PHP ≥ 8.0.0
**Proposed:** PHP ≥ 8.1.0
### Justification for Version Bump:
- August 2025: PHP 8.1 has been stable for ~4 years
- PHP 8.0 reached end-of-life in November 2023
- Major frameworks already require PHP 8.1+
- Enum feature is fundamental to the proposal
## Implementation Strategy
### Phase 1: Community Discussion
- Gauge interest and concerns from the community
- Collect feedback on potential breaking changes
- Assess ecosystem impact
### Phase 2: Ecosystem Analysis
- Scan major logging libraries (Monolog, etc.) for compatibility
- Identify packages that might be affected
- Develop migration recommendations
### Phase 3: Implementation
- Create enum-based LogLevel
- Update documentation and examples
- Prepare migration guide
### Phase 4: Release Planning
- Coordinate as PSR-3 v4.0.0 major version
- Provide clear upgrade path documentation
- Consider deprecation timeline for v3.x
## Migration Guide
### For Library Authors:
```php
// Before: Type hint with string
function setLogLevel(string $level) { ... }
// After: Accept both for transition period
function setLogLevel(string|LogLevel $level) { ... }
// Future: Use enum directly
function setLogLevel(LogLevel $level) { ... }
```
### For Application Developers:
- Most code requires no changes
- Review any reflection-based log level handling
- Update type checks if using `instanceof`
## Alternative Approaches Considered
### 1. Create new PSR-X
**Pros:** No breaking changes to PSR-3
**Cons:** Ecosystem fragmentation, dual standards
### 2. Gradual transition with deprecation
**Pros:** Smoother migration path
**Cons:** Complex implementation, prolonged transition period
### 3. Maintain class constants alongside enum
**Pros:** Maximum compatibility
**Cons:** Code duplication, confusing developer experience
## Open Questions
1. Should we provide utility methods on the enum (e.g., `isErrorLevel()`, `getPriority()`)?
2. How should we handle the transition timeline?
3. Should this be part of a broader PSR-3 modernization effort?
## Ecosystem Impact Assessment Needed
Before proceeding, we should analyze:
- Monolog compatibility
- Framework logging implementations
- Popular logging-related packages
- Static analysis tool support
## References
- [PSR-3 Logger Interface Specification](https://www.php-fig.org/psr/psr-3/)
- [PHP 8.1 Enumerations RFC](https://wiki.php.net/rfc/enumerations)
- [PHP 8.1 Release Notes](https://www.php.net/releases/8.1/en.php)
## Conclusion
Converting LogLevel to an enum represents a natural evolution of PSR-3 toward modern PHP standards.
While requiring a major version bump due to PHP version requirements,
the change offers significant benefits in type safety and developer experience with minimal breaking changes for typical usage patterns.
The proposal maintains the core string values and access patterns that make PSR-3 widely adopted
while providing a foundation for future enhancements and better integration with modern PHP tooling.
---
**Next Steps:**
1. Community discussion on this proposal
2. Ecosystem compatibility analysis
3. Refinement based on feedback
4. Implementation planning if approved
