Оригинал: http://php.russofile.ru/ru/translate/sql/adodb01/
http://php.russofile.ru/ru/translate/sql/adodb02/
http://php.russofile.ru/ru/translate/sql/adodb03/

Оригинал на английском: http://phplens.com/lens/adodb/docs-adodb.htm
Перевод Феськов Кузьма <kuzma@russofile.ru.> http://kuzma.russofile.ru

ADODB - русская документация (часть 1)

v4.62 2 Apr 2005 (c) 2000-2005 John Lim (jlim#natsoft.com)
v4.62 14 Июль 2005 (c) 2005 Feskov Kuzma (kuzma#russofile.ru)

Это программное обеспечение распространяется под двумя лицензиями:
BSD-style и LGPL. Это означает, что вы можете использовать его в
компилируемых и коммерческих продуктах.

Содержание

* Вступление
* Уникальные возможности ADODB
* Инструкция по установке
* Минимальная установка
* Инициализация класса
* Поддержка Data Source Name (DSN)
* Примеры соединения с базами данных
* Настройка ADODB для более высокой производительности
* Дополнительные подсказки
* Модернизация ADODB
* Возможности PHP5
* Поддерживаемые базы данных

Вступление

Функции доступа к базам данных в PHP не стандартизированы. Это создает
потребность в классе, который бы скрыл эту разницу в программном
интерфейсе при работе с различными базами (инкапсулировать различия),
позволяя легко переключаться с одной базы данных на другую. Для работы
вам потребуется PHP версии 4.0.5 и выше, поскольку в скриптах
используется str_replace.

В настоящее время поддерживается работа с базами MySQL, Oracle,
Microsoft SQL Server, Sybase, Sybase SQL Anywhere, Informix,
PostgreSQL, FrontBase, SQLite, Interbase (Firebird and Borland
variants), Foxpro, Access, ADO, DB2, SAP DB и ODBC. Также были
успешными попытки подсоединиться к Progress и CacheLite. Мы надеемся,
что пользователи создадут драйвера и для других баз данных.

PHP поддерживает переменные сессии. Вы можете хранить данные сессии в
базе при помощи ADOdb для истинной мобильности и масштабируемости.
Дополнительную информацию ищите в Adodb-session.php.

Для того, чтобы писать настоящий переносимый код - почитайте
здесь.

Уникальные возможности ADODB


* Легок в изучении для Windows-программистов, поскольку использует
синтаксис близкий к Microsoft ADO.

* В отличие от других PHP классов, которые в основном фокусируются
только на SELECT-запросах, мы обращаем внимание также на команды
вставки (INSERT) и изменения (UPDATE) данных, которые очень быстро
могут модернизироваться под потребности различных баз данных.
Также существуют методы для обработки дат, конкатенации строк и
экранирования строк по правилам различных баз данных.

* Система мето-типов построена так, чтоб вы могли быть уверенными,
что сохраняемые вами данные, например CHAR, TEXT, STRING, будут
одинаковыми для всех баз данных.

* Легкая переносимость, потому что все низкоуровневые функции
вынесены отдельно и вам нет необходимости вносить изменения в ядро
класса.

* Переносимость на уровне создания таблиц и индексов.

* Контроль работы базы данных и тонкая настройка производительности.

* Поддержка сессии на уровне базы данных, поддержка истечения
времени сессии и уведомлений.

Инструкция по установке

Проверьте, что вы используете PHP 4.0.5 и выше. Распакуйте все файлы в
папку, доступную для вебсервера.

Для проверки попробуйте запустить несколько файлов из обучающего
курса. Убедитесь, что вы вы правильно установили параметры
подключения. Для отладки используйте команду $db->debug = true, как
показано ниже:

include('adodb/adodb.inc.php');
$db = ADONewConnection($dbdriver); # например 'mysql' или 'postgres'
$db->debug = true;
$db->Connect($server, $user, $password, $database);
$rs = $db->Execute('select * from some_small_table');
print "<pre>";
print_r($rs->GetRows());
print "</pre>";

Минимальная установка

Для разработчиков, которые нуждаются в минимальном наборе функций,
рекомендуем установить следующие файлы:

* adodb.inc.php
* adodb-lib.inc.php
* adodb-time.inc.php
* drivers/adodb-$database.inc.php
* license.txt (по юрридическим причинам)
* adodb-php4.inc.php
* adodb-iterator.inc.php

Дополнительно:

* adodb-error.inc.php и lang/adodb-$lang.inc.php (если вы
используете MetaError())

* adodb-csvlib.inc.php (если вы используете кэширование запросов -
CacheExecute(), и др.)

* adodb-exceptions.inc.php и adodb-errorhandler.inc.php (если вы
используете adodb error handler или исключения PHP5).

Инициализация класса

Для запуска ADODB требуется 2 файла: первый - adodb/adodb.inc.php
(содержит базовые функции, которые используются во всех классах) и,
второй, - adodb/driver/adodb-????.inc.php (определяет специфические
для конкретной базы данных функции).

Вот пример соединения с базой MySql:

include('/path/to/set/here/adodb.inc.php');
$conn = &ADONewConnection('mysql');

Всякий раз, как вы соединяетесь с базой данных, создается новый объект
(ADONewConnection($driver)). NewADOConnection($driver) -
альтернативное название предыдущей функции.

На этом этапе вы никак не связаны с базой данных. Вам надо
определиться - будете ли вы использовать постоянное или непостоянное
соединение. Преимущество постоянного соединения в том, что оно
быстрее, поскольку связь с базой данных никогда не теряется (даже
когда вы даете команду Close()). Непостоянные соединения требуют
гораздо меньше ресурсов, однако повышают вероятность того, что ваша
база данных и веб-сервер будут перегружены.

Для постоянного соединения используйте команду $conn->PConnect(). Для
непостоянного соединения - $conn->Connect(). Некоторые базы данных
поддерживают также Nconnect() - эта команда вынуждает создать новое
соединение.

Важное замечание: Если вы создаете два соединения, но оба они
используют одинаковое имя пользователя (userid) и пароль, PHP не
станет создавать новое соединение, а примет для работы первое, ранее
созданное. Это может привести к проблемам в том случае, если вы от
имени одного пользователя пытались соединиться к разным базам данных.
Решение данной проблемы состоит в том, чтобы всегда использовать
разное имя пользователя (userid) для разных баз данных, или
использовать команду Nconnect().

Поддержка Data Source Name (DSN)

Начиная с версии ADODB 4.51 вы можете соединяться с базой передавая
NewADOConnection() (или ADONewConnection()) параметры в виде DSN:

$driver://$username:$password@hostname/$database?options[=value]

NewADOConnection() вызывает Connect() или Pconnect() внутри себя. В
случае неудачи возвращает FALSE:

# непостоянное соединение
$dsn = 'mysql://root:pwd@localhost/mydb';
$db = NewADOConnection($dsn);
if (!$db) die("Connection failed");

# нет необходимости вызывать connect/pconnect
$arr = $db->GetArray("select * from table");

# постоянное соединение
$dsn2 = 'mysql://root:pwd@localhost/mydb?persist';

Если в DSN у вас присутствуют специальные символы, типа :? вы должны
вызвать команду rawurlencode:

$pwd = rawurlencode($pwd);
$dsn = "mysql://root:$pwd@localhost/mydb";

Стандартные варианты:

Для всех движков баз:

'persist', 'persistent', 'debug', 'fetchmode'

Для Interbase/Firebird:

'dialect','charset','buffers','role'

Для M'soft ADO

'charpage'

Для MySQL

'clientflags'

Для MySQLi

'port', 'socket', 'clientflags'

Для Oci8

'nls_date_format'

Для всех драйверов справедливо: если вы задали установить постоянное и
непостоянное соединения одновременно - будет установлено постоянное
соединение. Debug - включает отладку. Fetchmode - вызывает функцию
SetFetchMode().Если вы не указали никакого значение, то значение будет
выставлено в 1.

ADODB DSN совместимы с версией 1.0 формата PEAR DB's DSN Format.

Примеры соединения с базами данных

MySql и большинство других баз данных

Mysql соединение имеет очень простой формат и параметры аналогичны
mysql_connect:

$conn = &ADONewConnection('mysql');
$conn->PConnect('localhost','userid','password','database');

# или DSN
$dsn = 'mysql://user:pwd@localhost/mydb';
$conn = ADONewConnection($dsn); # нет необходимости в Connect()

# или постоянное DSN
$dsn = 'mysql://user:pwd@localhost/mydb?persist';
$conn = ADONewConnection($dsn); # нет необходимости в PConnect()

# Более сложный пример:
$pwd = urlencode($pwd);
$flags = MYSQL_CLIENT_COMPRESS;
$dsn = "mysql://user:$pwd@localhost/mydb?persist&clientflags=$flags";
$conn = ADONewConnection($dsn); # нет необходимости в Pconnect()

Для большинства драйверов вы можете использовать стандартную функцию
Connect($server, $user, $password, $database), или DSN (начиная с
версии 4.51). Исключения будут описаны ниже.
PostgreSQL

PostgreSQL 7 и 8 поддерживает строки соединения:

а) стандартная строка соединения:

$conn = &ADONewConnection('postgres');
$conn->PConnect('host=localhost port=5432 dbname=mary');

б) классические 4 параметра:

$conn->PConnect('localhost','userid','password','database');

в) DSN:

$dsn = 'postgres://user:pwd@localhost/mydb?persist'; # persist необязательный параметр
$conn = ADONewConnection($dsn); # нет необходимости в Connect/PConnect

LDAP

Вот пример для работы с LDAP сервером. Благодарим Джоша Элдридджа за
драйвер и этот пример:

require('/path/to/adodb.inc.php');

/* Убедитесь, что вы задали эти параметры ДО вызова Connect() */
$LDAP_CONNECT_OPTIONS = Array(
Array ("OPTION_NAME"=>LDAP_OPT_DEREF, "OPTION_VALUE"=>2),
Array ("OPTION_NAME"=>LDAP_OPT_SIZELIMIT,"OPTION_VALUE"=>100),
Array ("OPTION_NAME"=>LDAP_OPT_TIMELIMIT,"OPTION_VALUE"=>30),
Array ("OPTION_NAME"=>LDAP_OPT_PROTOCOL_VERSION,"OPTION_VALUE"=>3),
Array ("OPTION_NAME"=>LDAP_OPT_ERROR_NUMBER,"OPTION_VALUE"=>13),
Array ("OPTION_NAME"=>LDAP_OPT_REFERRALS,"OPTION_VALUE"=>FALSE),
Array ("OPTION_NAME"=>LDAP_OPT_RESTART,"OPTION_VALUE"=>FALSE)
);
$host = 'ldap.baylor.edu';
$ldapbase = 'ou=People,o=Baylor University,c=US';

$ldap = NewADOConnection( 'ldap' );
$ldap->Connect( $host, $user_name='', $password='', $ldapbase );

echo "<pre>";

print_r( $ldap->ServerInfo() );
$ldap->SetFetchMode(ADODB_FETCH_ASSOC);
$userName = 'eldridge';
$filter="(|(CN=$userName*)(sn=$userName*)(givenname=$userName*)(uid=$userName*)
)";

$rs = $ldap->Execute( $filter );
if ($rs)
while ($arr = $rs->FetchRow()) {
print_r($arr);
}

$rs = $ldap->Execute( $filter );
if ($rs)
while (!$rs->EOF) {
print_r($rs->fields);
$rs->MoveNext();
}

print_r( $ldap->GetArray( $filter ) );
print_r( $ldap->GetRow( $filter ) );

$ldap->Close();
echo "</pre>";

Использование DSN:

$dsn = "ldap://ldap.baylor.edu/ou=People,o=Baylor University,c=US";
$db = NewADOConnection($dsn);

Interbase/Firebird

База данных определяется в параметре $host:

$conn = &ADONewConnection('ibase');
$conn->PConnect('localhost:c:ibaseemployee.gdb','sysdba','masterkey');

или DSN:

$dsn = 'firebird://user:pwd@localhost/mydb?persist&dialect=3'; # persist необязательный параметр
$conn = ADONewConnection($dsn); # нет необходимости в Connect/PConnect

SQLite

SQLite создаст файл базы данных, если его до сих пор небыло:

$conn = &ADONewConnection('sqlite');
$conn->PConnect('c:path osqlite.db'); # sqlite создаст файл, если его небыло

или DSN:

$path = urlencode('c:path osqlite.db');
$dsn = "sqlite://$path/?persist"; # persist необязательный параметр
$conn = ADONewConnection($dsn); # нет необходимости в Connect/PConnect

Oracle (oci8)

С oci8 вы можете устанавливать соединение множеством способов.
Обратите внимание, что способы работы с oci8 прекрасно подходят и для
более новых версий Oracle (9i и 10g).

а) PHP и Oracle находятся на одной машине, используют SID поумолчанию:

$conn->Connect(false, 'scott', 'tiger');

б) TSN Name определяется в файле tnsnames.ora (или ONAMES, или
HOSTNAMES), аналогично 'myTNS':

$conn->PConnect(false, 'scott', 'tiger', 'myTNS');

или

$conn->PConnect('myTNS', 'scott', 'tiger');

в) Host адрес и SID:

$conn->Connect('192.168.0.1', 'scott', 'tiger', 'SID');

г) Host адрес и имя сервиса (Service Name):

$conn->Connect('192.168.0.1', 'scott', 'tiger', 'servicename');

д) строка соединения Oracle:

$cstr = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=$host)(PORT=$port))
(CONNECT_DATA=(SID=$sid)))";
$conn->Connect($cstr, 'scott', 'tiger');

е) ADODB DSN:

$dsn = 'oci8://user:pwd@tnsname/?persist'; # persist необязательный параметр
$conn = ADONewConnection($dsn); # нет необходимости в Connect/PConnect

$dsn = 'oci8://user:pwd@host/sid';
$conn = ADONewConnection($dsn);

$dsn = 'oci8://user:pwd@/'; # oracle на локальной машине
$conn = ADONewConnection($dsn);

Также вы можете установить кодировку (charset) для Oracle версии 9.2 и
выше (поддерживается в PHP версии 4.3.2 и выше и ADODB с версии 4.54).

$conn->charSet = 'we8iso8859p1';
$conn->Connect(...);

# или
$dsn = 'oci8://user:pwd@tnsname/?charset=WE8MSWIN1252';
$db = ADONewConnection($dsn);

DSN-less ODBC (примеры для Access, MSSQL и DB2)

ODBC DSN'ы могут быть созданы в панели настроек ODBC, или вы можете
использовать DSN-less соединения. Для использования DSN-less
соединений с ODBC вам понадобится PHP версии 4.3 или выше.

Для Microsoft Access:

$db =& ADONewConnection('access');
$dsn = "Driver={Microsoft Access Driver (*.mdb)};Dbq=d:
orthwind.mdb;Uid=Admin;Pwd=;";
$db->Connect($dsn);

Для Microsoft SQL Server:

$db =& ADONewConnection('odbc_mssql');
$dsn = "Driver={SQL Server};Server=localhost;Database=northwind;";
$db->Connect($dsn,'userid','password');

или, если вы предпочитаете использовать расширение mssql (который
ограничен функциональность mssql 6.5):
$db =& ADONewConnection('mssql');
$db->Execute('localhost', 'userid', 'password', 'northwind');

Для DB2:

$db =& ADONewConnection('db2');
$dsn = "driver={IBM db2 odbc DRIVER};Database=sample;hostname=localhost;port=50
000;protocol=TCPIP;".
"uid=root; pwd=secret";
$db->Connect($dsn);

DSN-less соединения с ADO

Если вы используете PHP версии меньше, чем 4.3.0, то DSN-less
соединения будут работать только с Microsoft's ADO, через, основанное
на Microsoft COM, API. Пример использования библиотеки ADODB и
Microsoft's ADO:

include('adodb.inc.php');
$db = &ADONewConnection("ado_mssql");
print "<h1>Соединение DSN-less $db->databaseType...</h1>";

$myDSN="PROVIDER=MSDASQL;DRIVER={SQL Server};"
. "SERVER=flipper;DATABASE=ai;UID=sa;PWD=;" ;
$db->Connect($myDSN);

$rs = $db->Execute("select * from table");
$arr = $rs->GetArray();
print_r($arr);

Настройка ADODB для более высокой производительности

ADODB - это очень большая библиотека, которая всеже превосходит все
другие библиотеки PHP в производительности. Это происходит потому, что
она разработана в виде слоев, подобно луку, самые быстрые функции
расположены во внутреннем слое. Придерживайтесь использования
следующих функций для большей производительности:

Самый низкоуровневый слой:

Connect, PConnect, NConnect
Execute, CacheExecute
SelectLimit, CacheSelectLimit
MoveNext, Close
qstr, Affected_Rows, Insert_ID

Самый быстрый способ получить доступ к данным, это обращаться
непосредственно к массиву с данными $recordset->fields. Также
установите значения глобальным переменным $ADODB_FETCH_MODE =
ADODB_FETCH_NUM, и (для oci8, ibase/firebird и odbc) $ADODB_COUNTRECS
= false до того, как подключитесь к базе данных.

Используйте связанные параметры, если ваша база данных поддерживает
это, поскольку это улучшает повторное использование запросов.
Используйте систему тонкой настройки ADODB для быстрого выявления
узких мест. На время написания (Дек. 2003) это справедливо и для oci8
и odbc драйверов.

Наконец, убедитесь, что у вас установлен PHP акселератор кэширования,
например, APC, Turck MMCache, Zend Accelerator или ionCube.

Несколько примеров:

Быстрый доступ к данным в PHP:

$rs =& $rs->Execute($sql);
while (!$rs->EOF) {
var_dump($rs->fields);
$rs->MoveNext();
}

Быстрый доступ к данным в ADODB:

$rs =& $rs->Execute($sql);
$array = adodb_getall($rs);
var_dump($array);

Дополнительные подсказки

Если у вас установлено расширение ADODB, написанное на C, вы можете
заменить ваши запросы к $rs->MoveNex() на adodb_movenex($rs). Эта
команда удваивает скорость операции. Для того, чтобы получить записи
целиком, используйте GetArray(), которая использует высокоскоростную
функцию расширения adodb_getall($rs).

Execute() - это основной способ запуска запросов. Вы можете
использовать функции низкого уровня _Execute() и _query(), чтобы
уменьшить цепочку функций. Обе эти функции принимают теже самые
параметры, что и Execute().

Если вы не используете связанные параметры, или ваша база данных
поддерживает связанные параметры (без эмуляции) вы можете вызывать
_Execute() непосредственно. Вызов этих функций обходит эмуляцию
связанных параметров. _Execute() поддерживает отладку.

Если вам не требуется отладка, вы не используете связанные данные и
вам не нужны возвращаемые значения - используйте функцию _query(). Эта
функция хорошо подходит для вставки (INSERT), обновления (UPDATE) и
удаления (DELETE). Вызов функции _query() позволит вам обойти отладку,
эмуляцию связанных данных и обработку возвращаемых результатов.
Функция возвращает TRUE или FALSE.

Для Informix вы можете выключить scrollable курсоры командой
$db->cursorType = 0.

Модернизация ADODB

Вы вполне можете хотеть изменить ADODB под свои собственные нужды. К
счастью, вы легко можете поддерживать обратную совместимость расширяя
ADODB и используя переменную $ADODB_NEWCONNECTION.
$ADODB_NEWCONNECTION позволяет перекрыть поведение ADONewConnection().
ADONewConnection() проверяет эту переменную и вызывает функцию с
именем, сохраненным в этой переменной.

В следующем примере, новые функциональные возможности для объекта
соединения помещены в классы hack_mysql и hack_postgres7. Название
классов (навязанные соглашения) для обработки данных контролируются
при помощи переменной $rsPrefix. Здесь мы устанавливаем ее в
'hacks_rs_', это заставит ADODB использовать hacks_rs_mysql и
hacks_rs_postgres7 как классы для обработки данных.

class hack_mysql extends adodb_mysql {
var $rsPrefix = 'hack_rs_';
/* Ваши изменения здесь */
}

class hack_rs_mysql extends ADORecordSet_mysql {
/* Ваши изменения здесь */
}

class hack_postgres7 extends adodb_postgres7 {
var $rsPrefix = 'hack_rs_';
/* Ваши зменения здесь */
}

class hack_rs_postgres7 extends ADORecordSet_postgres7 {
/* Ваши изменения здесь */
}

$ADODB_NEWCONNECTION = 'hack_factory';

function& hack_factory($driver)
{
if ($driver !== 'mysql' && $driver !== 'postgres7') return false;

$driver = 'hack_'.$driver;
$obj = new $driver();
return $obj;
}

include_once('adodb.inc.php');

Незабудьте вызывать конструктор родительского класса из вашего
конструктора. Если вы хотите использовать драйвер ADODB поумолчанию -
верните FALSE из hack_factory().

Возможности PHP5

Начиная с версии ADODB 4.02 класс прозрачно определяет, какую версию
PHP вы используете. В случае обнаружения PHP5 становятся доступными
следующие возможности:

* Foreach итераторы: это очень естественный способ обработки данных:

$ADODB_FETCH_MODE = ADODB_FETCH_NUM;
$rs = $db->Execute($sql);
foreach($rs as $k => $row) {
echo "r1=".$row[[ ."]] r2=".$row."";
}

* Исключения: Стоит включить adodb-exeptions.inc.php и вы с
легкостью сможете перехватывать исключения на ошибках в момент их
возникновения:

include("../adodb-exceptions.inc.php");
include("../adodb.inc.php");
try {
$db = NewADOConnection("oci8");
$db->Connect('','scott','bad-password');
} catch (exception $e) {
var_dump($e);
adodb_backtrace($e->gettrace());
}

Обратите внимание, что достижение EOF не считается ни ошибкой ни
исключением. Если вы хотите использовать драйвер поумолчанию - верните
FALSE.

Поддерживаемые базы данных

Параметр 'Имя' - это то, что вы должны передать в функцию
NewADOConnection($name).

Колонка 'Тест' указывает, насколько хорошо код был проверен и
используется:

* A - хорошо проверенный и используемый многими людьми;

* B - проверен и годен к употреблению, однако некоторые особенности
не могут быть реализованы;

* C - экспериментальный драйвер, не может поддерживать все
возможности ADODB.

Колонка 'RecordCount()' показывает - возвращает ли эта функция
колличество запрошенных строк или возвращает -1, если SELECT выполнен.
Если указано 'Y/N' - происходит эмуляция, если глобальная переменная
$ADODB_COUNTRECS=true (это значение по умолчанию). Обратите внимание,
что для большого количества результатов лучше эту возможность
выключить, потомучто потребуется значительное количество памяти для
проведения расчетов. Также, эмуляция снижает скорость работы на
40-50%. Это эмулируется в большинстве баз данных кроме PostgreSQL и
MySql. Эта переменная проверяется каждый раз, когда вы запускаете
запрос, так что вы можете выбрать, какие данные вам считать.