MeekroDB

The Simple PHP MySQL Library

 

Quick Start


Setup

To get started, simply drop meekrodb.class.php into a directory, include it, and configure your application's database information. Remember that the library won't actually establish a database connection until you run the first query.
    require_once 'meekrodb.2.3.class.php';
    DB::$user = 'my_database_user';
    DB::$password = 'my_database_password';
    DB::$dbName = 'my_database_name';
  

Running Queries

To run a simple query without any parameters, just use the query() method.
DB::query("SELECT * FROM tbl");
You can specify string, integer, and decimal parameters by using %s, %i, and %d placeholders in the query, and attaching the parameters as shown below. The library will run all needed safety checks, such as escaping strings and making sure integers are really integers.
DB::query("SELECT * FROM tbl WHERE name=%s AND age > %i AND height <= %d", $name, 15, 13.75);
Similarly, you can use the list placeholders %ls, %li, and %ld to substitute for a list of strings, a list of integers, and a list of decimal numbers, respectively. These are generally used with IN and NOT IN MySQL comparisons.
  DB::query("SELECT * FROM tbl WHERE name IN %ls AND age NOT IN %li", 
    array('John', 'Bob'), array(12, 15));
If you need to refer to a specific parameter, rather than just getting them in the order that they were passed in, you can put a number after the placeholder. The first parameter passed will have number 0. You can even re-use the same parameter multiple times!
DB::query("SELECT * FROM tbl WHERE name=%s2 AND age > %i0 AND height <= %d1", 
    15, 13.75, $name);

Retrieving Results

Results are returned as an array of associative arrays.
    $results = DB::query("SELECT name, age, height FROM tbl");
    foreach ($results as $row) {
      echo "Name: " . $row['name'] . "\n";
      echo "Age: " . $row['age'] . "\n";
      echo "Height: " . $row['height'] . "\n";
      echo "-------------\n";
    }
  

Large Inserts and Updates

You can do a large INSERT or REPLACE by using the MeekroDB insert() and replace() functions. Their format was designed to be simpler than the standard insert format used by MySQL.
  $name = 'Frank';
  DB::insert('tbl', array(
    'name' => $name,
    'age' => 23,
    'height' => 10.75
  ));
  
You can use a similar syntax to easily do a large UPDATE.
  // update the age and height for everybody named John
  $name = 'John';
  DB::update('tbl', array(
    'age' => 25,
    'height' => 10.99
  ), "name=%s", $name);
  

Special Queries

There are many cases where you just need the first row of results. You can get that quickly with the queryFirstRow() function.
    $row = DB::queryFirstRow("SELECT name, age, height FROM tbl WHERE name=%s LIMIT 1", 'Joe');
    echo "Name: " . $row['name'] . "\n"; // will be Joe, obviously
    echo "Age: " . $row['age'] . "\n";
    echo "Height: " . $row['height'] . "\n";
  
Similarly, you might need just the first field. The queryFirstField() function will provide that.
    $count = DB::queryFirstField("SELECT COUNT(*) FROM tbl WHERE age > %i", 12);
    echo "We have " . $count . " users whose age is greater than 12!";
  
Though it's more rare, sometimes you might need an array of values in one column only.
    // print all names in alphabetical order, skipping any duplicates
    $names = DB::queryFirstColumn("SELECT DISTINCT name FROM tbl ORDER BY name ASC");
    foreach ($names as $name) {
      echo $name . "\n";
    }
  

Query Debugging

If you have a bunch of queries being used to generate a page, you can get an overview of them be enabling debug mode. Just stick the following line at the top of your application, and your output will include a list of queries that were run (with all variables already evaluated) and the runtime for each query.
DB::debugMode();

Object-Oriented

We recommend the static class approach (as shown in the examples above) because most projects don't need multiple database connections, and it's annoying to pass $db objects around all the time. Still, MeekroDB works the same in object-oriented mode. First, you have to create a new MeekroDB instance. You'll need to pass the standard connection details as shown, and any that you don't pass will be taken from the static instance.
$mdb = new MeekroDB($host, $user, $pass, $dbName, $port, $encoding);
Once the instance is created, you can use all parameters and methods that are covered in the documentation. Some examples:
    $row = $mdb->queryFirstRow("SELECT name, age FROM tbl WHERE name=%s LIMIT 1", 'Joe');
    echo "Name: " . $row['name'] . "\n"; // will be Joe, obviously
    
    $mdb->param_char = '##';
    $row2 = $mdb->queryFirstRow("SELECT name, age FROM tbl WHERE name=##s LIMIT 1", 'Frank');
    echo "Name: " . $row2['name'] . "\n"; // will be Frank, obviously
  

That's it!

There's more to be had, but that covers the basics. Check out our documentation for more details, or download MeekroDB now!

Copyright (C) 2008-2017 :: :: LGPL v3 :: GitHub Tracker