Add unit tests to PdoSource

.github/workflows/build.yml

@@ -0,0 +1,45 @@
+on:
+  push:
+    branches: [ 'master' ]
+  pull_request:
+    branches: [ 'master' ]
+
+permissions:
+  contents: read
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php-versions: [ '5.3', '5.4', '5.5', '5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ]
+
+    name: Run Unit Test on PHP ${{ matrix.php-versions }}
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+
+    - name: Install PHP
+      uses: shivammathur/setup-php@v2
+      with:
+        php-version: ${{ matrix.php-versions }}
+
+    - name: Check the PHP version
+      run: php -v
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate --strict
+
+    - name: Install dependencies
+      run: composer install --prefer-dist --no-progress
+
+    - name: Run test suite
+      run: vendor/bin/phpunit --coverage-clover=coverage.clover
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

README.md

@@ -63,7 +63,7 @@ $table = Table::fromRequest($request);
 // --------------------------------------
 ```
 
-By default, getting columns from the payload of the Javascript part of `DataTables` does provide its name. As the column name is required for getting its data from a source, there is a need to map its column to the database table:
+By default, getting columns from the payload of the Javascript part of `DataTables` does not provide its name (e.g., `forename`, `surname`, etc.). As the column name is required for getting its data from a source, there is a need to map its column to the database table:
 
 ``` php
 // index.php
@@ -72,7 +72,10 @@ By default, getting columns from the payload of the Javascript part of `DataTabl
 
 $table->setName('users');
 
+// The first column will be named as "forename" ---
 $table->mapColumn(0, 'forename');
+// ------------------------------------------------
+
 $table->mapColumn(1, 'surname');
 $table->mapColumn(2, 'position');
 $table->mapColumn(3, 'office');
@@ -83,35 +86,55 @@ $table->mapColumn(5, 'salary');
 
 ```
 
-Once the table has been properly configured, use the `Query` class and the `Request` class to generate the requested data to the table: 
+Once the table has been properly configured, initialize a source (e.g., `PdoSource`) that will be used for getting the data of the specified table:
+
+``` php
+// index.php
+
+use Rougin\Datatables\Source\PdoSource;
+
+// ...
+
+// Create a PDO instance... --------------
+$dsn = 'mysql:host=localhost;dbname=demo';
+
+$pdo = new PDO($dsn, 'root', /** ... */);
+// ---------------------------------------
+
+// ...then pass it to the PdoSource ---
+$source = new PdoSource($pdo);
+// ------------------------------------
+
+// ...
+```
+
+Then use the `Query` class to generate the requested data: 
 
 ``` php
 // index.php
 
-use Rougin\Datatables\Request;
 use Rougin\Datatables\Query;
 
 // ...
 
-// Parse the data from the query params ---
-$request = new Request($params);
-// ----------------------------------------
+/** @var \Rougin\Datatables\Source\SourceInterface */
+$source = /** ... */;
 
-$query = new Query($request);
+$query = new Query($request, $source);
 
 /** @var \Rougin\Datatables\Result */
 $result = $query->getResult($table);
 ```
 
-Once the parsed from `Query`, it will be returned as `Result` class in which returns the response as an array or as JSON:
+The `getResult` from the `Query` class will return as the `Result` class in which returns the response as an array or as JSON format:
 
 ``` php
 // index.php
 
 // ...
 
 /** @var \Rougin\Datatables\Result */
-$result = $query->parse($table);
+$result = $query->getResult($table);
 
 echo $result->toJson();
 ```
@@ -122,33 +145,82 @@ $ php index.php
 
 ``` json
 {
-  "draw": 2,
-  "recordsFiltered": 0,
-  "recordsTotal": 0,
-  "data": []
+  "draw": 1,
+  "recordsFiltered": 57,
+  "recordsTotal": 57,
+  "data":
+  [
+    [
+      "Airi",
+      "Satou",
+      "Accountant",
+      "Tokyo",
+      "2008-11-28",
+      "162700.0"
+    ],
+    [
+      "Angelica",
+      "Ramos",
+      "Chief Executive Officer (CEO)",
+      "London",
+      "2009-10-09",
+      "1200000.0"
+    ]
+  ]
 }
 ```
 
-To provide data from a specified source (e.g., from database), kindly use the `setSource` method from the `Query` class:
-
-``` php
-// index.php
-
-use Acme\Sources\ModelSource;
-use Acme\Models\User;
-use Rougin\Datatables\Source;
-
-// ...
+## Creating custom sources
 
-/** @var \Rougin\Datatables\Query */
-$query = /** ... */;
+To create a custom source, kindly use the `SourceInterface` for its implementation:
 
-/** @var \Rougin\Datatables\Source\SourceInterface */
-$source = new ModelSource(new User);
+``` php
+namespace Rougin\Datatables\Source;
 
-$query->setSource($source);
+use Rougin\Datatables\Request;
+use Rougin\Datatables\Table;
 
-// ...
+interface SourceInterface
+{
+    /**
+     * Returns the total items after filter.
+     *
+     * @return integer
+     */
+    public function getFiltered();
+
+    /**
+     * Returns the items from the source.
+     *
+     * @return string[][]
+     */
+    public function getItems();
+
+    /**
+     * Returns the total items from the source.
+     *
+     * @return integer
+     */
+    public function getTotal();
+
+    /**
+     * Sets the payload to be used in the source.
+     *
+     * @param \Rougin\Datatables\Request $request
+     *
+     * @return self
+     */
+    public function setRequest(Request $request);
+
+    /**
+     * Sets the table to be used in the source.
+     *
+     * @param \Rougin\Datatables\Table $table
+     *
+     * @return self
+     */
+    public function setTable(Table $table);
+}
 ```
 
 ## Changelog

src/Column.php

@@ -10,11 +10,9 @@
 class Column
 {
     /**
-     * NOTE: From payload, it is known as "data".
-     *
-     * @var integer
+     * @var string
      */
-    protected $index;
+    protected $data;
 
     /**
      * @var string
@@ -69,13 +67,13 @@ public function isSearchable()
     }
 
     /**
-     * @param integer $index
+     * @param string $data
      *
      * @return self
      */
-    public function setIndex($index)
+    public function setData($data)
     {
-        $this->index = $index;
+        $this->data = $data;
 
         return $this;
     }

src/Query.php

@@ -22,11 +22,16 @@ class Query
     protected $source;
 
     /**
-     * @param \Rougin\Datatables\Request $request
+     * @param \Rougin\Datatables\Request                $request
+     * @param \Rougin\Datatables\Source\SourceInterface $source
      */
-    public function __construct(Request $request)
+    public function __construct(Request $request, SourceInterface $source)
     {
         $this->request = $request;
+
+        $source->setRequest($request);
+
+        $this->setSource($source);
     }
 
     /**

src/Request.php

@@ -57,9 +57,16 @@ public function getColumns()
                 $row->setName($name);
             }
 
-            /** @var integer */
-            $index = $item['data'];
-            $row->setIndex($index);
+            /** @var string */
+            $data = $item['data'];
+            $row->setData($data);
+
+            // It may be a column name ---
+            if (! is_numeric($data))
+            {
+                $row->setName($data);
+            }
+            // ---------------------------
 
             $searchable = $item['searchable'] === 'true';
             $row->setSearchable($searchable);