README

Datatables is a simple PHP package that handles the server-side of DataTables. Its server-side response can be used from the HTML which requires little to no configuration.

Installation

Install the Datatables package via Composer:

$ composer require rougin/datatables

Basic usage

Prior in configuring Datatables, kindly ensure that the serverSide property is set to true in the Javascript part:

// index.js

let options = { processing: true }

options.ajax = 'http://localhost:8000'

options.serverSide = true

new DataTable('#example', options)

<!-- index.html -->

<!-- ... -->

<table id="example"></table>

Note

For more information in the above example, kindly see the official guide on how to implement server-side rendering of data to DataTables.

From the PHP part, use the Table class to define the specified table:

// 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:

// index.php

// ...

// The first column will be named as "forename" ---
$table->mapColumn(0, 'forename');
// ------------------------------------------------

$table->mapColumn(1, 'surname');
$table->mapColumn(2, 'position');
$table->mapColumn(3, 'office');
$table->mapColumn(4, 'date_start');
$table->mapColumn(5, 'salary');

// ...

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:

// 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:

// index.php

use Rougin\Datatables\Query;

// ...

/** @var \Rougin\Datatables\Source\SourceInterface */
$source = /** ... */;

$query = new Query($request, $source);

/** @var \Rougin\Datatables\Result */
$result = $query->getResult($table);

The getResult from the Query class returns a Result class in which returns the response as an array or as JSON format:

// index.php

// ...

/** @var \Rougin\Datatables\Result */
$result = $query->getResult($table);

echo $result->toJson();

$ php index.php

{
  "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"
    ],

    // ...
  ]
}

Column formatters

Each table column accepts an optional formatter callback to transform values before output, matching the SSP formatter contract:

// index.php

// ...

// Get the columns from the table ---
$columns = $table->getColumns();
// ----------------------------------

// Format salary as currency --------------
$columns[5]->setFormatter(function ($value)
{
    return '$' . number_format($value, 2);
});
// ----------------------------------------

// Compose full name from two fields -----
$fn = function ($value, $row)
{
    return $value . ' ' . $row['surname'];
};

$columns[0]->setFormatter($fn);
// ---------------------------------------

// ...

Creating custom sources

To create a custom source, kindly use the SourceInterface for its implementation:

namespace Rougin\Datatables\Source;

use Rougin\Datatables\Request;
use Rougin\Datatables\Table;

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();

    /**
     * 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

Please see CHANGELOG for more recent changes.

Contributing

See CONTRIBUTING on how to contribute.

License

The MIT License (MIT). Please see LICENSE for more information.