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

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

Источник: realcoding.net

[1 страница]

1. Вступление

Функции доступа к базам данных в 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.

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

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

* Легок в изучении для Windows-программистов, поскольку использует синтаксис близкий к Microsoft ADO.
* В отличие от других PHP классов, которые в основном фокусируются только на SELECT-запросах, мы обращаем внимание также на команды вставки (INSERT) и изменения (UPDATE) данных, которые очень быстро могут модернизироваться под потребности различных баз данных. Также существуют методы для обработки дат, конкатенации строк и экранирования строк по правилам различных баз данных.
* Система мето-типов построена так, чтоб вы могли быть уверенными, что сохраняемые вами данные, например CHAR, TEXT, STRING, будут одинаковыми для всех баз данных.
* Легкая переносимость, потому что все низкоуровневые функции вынесены отдельно и вам нет необходимости вносить изменения в ядро класса.
* Переносимость на уровне создания таблиц и индексов.
* Контроль работы базы данных и тонкая настройка производительности.
* Поддержка сессии на уровне базы данных, поддержка истечения времени сессии и уведомлений.

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

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

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

<?php

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 &lt;pre>;
print_r($rs->GetRows());
print &lt;/pre>;

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

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

* 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).

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

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

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

<?php
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().

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

Начиная с версии ADODB 4.51 вы можете соединяться с базой передавая NewADOConnection() (или ADONewConnection()) параметры в виде DSN:
$driver://$username:$password@hostname/$database?options[=value]

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

<?php

# непостоянное соединение
$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:

<?php

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

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

* Для всех движков баз: persist, persistent, debug, fetchmode
* Для Interbase/Firebird: dialect,charset,buffers,role
* Для Msoft ADO: charpage
* Для MySQL: clientflags
* Для MySQLi: port, socket, clientflags
* Для Oci8: nls_date_format

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

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

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

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

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

<?php

$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 поддерживает строки соединения:

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

<?php

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

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

<?php

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

в) DSN:

<?php

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

LDAP

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

<?php

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 &lt;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 &lt;/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=50000;protocol=TCPIP;.
                uid=root; pwd=secret;
$db->Connect($dsn);

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

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

include(adodb.inc.php); 
$db = &ADONewConnection(ado_mssql);
print &lt;h1>Соединение DSN-less $db->databaseType...&lt;/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);

Оглавление | Обсудить на форуме | Главная страница сайта | Карта сайта |