Introduction

PHP is a very common technology used to create dynamic websites and the PDO extension makes it easy to access the database from PHP.

PDO stands for PHP Data Objects and represents a connection between PHP and a database server. It provides a data-access abstraction layer which means that, regardless of which database you are using, you use the same functions to issue queries and fetch data. For details and further information on PDO, please see the PDO part of the PHP Manual.

PDO is great for abstracting the database access in your PHP application. As long as the PDO database driver for the specific database is installed and standard SQL is used, PDO lets you switch database by simply changing the connection string.

PDO Mimer is a driver that implements the PDO interface to enable access from PHP to Mimer SQL databases.

See the installation guide and example session below to get a more hands-on experience of the pdo_mimer extension.

Requirements and prerequisites

The following requirements must be fulfilled to use PDO Mimer:

  • PDO Mimer is supported on 64-bit Linux, macOS and Windows systems
  • Mimer SQL version 11, or later (available at our Download page)
  • PHP 8.1, or later

PDO Mimer is under MIT license and is open source. The source code for PDO Mimer can be found on GitHub.

If you are experiencing any difficulties with PDO Mimer, its installation, usage or documentation, please create a new issue on GitHub. All feedback is appreciated to help us at Mimer Information Technology to improve our product.

Installation

Install PDO Mimer to your PHP environment using one of the methods described below. Preferably, let the extension end up in the PHP extension folder (ext), otherwise the location may have to be pointed out more specifically in the php.ini file, see the Permanent setup using php.ini section.

Again, PHP version 8 or higher is needed for a proper installation session – verify the PHP version installed using the following command:

php --version

Linux, building from source using pickle

php pickle.phar install --source https://github.com/mimersql/pdo_mimer

Linux, building from source manually

This method requires the php-dev package which can be installed by a package manager, for example using apt on Ubuntu:

apt install php-dev

Then the installation can be made as follows:

git clone https://github.com/mimersql/pdo_mimer && cd pdo_mimer
phpize
./configure --with-pdo-mimer
make
make install

macOS, building from source using pickle

Besides php, packages like pickle, libtool, automake, and autoconf may have to be installed, possibly using brew as in the following example.

brew install php
brew install pickle
brew install libtool automake autoconf nasm pkgconf

Then it is time to build and install the pdo_mimer extension:

% php /opt/homebrew/bin/pickle install --source https://github.com/mimersql/pdo_mimer
  - Installing pdo_mimer (master): Cloning master from cache
+-----------------------------------+-----------+
| Package name                      | pdo_mimer |
| Package version (current release) | 1.0.0     |
| Package status                    | stable    |
+-----------------------------------+-----------+
%

Windows

From https://github.com/mimersql/pdo_mimer/releases/latest, download one of the releases available, i.e. the one that corresponds to the PHP version you have installed. After downloading, extract the zip file and put the pdo_mimer.dll file in the PHP extension folder.
Packages tagged with ‘NTS’ means Non Thread Safe, which also should match the PHP installed. Verify this using the following command:

php -i | findstr "Thread"

Enable PDO Mimer

Enable pdo_mimer either by adding the Mimer SQL PDO extension to your php.ini configuration file, or by giving it as an option when running PHP as follows:

php -dextension=pdo_mimer ...

Note. If the Mimer SQL extension is not located in the PHP extension directory, you can give the full path as argument instead – see the following section for an example.

Permanent setup using php.ini

To get the extension permanently enabled, the php.ini file should be updated. Locate the php.ini file as follows, here performed on a linux platform:

# php --ini | grep php.ini
Configuration File (php.ini) Path: /etc/php/7.2/cli
Loaded Configuration File:         /etc/php/7.2/cli/php.ini
#

Now, update the php.ini file by adding one of the following lines. It should be noticed that in this file a leading semicolon (;) means that the line is commented out.

If the extension gets located in the default PHP extension location after installation, the following line will be enough:

extension=pdo_mimer

But, the extension may end up in another location depending on the installation method. In this case the definition may have to be more precise like in the following example, taken from the macOS platform:

extension=/opt/homebrew/Cellar/php/8.2.7_1/pecl/20220829/pdo_mimer.so

Verify the installation

To verify the installation the php -m command is used.
If the php.ini file is updated for pdo_mimer the -dextension directive can be skipped in the command below.

Verify on Linux or macOS

# php -m -dextension=pdo_mimer | grep pdo_mimer
pdo_mimer
#

Verify on Windows

> php -m -dextension=pdo_mimer | findstr pdo_mimer
pdo_mimer
>

Example session

The example shown below uses the PHP CLI.
A Mimer SQL database called “testdb” is presumed to be up and running, and a database user called MIMER_USER with password MIMER_PWD should be created. How to create a database can be read about in the Mimer SQL Documentation Set, the section called Creating a Mimer SQL Database.

To create the database ident the bsql tool can be used. Log in as the SYSADM user and do the following:

CREATE IDENT MIMER_USER AS USER USING 'MIMER_PWD';
GRANT DATABANK TO MIMER_USER;
CONNECT TO 'testdb' USER 'mimer_user' USING 'MIMER_PWD';
CREATE DATABANK example_db;
DISCONNECT;
EXIT;

Now to the PHP example session. Here is the example PHP source code:

  $employees = [ 
    ['John Smith', 30], 
    ['Jane Doe', 40],
  ];
  $db = new PDO('mimer:dbname=testdb', 'MIMER_USER', 'MIMER_PWD');
  
  $db->exec(<<<SQL
    CREATE TABLE employees (
    id INT PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    age INT
    )
  SQL);
  
  $stmt = $db->prepare('INSERT INTO employees (id, name, age) VALUES (?, ?, ?)');
  
  foreach ( $employees as $id => [$name, $age]) { 
    $stmt->bindValue(1, $id, PDO::PARAM_INT); 
    $stmt->bindValue(2, $name, PDO::PARAM_STR); 
    $stmt->bindValue(3, $age, PDO::PARAM_INT);
    if ($id != array_key_last($employees)) { 
      $stmt->mimerAddBatch(); 
    }      
  }
  $stmt->execute();
  $stmt = $db->query('select name, age from employees');
  while ($row = $stmt->fetch(PDO::FETCH_NUM)) {
      print "Name: {$row[0]} ";
      print "Age: {$row[1]}\n";
    }
    $stmt = NULL;
    $db->exec("drop table employees");
    $db = NULL;
   

Start PHP interactively using the php -a command and paste the source code above at the “php >” prompt.

Again, if the php.ini file is updated for pdo_mimer, the -dextension directive can be omitted.
The session should execute as follows on the screen, creating a table, inserting some values, and then those values are selected from the table. Finally the table is dropped.

$ php -dextension=pdo_mimer -a
php > $db = new PDO('mimer:dbname=testdb', 'MIMER_USER', 'MIMER_PWD');
php > $db->exec(<<<SQL
<<< > CREATE TABLE employees (
<<< >     id INT PRIMARY KEY,
<<< >     name VARCHAR(50) NOT NULL,
<<< >     age INT
<<< > )
<<< > SQL);
php >
php > $employees = [
php >   ['John Smith', 30],
php >   ['Jane Doe', 40],
php > ];
php >
php > $stmt = $db->prepare('INSERT INTO employees (id, name, age) VALUES (?, ?, ?)');
php > foreach ( $employees as $id => [$name, $age]) {
php {     $stmt->bindValue(1, $id, PDO::PARAM_INT);
php {     $stmt->bindValue(2, $name, PDO::PARAM_STR);
php {     $stmt->bindValue(3, $age, PDO::PARAM_INT);
php {     if ($id != array_key_last($employees))
php {         $stmt->mimerAddBatch();
php { }
php > $stmt->execute();
php >
php > $stmt = $db->query('SELECT id, name, age FROM employees');
php > while ($row = $stmt->fetch(PDO::FETCH_NUM)) {
php {     print "Name: {$row[0]} ";
php {     print "Age: {$row[1]}\n";
php { }
Name: John Smith Age: 30
Name: Jane Doe Age: 40
php > $stmt = NULL;
php > $db->exec("drop table employees");
php > $db = NULL;

Do just “exit” to leave the PHP prompt.

Note! If the database environment is not properly prepared, or, if the database server is not started, the example session will fail.

Important Links