Feature/Implement paginated result for EloquentCriteriaParser and related classes. (#8)

Author: othercodes

.github/workflows/documentation.yml

@@ -6,20 +6,19 @@ on:
 
 jobs:
   publish:
+    name: Publish Documentation
     runs-on: ubuntu-latest
 
-    strategy:
-      matrix:
-        php-version: [ '8.2' ]
-
     steps:
       - name: Checkout source code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: ${{ matrix.php-version }}
+          php-version: '8.3'
           extensions: mbstring
           coverage: xdebug
           tools: composer:v2
@@ -45,4 +44,4 @@ jobs:
         with:
           path: "wiki/"
         env:
-          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
+          GH_PERSONAL_ACCESS_TOKEN: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

.github/workflows/sonar.yml

@@ -0,0 +1,54 @@
+name: SonarCloud
+
+on:
+  push:
+    branches: [ 'main' ]
+  pull_request:
+    types: [ 'opened', 'synchronize', 'reopened' ]
+
+jobs:
+  sonarcloud:
+    name: SonarCloud Analysis
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Install PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: xdebug
+          tools: composer:v2
+
+      - name: Cache dependencies
+        uses: actions/[email protected]
+        with:
+          path: ~/.composer/cache
+          key: php-${{ matrix.php-version }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: php-${{ matrix.php-version }}-composer-
+
+      - name: Validate composer.json and composer.lock
+        run: composer validate
+
+      - name: Install Dependencies
+        run: composer install --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist
+
+      - name: Execute Unit, Integration and Acceptance Tests
+        run: composer test
+
+      - name: Fix paths in coverage reports for Sonar
+        run: |
+          sed -i 's@'$GITHUB_WORKSPACE'@/github/workspace/@g' coverage.xml
+          sed -i 's@'$GITHUB_WORKSPACE'@/github/workspace/@g' test.xml
+
+      - name: Run SonarCloud Scan
+        uses: SonarSource/sonarcloud-github-action@v2
+        with:
+          projectBaseDir: .
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

.github/workflows/test.yml

@@ -8,11 +8,12 @@ on:
 
 jobs:
   test:
+    name: Test on PHP ${{ matrix.php-version }}
     runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        php-version: [ '8.2', '8.3' ]
+        php-version: [ '8.2', '8.3', '8.4']
 
     steps:
       - name: Checkout source code
@@ -37,7 +38,7 @@ jobs:
       - name: Validate composer.json and composer.lock
         run: composer validate
 
-      - name: Install dependencies
+      - name: Install Dependencies
         if: steps.composer-cache.outputs.cache-hit != 'true'
         run: composer install --prefer-dist --no-progress --no-suggest
 
@@ -46,14 +47,3 @@ jobs:
 
       - name: Execute Unit, Integration and Acceptance Tests
         run: composer test
-
-      - name: Fix coverage.xml for Sonar
-        run: |
-          sed -i 's@'$GITHUB_WORKSPACE'@/github/workspace/@g' coverage.xml
-          sed -i 's@'$GITHUB_WORKSPACE'@/github/workspace/@g' test.xml
-
-      - name: SonarCloud Scan
-        uses: SonarSource/sonarcloud-github-action@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/project.yml

@@ -0,0 +1,67 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: php
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "on-laravel"

composer.json

@@ -13,13 +13,15 @@
   "require": {
     "php": "^8.2.0",
     "complex-heart/sdk": "^2.0.0",
+    "complex-heart/criteria": "^4.1",
     "laravel/framework": "^11.0.0"
   },
   "require-dev": {
     "pestphp/pest": "*",
     "pestphp/pest-plugin-faker": "^2.0",
     "phpstan/phpstan": "*",
-    "mockery/mockery": "^1.6"
+    "mockery/mockery": "^1.6",
+    "laravel/pint": "^1.25"
   },
   "autoload": {
     "psr-4": {

phpstan.neon

@@ -0,0 +1,5 @@
+parameters:
+    paths:
+        - src/
+        - tests/
+    level: 9

src/Infrastructure/Laravel/Pagination/PaginatedCollection.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ComplexHeart\Infrastructure\Laravel\Pagination;
+
+use ComplexHeart\Domain\Criteria\Contracts\PaginatedResult;
+use Illuminate\Support\Collection;
+
+/**
+ * Class PaginatedCollection
+ *
+ * @template TKey of array-key
+ * @template TValue
+ *
+ * @extends Collection<TKey, TValue>
+ *
+ * @author Unay Santisteban <[email protected]>
+ */
+class PaginatedCollection extends Collection implements PaginatedResult
+{
+    /**
+     * PaginatedCollection constructor.
+     *
+     * @param  iterable<TKey, TValue>  $items
+     */
+    public function __construct(
+        iterable $items = [],
+        private readonly int $total = 0,
+        private readonly int $perPage = 0,
+        private readonly int $currentPage = 1,
+    ) {
+        parent::__construct($items);
+    }
+
+    /**
+     * Create a new PaginatedCollection instance.
+     *
+     * @param  array<TKey, TValue>  $items
+     * @return self<TKey, TValue>
+     */
+    public static function paginate(
+        array $items,
+        int $total,
+        int $perPage,
+        int $currentPage
+    ): self {
+        return new self($items, $total, $perPage, $currentPage);
+    }
+
+    /**
+     * Get the items for the current page
+     *
+     * @return array<int, mixed>
+     */
+    public function items(): array
+    {
+        return $this->all();
+    }
+
+    /**
+     * Get total number of items across all pages
+     */
+    public function total(): int
+    {
+        return $this->total;
+    }
+
+    /**
+     * Get items per page
+     */
+    public function perPage(): int
+    {
+        return $this->perPage;
+    }
+
+    /**
+     * Get current page number (1-indexed)
+     */
+    public function currentPage(): int
+    {
+        return $this->currentPage;
+    }
+
+    /**
+     * Get last page number
+     */
+    public function lastPage(): int
+    {
+        if ($this->perPage === 0) {
+            return 1;
+        }
+
+        return (int) ceil($this->total / $this->perPage);
+    }
+
+    /**
+     * Check if there are more pages after the current one
+     */
+    public function hasMorePages(): bool
+    {
+        return $this->currentPage < $this->lastPage();
+    }
+
+    /**
+     * Check if the current page is empty
+     */
+    public function isEmpty(): bool
+    {
+        return parent::isEmpty();
+    }
+
+    /**
+     * Check if the current page is not empty
+     */
+    public function isNotEmpty(): bool
+    {
+        return parent::isNotEmpty();
+    }
+}

src/Infrastructure/Laravel/Persistence/Contracts/IlluminateCriteriaParser.php

@@ -5,23 +5,25 @@
 namespace ComplexHeart\Infrastructure\Laravel\Persistence\Contracts;
 
 use ComplexHeart\Domain\Criteria\Criteria;
+use ComplexHeart\Domain\Criteria\Page;
 use Illuminate\Contracts\Database\Query\Builder;
-use Illuminate\Contracts\Pagination\LengthAwarePaginator;
 
 /**
  * Interface IlluminateCriteriaParser
  *
  * @author Unay Santisteban <[email protected]>
- * @package ComplexHeart\Infrastructure\Laravel\Persistence\Contracts
  */
 interface IlluminateCriteriaParser
 {
     /**
      * Apply a criteria into the given QueryBuilder.
      *
-     * @param  Builder  $builder
-     * @param  Criteria  $criteria
-     * @return Builder|LengthAwarePaginator<int, mixed>
+     * Returns an array containing:
+     * - 'builder': Query builder with filters, ordering, and pagination applied
+     * - 'total': Total count before pagination
+     * - 'page': Page value object from criteria
+     *
+     * @return array{builder: Builder, total: int, page: Page, currentPage: int}
      */
-    public function applyCriteria(Builder $builder, Criteria $criteria): Builder|LengthAwarePaginator;
+    public function applyCriteria(Builder $builder, Criteria $criteria): array;
 }