DLib PHP Library API

General database functions

The following code shows how a database connection is created, switched to and then opened. Records from a Stock Item table are then read (see dbclasses.php for how to define record layouts).

  $con1 = newDbConnection ("mysql", "localhost", "dblocal", "dbuser",
    "abcd123", "root", "rootpswd");

  switchDatabase ($con1);

  if (dbConnect ())
  {
    list ($ok, $stkList) = readStockItems ("cost < 0.50");

    foreach ($stkList as $stk)
      print "$stk->code - $stk->description - $stk->price\n";

    dbClose ();
  }

Class/Function/Method List

• addSQL
• addTable
• addWhere
• createTables
• dbClose
• dbConnect
• dbMsg
• dbUpdate
• doSQL
• fieldDetails
• getDbTrace
• newDbConnection
• readFromMulti
• removeDbMsg
• switchDatabase
• tableDetails
• transBegin
• transCommit
• transEnd
• transRollback
• updateTable
• updateTables

File Version: 5.4.4 - 5 Jun, 2008

string addSQL ($where, $sql, [$doOR])

Adds another bit of SQL statement to make up a WHERE statement for SQL. Similar to addWhere except that it does not assumes the presence of a global $where variable.

Result: Returns the new $where string.

void addTable ($tableName, $className, [$autoFuncs], [$modName])

Add a table definition to the current settings. Creates a global TableDef variable called $tdXXX where XXX is $className. Optionally creates the default standard database functions associated with that class (see dbautofuncs.php). See dbclasses.php for the TableDef class.

  addTable ("stockitems", "StockItem", true);

void addWhere ($sql, [$doOR], [$clr])

Adds another bit of SQL statement to make up a WHERE statement for SQL - assumes the presence of a global $where variable being used by the calling code.

  $where = "";

  if (!empty ($name))
    addWhere ("name LIKE '%$name%'");

  if (!empty ($town))
    addWhere ("town LIKE '%$town%'");

  list ($ok, $recList) = readContacts ($where, "name");

void createTables ()

Create all tables using data in $_db->tables (from classes that extend (Ex)DbRecord). Note that only table allowed in the currently enabled database will be created.

boolean dbClose ()

Close the currently selected database. To close multiple databases then use switchDatabase to select a db and then close it using this function.

Result: True if database successfully closed.

boolean dbConnect ()

Connect to the specified database optionally creating the database if allowed. If we don't find any records in the systemval table then attempt to do a create on all the tables.

Result: True if the connect succeeded.

  $con1 = newDbConnection ("mysql", "localhost", "dblocal", "dbuser", "abcd123");

  switchDatabase ($con1);

  if (dbConnect ())
  {
    // Connection succeeded!

    // Do some database access here...
  }

void dbMsg ($msg)

Database message handler. This accumulates database errors into one string for later display.

void dbUpdate ()

Check to see if a database update is required. This is performed either once a day, once an hour or every time this function is called (depending upon the setting of $_db->dbChanges).

boolean doSQL ($sql)

Execute an SQL statement. If it fails then it checks for record layout changes and, if found, attempts to update the table (except for SystemVal).

Result: Returns true if SQL succeeded.

  if (doSQL ("UPDATE stockitems SET price = 10.23 WHERE ref = 'A2-DEX'"))
    print "Update succeeded";

[mixed] fieldDetails ($table, $field)

Return the DbField info about the specified field in the specified table.

Result: Returns a two element array: 0 = a boolean success indicator; 1 = an (Ex)DbField class record containing the field details.

string getDbTrace ([$addBR])

Return the current database trace as a string.

Result: String containing a formatted copy of the current DB trace.

int newDbConnection ($dbType, $dbHost, $dbName, $dbUser, $dbPswd, [$dbMaster], [$dbMPswd], [$dbPrefix])

Set up a database connection's details. Any number of connections can be set up and then switched between using the switchDatabase function.

Result: Connection number.

  $con1 = newDbConnection ("mysql", "localhost", "dblocal", "dbuser",
    "abcd123", "root", "rootpswd");

  $con2 = newDbConnection ("access", "www.banana.org", "dbxyz",
    "dbuser", "defg987");

array readFromMulti ($classNames, $joinFlds, [$where], [$order], [$limit], [$fields], [$groupby])

Read from multiple tables.

Result: Element 0 is either true or false denoting the success or otherwise of the call. Element 1 is an array of objects where each object itself an array of the specified class records.

  list ($ok, $recList) = readFromMulti ("Business,Address", "ref",
    "t1.town LIKE '%Hampstead%', "t0.name");

  foreach ($recList as $rec)
  {
    list ($business, $address) = $rec;
    print $business->name . "\n" . $address->addr1 . "\n" .
      $address->town;
  }

void removeDbMsg ()

Remove the last entry from dbMsg. Used where an error occurs but is then handled properly by the calling code.

void switchDatabase ($con, [$connect])

Change which database we are currently accessing.

  switchDatabase ($con1);
  list ($ok, $recList) = readStockItems ("cost < 0.50");

  if ($ok)
  {
    switchDatabase ($con2);

    foreach ($recList as $rec)
    {
      $rec2 = new StockItem ($rec->ref);

      if (!$rec2->ok)
        $rec->newRec = true;

      $rec->save ();
    }

    switchDatabase ($con1);
  }

[mixed] tableDetails ($name, [$isClass])

Get table entry from the table or class name name.

Result: Returns an array of 3 items: 0 = boolean success indicator; 1 = the associated (Ex)TableDef class; 2 = a blank instance of the associated record class.

boolean transBegin ()

Begin a transaction. Note that these Transaction functions can only be used on tables that can handle transactions (e.g. InnoDB, BDB etc for MySQL).

Result: Success value.

boolean transCommit ()

Commit (end) a transaction.

Result: Success value.

boolean transEnd ()

End (commit) a transaction - alternate name.

Result: Success value.

boolean transRollback ()

Roll back a transaction.

Result: Success value.

void updateTable ($table)

Update a table definition. This compares the stored record layout with the DbField entries for that record and, if differences are detected, then it attempts to automatically update the database table to bring them into sync.

void updateTables ()

Checks to see if any tables need updating (calls updateTable for all tables defined).