Skip to main content

Core Objects and Utilities

This documentation covers the core utility classes and support components that provide foundational functionality across the stdlib package.

Enum Class​

The Enum class provides utilities for working with PHP 8.1+ BackedEnum types safely.

Purpose​

Type-safe enum value extraction with validation, preventing runtime errors from incorrect enum type assumptions.

Key Methods​

Safe Value Extraction​

  • string(BackedEnum $enum) - Safely extracts string value from string-backed enums
  • int(BackedEnum $enum) - Safely extracts integer value from integer-backed enums

Usage Scenarios​

  • API response formatting where enum values need conversion
  • Database storage of enum values
  • Form handling with enum-backed fields
  • Configuration processing with enum options
  • Type-safe enum value access

Type Safety Features​

  • Validates enum backing type before extraction
  • Throws InvalidArgumentException for type mismatches
  • Prevents runtime errors from assuming wrong backing type
  • Clear error messages for debugging

Integration Benefits​

  • Works with any PHP 8.1+ backed enum
  • Compatible with custom enum classes
  • Provides consistent interface across different enum types
  • Enables safe enum handling in generic code

StaticCache Class​

The StaticCache class provides a sophisticated static caching system with partitioning and enable/disable capabilities.

Purpose​

High-performance static caching with advanced features like partitioning, conditional enabling, and flexible cache management.

Key Methods​

Basic Cache Operations​

  • add(string $key, mixed $value, ?string $partition) - Adds value to cache with optional partitioning
  • get(string $key, ?string $partition) - Retrieves value from cache
  • remove(string $key, ?string $partition) - Removes specific key from cache
  • contains(string $key, ?string $partition) - Checks if key exists in cache

Advanced Operations​

  • flush(?string $partition) - Clears entire cache or specific partition
  • remember(string $key, callable $callback, ?string $partition) - Cache-or-execute pattern
  • enable() / disable() - Control cache functionality
  • enabled() / disabled() - Check cache state

Usage Scenarios​

  • Application-level caching for expensive operations
  • Configuration caching across request boundaries
  • Computed value storage for repeated calculations
  • Temporary data storage during complex operations
  • Performance optimization for frequently accessed data

Advanced Features​

Partitioning​

  • Organize cache entries into logical groups
  • Selective cache clearing by partition
  • Namespace isolation between different cache uses
  • Better cache management and organization

Enable/Disable Control​

  • Runtime cache control for testing scenarios
  • Conditional caching based on environment
  • Performance debugging capabilities
  • Development vs production behavior differences

Enum Key Support​

  • Support for enum-based cache keys
  • Type-safe key generation
  • Better code organization with meaningful key names

Performance Considerations​

  • Static storage provides fastest access times
  • Memory-based caching eliminates I/O overhead
  • Partitioning prevents cache pollution
  • Selective flushing maintains cache efficiency

Php Class​

The Php class provides utilities for PHP version checking and compatibility management.

Purpose​

Reliable PHP version detection and comparison for feature detection and compatibility checking.

Key Methods​

Version Comparison​

  • greaterThanOrEqual(string $version) - Checks if current PHP version is greater than or equal to specified version
  • lessThanOrEqual(string $version) - Checks if current PHP version is less than or equal to specified version
  • greaterThan(string $version) - Strict greater than comparison
  • lessThan(string $version) - Strict less than comparison
  • equalTo(string $version) - Exact version matching

Usage Scenarios​

  • Feature detection based on PHP version
  • Compatibility checking before using language features
  • Conditional code execution based on PHP capabilities
  • Library compatibility validation
  • Deployment environment verification

Version-Dependent Development​

  • Enable modern PHP features conditionally
  • Maintain backward compatibility
  • Provide fallbacks for older PHP versions
  • Validate runtime environment capabilities

Support Traits​

The stdlib provides several traits that enhance class functionality across the system.

HasEnumValue Trait​

Enhances PHP enums with additional functionality for UI generation and data handling.

Key Methods​

  • values() - Extract all enum values as array
  • titleCasedValues() - Get formatted title-case values for display
  • from() - Safe enum creation that returns null instead of throwing exceptions
  • options(array $include = [], array $exclude = []) - Generate filtered select options
  • name() - Get formatted display name

Usage Scenarios​

  • Form select option generation
  • Enum value validation and conversion
  • UI component data preparation
  • API response formatting
  • Display name generation

StaticCacheEnabled Trait​

Provides enable/disable functionality for static cache implementations.

Key Methods​

  • enable() / disable() - Control cache state
  • enabled() / disabled() - Check current state

Macroable Trait​

Enables dynamic method addition to classes, marked as experimental.

Key Features​

  • Dynamic method registration
  • Static and instance method support
  • Eloquent model integration
  • Closure binding capabilities
  • Method existence checking

Common Patterns​

Wrapper Strategy​

Many core classes follow a wrapper pattern:

  • Provide enhanced interfaces over Laravel functionality
  • Add version checking and validation
  • Maintain compatibility while adding features
  • Enable consistent error handling

Version Safety​

Core classes emphasize version safety:

  • Automatic dependency version checking
  • Clear error messages for version mismatches
  • Graceful degradation where possible
  • Consistent version requirement handling

Performance Focus​

Core utilities are designed for performance:

  • Static caching for frequently accessed data
  • Minimal overhead wrapper implementations
  • Efficient version checking strategies
  • Memory-conscious data structures

Type Safety​

All core classes prioritize type safety:

  • Strong typing in method signatures
  • Runtime type validation where needed
  • Clear exception handling for type errors
  • IDE-friendly interfaces for autocompletion