Datatables
![Software License][ico-license]
![Coverage Status][ico-coverage]
, (*1)
Datatables is a simple PHP package that handles the server-side of DataTables. Its server-side response can be used by DataTables from the HTML which requires little to no configuration., (*2)
Installation
Install the Datatables package via Composer:, (*3)
``` bash
$ composer require rougin/datatables, (*4)
## Basic usage
Prior in configuring `Datatables`, kindly ensure that the `serverSide` property is set to `true` in the Javascript part:
``` js
// index.js
let options = { processing: true }
options.ajax = 'http://localhost:8000'
options.serverSide = true
new DataTable('#example', options)
``` html
, (*5)
> [!NOTE]
> For more information in the above example, kindly see the [official guide](https://datatables.net/examples/data_sources/server_side.html) on how to implement server-side rendering of data to `DataTables`.
From the PHP part, use the `Table` class to define the specified table:
``` php
// index.php
use Rougin\Datatables\Request;
use Rougin\Datatables\Table;
// ...
// The $_GET variable should be returned ---
// and parsed as array<string, mixed> ------
$request = new Request($_GET);
// -----------------------------------------
// Parse columns based on the Request ---------
$table = Table::fromRequest($request, 'users');
// --------------------------------------------
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:, (*6)
``` php
// index.php, (*7)
// ..., (*8)
// The first column will be named as "forename" ---
$table->mapColumn(0, 'forename');
// ------------------------------------------------, (*9)
$table->mapColumn(1, 'surname');
$table->mapColumn(2, 'position');
$table->mapColumn(3, 'office');
$table->mapColumn(4, 'date_start');
$table->mapColumn(5, 'salary');, (*10)
// ..., (*11)
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:, (*12)
``` php
// index.php, (*13)
use Rougin\Datatables\Query;, (*14)
// ..., (*15)
/** @var \Rougin\Datatables\Source\SourceInterface */
$source = /** ... */;, (*16)
$query = new Query($request, $source);, (*17)
/** @var \Rougin\Datatables\Result */
$result = $query->getResult($table);, (*18)
The `getResult` from the `Query` class returns a `Result` class in which returns the response as an array or as JSON format:
``` php
// index.php
// ...
/** @var \Rougin\Datatables\Result */
$result = $query->getResult($table);
echo $result->toJson();
``` bash
$ php index.php, (*19)
``` json
{
"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"
],
// ...
]
}
Creating custom sources
To create a custom source, kindly use the SourceInterface for its implementation:, (*20)
``` php
namespace Rougin\Datatables\Source;, (*21)
use Rougin\Datatables\Request;
use Rougin\Datatables\Table;, (*22)
interface SourceInterface
{
/**
* Returns the total items after filter. If no filters
* are defined, the value should be same with getTotal.
*
* @return integer
*/
public function getFiltered();, (*23)
/**
* 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);
}, (*24)
## Changelog
Please see [CHANGELOG][link-changelog] for more information what has changed recently.
## Testing
If there is a need to check the source code of `Datatables` for development purposes (e.g., creating fixes, new features, etc.), kindly clone this repository first to a local machine:
``` bash
$ https://github.com/rougin/authsum.git "Sample"
After cloning, use Composer to install its required packages:, (*25)
``` bash
$ cd Sample
$ composer update, (*26)
Once the packages were installed, kindly check the following below on how to maintain the code quality and styling guide when interacting the source code of `Datatables`:
### Unit tests
`Datatables` also contains unit tests that were written in [PHPUnit](https://phpunit.de/index.html):
``` bash
$ composer test
When creating fixes or implementing new features, it is recommended to run the above command to always check if the updated code introduces errors during development., (*27)
Code quality
To retain the code quality of Datatables, a static code analysis code tool named PHPStan is being used during development. To start, kindly install the specified package in global environment of Composer:, (*28)
``` bash
$ composer global require phpstan/phpstan, (*29)
Once installed, `PHPStan` can now be run using the `phpstan` command:
``` bash
$ cd Sample
$ phpstan
Coding style
Asides from code quality, Datatables also uses a tool named PHP Coding Standards Fixer for maintaining an opinionated style guide. The said tool needs also to be installed in the global environment of Composer:, (*30)
``` bash
$ composer global require friendsofphp/php-cs-fixer, (*31)
After being installed, use the `php-cs-fixer` command in the same `Datatables` directory:
``` bash
$ cd Sample
$ php-cs-fixer fix --config=phpstyle.php
The specified phpstyle.php currently follows the PSR-12 as the baseline of the coding style and uses Allman as its indentation style., (*32)
[!NOTE]
Installing PHPStan and PHP Coding Standards Fixer requires a version of PHP that is 7.4 and above., (*33)
License
The MIT License (MIT). Please see LICENSE for more information., (*34)
Wallogit.com
