Design Principles
Design Principles
Core architectural philosophy and design decisions behind Cbox System Metrics.
Pure PHP
No external dependencies. The library reads directly from system sources:
- Linux:
/proc,/sysfilesystems - macOS: System commands (
sysctl,vm_stat, etc.)
Benefits:
- Works out of the box
- No compilation needed
- No version conflicts
- Easy deployment
Strict Types
declare(strict_types=1) everywhere. Full type safety:
- PHPStan Level 9 compliance
- No implicit type coercion
- Catch type errors at static analysis time
Benefits:
- Prevents type-related bugs
- Self-documenting code
- Better IDE support
- Refactoring safety
Immutable DTOs
All DTOs use PHP 8.3 readonly classes:
readonly class CpuSnapshot {
public function __construct(
public CpuTimes $total,
public array $perCore,
public DateTimeImmutable $timestamp,
) {}
}
Benefits:
- No accidental mutations
- Thread-safe by design
- Predictable behavior
- Clear ownership semantics
See Immutable DTOs for details.
Result Pattern
No uncaught exceptions. All operations return Result<T>:
$result = SystemMetrics::cpu();
if ($result->isSuccess()) {
$cpu = $result->getValue();
}
Benefits:
- Explicit error handling
- No surprise exceptions
- Functional programming style
- Type-safe error propagation
See Result Pattern for details.
Interface-Driven
All sources implement interfaces:
interface CpuMetricsSource {
public function read(): Result;
}
Benefits:
- Easy to swap implementations
- Dependency injection friendly
- Testable with stubs
- Clear contracts
Action Pattern
Small, focused use cases:
class ReadCpuMetricsAction {
public function execute(): Result {
return $this->source->read();
}
}
Benefits:
- Single responsibility
- Easy to test
- Clear boundaries
- Composable
See Action Pattern for details.