Installing

DataTables and Editor are powerful libraries, but before you can use them, they need to be installed on your system! This guide walks through how to use the Editor PHP libraries, including installing the demo package and making use of the libraries in your own project.

Demo package installation

The installation is a simple four step process which the documentation below will guide you though.

Download

To download the Editor PHP package, if you haven't already, open the Editor download page and select the Editor PHP package. If you already have a DataTables account the download will start immediately. if you don't have a DataTables account you will be asked to create one to start a trial.

When the download completes, unzip the Editor-PHP-1.9.0, ready for editing and uploading.

Examples SQL

The next step is to load your database with the tables and data required for the Editor demos. The Editor PHP libraries work with a number of different databases, each of which requires its own SQL. The following links contain the SQL needed for each of the supported databases:

Select the appropriate file for your database and then run the SQL contained within on your database access portal (SQL Server Management Studio, CLI, phpMyAdmin or pgAdmin3 for example). The demo SQL will create new tables and enter data into them. Note that they will overwrite any conflicting table names - installing the demo into a new database is recommended and also, as is good practice, ensure that you have backed up your database.

Database connection

Now that the database is primed with data and tables, we need to instruct the Editor examples how to make a connection to the database so it can perform CRUD actions. For this the only file you need to edit is lib/config.php in the Editor directory.

Edit this file in your preferred text editor by simply filling in the parameters of the $sql_details array - this array provides the information that the Editor libraries need to make a connection to your database.

The config.php file will look like this:

<?php if (!defined('DATATABLES')) exit(); // Ensure being used in DataTables env.

// Enable error reporting for debugging (remove for production)
error_reporting(E_ALL);
ini_set('display_errors', '1');
 
 
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Database user / pass
 */
$sql_details = array(
    "type" => "",    // Database type: "Mysql", "Postgres", "Sqlserver", "Sqlite" or "Oracle"
    "user" => "",    // User name
    "pass" => "",    // Password
    "host" => "",    // Database server
    "port" => "",    // Database port (can be left empty for default)
    "db"   => "",    // Database name
    "dsn"  => "",    // PHP DSN extra information. Set as `charset=utf8mb4` if you are using MySQL
    "pdo"  => null   // Existing PDO connection. Use with `type` and no other parameters.
);

Note that on lines 3-5 we enable error reporting. This can be very useful for debugging problems when getting started with Editor, but you may wish to remove these two lines before deploying your web-site.

Web-server

We are now ready to upload the files to your web-server and get them running. The Editor PHP demo files will run on any web-server capable of running PHP 5.3 or newer (e.g. Nginx, Apache, IIS, etc). Transfer the files to your web-server's root directory (or a nested directory if you prefer - either will work) using SFTP, FTP, or whatever method you prefer to get the files onto your server.

Running the examples

To now run the examples simply load http://myWebSite.com/Editor-PHP-1.9.0/examples/ in your web-browser. The examples are now running on your own server!

Edit these files and look around at how things are done to get an idea of how you can implement your own Editor use cases on your own sites / app!

Direct inclusion

When you are ready to include the Editor PHP libraries in your own application, copy the lib directory from the download package, get the source files from their GitHub repository or use composer (see below).

Set up the config.php file as described above to make the database connection and then ensure that you include the DataTables.php file where you wish to use the Editor classes. They include an auto-loader, so files are automatically included by PHP when required.

Composer

Composer is a dependency and package manager for PHP which can be used to easily manage and install external libraries such as Editor's PHP libraries. Using composer the datatables.net/editor-php package can be added to your composer.json file:

{
  "require": {
        "datatables.net/editor-php": "1.*"
    }
}

Then a simple composer install will install the Editor PHP libraries. Ensure that you include require 'vendor/autoload.php'; as normal with composer to have it auto load the classes needed.

Database connection

The Editor PHP demos and direct inclusion method above use the $sql_details array in a configuration file to automatically create a database variable for use. That isn't available in the composer package, primarily because you are likely to already have your own database connection from else where in the app that you should reuse. This is done by using the DataTables\Database class and passing in information about the database type and the connection reference. For example if $database is a PDO reference use:

$db = new DataTables\Database( array(
    "type" => "Mysql",
    "pdo" => $database
) );

Similarly, if you don't have a connection that should be reused, you can pass in the same options as described above for the $sql_details array into the DataTables\Database constructor and it will create the connection for you.

Composer example

Once you have the database connection configured, the use of the Editor class is just the same as for direct inclusion - e.g.:

<?php

use
    DataTables\Database,
    DataTables\Editor,
    DataTables\Editor\Field;

require 'vendor/autoload.php';
require 'db.php'; // defines $database

$db = new Database( array(
    "type" => "Mysql",
    "pdo" => $database
) );

// Build our Editor instance and process the data coming from _POST
Editor::inst( $db, 'myDatabase' )
    ->fields(
        Field::inst( 'first_name' ),
        // ...
    )
    ->process( $_POST )
    ->debug(true)
    ->json();

Next steps

With the Editor libraries running, the next step is to start experimenting and understanding how the Editor PHP code operates so you can create your own editable tables.