Download the PHP package kevinpirnie/kpt-datatables without Composer

KPT DataTables

Advanced PHP DataTables library with full CRUD operations, multi-table JOIN support, per-column filter accordion, calculated columns, footer aggregations, inline editing, Select2 AJAX dropdowns, file uploads, bulk actions, tabbed modal forms, and a theme system covering UIKit3, Bootstrap 5, Tailwind CSS, and a framework-agnostic Plain theme. All rendering is server-side PHP with client-side interactivity handled by a zero-dependency vanilla JS class.

Table of Contents

• Requirements
• Installation
• Dependencies
• Quick Start
• Asset Inclusion
• AJAX Handling
• Themes
• Core Configuration Methods
  • table()
  • primaryKey()
  • database()
  • columns()
  • join()
  • where()
  • filter()
  • sortable()
  • inlineEditable()
  • perPage()
  • pageSizeOptions()
  • search()
  • defaultSort()
  • groupBy()
• Action Configuration
  • actions()
  • actionGroups()
• Bulk Actions
• Modal Forms
  • addForm()
  • editForm()
  • Field Types
  • Tabbed Forms
  • allow_on Field Overrides
• Calculated Columns
• Footer Aggregations
• Styling
  • tableClass()
  • rowClass()
  • columnClasses()
• File Uploads
• Rendering
• Static Methods
• Standalone Component Renderers
• Filter Accordion Reference
• WHERE Conditions Reference
• Column Definition Reference
• JavaScript API
• Building Assets
• Testing
• Security
• Contributing
• License

Requirements

• PHP 8.2 or higher
• PDO extension
• JSON extension
• MySQL / MariaDB database

Installation

Dependencies

Quick Start

Asset Inclusion

Assets must be included before the rendered table HTML. The static helper methods handle framework CDN links, theme-specific CSS, and all library JS in one call.

UIKit example:

Bootstrap example:

Tailwind / Plain (no CDN):

Tailwind CSS must be compiled separately. See Building Assets.

AJAX Handling

All CRUD operations, search, pagination, sorting, filtering, and bulk actions are handled server-side through a single AJAX endpoint — the same URL that renders the page. The AJAX handler must be invoked before any HTML output.

The handleAjax() method internally routes the action parameter to the appropriate handler and outputs JSON before calling exit. Supported actions dispatched automatically by the JS layer:

Themes

The theme is set via the fluent theme() method. It configures all CSS class mappings used throughout rendering and controls which CDN assets are included.

Core Configuration Methods

All methods return $this for fluent chaining unless otherwise noted.

table()

Sets the primary database table. Supports table aliases. Auto-loads the table schema from the database for field type detection and form generation.

When an alias is used, the base table name (without alias) is automatically tracked separately for INSERT, UPDATE, and DELETE operations.

primaryKey()

Overrides the auto-detected primary key. Supports qualified (aliased) names.

The library automatically strips the table prefix when building WHERE id = ? clauses for mutations.

database()

Configures or replaces the database connection after construction.

columns()

Defines which columns to display. Keys are database column names (supports dot notation for joined tables and expression AS alias syntax). Values are display labels or full configuration arrays.

Simple format:

Enhanced format (type overrides, options, form classes):

See Column Definition Reference for all supported type overrides.

join()

Adds a SQL JOIN clause. Multiple joins are supported and applied to all data, count, and aggregation queries.

where()

Adds static server-side WHERE conditions that always apply to data queries, count queries, and mutations. These are invisible to the user.

Each condition requires field, comparison, and value keys.

Supported comparison operators: =, !=, <>, >, <, >=, <=, LIKE, NOT LIKE, IN, NOT IN, REGEXP

For IN / NOT IN pass an array as the value:

WHERE conditions applied through where() are also appended to UPDATE and DELETE queries for security, ensuring mutations cannot affect records outside the configured scope.

filter()

Configures the user-facing collapsible filter accordion rendered above the table. Each key is a database column (dot notation supported). Values can be a shorthand operator string or a full configuration array.

Shorthand:

Full configuration:

See Filter Accordion Reference for all supported operators and input types.

sortable()

Defines which columns produce clickable sort headers. Pass column names exactly as they appear in columns() keys, or use alias names for aliased expressions.

Clicking a sortable header cycles ASC → DESC → ASC. Sort icons update accordingly.

inlineEditable()

Marks specific columns as double-click-to-edit. The appropriate inline editor (text input, select, boolean toggle, image uploader, etc.) is determined from the column's type in the schema or columns() override.

Supported inline edit types: text, email, number, date, datetime-local, textarea, select, select2, boolean, image, datepicker.

perPage()

Sets the initial (default) number of records displayed per page.

pageSizeOptions()

Configures the options available in the per-page selector. When $includeAll is true, an "All records" option (value 0) is appended.

The per-page selector renders as a <select> dropdown by default, or as a button group when renderPageSizeSelectorComponent(true) is called.

search()

Enables or disables the global search input. Enabled by default.

defaultSort()

Sets the column and direction used for initial data load. Without this, data loads in database natural order.

groupBy()

Adds a GROUP BY clause to data and count queries. When a group-by is active, the count query wraps the grouped result in a subquery to return the true number of groups. Aggregation queries also wrap accordingly.

Action Configuration

actions()

Configures the built-in action column (edit / delete buttons) with placement and visibility.

actionGroups()

Replaces the default edit/delete buttons with a flexible group system that supports built-in actions, custom link actions, PHP callback actions, and raw HTML injection — all with configurable ordering and separators.

Each element of $groups is either:

• An array of built-in action keys ('edit', 'delete')
• An associative array of custom action configurations

Built-in actions:

Custom link action:

Placeholder substitution — {id} and {column_name} placeholders in href, title, onclick, and attributes values are replaced with the row's actual data:

PHP callback action (server-side execution):

HTML injection — inject arbitrary HTML before or after any action or group:

Bulk Actions

Enables a checkbox column and a toolbar for performing operations on multiple selected records simultaneously.

With default delete-only:

With custom actions:

The callback signature is function(array $ids, Database $db, string $baseTableName): bool|int.

Clicking a row (outside the action/check cell) toggles its checkbox. A "select all" checkbox in the header selects the entire current page.

Modal Forms

addForm()

Configures the "Add Record" modal and its form fields.

editForm()

Configures the "Edit Record" modal. The primary key field is automatically injected as a hidden input and populated by the JS fetch_record AJAX call.

Field Types

All field configurations share common keys:

Supported types:

select2 field extra keys:

Query parameter substitution — use {field_name} placeholders in select2 queries to filter options based on other fields in the same record:

datepicker field extra keys:

Values are stored internally as YYYY-MM-DD regardless of display format.

static field extra keys:

Tabbed Forms

Any form field can be assigned to a named tab by adding a tab key. Fields without a tab key are grouped under a "General" tab that is prepended automatically.

Tab navigation is rendered using the active theme's tab component (UIKit uk-tab, Bootstrap nav-tabs, or the custom kp-dt-tabs plain/tailwind component).

allow_on Field Overrides

Fields in the edit form can be conditionally modified when a specific condition on the fetched record is met. The server evaluates the condition during fetch_record and sends field overrides back to the client.

Supported operators for allow_on: ==, !=, >, >=, <, <=, IN, NOT IN

To remove an attribute set null or false as its value in set_attributes.

Calculated Columns

Computed columns are added to the SELECT as SQL expressions and rendered in the table like any other column. They cannot be edited inline.

calculatedColumn()

Builds the expression from an array of column names joined by an operator.

calculatedColumnRaw()

Accepts a raw SQL expression for complex calculations.

Footer Aggregations

Calculates SUM and/or AVG per column and displays the results in the table footer. Two scopes are supported: page (calculated client-side from the current page data) and all (calculated server-side across the full filtered recordset).

footerAggregate()

footerAggregateColumns()

Applies the same type and scope to multiple columns at once.

Aggregation columns work with calculated columns — pass the alias name:

Styling

tableClass()

Overrides the default CSS classes on the <table> element.

rowClass()

Sets a base CSS class applied to every <tr>. The record's primary key value is appended, e.g., my-row-42.

columnClasses()

Applies CSS classes to specific <td> (and <th>) elements by column key.

File Uploads

Configures server-side validation for file uploads submitted through file or image form fields, or via inline image editing.

Uploaded files are stored with a uniqid() prefix to prevent collisions. The stored filename (not path) is saved to the database field.

Rendering

renderDataTableComponent()

Renders the complete DataTable HTML: the container, filter accordion, table (with header, body, footer, aggregation rows), all modals, and the JS initialization script. This is the primary output method.

Static Methods

getCssIncludes()

getJsIncludes()

Standalone Component Renderers

Individual components can be rendered outside renderDataTableComponent() for custom layouts.

When calling renderFilterAccordionComponent() manually, remove the internal call by ensuring the filter accordion is not rendered inside renderContainer(). Rendering it twice causes duplicate DOM IDs.

Filter Accordion Reference

Operators

Input Types

Active Filter Badge

When filters are applied, a count badge appears in the accordion header. The badge updates automatically as filters are added or removed and clears when resetFilters() is called.

WHERE Conditions Reference

where() conditions differ from filter() conditions:

Both are applied simultaneously — where() conditions are evaluated first, filter conditions are appended with AND.

Column Definition Reference

When using the enhanced column format (array value instead of string label), the following keys control display and form behavior:

Auto-detected types from MySQL schema:

JavaScript API

The DataTablesJS class is instantiated automatically by the PHP renderInitScript() output and exposed on window.DataTables. You can call its methods directly from inline event handlers or your own JS.

Core Methods

CRUD Methods

Selection and Bulk

Notifications and Modals

Global Helper Objects

Building Assets

Node.js tooling is used to compile and minify JS and CSS. Install dependencies first:

Available npm Scripts

Output Locations

Testing

Tests cover UIKit, Bootstrap, Tailwind, and Plain theme rendering as well as AJAX handler routing. The CI matrix runs against PHP 8.2, 8.3, and 8.4 with both lowest and highest dependency sets.

Security

• All GET/POST inputs are sanitized before use in SQL queries.
• All SQL values are passed through PDO bound parameters — no string interpolation of user input.
• Column names, sort directions, and filter operators are validated against whitelists.
• The where() conditions are appended to all mutations, scoping UPDATE and DELETE to only records matching the developer-defined filter.
• Allowed AJAX actions are validated against a whitelist before dispatch.
• Inline editable columns are validated server-side before any UPDATE is executed.
• File uploads validate extension and size server-side independently of the client.

For security-related issues, email [email protected] rather than opening a GitHub issue.

Full Configuration Example

Browser Support

Chrome 60+, Firefox 60+, Safari 12+, Edge 79+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

Roadmap

• [ ] CSV / Excel / PDF export
• [ ] REST API endpoints
• [x] Multi-framework theme support
• [x] Calculated columns and footer aggregations
• [x] Column filter accordion with BETWEEN date range support
• [x] Select2 AJAX searchable dropdowns
• [x] Tabbed modal forms
• [x] Conditional field overrides (allow_on)
• [x] Custom datepicker with format tokens

License

The MIT License (MIT). See LICENSE for details.

Support

• Issues: GitHub Issues
• Discord: Join the server

Made with ❤️ by Kevin Pirnie