v3.0: Refactor exception architecture and simplify API with generator-based returns

.github/actions/composer-install/action.yml

@@ -1,32 +1,36 @@
 name: Composer install with cache
 description: Set up PHP with Composer and install dependencies using cache
 inputs:
-  php-version:
-    description: PHP version to install
-    required: true
+    php-version:
+        description: PHP version to install
+        required: true
+    coverage:
+        description: Code coverage driver to enable (none, xdebug, pcov)
+        required: false
+        default: none
 runs:
-  using: composite
-  steps:
-    - name: Setup PHP
-      uses: shivammathur/setup-php@v2
-      with:
-        php-version: ${{ inputs.php-version }}
-        coverage: none
-        tools: composer
+    using: composite
+    steps:
+        -   name: Setup PHP
+            uses: shivammathur/setup-php@v2
+            with:
+                php-version: ${{ inputs.php-version }}
+                coverage: ${{ inputs.coverage }}
+                tools: composer
 
-    - name: Get composer cache directory
-      id: composer-cache
-      shell: bash
-      run: echo "dir=$(composer config cache-dir)" >> $GITHUB_OUTPUT
+        -   name: Get composer cache directory
+            id: composer-cache
+            shell: bash
+            run: echo "dir=$(composer config cache-dir)" >> $GITHUB_OUTPUT
 
-    - name: Cache dependencies
-      uses: actions/cache@v4
-      with:
-        path: ${{ steps.composer-cache.outputs.dir }}
-        key: ${{ runner.os }}-php-${{ inputs.php-version }}-composer-${{ hashFiles('**/composer.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-php-${{ inputs.php-version }}-composer-
+        -   name: Cache dependencies
+            uses: actions/cache@v4
+            with:
+                path: ${{ steps.composer-cache.outputs.dir }}
+                key: ${{ runner.os }}-php-${{ inputs.php-version }}-composer-${{ hashFiles('**/composer.lock') }}
+                restore-keys: |
+                    ${{ runner.os }}-php-${{ inputs.php-version }}-composer-
 
-    - name: Install dependencies
-      shell: bash
-      run: composer install --no-interaction --no-progress --prefer-dist
+        -   name: Install dependencies
+            shell: bash
+            run: composer install --no-interaction --no-progress --prefer-dist

.github/dependabot.yml

@@ -1,16 +1,16 @@
 version: 2
 updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    commit-message:
-      prefix: "ci"
-      include: "scope"
-  - package-ecosystem: "composer"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    commit-message:
-      prefix: "deps"
-      include: "scope"
+    -   package-ecosystem: "github-actions"
+        directory: "/"
+        schedule:
+            interval: "weekly"
+        commit-message:
+            prefix: "ci"
+            include: "scope"
+    -   package-ecosystem: "composer"
+        directory: "/"
+        schedule:
+            interval: "weekly"
+        commit-message:
+            prefix: "deps"
+            include: "scope"

.github/workflows/ci.yml

@@ -1,43 +1,60 @@
 name: CI
 
 on:
-  push:
-    branches: ["master"]
-  pull_request:
+    push:
+        branches: [ "master" ]
+    pull_request:
 
 jobs:
-  tests:
-    runs-on: ubuntu-latest
-    strategy: &php-matrix
-      fail-fast: false
-      matrix:
-        php-version: ['8.2', '8.3']
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-
-      - name: Install dependencies
-        uses: ./.github/actions/composer-install
-        with:
-          php-version: ${{ matrix.php-version }}
-
-      - name: Run tests
-        run: composer test
-
-  quality:
-    needs: tests
-    runs-on: ubuntu-latest
-    strategy: *php-matrix
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-
-      - name: Install dependencies
-        uses: ./.github/actions/composer-install
-        with:
-          php-version: ${{ matrix.php-version }}
-
-      - name: Quality checks
-        run: composer quality
+    tests:
+        runs-on: ubuntu-latest
+        strategy: &php-matrix
+            fail-fast: false
+            matrix:
+                php-version: [ '8.2', '8.3' ]
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v6
+
+            -   name: Install dependencies
+                uses: ./.github/actions/composer-install
+                with:
+                    php-version: ${{ matrix.php-version }}
+                    coverage: xdebug
+
+            -   name: Run tests with coverage
+                run: composer test -- --coverage-clover=build/logs/clover.xml
+
+            -   name: Upload test results
+                uses: actions/upload-artifact@v4
+                if: always()
+                with:
+                    name: test-results-php${{ matrix.php-version }}
+                    path: build/logs/junit.xml
+
+            -   name: Upload coverage reports
+                uses: actions/upload-artifact@v4
+                if: success()
+                with:
+                    name: coverage-reports-php${{ matrix.php-version }}
+                    path: |
+                        build/logs/clover.xml
+                        build/coverage/
+
+    quality:
+        needs: tests
+        runs-on: ubuntu-latest
+        strategy: *php-matrix
+
+        steps:
+            -   name: Checkout code
+                uses: actions/checkout@v6
+
+            -   name: Install dependencies
+                uses: ./.github/actions/composer-install
+                with:
+                    php-version: ${{ matrix.php-version }}
+
+            -   name: Quality checks
+                run: composer quality

.gitignore

@@ -13,3 +13,6 @@ phpunit.phar
 
 ### Tooling cache
 var/
+
+### Build artifacts
+build/

.php-cs-fixer.php

@@ -12,8 +12,8 @@
 $finder = PhpCsFixer\Finder::create()
     ->files()
     ->name('*.php')
-    ->in(__DIR__ . '/src')
-    ->in(__DIR__ . '/tests');
+    ->in(__DIR__.'/src')
+    ->in(__DIR__.'/tests');
 
 return (new PhpCsFixer\Config())
     ->setUsingCache(true)
@@ -43,7 +43,6 @@
         'no_leading_namespace_whitespace' => true,
         'no_trailing_whitespace' => true,
         'no_trailing_whitespace_in_comment' => true,
-        'no_unused_imports' => true,
         'no_whitespace_in_blank_line' => true,
         'object_operator_without_whitespace' => true,
         'ordered_imports' => true,
@@ -67,5 +66,6 @@
         'single_line_after_imports' => true,
         'single_quote' => true,
         'visibility_required' => true,
+        'yoda_style' => ['equal' => true, 'identical' => true, 'less_and_greater' => true],
     ])
     ->setFinder($finder);

CHANGELOG.md

@@ -5,9 +5,57 @@ 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/spec2.0.0.html).
 
+## [3.0.0] - 2025-12-05
+
+### Added
+
+- Added comprehensive exception architecture with typed exception hierarchy:
+  - `PaginationExceptionInterface` for type-safe exception catching
+  - `PaginationException` as base exception class
+  - `InvalidPaginationArgumentException` for parameter validation errors
+  - `InvalidPaginationResultException` for result validation errors
+- Added `OffsetAdapter::generator()` method for direct generator access
+- Added `OffsetResult::empty()` static factory for creating empty results
+- Added `OffsetResult::generator()` method for accessing internal generator
+- Added strict input validation to `OffsetAdapter::execute()`, rejecting negative values and invalid `limit=0` combinations
+- Added deterministic loop guards to prevent infinite pagination
+- Enhanced `SourceInterface` documentation with comprehensive behavioral specifications
+
+### Changed
+
+- **BREAKING**: Renamed `OffsetResult::getTotalCount()` to `OffsetResult::getFetchedCount()` for semantic clarity
+- **BREAKING**: Removed `SourceResultInterface` and `SourceResultCallbackAdapter` to simplify architecture
+- **BREAKING**: `OffsetResult` no longer implements `SourceResultInterface`
+- **BREAKING**: `SourceInterface::execute()` now returns `\Generator<T>` directly instead of wrapped interface
+- Enhanced type safety with `positive-int` types in `SourceInterface` PHPDoc
+- Reorganized test methods for better logical flow and maintainability
+- Improved property visibility (changed some `protected` to `private` in `OffsetResult`)
+- Updated `SourceCallbackAdapter` with enhanced validation and error messages
+
+### Removed
+
+- Removed `SourceResultInterface` and `SourceResultCallbackAdapter` classes
+- Removed `ArraySourceResult` test utility class
+- Removed `SourceResultCallbackAdapterTest` test class
+- Removed unnecessary interface abstractions for cleaner architecture
+
+### Fixed
+
+- Fixed potential infinite loop scenarios in pagination logic
+- Enhanced error messages for better developer experience
+- Improved validation of pagination parameters
+
+### Dev
+
+- Enhanced test organization with logical method grouping
+- Added comprehensive test coverage for new exception architecture
+- Improved static analysis type safety
+- Added 31 new tests for enhanced functionality
+
 ## [2.0.0] - 2025-12-04
 
 ### Added
+
 - Added `declare(strict_types=1)` to all source files for improved type safety
 - Added comprehensive README with usage examples and installation instructions
 - Added PHP version badge to README
@@ -17,30 +65,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/spec2.
 - Added PHP-CS-Fixer code style configuration
 
 ### Changed
+
 - **BREAKING**: Updated minimum PHP version requirement from 7.4 to 8.2
 - **BREAKING**: Updated `somework/offset-page-logic` dependency to `^2.0` (major version update)
 - Updated PHPUnit to `^10.5` for PHP 8.2+ compatibility
 - Updated PHPStan to `^2.1`
 - Updated PHP-CS-Fixer to `^3.91`
-- Improved property visibility in `OffsetResult` (changed `protected` to `private`)
-- Fixed logic error in `OffsetResult::fetchAll()` method
-
-### Removed
-- Removed legacy CI configurations (if any existed)
-- Removed deprecated code patterns and old PHP syntax
-
-### Fixed
-- Fixed incorrect while loop condition in `OffsetResult::fetchAll()`
 
 ### Dev
-- Added `ci` composer script for running all quality checks at once
-- Improved CI workflow to use consolidated quality checks
-- Enhanced Dependabot configuration with better commit message prefixes
-- Added explicit PHP version specification to PHPStan configuration
-- Improved property declarations using PHP 8.2+ features (readonly properties)
-- Added library type specification and stability settings to composer.json
 
-### Dev
 - Migrated from Travis CI to GitHub Actions
 - Added comprehensive CI pipeline with tests, static analysis, and code style checks
 - Added composer scripts: `test`, `stan`, `cs-check`, `cs-fix`