docs: prep for 1.0.0 release

Author: evansims

CHANGELOG.md

@@ -1,13 +1,31 @@
 # Changelog
 
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
+## [1.0.0] - 2025-01-05
+
 ### Added
 
+#### Core Features
+- **OpenFGA Integration**: Complete integration with OpenFGA for fine-grained authorization in Laravel applications
+- **Multi-connection Support**: Configure and use multiple OpenFGA instances simultaneously
+- **Eloquent Model Integration**: `HasAuthorization` trait for seamless model-based permissions
+- **Middleware Protection**: Route middleware for declarative authorization (`openfga`, `openfga.any`, `openfga.all`)
+- **Blade Directives**: Authorization directives for view-level access control (`@can`, `@cannot`, `@canany`)
+- **Artisan Commands**: CLI commands for managing permissions and debugging authorization
+- **Queue Integration**: Asynchronous permission operations with Laravel's queue system
+- **Advanced Caching**: Multi-tier caching with WriteBehindCache for performance optimization
+- **OpenTelemetry Support**: Built-in observability with OpenTelemetry integration
+
 #### Type Safety Enhancements
-- **Strict typing throughout codebase**: All PHP files now use `declare(strict_types=1)` for enhanced type safety
-- **Comprehensive generic annotations**: Added detailed PHPDoc type annotations with generics for arrays, collections, and return types
-- **DTO (Data Transfer Object) pattern**: Introduced `PermissionCheckRequest` DTO to replace associative arrays, providing better type safety and structure
+- **Strict typing throughout codebase**: All PHP files use `declare(strict_types=1)` for enhanced type safety
+- **Comprehensive generic annotations**: Detailed PHPDoc type annotations with generics for arrays, collections, and return types
+- **DTO (Data Transfer Object) pattern**: Introduced `PermissionCheckRequest` DTO for better type safety and structure
 - **Interface contracts**: Enhanced interfaces with strict type declarations and comprehensive documentation
 
 #### PHP 8.3+ Features
@@ -19,137 +37,46 @@
 #### Developer Experience
 - **Enhanced IDE support**: Comprehensive PHPDoc annotations enable better autocomplete and static analysis
 - **Type-safe method chaining**: Fluent APIs with proper return type annotations
-- **Strict parameter validation**: Runtime type checking combined with static analysis
-- **Exception handling improvements**: Type-safe error handling with proper exception hierarchies
-
-### Enhanced
-
-#### Core Components
-- **OpenFgaManager**: Added strict typing for all manager operations with comprehensive generics
-- **Authorization Gate**: Enhanced gate implementation with template types and strict checking
-- **Model Traits**: Improved HasAuthorization trait with type-safe method signatures
-- **Cache Layer**: Type-safe caching implementation with proper key typing
-
-#### API Signatures
-```php
-/**
- * Batch check multiple permissions at once.
- *
- * @param array<int, array{user: string, relation: string, object: string}> $checks
- * @param string|null $connection Optional connection name
- * @return array<string, bool> Keyed by "user:relation:object"
- */
-public function batchCheck(array $checks, ?string $connection = null): array
-
-/**
- * Check if a user has a specific permission.
- *
- * @param string $user
- * @param string $relation
- * @param string $object
- * @param array<array{user: string, relation: string, object: string}|TupleKey> $contextualTuples
- * @param array<string, mixed> $context
- * @param string|null $connection
- */
-public function check(
-    string $user,
-    string $relation,
-    string $object,
-    array $contextualTuples = [],
-    array $context = [],
-    ?string $connection = null,
-): bool
-```
-
-#### Model Integration
-```php
-/**
- * Grant multiple permissions to multiple users.
- *
- * @param array<int|Model|string> $users The users to grant permissions to
- * @param array<string>|string $relations The relations/permissions to grant
- */
-public function grantMany(array $users, array|string $relations): bool
-
-/**
- * Get all relations a user has with this model.
- *
- * @param int|Model|string $user The user to check
- * @param array<string> $relations Optional relation filters
- * @return array<string, bool>
- */
-public function getUserRelations($user, array $relations = []): array
-```
-
-### Technical Improvements
-
-#### Static Analysis
-- **PHPStan Level 8**: Configured for maximum static analysis strictness
-- **Psalm integration**: Added comprehensive type checking with Psalm
-- **Rector support**: Automated code quality improvements and PHP version compliance
-- **PHP-CS-Fixer**: Enforced consistent coding standards
-
-#### Testing Enhancements
-- **Type-safe test utilities**: Enhanced testing framework with proper type annotations
-- **Mock improvements**: Better type safety in test doubles and fakes
-- **Assertion helpers**: Type-safe assertion methods for authorization testing
-
-### Breaking Changes
-
-**None Expected** - All type safety improvements are backward compatible. Existing code will continue to work without modification.
-
-### Migration Notes
-
-While no breaking changes are expected, developers can benefit from the enhanced type safety by:
+- **Comprehensive Example Application**: Full-featured example app demonstrating best practices
+- **Testing Utilities**: `FakesOpenFga` trait and test helpers for easy testing
+- **Docker Integration**: Optimized Docker setup for integration testing
 
-1. **Enabling strict typing in your models**:
-   ```php
-   <?php
+#### Documentation
+- **Complete API documentation**: All public methods fully documented with type information
+- **Example application**: Comprehensive example showing real-world usage patterns
+- **Migration guides**: Clear instructions for integrating into existing applications
+- **Best practices guide**: Authorization patterns and performance optimization tips
 
-   declare(strict_types=1);
+### Technical Details
 
-   namespace App\Models;
-
-   use OpenFGA\Laravel\Traits\HasAuthorization;
-   ```
-
-2. **Using the new DTO pattern**:
-   ```php
-   use OpenFGA\Laravel\DTOs\PermissionCheckRequest;
-
-   $request = PermissionCheckRequest::fromUser(
-       user: $user,
-       relation: 'editor',
-       object: 'document:123'
-   );
-   ```
-
-3. **Leveraging enhanced type hints**:
-   ```php
-   /** @var array<string, bool> $permissions */
-   $permissions = $model->getUserRelations($user, ['editor', 'viewer']);
-   ```
-
-### Performance Improvements
-
-- **Reduced runtime type checking overhead** through compile-time guarantees
-- **Better opcode optimization** via strict type declarations
-- **Enhanced caching efficiency** with type-safe cache keys
-
----
-
-## [1.0.0] - Initial Release
-
-### Added
-- Core OpenFGA integration for Laravel
-- Multi-connection support
-- Eloquent model integration with HasAuthorization trait
-- Middleware for route protection
-- Blade directives for view-level authorization
-- Comprehensive testing utilities
-- Artisan commands for CLI management
-- Advanced caching and queue support
-- Complete documentation
+#### Static Analysis
+- **PHPStan Level 2**: Configured for robust static analysis
+- **Psalm Level 6**: Type checking with Psalm for additional safety
+- **Rector support**: Automated code quality improvements and PHP version compliance
+- **PHP-CS-Fixer**: Enforced PSR-12 coding standards
+
+#### Testing
+- **Unit Tests**: Comprehensive unit test coverage with Pest PHP
+- **Integration Tests**: Full integration test suite with real OpenFGA instance
+- **Example Tests**: Complete test suite for the example application
+- **GitHub Actions**: Automated CI/CD pipeline for quality assurance
+
+#### Performance
+- **Efficient caching strategies**: Multi-tier caching with write-behind optimization
+- **Batch operations**: Support for batch permission checks and writes
+- **Connection pooling**: Efficient HTTP client management
+- **Lazy loading**: Deferred service provider for faster boot times
+
+### Security
+- **Secure by default**: No credentials in code, environment-based configuration
+- **Input validation**: Comprehensive validation of all authorization inputs
+- **Error handling**: Graceful degradation with proper error messages
+
+### Compatibility
+- **Laravel**: 11.x and 12.x
+- **PHP**: 8.3+
+- **OpenFGA**: 1.x
+- **PSR Standards**: PSR-4, PSR-12 compliant
 
 [Unreleased]: https://github.com/evansims/openfga-laravel/compare/v1.0.0...HEAD
 [1.0.0]: https://github.com/evansims/openfga-laravel/releases/tag/v1.0.0

tests/Support/TestHelpers.php

@@ -185,6 +185,18 @@ function chain(...$expectations): Closure
     };
 }
 
+// Helper to create middleware test user (deprecated - use TestFactories::createTestUser)
+function createMiddlewareTestUser(mixed $id, string $authId): object
+{
+    return TestFactories::createTestUser(authId: $authId, identifier: $id);
+}
+
+// Helper function to create test user for middleware tests (deprecated - use TestFactories::createTestUser)
+function createTestUser(string $authId = 'user:123', mixed $identifier = 123): object
+{
+    return TestFactories::createTestUser(authId: $authId, identifier: $identifier);
+}
+
 // Helper to setup route
 function setupRoute(Request $request, string $path, string $paramName, mixed $paramValue): void
 {