Generate Docs

CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `encoredigitalgroup/stdlib`, a collection of standard library classes and functions for PHP at Encore Digital Group. It provides utilities, helpers, and
+standardized patterns for PHP development.
+
+## Coding Rules
+
+Always follow these rules when writing code:
+
+- Casing rules:
+    - Variables are always camelCase
+    - Functions are always camelCase
+    - Paths are always PascalCase
+    - Classes are always PascalCase
+- Comments and docblocks:
+    - Only add comments when they add real value. Comments should always describe *why* not *what*
+    - Only add minimal docblocks to help improve code intelligence and static analysis
+- Never use `private`, `final`, or `readonly` keywords. If they are needed, the developer will implement them.
+- Avoid magic strings when an enum or a const is an option. Look in the existing codebase for an enum—it'll often be there
+- Avoid variables if possible. eg. rather than calling `$response = $this->get(...)` followed by `assetsRedirect()`, just chain the calls
+- Use the early return pattern where possible
+- Prefer arrow functions when the line will stay under 80-100 chars
+- Testing:
+    - All tests should be written using PestPHP. Related tests should be grouped by `describe()` blocks.
+    - All tests should be written using the `test()` function instead of the `it()` function.
+    - Avoid tests that are largely testing that the code behaves specifically as it is written, and instead test the intention. eg. a validation message may change over
+      time, but the invalid input should not be allowed regardless.
+    - When calling eloquent factories:
+        - Prefer named factory methods over `state` or passing values to `create` where possible
+        - Only factory data that is relevant to the test--favor defaults otherwise
+        - Eloquent factories should create necessary relationships implicitly. If you don't need a relation for the test, let the factory create it rather than creating
+          it in the test.
+- Always run `composer format`, `composer analyse`, and `composer test` on your code before considering it done
+- If there are "todo" comments that need to be resolved before the code gets merged, use `// FIXME`
+
+## Development Commands
+
+### Testing
+
+- Run all tests: `vendor/bin/pest`
+- Composer Command: `composer test`
+- Tests are located in `tests/` directory using Pest testing framework
+
+### Code Quality & Analysis
+
+- Static analysis: `composer analyse`
+- Code formatting: `composer format`
+
+## Architecture & Code Structure
+
+### Core Namespacing
+
+All classes use the `EncoreDigitalGroup\StdLib` namespace with PSR-4 autoloading from the `src/` directory.
+
+### Key Directories
+
+- `src/Objects/` - Main utility classes organized by domain:
+    - `Support/Types/` - Enhanced type classes (Str, Arr, Number)
+    - `Http/` - HTTP-related utilities (Url, HttpMethod, HttpStatusCode)
+    - `Filesystem/` - File and directory utilities
+    - `Geography/` - Geographic data structures
+    - `Serializers/` - JSON/XML serialization with normalizers
+    - `Calendar/` - Date/time utilities
+- `src/ObjectHelpers/` - Functional helper files automatically loaded
+- `src/Exceptions/` - Custom exception hierarchy
+- `src/Attributes/` - Custom PHP attributes (Api, Deprecated, Internal)
+- `src/Support/Internal/` - Internal support classes and composer scripts
+
+### Helper Functions
+
+Global helper functions are auto-loaded from files in `src/ObjectHelpers/`:
+
+- `enum_helpers.php`
+- `file_helpers.php`
+- `php_function_helpers.php`
+- `str_helpers.php`
+- `url_helpers.php`
+- `val_helpers.php`
+
+### Dependency Strategy
+
+- Uses Laravel collections and support packages (`illuminate/collections`, `illuminate/support`)
+- Supports multiple Laravel versions (^10|^11|^12)
+- Wrapper classes like `Once` check minimum dependency versions at runtime
+
+### Code Style Standards
+
+- Uses custom PHP-CS-Fixer rules with specific class element ordering
+- PHPStan level 8 static analysis
+- Cognitive complexity limits: 50 for classes, 10 for functions
+- Excludes Attributes, ObjectHelpers, and Exceptions from coverage analysis
+
+### Testing Approach
+
+- Pest framework for unit tests
+- Test files in `tests/Unit/` directory
+- Some wrapper classes marked with `@codeCoverageIgnore`

composer.json

@@ -47,7 +47,10 @@
     "scripts": {
         "post-autoload-dump": [
             "EncoreDigitalGroup\\StdLib\\Support\\Internal\\Composer\\Scripts::postAutoloadDump"
-        ]
+        ],
+        "format": "vendor/bin/rector && vendor/bin/duster fix",
+        "analyse": "vendor/bin/phpstan analyse",
+        "test": "vendor/bin/pest"
     },
     "minimum-stability": "stable"
 }

docs/README.md

@@ -0,0 +1,173 @@
+# EncoreDigitalGroup/StdLib Documentation
+
+Welcome to the comprehensive developer documentation for EncoreDigitalGroup/StdLib, a collection of standardized PHP classes and utilities designed to enhance development
+productivity and ensure consistency across projects.
+
+## Overview
+
+The stdlib provides object-oriented utilities that extend and enhance common PHP operations, with a focus on type safety, performance, and developer experience. All
+classes are designed to integrate seamlessly with Laravel applications while remaining framework-agnostic where possible.
+
+## Documentation Structure
+
+### [Support/Types Classes](./support-types.md)
+
+Enhanced type utility classes that extend Laravel's base functionality:
+
+- **Str** - Advanced string manipulation and formatting
+- **Arr** - Sophisticated array operations with structure preservation
+- **Number** - Safe number operations with validation
+
+### [HTTP Classes](./http.md)
+
+HTTP-related utilities and constants for web applications:
+
+- **Url** - Safe URL encoding/decoding operations
+- **HttpMethod** - Type-safe HTTP method constants
+- **HttpStatusCode** - Comprehensive HTTP status code constants
+- **HttpStatusName** - Human-readable status descriptions
+
+### [Filesystem Classes](./filesystem.md)
+
+File and directory operations with robust error handling:
+
+- **File** - Safe file operations with proper validation
+- **Directory** - Advanced directory analysis and scanning
+- **ExitCode** - Standardized CLI application exit codes
+
+### [Geography Classes](./geography.md)
+
+Comprehensive geographic data structures and utilities:
+
+- **Country** - World countries enumeration with enhanced functionality
+- **DivisionType** - Political division types (states, provinces, regions)
+- **Canada/UnitedStates** - Specific country subdivision enums with abbreviations
+
+### [Serializers Classes](./serializers.md)
+
+Object serialization system built on Symfony components:
+
+- **AbstractSerializer** - Base serialization functionality with normalizer management
+- **JsonSerializer/XmlSerializer** - Format-specific serialization implementations
+- **CarbonNormalizer** - Specialized Carbon date object handling
+- **LaravelCollectionNormalizer** - Laravel Collection serialization support
+
+### [Calendar Classes](./calendar.md)
+
+Date and time utilities with type-safe operations:
+
+- **DayOfWeek** - Type-safe day representation with flexible conversion
+- **Month** - Month enumeration with navigation capabilities
+
+### [Core Objects and Utilities](./core-objects.md)
+
+Foundational classes providing system-wide functionality:
+
+- **Once** - Memoization wrapper with version checking
+- **Deferred** - Deferred execution capabilities
+- **Enum** - Safe enum value extraction utilities
+- **StaticCache** - Advanced static caching with partitioning
+- **Php** - PHP version detection and comparison
+- **Support Traits** - Reusable functionality enhancements
+
+## Key Features
+
+### Type Safety
+
+- Extensive use of PHP 8.1+ enums and type declarations
+- Safe conversion methods that validate input types
+- Clear exception handling with meaningful error messages
+- IDE-friendly interfaces with comprehensive autocompletion
+
+### Laravel Integration
+
+- Seamless compatibility with Laravel applications
+- Extensions of familiar Laravel classes (Str, Arr, Number)
+- Support for Laravel Collections and Carbon dates
+- Integration with Laravel's service container and facades
+
+### Performance Optimization
+
+- Static caching capabilities for expensive operations
+- Memory-efficient operations on large datasets
+- Optimized algorithms for common operations
+- Minimal overhead wrapper implementations
+
+### Developer Experience
+
+- Consistent API patterns across all classes
+- Comprehensive error handling and validation
+- Clear documentation and usage examples
+- IDE autocompletion and static analysis support
+
+## Architecture Principles
+
+### Inheritance Strategy
+
+Many stdlib classes extend their Laravel counterparts, providing:
+
+- All existing Laravel functionality
+- Additional stdlib-specific methods
+- Seamless integration with existing code
+- Drop-in replacement capability
+
+### Error Handling
+
+Robust error handling throughout the system:
+
+- Custom exceptions for specific error types
+- Meaningful error messages with context
+- Validation before potentially failing operations
+- Safe defaults and fallback behavior
+
+### Version Safety
+
+- Automatic dependency version checking
+- Clear error messages for version mismatches
+- Graceful degradation where possible
+- Consistent version requirement handling
+
+## Getting Started
+
+### Installation
+
+The stdlib is designed to be included as a Composer dependency in your PHP projects.
+
+### Basic Usage Patterns
+
+1. **Type-Safe Operations** - Use enum-based constants instead of magic strings/numbers
+2. **Enhanced Laravel Methods** - Leverage stdlib extensions of Laravel classes
+3. **Geographic Data** - Utilize comprehensive country and region enumerations
+4. **Serialization** - Implement robust object serialization with custom normalizers
+5. **Caching** - Optimize performance with static caching capabilities
+
+### Integration Guidelines
+
+- Follow existing patterns when extending stdlib functionality
+- Use provided traits to enhance custom classes
+- Leverage type-safe enums for constants and options
+- Implement proper error handling using stdlib exceptions
+
+## Support and Development
+
+### Testing
+
+All stdlib classes are thoroughly tested using PestPHP with comprehensive test coverage.
+
+### Code Quality
+
+The codebase maintains high quality standards through:
+
+- PHPStan level 8 static analysis
+- Custom PHP-CS-Fixer rules for consistent formatting
+- Rector for code modernization and refactoring
+- Comprehensive documentation for all public APIs
+
+### Contributing
+
+When contributing to the stdlib, follow the established patterns and maintain consistency with existing implementations.
+
+---
+
+*This documentation provides comprehensive coverage of all object classes in the EncoreDigitalGroup/StdLib package. For specific implementation details, refer to the
+individual class documentation files.*