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


Оглавление (нажмите, чтобы открыть):

Документация по PHP. Мануал по PHP, книги.

Документация на русском языке:
Перевод официальной документации — http://www.php.net/manual/ru/
Далеко не все еще переведено, но, тем не менее, эту ссылку можно рекомендовать, как замену официального англоязычного мана. Что переведено — будет по-русски. Не переведенное же будет точной копией английского.
Скачать полную версию документации в различных форматах (в том числе — в очень удобном .chm) можно здесь: http://www.php.net/download-docs.php
Перевод делается руками добровольцев, которых, как всегда, не хватает. Если вы хотите помочь этому благородному делу и чувствуете себя в силах, то пишите (in English please), в лист рассылки по адресу doc-ru@lists.php.net, а так же по этому адресу с благодарностью будут приняты сообщения о неточностях в переводе.

Удобно: Быстрый доступ к описанию функции из онлайн документации можно получить введя в браузере адрес www.php.net/имя_функции

Существует полный русский перевод документации от версии 4.2 от некоего Александра Пирамидина.
Перевод машинный, но тем не менее — вполне читабельный. ЧУДОВИЩНО устарел.
пользоваться этим переводом можно только в самом КРАЙНЕМ случае!
Только если нужный вам участок официальной документации не переведен, а в английском, даже с переводчиком — ни в зуб ногой.
Онлайн, на PHPClub-e, без баннеров: http://phpclub.ru/manrus/
chm-версия: http://web.php.net.ua/download?what=php4

Документация на английском языке.
Самая актуальная и правильная:
Онлайн, с комментариями пользователей: http://www.php.net/manual/en/
Очень удобно иметь всю документацию в одном файле с быстрым поиском. Такая документация есть, в формате windows help (.chm):
http://www.php.net/distributions/manual/php_manual_en.chm
Расширенный вариант документации в формате .chm, с очень ценными комментариями пользователей постоянно обновляется на этом сайте
http://weblabor.hu/php-doc-chm

Книги, журналы

PHP. Сборник рецептов. Пeревод самой лучшей книги по PHP.
Уникальная книга. Собрание конкретных ответов на конкретные вопросы. Как дату сложить, отнять, отформатировать. Как со строками работать, с файлами, с БД. Если сравнивать книги по количеству воды в них, то это будет пустыня Сахара. Книга разбита на 20 глав, каждая глава состоит из разделов вида: постановка проблемы — решение — объяснение.
Немного устарела, в плане того, в чем пхп сильно ушел вперед — XML, обработка ошибок. Однако в базовых основах языка остается непревзойдённой. Может использоваться как в виде справочника для решения конкретных проблем, так и в виде учебника.

Котеров Д., Костарев А., «PHP5 в подлиннике».
Второе издание знаменитой книги Д.Котерова. Не имеет ничего общего с первым. Это не переработанная, это совершенно новая книга. Уникальна тем, что подходит как начинающему, так и профессионалу — в ней изложены все аспекты программирования на PHP. В отличие от всех прочих скороспелок по «PHP5», вышедших ДО выхода самой пятой версии, книга действительно написана на материале релиза 5 версии.

Kuzma’s PHP Look

HOW TO по оптимизации PHP

В этом материале мы объясним, почему оптимизация PHP захватывает собой гораздо больше факторов, нежели простая оптимизация кода, и почему настройка PHP требует понимания, каким образом работает PHP относительно других компонентов вашего сервера. Также мы займемся выявлением узких мест, связанных с этими компонентами и устранением их. Также мы затронем вопросы оптимизации ваших PHP скриптов, чтобы они работали еще быстрее.

PDO. Часть 1.

Сегодня я начинаю цикл статей, посвящённых PDO, в котором мы разберём, что такое PDO, зачем он нам нужен и как его использовать.

Наверняка, многие уже слышали аббревиатуру PDO, но мало кто знает, что же это. Вот давайте сегодня об этом и поговорим.

Что такое PDO?

PDO(PHP Data Objects) — это просто интерфейс, позволяющий нам абстрагироваться от конкретной базы данных. Лучше всего показать на примере.

mysql_connect($host, $user, $pass); // MySQL
mysql_select_db($db);

pg_connect(«host=$host, dbname=$db, user=$user, password=$pass»); // PostgreSQL

В коде выше представлены способы для подключения к трём разным базам данных: MySQL, sqlite и PostgreSQL. Как видите, функции у каждой БД отличаются.

То же самое с другими действиями. Например, выборка данных из БД.

$sql = «INSERT INTO(name, pass) VALUES($name, $pass)»;

mysql_query($sql); // MySQL
sqlite_query($sql); // sqlite
pg_query($sql); // PostgreSQL

Зачем нужен PDO?

Представим, что у нас есть огромная база данных PostgreSQL, и мы решили сменить её на MySQL. Нам придётся переписывать очень много кода, и, скорее всего, без ошибок не обойдётся. Чтобы решить эту проблему и существует PDO, позволяющий нам не зависеть от конкретной базы.

Давайте рассмотрим, как мы теперь можем подключиться.

$db = new PDO(«mysql:host=$host;dbname=$db», $user, $pass); // MySQL
$db = new PDO(«sqlite:host=$host;dbname=$db», $user, $pass); // sqlite
$db = new PDO(«pgsql:host=$host;dbname=$db», $user, $pass); // PostgreSQL

Как видно из кода выше, в этих трёх подключениях меняется только строчка с названием БД, а остальное всё то же самое.

Чтобы что-нибудь выбрать, мы можем написать так:

Всё! Запрос выполнится независимо от того, какая у нас база данных.

Поддержка

PDO доступен с PHP 5.1. Чтобы мы могли «забыть», какую базу данных мы используем, за нас всё делают их драйверы. Чтобы их активировать, зайдите в файл php.ini и найдите там строчки, которые начинаются на extension=php_pdo_, а затем идёт название базы данных, и раскоментируйте их.

На этом всё для вступительной статьи, а в следующей мы уже начнём разбираться, как использовать PDO.

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

Если у Вас остались какие-либо вопросы, либо у Вас есть желание высказаться по поводу этой статьи, то Вы можете оставить свой комментарий внизу страницы.

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Она выглядит вот так:

  • BB-код ссылки для форумов (например, можете поставить её в подписи):
  • Комментарии ( 8 ):

    Теперь понятно стало. Спасибо за статью!

    А как работать с базой данных на простом текстовом файле ? Например с расширением .dat ? Как подключаться к такой базе данных ? Как делать выборку ? И так далее. И ещё :»Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.» Перехожу по ссылке : «Михаил ограничил доступ к своей странице.» Это что за такое странное приглашение добавиться .

    База данных на простом текстовом файле — это sqlite. Работать с ним через PDO точно так же, как и с MySQL. Об этом написано в статье, так что читайте внимательней. Если Вы хотите работать с обычным текстовым файлом, то Вам нужно использовать соответствующие функции. О них было написано на сайте ранее. На счёт вконтакте написано, что Вы можете добавиться в друзья и оставлять отзывы на стене страницы, а все вопросы пишите в службу тех. поддержки.

    В контакте я не могу добавиться в друзья. Страница заблокирована. Подскажите пожалуйста, или дайте ссылку на статью, где было описана работа с текстовыми файлами. И могу ли я эти функции использовать как обращение к базе данных на файлах ? Именно как к обычному текстовому файлу, а даже не sqlite. хотя он тоже является простым текстовым файлом.

    http://myrusakov.ru/file-php.html Судя по вашим вопросам, Вы не совсем понимаете работу php и баз данных. Советую приобрести курс «PHP и MySQL с нуля до гуру», и тогда вопросы отпадут.

    Всё понял. Этот момент, работу с файлами я знаю. Просто может я не так изъясняюсь. Мне не просто даётся всё это, мозг не так работает, как у молодого поколения. А изучать хочется, интересно. И Вам ОГРОМНОЕ спасибо за то что Вы помогаете ! А что насчёт «В КОНТАКТЕ» ?

    Использование библиотеки ADO (Microsoft ActiveX Data Object)

    Понятие о библиотеке ADO

    Библиотека ADO (Microsoft ActiveX Data Object) служит для доступа к базам данных различных типов и предоставляет объектный программный интерфейс к интерфейсу OLE DB, который предлагается компанией Microsoft как альтернатива интерфейсу ODBC. Объектная модель ADO реализована на базе технологии COM (Component Object Model).

    Библиотека ADO может быть использована в любых средах, которые в состоянии выступить в роли OLE-клиента, например, в MS Office (VBA), 1C:Предприятии, административных скриптах Windows (.vbs и .js) и т.д. Примеры кода в настоящей статье будут приводиться на языке VBScript для административных скриптов Windows. С помощью библиотеки ADO можно обратиться к огромному количеству типов баз данных, например, dBASE, Access, Excel, Oracle, Paradox, MS SQL Server, Sybase, текстовые файлы, FoxPro, Active Directory Service, Microsoft Jet, Interbase, Informix, PostgreSQL, MySQL и т.д., необходимо только наличие установленного соответствующего OLE-провайдера («драйвера» соответствующего типа базы данных, который устанавливается в систему как правило из дистрибутива этой же базы данных). Примеры кода в настоящей статье будут приводиться только для MS SQL Server, т.к. невозможно объять необъятное. Перечень свойств и методов ADO, приведённый в этой статье, не является исчерпывающим (в некоторых случаях и описание некоторых свойств и методов не является полным). Полное описание объектной модели библиотеки ADO вы можете получить в MSDN или в файле «ADO210.CHM», который входит в поставку MS Office. Однако материала данной статьи достаточно, чтобы начать работать с ADO.

    Основными объектами библиотеки ADO являются объекты Connection, Command и Recordset.

    Объект Connection


    Объект Connection обеспечивает создание подключения к источнику данных и эквивалентен текущему сетевому соединению с сервером. Объект Connection предоставляет возможность настройки соединения перед его открытием, установки базы данных по умолчанию, установки и разрыва соединения с источником данных, задания настроек и выполнения команды с помощью метода Execute. Примечание: для выполнения команды можно использовать также метод Execute объекта Command, не прибегая к объекту Connection.

    Объект Connection создаётся следующим образом:

    Set objConn = CreateObject(«ADODB.Connection»)

    После этого вы можете вызывать и использовать методы и свойства этого объекта для доступа к базам данных:

    Описание
    VersionСодержит строку, определяющую версию библиотеки. Только чтение.
    ConnectionStringОпределяет параметры подключения к источнику данных. Чтение и запись. Это строка, содержащая несколько параметров, разделённых точкой с запятой. Свойство ConnectionString автоматически получает значение, заданное в качестве одноимённого аргумента метода Open. Свойство ConnectionString доступно для записи только для закрытого соединения. Многочисленные примеры различных строк подключения для различных типов баз данных вы можете найти в Интернете или в документации к соответствующим программным продуктам.
    ConnectionTimeoutУстанавливает или возвращает число секунд ожидания подключения к базе данных. Значение по умолчанию — 15. Используйте это свойство, если возникают проблемы из-за плотного сетевого трафика или загруженности сервера. Если время, указанное в ConnectionTimeout, истекает до открытия подключения, происходит ошибка, и ADO отменяет попытку подключения. Если Вы установите свойство в ноль, ADO будет ждать бесконечно, пока подключение не будет открыто. Удостоверьтесь, что используемый провайдер поддерживает свойство ConnectionTimeout. Свойство доступно для записи только для закрытого соединения.
    CommandTimeoutУстанавливает или возвращает число секунд ожидания выполнения команды. Значение по умолчанию — 30. Чтение и запись. Используйте это свойство, если возникают проблемы из-за плотного сетевого трафика или загруженности сервера. Если время, указанное в CommandTimeout, истекает до завершения выполнения команды, происходит ошибка, и ADO отменяет команду. Если Вы установите свойство в ноль, ADO будет ждать бесконечно, пока команда не будет выполнена. Удостоверьтесь, что используемый провайдер поддерживает свойство CommandTimeout. Установка CommandTimeout объекта Connection никак не связана с установкой свойства CommandTimeout объекта Command.
    ProviderУстанавливает или возвращает строковое значение, которое содержит имя используемого провайдера. По умолчанию — «MSDASQL». Провайдер может быть также установлен содержанием свойства ConnectionString или параметром метода Open. Определение провайдера в более чем одном месте может иметь непредсказуемые результаты.
    DefaultDatabaseУстанавливает или возвращает строковое значение, которое содержит заданную по умолчанию базу данных. Если есть заданная по умолчанию база данных, запросы SQL могут использовать «дисквалифицированный» синтаксис для обращения к объектам в этой базе данных. Чтобы обращаться к объектам из другой базы данных, вы должны «квалифицировать» имена объектов именем этой базы данных. При подключении провайдер записывает заданную по умолчанию базу данных в это свойство. Некоторые провайдеры разрешают только одну такую базу данных на одно подключение, и в этом случае вы не сможете изменить это свойство. Некоторые источники данных и провайдеры могут не поддерживать это свойство, генерируя ошибку или возвращая пустую строку.
    CursorLocationОпределяет расположение курсора, т.е. место, где выполняется работа с данными. Возможные значения:

    • adUseNone(1) — курсор не используется (только для совместимости со старыми версиями).
    • adUseServer(2) — курсор на стороне провайдера (по умолчанию).
    • adUseClient(3) — курсор на стороне пользователя. Может предоставлять дополнительные возможности, которые отсутствуют на стороне провайдера.

    Изменение свойства CursorLocation не имеет никакого эффекта при уже существующем подключении. Связанные объекты Recordset и курсоры, возвращённые методом Execute, наследуют эту установку. При открытом объекте Recordset это свойство доступно только для чтения.
    ModeОпределяет режим доступа для изменения данных в сеансе. Возможные значения:

    • adModeUnknown(0) — режим доступа не установлен или не может быть определён (по умолчанию).
    • adModeRead(1) — режим только для чтения.
    • adModeWrite(2) — режим только для записи.
    • adModeReadWrite(3) — режим для чтения и записи.
    • adModeShareDenyRead(4) — не разрешает открывать соединение на чтение другим пользователям.
    • adModeShareDenyWrite(8) — не разрешает открывать соединение на запись другим пользователям.
    • adModeShareExclusive(12) — не разрешает открывать соединение другим пользователям.
    • adModeShareDenyNone(16) — разрешает открывать соединение с любым видом доступа другим пользователям.

    Вы можете установить это свойство только тогда, когда объект Connection закрыт.
    ErrorsСодержит коллекцию объектов Error. Любая инструкция, использующая объекты ADO, может сгенерировать одну или более ошибок провайдера. Когда происходит ошибка, в эту коллекцию могут быть помещены один или более объектов Error. Если следующая подобная инструкция также сгенерирует ошибку, коллекция будет очищена и заполнена заново. Каждый объект Error представляет определённую ошибку провайдера, но не ошибку ADO (ошибки ADO подвергаются механизму обработки исключительных ситуаций). Используйте метод Clear, чтобы вручную очистить коллекцию Errors. Некоторые свойства и методы возвращают предупреждения, которые появляются как объекты Error в коллекции Errors, при этом не останавливая выполнение программы. Перед тем, как вы вызываете методы Resync, UpdateBatch или CancelBatch объекта Recordset, метод Open объекта Connection, или устанавливаете свойство Filter объекта Recordset, вызовите метод Clear коллекции Errors. После этого вы можете прочитать свойство Count коллекции Errors, чтобы проверить возвращенные предупреждения.
    StateСодержит состояние объекта. Только чтение. Свойство State может принимать следующие значения:

    • adStateClosed(0) — объект закрыт.
    • adStateOpen(1) — объект открыт.
    • adStateConnecting(2) — объект соединяется.
    • adStateExecuting(4) — объект выполняет команду.
    • adStateFetching(8) — объект выполняет выборку строк.

    PropertiesСодержит коллекцию динамических свойств соединения (объектов Property). Подробнее — см. раздел «Динамические свойства объектов».
    Open(ConnectionString, UserID, Password, Options)Открывает сеанс подключения к источнику данных. Параметры:

    • ConnectionString — необязательный. Строка, определяющая параметры подключения к источнику данных. Автоматически наследует значение свойства ConnectionString объекта Connection. Вы можете или установить свойство ConnectionString объекта Connection перед вызовом метода Open, или использовать параметр ConnectionString метода Open.
    • UserID — необязательный. Имя пользователя, используемое при соединении.
    • Password — необязательный. Пароль пользователя.
    • Options — необязательный. Способ подключения к источнику данных. Возможные значения:
      • adAsyncConnect(16) — открывает подключение асинхронно. Чтобы определить, когда подключение станет доступным, можно обрабатывать событие ConnectComplete.
      • adConnectUnspecified(-1) — по умолчанию. Открывает подключение синхронно.

    Если вы передаете информацию о пользователе и пароле как в строке ConnectionString, так и в параметрах UserID и Password, параметры UserID и Password имеют приоритет. Закончив ваши операции с открытым подключением, используйте метод Close() для освобождения всех связанных системных ресурсов.
    Close()Закрывает соединение с источником данных. Закрытие объекта не приводит к удалению его из памяти. Можно изменить свойства объекта, а затем открыть его снова. При закрытии подключения закрываются также все активные наборы записей (объекты Recordset) для данного подключения. Объекты Command, связанные с данным подключением, уже не будут связаны с данным объектом Connection. Закрытие объекта Connection во время транзакции генерирует ошибку и ADO автоматически откатывает транзакцию.
    Execute(CommandText, RecordsAffected, Options)Выполняет запрос, оператор SQL, хранимую процедуру или любую другую команду, доступную провайдеру. Возвращает объект Recordset, доступный только для чтения курсором Forward-only, если переданная команда возвращает записи. (Если нужен объект Recordset, доступный для записи, следует создать его непосредственно, и воспользоваться его свойствами и методами.) Параметры:

    • CommandText — обязательный. Строка, содержащая оператор SQL, имя таблицы, хранимой процедуры или другую команду провайдера.
    • RecordsAffected — необязательный. Целое число (long), определяющее число записей, затронутых командой. Заполняется провайдером.
    • Options — необязательный. Целое число (long), определяющее тип команды. Возможные значения (значения можно суммировать):
      • adCmdText(1) — текстовое определение команды или хранимой процедуры.
      • adCmdTable(2) — создать SQL-запрос, который вернёт все строки указанной таблицы.
      • adCmdStoredProc(4) — хранимая процедура.
      • adCmdUnknown(8) — тип команды неизвестен (по умолчанию).
      • adAsyncExecute(16) — асинхронное выполнение команды.
      • adExecuteNoRecords(128) — не возвращать строки.

    Cancel()Отменяет выполнение последнего асинхронного вызова Execute() или Open(), если действие ещё не завершено.
    ConnectComplete(pError, adStatus, pConnection)Событие возникает после того, как осуществлено подключение к источнику данных. Параметры:

    • pError — содержит объект Error, если произошли ошибки (свойство adStatus равно adStatusErrorsOccurred(2))
    • adStatus — определяет состояние соединения. Возможные значения (для всех событий):
      • adStatusOK(1) — операция произведена успешно.
      • adStatusErrorsOccurred(2) — операция потерпела неудачу.
      • adStatusCantDeny(3) — операция не может быть отменена.
      • adStatusCancel(4) — произошла отмена операции.
      • adStatusUnwantedEvent(5) — предотвращает последующие уведомления до завершения выполнения метода события.
    • pConnection — объект Connection, который вызвал событие.

    Disconnect(adStatus, pConnection)Событие возникает после того, как прервано подключение к источнику данных. Параметры аналогичны параметрам события ConnectComplete.
    InfoMessage(pError, adStatus, pConnection)Событие возникает каждый раз, когда генерируется предупреждение (warning). Параметры аналогичны параметрам события ConnectComplete.
    WillConnect(ConnectionString, UserID, Password, Options, adStatus, pConnection)Событие возникает перед тем, как осуществлено подключение к источнику данных. Параметры в основном аналогичны параметрам события ConnectComplete. Options — целое число (long), которое указывает способ подключения — adAsyncConnect(16) или adConnectUnspecified(-1). В обработчике события можно изменять параметры подключения.
    WillExecute(Source, CursorType, LockType, Options, adStatus, pCommand, pRecordset, pConnection)Событие возникает перед выполнением команды. Параметры:

    • Source — строка, содержащая оператор SQL или имя хранимой процедуры.
    • CursorType — тип курсора для Recordset, который будет открыт. Тип курсора можно изменять. Возможные значения:
      • adOpenUnspecified(-1) — тип курсора не определён.
      • adOpenForwardOnly(0) — определяет forward-only курсор. То же, что и статический курсор, но вы можете прокручивать записи только вперед. Это оптимизирует выполнение, если вы должны сделать только один проход по Recordset’у.
      • adOpenKeyset(1) — Определяет keyset-курсор. То же, что и динамический курсор, но вы не можете видеть записи, добавляемые другими пользователями, хотя записи, удаляемые другими пользователями, недоступны в вашем Recordset’е. Изменения данных другими пользователями видимы.
      • adOpenDynamic(2) — Определяет динамический курсор. Добавления, изменения и удаления другими пользователями видимы; разрешены все типы движения через Recordset, исключая закладки, если провайдер их не поддерживает.
      • adOpenStatic(3) — Определяет статический курсор. Статическая копия набора записей, которую вы можете использовать, чтобы найти данные или генерировать отчёты. Добавления, изменения или удаления другими пользователями не видимы.
    • LockType — тип блокировки для Recordset, который будет открыт. Возможные значения:
      • adLockUnspecified(-1) — тип блокировки не определён.
      • adLockReadOnly(1) — только для чтения. Вы не можете изменить данные.
      • adLockPessimistic(2) — пессимистическая блокировка. Провайдер гарантирует успешное редактирование записей. Запись блокируется сразу после начала редактирования и до момента сохранения записей.
      • adLockOptimistic(3) — оптимистическая блокировка. Провайдер осуществляет блокировку записей только в момент сохранения изменений, т.е. когда вы вызываете метод Update().
      • adLockBatchOptimistic(4) — оптимистические пакетные модификации. Требуется для пакетного режима модификации (отложенное сохранение записей).
    • Options — целое число (long), указывающее опции выполнения команды или открытия Recordset’а.
    • adStatus — определяет состояние события. Возможные значения — см. описание аналогичного параметра события ConnectComplete.
    • pCommand — объект Command, для которого применяется это событие.
    • pRecordset — объект Recordset, для которого применяется это событие.
    • pConnection — объект Connection, для которого применяется это событие.

    Событие WillExecute может произойти из-за вызовов Connection.Execute, Command.Execute, или Recordset.Open. Параметр pConnection всегда содержит ссылку на объект Connection. Если событие происходит из-за вызова Connection.Execute, параметры pRecordset и pCommand будут установлены в Nothing. Если событие происходит из-за вызова Recordset.Open, параметр pRecordset будет содержать ссылку на объект Recordset, а параметр pCommand будет установлен в Nothing. Если событие происходит из-за вызова Command.Execute, параметр pCommand будет содержать ссылку на объект Command, а параметр pRecordset будет установлен в Nothing.
    ExecuteComplete(RecordsAffected, pError, adStatus, pCommand, pRecordset, pConnection)Событие происходит после завершения работы команды. Параметр RecordsAffected — целое число (long) — содержит количество записей, которые затрагивает команда. Остальные параметры аналогичны одноимённым параметрам описанных выше других событий. Событие ExecuteComplete может произойти вследствие вызовов Connection.Execute, Command.Execute, Recordset.Open, Recordset.Requery или Recordset.NextRecordset.
    BeginTrans()

    RollbackTrans()

    Вызов метода BeginTrans начинает новую транзакцию. Провайдеры, которые поддерживают вложенные транзакции, при вызове метода BeginTrans в пределах открытой транзакции начинают новую, вложенную транзакцию. Возвращаемое методом BeginTrans значение указывает уровень вложения: возвращаемое значение «1» указывает, что вы открыли транзакцию верхнего уровня (то есть транзакция не вложена в пределах другой транзакции), «2» указывает, что вы открыли транзакцию второго уровня (транзакция, вложенная в пределах транзакции верхнего уровня), и т.д.

    Вызов метода CommitTrans сохраняет изменения, сделанные в пределах открытой транзакции и завершает транзакцию. Вызов метода RollbackTrans полностью отменяет любые изменения, сделанные в пределах открытой транзакции и завершает транзакцию. Вызов любого из этих методов в момент, когда нет никакой открытой транзакции, генерирует ошибку. Вызовы методов CommitTrans или RollbackTrans затрагивают только последнюю открытую транзакцию; вы должны закрыть или откатить текущую транзакцию прежде, чем разрешить любые высокоуровневые транзакции.

    BeginTransComplete(TransactionLevel, pError, adStatus, pConnection)

    CommitTransComplete(pError, adStatus, pConnection)

    RollbackTransComplete(pError, adStatus, pConnection)

    Эти события вызываются после того, как заканчивает выполняться соответствующая операция (по работе с транзакциями) на объекте Connection.
    OpenSchema(QueryType, Criteria, SchemaID)Получает информацию схемы базы данных от провайдера. Возвращает объект Recordset. Recordset будет открыт как статический курсор только для чтения. Параметры:

    • QueryType — число, тип запроса схемы. Подробнее — см. MSDN, описание перечисления «SchemaEnum».
    • Criteria — необязательный. Массив ограничений запроса (фильтр). Подробнее — см. MSDN.
    • SchemaID — GUID для запроса схемы провайдера, не определенной спецификацией. Этот параметр требуется, если QueryType установлен в adSchemaProviderSpecific(-1); иначе этот параметр не используется.

    Объект Error содержит информацию об ошибках доступа к данным, которые принадлежат отдельной операции провайдера. Вы можете обратиться к свойствам объекта Error, чтобы получить информацию о каждой ошибке:

    Описание
    Description Содержит строку, определяющую короткое описание ошибки. Это свойство по умолчанию.
    Number Содержит уникальный код, определяющий тип ошибки (целое число).
    Source Идентифицирует имя объекта, который вызвал ошибку (строка).
    SQLState Содержит строку из пяти символов, которая указывает код ошибки по стандарту SQL ANSI.
    NativeError Содержит определённый провайдером код ошибки (целое число).

    Подключаемся к базе данных и выполняем запрос с помощью объекта Connection:

    Работаем с ошибками провайдера:

    Пример асинхронного подключения и обработки событий:

    Пример асинхронного выполнения запроса и обработки событий:

    Пример работы с транзакциями:

    Пример работы с методом OpenSchema:

    Динамические свойства объектов

    Объекты Connection, Command, Recordset, Parameter и Field имеют встроенную коллекцию Properties, содержащую объекты Property. Коллекция имеет следующие свойства и методы:

    • Count — содержит количество объектов в коллекции.
    • Item(index) — возвращает элемент коллекции по имени или порядковому номеру.
    • Refresh() — обновляет коллекцию, чтобы отразить доступные объекты, определённые провайдером.

    Объект Property представляет динамические характеристики объекта ADO, которые определяются провайдером данных. Объект Property обладает следующими свойствами:

    Описание
    NameСодержит имя свойства (строка).
    TypeСодержит тип свойства. Может принимать значения перечисления DataTypeEnum (подробнее — см. MSDN, а также свойство Type объекта Parameter в данной статье).
    ValueСодержит значение свойства.
    AttributesСодержит одну или несколько характеристик свойства — сумму одной или более констант:

    • adPropNotSupported(0) — провайдер не поддерживает это свойство.
    • adPropRequired(1) — пользователь должен задать значение данного свойства перед инициализацией источника данных.
    • adPropOptional(2) — пользователю не требуется задавать значение данного свойства перед инициализацией источника данных.
    • adPropRead(512) — данное свойство доступно для чтения.
    • adPropWrite(1024) — пользователь может задать значение данному свойству.

    Вы можете изменять значения (Value) этих свойств, но не их характеристики (Attributes). Вы не можете удалить такое свойство.

    Чтение коллекции Properties:

    Смена текущей базы данных с помощью коллекции Properties:

    Объект Command

    Объект Command создаётся следующим образом:

    Set objComm = CreateObject(«ADODB.Command»)

    После этого вы можете вызывать и использовать методы и свойства этого объекта.

    Объект Command существует для задания и выполнения команд и запросов. Хотя запрос можно выполнить и без использования объекта Command (с помощью метода Execute объекта Connection или метода Open объекта Recordset), объект Command незаменим при выполнении запроса с параметрами и удобен в случае, когда требуется сохранить текст команды для её повторного использования. Объект Command может быть использован как в паре с объектом Connection, так и без него, т.к. строку подключения можно задать непосредственно в свойстве ActiveConnection объекта Command.

    Свойства и методы объекта Command:


    Описание
    ActiveConnectionОпределяет объект Connection, с которым связан данный объект Command. Значением этого свойства может быть и строка, содержащая ту же информацию, что и свойство ConnectionString объекта Connection. Попытка выполнить метод Execute объекта Command при незаданном свойстве ActiveConnection приведёт к ошибке. Назначение закрытого объекта Connection в качестве значения свойства ActiveConnection также вызовет ошибку (объект должен быть открыт). Закрытие объекта Connection, с которым связан объект Command, устанавливает свойство ActiveConnection в Nothing.
    CommandTextСтрока, определяющая текст команды, например, оператор SQL, имя таблицы или вызов хранимой процедуры. В зависимости от установки свойства CommandType, ADO может автоматически изменить свойство CommandText.
    CommandTimeoutУстанавливает или возвращает число секунд ожидания выполнения команды. Значение по умолчанию — 30. Чтение и запись. Используйте это свойство, если возникают проблемы из-за плотного сетевого трафика или загруженности сервера. Если время, указанное в CommandTimeout, истекает до завершения выполнения команды, происходит ошибка, и ADO отменяет команду. Если Вы установите свойство в ноль, ADO будет ждать бесконечно, пока команда не будет выполнена. Удостоверьтесь, что используемый провайдер поддерживает свойство CommandTimeout. Установка CommandTimeout объекта Connection никак не связана с установкой свойства CommandTimeout объекта Command.
    CommandTypeОпределяет тип команды. Возможные значения:

    • adCmdUnspecified(-1) — тип команды не определён.
    • adCmdText(1) — текстовое определение команды или хранимой процедуры.
    • adCmdTable(2) — создать SQL-запрос, который вернёт все строки указанной таблицы.
    • adCmdStoredProc(4) — хранимая процедура.
    • adCmdUnknown(8) — тип команды неизвестен (по умолчанию).

    Если значение свойства равно adCmdUnknown (по умолчанию), команды могут выполняться медленнее, потому что ADO должна делать запросы провайдеру, чтобы определить, является ли CommandText инструкцией SQL, хранимой процедурой или именем таблицы. Если свойство CommandType не соответствует типу команды в свойстве CommandText, при вызове метода Execute происходит ошибка.
    PreparedУказывает, сохранить ли откомпилированную версию команды перед первым выполнением (true или false). Это может замедлить первое выполнение команды, но ускорит любое последующее выполнение. Если провайдер не поддерживает компиляцию команды, при установке этого свойства в true может произойти ошибка (или автоматическая установка в false).
    StateСодержит состояние объекта. Только чтение. Возможные значения:

    • adStateClosed(0) — объект закрыт.
    • adStateOpen(1) — объект открыт.
    • adStateConnecting(2) — объект соединяется.
    • adStateExecuting(4) — объект выполняет команду.
    • adStateFetching(8) — объект выполняет выборку строк.

    Свойство State может иметь комбинацию значений. Например, если асинхронно выполняется инструкция, это свойство будет иметь объединенное значение adStateOpen и adStateExecuting.
    PropertiesСодержит коллекцию динамических свойств объекта (объектов Property). Подробнее — см. раздел «Динамические свойства объектов».
    ParametersСодержит коллекцию параметров объекта (объектов Parameter). Использование метода Refresh() этой коллекции отыскивает информацию параметров для хранимой процедуры или параметрического запроса. Некоторые провайдеры не поддерживают хранимые процедуры или параметрические запросы; в этом случае вызов метода Refresh() вызовет ошибку. Перед вызовом метода Refresh() вы должны правильно установить значения свойств ActiveConnection, CommandText и CommandType. Если вы обращаетесь к коллекции перед вызовом метода Refresh(), ADO автоматически вызовет его и заполнит коллекцию. Коллекция параметров имеет следующие свойства и методы:

    • Count — содержит количество объектов в коллекции.
    • Item(index) — возвращает элемент коллекции по имени или порядковому номеру.
    • Append(object) — добавляет предварительно созданный объект в коллекцию.
    • Delete(index) — удаляет элемент из коллекции по имени или порядковому номеру.
    • Refresh() — обновляет коллекцию, чтобы отразить доступные объекты, определённые провайдером.

    NamedParametersУказывает, нужно ли передавать провайдеру имена параметров. Булево (по умолчанию — ложь). Если это свойство установлено в True, ADO передаёт значение имени каждого параметра в коллекции параметров. Провайдер использует имя параметра, чтобы установить соответствие параметрам в свойстве CommandText. Если это свойство установлено в ложь, имена параметров игнорируются, и провайдер использует порядок параметров, чтобы установить соответствие параметрам в свойстве CommandText.
    Execute(RecordsAffected, Parameters, Options)Выполняет запрос, оператор SQL, хранимую процедуру или любую другую команду, доступную провайдеру. В основном аналогичен методу Execute() объекта Connection (см. выше). Все параметры являются необязательными. Параметр «Parameters» представляет собой массив параметров типа Variant, передаваемый оператору SQL (не для выходных параметров).
    Cancel()Отменяет выполнение последнего асинхронного вызова Execute(), если действие ещё не завершено.
    CreateParameter(Name, Type, Direction, Size, Value)Создаёт и возвращает объект Parameter с заданными свойствами. Метод CreateParameter не добавляет созданный параметр к коллекции Parameters. Для этого следует использовать метод Append(objParameter) этой коллекции. Аргументы метода CreateParameter (все аргументы необязательные):

    • Name — строка, имя параметра.
    • Type — целое число (long), тип данных параметра (строка, число, булево и т.д.). Подробнее — см. в MSDN значения перечисления DataTypeEnum, а также свойство Type объекта Parameter в данной статье.
    • Direction — целое число (long), «направление» параметра. Возможные значения:
      • adParamUnknown(0) — направление параметра неизвестно.
      • adParamInput(1) — по умолчанию, входной параметр.
      • adParamOutput(2) — выходной параметр.
      • adParamInputOutput(3) — параметр представляет собой и входной, и выходной параметр
      • adParamReturnValue(4) — параметр представляет собой возвращаемое значение.
    • Size — целое число (long), максимальная длина параметра в символах или байтах.
    • Value — Variant, значение параметра.

    Объект Parameter является членом коллекции Parameters и представляет собой параметр запроса с параметрами (например, критерий сравнения предложения WHERE оператора SELECT) или параметр хранимой процедуры. В зависимости от функциональных возможностей провайдера некоторые методы или свойства объекта Parameter могут быть недоступны. Если вы знаете имена и свойства параметров, связанных с хранимой процедурой или параметризованным запросом, вы можете использовать метод CreateParameter для создания объектов Parameter и метод Append() для добавления их к коллекции параметров. Это позволит вам не вызывать метод Refresh() коллекции параметров, чтобы отыскать информацию о параметрах с помощью провайдера (потенциально ресурсоёмкая операция). Свойства и методы объекта Paramrter:

    Описание
    NameСтрока, имя параметра. Для объектов Parameter, ещё не добавленных в коллекцию параметров, это свойство доступно для чтения и записи, в противном случае — только для чтения.
    ValueVariant, значение параметра. Если команда содержит параметр, свойство Value которого пусто, и вы получаете от команды объект Recordset, вы должны закрыть Recordset перед чтением свойства Value. Иначе (для некоторых провайдеров) свойство Value может не содержать правильное значение.
    AttributesСодержит сумму одной или более характеристик объекта (целое число, long). Чтение и запись. Возможные значения:

    • adParamSigned(16) — параметр принимает значения со знаком.
    • adParamNullable(64) — параметр принимает пустые значения.
    • adParamLong(128) — параметр принимает двоичные данные.

    DirectionЦелое число (long), «направление» параметра. Возможные значения — см. описание метода CreateParameter объекта Command. Не все провайдеры могут определить направление параметров в их хранимых процедурах. В таких случаях вы должны установить свойство Direction прежде, чем выполните запрос.
    PrecisionУказывает степень точности для числовых значений. Целое число (byte), которое указывает максимальное число цифр.
    NumericScaleУказывает масштаб числовых значений. Целое число (byte), которое указывает число десятичных разрядов справа от десятичной точки.
    SizeЦелое число (long), максимальная длина параметра в символах или байтах. Во многих случаях во избежание ошибок крайне желательно заполнить этот параметр.
    TypeЦелое число (long), тип данных параметра (строка, число, булево и т.д.). Подробнее — см. в MSDN значения перечисления DataTypeEnum. Некоторые возможные значения:

    • adEmpty(0) — значение не задано.
    • adSmallInt(2) — двухбайтное целое со знаком.
    • adInteger(3) — четырёхбайтное целое со знаком.
    • adSingle(4) — число с плавающей запятой с одинарной точностью.
    • adDouble(5) — число с плавающей запятой с двойной точностью.
    • adCurrency(6) — денежная сумма с фиксированной точкой с четырьмя цифрами справа от десятичной точки (восьмибайтное целое число со знаком).
    • adError(10) — 32-битный код ошибки.
    • adBoolean(11) — булево значение.
    • adDecimal(14) — числовое значение с фиксированной точностью и масштабом.
    • adTinyInt(16) — однобайтное целое со знаком.
    • adUnsignedTinyInt(17) — однобайтное целое без знака.
    • adUnsignedSmallInt(18) — двухбайтное целое без знака.
    • adUnsignedInt(19) — четырёхбайтное целое без знака.
    • adBigInt(20) — восьмибайтное целое со знаком.
    • adUnsignedBigInt(21) — восьмибайтное целое без знака.
    • adBinary(128) — двоичное значение.
    • adChar(129) — строковое значение.
    • adUserDefined(132) — определяемая пользователем переменная.
    • adDBDate(133) — дата формата yyyymmdd.
    • adDBTime(134) — время формата hhmmss.
    • adDBTimeStamp(135) — дата и время формата yyyymmddhhmmss плюс тысячные доли секунды.

    AppendChunk(Data)Добавляет данные в конец большого текста или двоичных данных. Параметр Data имеет тип Variant. В ситуациях, когда системная память ограничена, вы можете использовать метод AppendChunk для управления большими значениями по частям. Первый вызов AppendChunk() перезаписывает новые данные поверх любых существующих данных. Последующие вызовы AppendChunk() добавляют данные к существующим данным параметра. Вызов AppendChunk() с пустым значением удаляет все данные параметра.
    PropertiesСодержит коллекцию динамических свойств объекта (объектов Property). Подробнее — см. раздел «Динамические свойства объектов».

    Пример «независимого» использования объекта Command:

    Пример использования объекта Command в паре с объектом Connection:

    Пример получения информации о параметрах хранимой процедуры:

    Пример исполнения хранимой процедуры с параметрами — упаковка файла в CAB-архив средствами SQL-сервера:

    Объект Recordset

    Объект Recordset создаётся следующим образом:

    Set objConn = CreateObject(«ADODB.Recordset»)

    После этого вы можете вызывать и использовать методы и свойства этого объекта. Объект Recordset состоит из записей и полей. Не все свойства объекта поддерживаются всеми провайдерами.

    При открытии набора записей (Recordset’а) вы должны определить тип используемого курсора. В библиотеке ADO определены четыре типа курсоров:

    • Динамический курсор (Dynamic cursor). Позволяет видеть данные, добавленные, изменённые и удалённые другими пользователями. Допускает все типы переходов по набору записей, а также использование закладок, если это позволяет провайдер.
    • Курсор набора данных (Keyset cursor). Позволяет видеть данные, изменённые другими пользователями. Допускает все типы переходов по набору записей, а также использование закладок, если это позволяет провайдер.
    • Статический курсор (Static cursor). Позволяет получить копию набора записей для создания отчёта. Допускает все типы переходов по набору записей, а также использование закладок, если это позволяет провайдер.
    • Курсор Forward-only (Forward-only cursor). Аналогичен предыдущему, но позволяет проходить через набор записей только вперёд. Обеспечивает максимальную производительность.

    Чтобы открыть набор записей в одном из рассмотренных четырёх режимов, необходимо задать соответствующее значение свойству CursorType или параметру CursorType метода Open. Не все провайдеры поддерживают все типы курсоров. По умолчанию используется курсор типа Forward-only.

    При открытии объекта Recordset текущей записью становится первая запись, а свойства EOF и BOF получают значение False.

    Объект Recordset предусматривает два типа обновлений: немедленное и пакетное. В первом случае все изменения данных немедленно записываются в базу после вызова метода Update(). Во втором случае (если тип блокировки для Recordset — adLockBatchOptimistic(4), режим обновления будет пакетным) несколько обновлённых строк может помещаться в локальный буфер, после чего реализуется одновременное обновление нескольких полей источника данных с помощью метода UpdateBatch().

    Свойства и методы объекта Recordset:

    Описание
    ActiveConnectionСодержит объект Connection, к которому привязан данный Recordset, или строку параметров подключения (ConnectionString).
    ActiveCommandСодержит объект Command, который породил данный Recordset. Только чтение. Если объект Command не использовался, пусто.
    SourceСодержит источник данных объекта Recordset. Это ссылка на объект Command, оператор SQL, имя таблицы или хранимой процедуры. Свойству можно задать значение только при закрытом в данный момент объекте Recordset.
    FilterСодержит фильтр данных. Может принимать значения трёх типов:

    • Строка, составленная из одного или более индивидуальных предложений с операторами AND или OR, например «LastName = ‘Smith’ AND FirstName = ‘John'».
    • Массив закладок — уникальных значений Bookmark.
    • Одно из значений перечисления FilterGroupEnum (подробнее — см. MSDN).

    Используйте это свойство для выборочного сканирования объекта Recordset. Установка свойства переместит курсор на первую запись, которая удовлетворяет фильтру.
    CursorTypeСодержит тип курсора. Может быть изменено только до открытия объекта Recordset. Возможные значения — см. описание аргумента CursorType события WillExecute объекта Connection.
    LockTypeСодержит тип блокировки для объекта Recordset. Доступно для записи при закрытом объекте Recordset. Возможные значения — см. описание аргумента LockType события WillExecute объекта Connection.
    MaxRecordsИспользуйте это свойство, чтобы ограничить количество записей, которые возвращает провайдер в результате запроса к источнику данных. По умолчанию — 0, что означает, что провайдер возвращает все требуемые записи.
    StateСодержит состояние объекта. Возможные значения — см. описание свойства State объекта Command.
    CacheSizeУстанавливает количество записей объекта Recordset (обязательно больше 0), которые кэшируются (локально) в памяти. Значение по умолчанию 1. Например, если CacheSize = 10, после открытия объекта Recordset провайдер помещает первые 10 записей в локальную память. По мере того, как вы двигаетесь по записям объекта Recordset, провайдер возвращает данные из локального буфера памяти. Как только вы минуете последнюю запись в кэше, провайдер помещает следующие 10 записей из источника данных в кэш. Записи в кэше не отражают изменения, которые делают другие пользователи. Чтобы вызвать модификацию всех кэшируемых данных, используйте метод Resync().
    Open(Source, ActiveConnection, CursorType, LockType, Options)Открывает курсор. Все параметры необязательные. Параметры:

    • Source — может принимать следующие значения:
      • Ссылка на объект Command.
      • Строка с оператором SQL, именем таблицы или хранимой процедуры.
      • Имя файла с сохранённым набором записей.
    • ActiveConnection — ссылка на объект Connection или строка параметров подключения (ConnectionString).
    • CursorType — тип курсора. Возможные значения — см. описание аргумента CursorType события WillExecute объекта Connection.
    • LockType — тип блокировки записей. Возможные значения — см. описание аргумента LockType события WillExecute объекта Connection.
    • Options — целое число (long), определяющее тип команды. Возможные значения (значения можно суммировать):
      • adCmdText(1) — текстовое определение команды или хранимой процедуры.
      • adCmdTable(2) — создать SQL-запрос, который вернёт все строки указанной таблицы.
      • adCmdStoredProc(4) — хранимая процедура.
      • adCmdUnknown(8) — тип команды неизвестен (по умолчанию).
      • adAsyncExecute(16) — асинхронное выполнение команды. Нельзя сочетать с adCmdTableDirect(512).
      • adAsyncFetch(32) — строки, не находящиеся в кеше (размер кеша определяется свойством CacheSize), будут выбраны асинхронно.
      • adAsyncFetchNonBlocking(64) — никогда не осуществлять блокировки при поиске.
      • adCmdFile(256) — имя файла с сохранённым набором записей.
      • adCmdTableDirect(512) — создать SQL-запрос, который вернёт все строки указанной таблицы. Позволяет использовать метод Seek() в паре со свойством Index (в данной статье не рассматриваются), если используется курсор на стороне сервера.

    По умолчанию Recordset будет открыт с курсором forward-only read-only на стороне сервера.
    Close()Закрывает объект Recordset. Если вы закрываете объект Recordset в пакетном режиме модификации, все изменения после последнего вызова UpdateBatch() будут потеряны.
    RecordCountСодержит количество записей в объекте Recordset. Если провайдер или тип курсора не поддерживает данное свойство, содержит -1.
    Requery(Options)Обновляет данные в объекте Recordset путём повторного выполнения запроса. Эквивалентно вызову Close(), а затем Open(). Возможные значения параметра Options — см. описание аргумента Options метода Open() объекта Recordset.
    Resync(AffectRecords, ResyncValues)Обновляет данные в объекте Recordset. Не выполняет повторного запроса к базе данных, поэтому вновь добавленные записи не будут видны. Если существующие записи были удалены из базы данных, произойдёт ошибка. Этот метод обычно используют со статическим курсором или курсором типа Forward-only, чтобы видеть изменения, внесённые в базу данных. Параметры (все параметры необязательные):

    • AffectRecords — определяет записи, на которые воздействует метод. Возможные значения:
      • adAffectCurrent(1) — обновляет только текущую запись.
      • adAffectGroup(2) — обновляет все записи, удовлетворяющие фильтру, заданному свойством Filter (например, если Filter — массив «закладок»).
      • adAffectAll(3) — по умолчанию. Обновляет все записи. Однако, если свойство Filter содержит строку типа «Author =’Smith'», то операция затронет только часть записей.
      • adAffectAllChapters(4) — обновляет все записи.
    • ResyncValues — определяет возможность перезаписи значений основной таблицы. Возможные значения:
      • adResyncAllValues(2) — по умолчанию. Осуществляет перезапись данных с отменой отложенных обновлений.
      • adResyncUnderlyingValues(1) — изменённые данные не перезаписываются и отложенные обновления не отменяются.

    Save(FileName, PersistFormat)Сохраняет набор записей в файл или объект Stream (не рассматривается в данной статье). Может быть вызван только для открытого набора записей. После вызова метода текущей становится первая строка набора записей. Параметры (все параметры необязательные):

    • FileName — полное имя файла, в котором будет сохранён набор записей, или ссылка на объект Stream. По умолчанию используется свойство Source как имя файла. В принципе, сюда можно поместить ссылку на любой объект, который поддерживает OLE DB IStream интерфейс, например, MSXML DOM object («MSXML.DOMDocument»).
    • PersistFormat — формат, в котором будет сохранён набор записей. Возможные значения:
      • adPersistADTG(0) — по умолчанию. Формат Microsoft Advanced Data TableGram (ADTG).
      • adPersistXML(1) — специфический формат XML ADO в кодировке UTF-8.
      • adPersistProviderSpecific(2) — собственный формат провайдера.

    Если установлено свойство Filter, будут сохранены только записи, удовлетворяющие фильтру.
    Clone(LockType)Возвращает копию исходного объекта Recordset. Необязательный параметр LockType определяет тип блокировки: как у оригинала или только для чтения. Допустимые значения — adLockUnspecified(-1) или adLockReadOnly(1). Использование метода Clone() более эффективно, чем создание и открытие нового объекта Recordset с теми же параметрами. Свойство Filter оригинала не будет применено к клону. Текущей записью только что созданного клона будет первая. Изменения, которые вы делаете в оригинальном объекте Recordset, видимы во всех его клонах независимо от типа курсора. Однако после того, как вы выполните метод Requery() на оригинале, клоны больше не будут синхронизированы с оригиналом. Закрытие оригинала не закрывает копии. Значения закладок (Bookmark) взаимозаменяемы для оригинала и клонов. Некоторые события объекта Recordset (объект Recordset имеет события — в данной статье они не рассматриваются) будут происходить одновременно для всех клонов. Однако, поскольку текущая запись оригинала может отличаться от текущей записи клона, события могут быть неверно обработаны для клона.
    BOF
    EOF
    Если свойство BOF содержит True, текущая запись (курсор) находится перед первой записью в объекте Recordset. Если свойство EOF содержит True, текущая запись (курсор) находится после последней записи в объекте Recordset. При открытии пустого объекта Recordset оба этих свойства содержат True.
    Move(NumRecords, Start)Передвигает позицию текущей записи в наборе записей. Параметры:

    • NumRecords — целое число (long), количество записей, на которое перемещается позиция. При использовании отрицательных значений позиция передвигается назад.
    • Start — необязательный. Может быть закладкой, с которой начинается отсчёт (см. свойство Bookmark). Другие возможные значения:
      • adBookmarkCurrent(0) — от текущей записи (по умолчанию).
      • adBookmarkFirst(1) — от первой записи.
      • adBookmarkLast(2) — от последней записи.

    Вызов метода для пустого набора записей приведёт к ошибке.
    MoveFirst()
    MoveLast()
    MoveNext()
    MovePrevious()
    Передвигают позицию текущей записи соответственно на первую, последнюю, следующую или предыдущую запись. Вызов MoveFirst() в объекте Recordset типа forward-only может заставить провайдера заново выполнить команду, которая сгенерировала этот Recordset.
    AbsolutePositionПри установке перемещает курсор на запись под данным номером. Доступно не для всех видов курсоров. Значение в интервале с 1 по RecordCount. Свойство поддерживается не всеми провайдерами.
    BookmarkЗакладка в виде числа. Доступно не для всех видов курсоров. Никак не связана с номером записи. Можно при проходе по таблице запомнить значение Bookmark во временной переменной, а затем вернуться обратно на данную запись путём установки свойства из этой переменной. Закладка уникально идентифицирует запись. Тип данных закладки определяется провайдером и воспринимается ADO как Variant.
    PageSizeЗадаёт число записей на странице. По умолчанию — 10. Доступно не для всех видов курсоров.
    PageCountСодержит количество страниц. Автоматически пересчитывается при изменении PageSize. Доступно не для всех видов курсоров.
    AbsolutePageПри установке перемещает курсор на начало данной страницы. Доступно не для всех видов курсоров. Значение в интервале с 1 по PageCount. Свойство поддерживается не всеми провайдерами.
    Delete(AffectRecords)Удаляет текущую запись или группу записей. Если объект Recordset не допускает удаления записей, произойдёт ошибка. Если вы находитесь в пакетном режиме модификации, фактическое удаление происходит при вызове UpdateBatch(). Вы можете отменить удаление вызовом CancelBatch(). Параметр AffectRecords (необязательный) может принимать значения:

    • adAffectCurrent(1) — удаляется текущая запись (по умолчанию).
    • adAffectGroup(2) — удаляются все записи, удовлетворяющие фильтру, заданному свойством Filter.

    AddNew(Fields, Values)Добавляет запись с указанными значениями полей в конец объекта Recordset и делает её текущей. Параметры (все параметры необязательные):

    • Fields — имя поля или массив имён полей, для которых задаются значения.
    • Values — значение поля или массив значений полей.

    Чтобы сохранить добавленную запись, необходимо вызвать метод Update(). При непосредственном режиме модификации, если вы передаете параметры Fieldlist и Values, ADO немедленно отправляет новую запись в базу данных (вызов Update() не нужен). В пакетном режиме модификации для сохранения записи в базе данных нужно вызвать метод UpdateBatch().
    Update(Fields, Values)Сохраняет любые изменения текущей записи объекта Recordset. Параметры (все параметры необязательные):

    • Fields — имя поля или массив имён полей, в которых следует сохранить изменения.
    • Values — значение поля или массив значений полей.

    Если курсор перемещён с добавленной или изменённой записи, метод вызывается автоматически.
    CancelUpdate()Отменяет любые изменения или добавления записей, проведённые до использования метода Update().
    UpdateBatch(AffectRecords, PreserveStatus)Для пакетного режима модификации: записывает все изменения объекта Recordset в базу данных. Только для курсоров Keyset или Static. Если вызов метода привёл к ошибкам из-за конфликта с основными данными (например, запись была уже удалена другим пользователем), используйте коллекцию Errors и обрабатывайте ошибки времени выполнения (run-time errors). Используйте свойства Filter и Status, чтобы определить местонахождение записей с конфликтами. Чтобы отменить все ожидающие разрешения пакетные модификации, используйте метод CancelBatch(). Порядок, в котором модификации выполняются на источнике данных, не обязательно тот же, в котором эти модификации были выполнены в текущем объекте Recordset. Параметры (все параметры необязательные):

    • AffectRecords — указывает, какие записи затронет метод. Возможные значения — см. описание аргумента AffectRecords метода Resync().
    • PreserveStatus — если установлено в True, свойство Status каждой записи остаётся неизменным.

    CancelBatch(AffectRecords)Отменяет любые ожидающие разрешения модификации в пакетном режиме модификации. Обработка ошибок аналогична методу UpdateBatch(). Необязательный параметр AffectRecords указывает, какие записи затронет метод. Возможные значения — см. описание аргумента AffectRecords метода Resync().
    StatusСодержит статус текущей записи относительно пакетных модификаций или других объёмных операций. Возможные значения — см. в MSDN описание перечисления RecordStatusEnum.
    SetAllRowStatus(recStatus)Устанавливает свойство Status всех записей к указанному значению. Единственное допустимое значение аргумента recStatus — adRecNew(1) — указывает, что запись новая.
    EditModeСодержит состояние редактирования текущей записи (был ли вызван метод Update() или UpdateBatch() для сохранения изменений). Возможные значения:

    • adEditNone(0) — редактирование не проводилось.
    • adEditInProgress(1) — редактирование проводилось, но изменения не сохранены.
    • adEditAdd(2) — текущая запись добавлена с помощью метода AddNew(), но ещё не сохранена.
    • adEditDelete(4) — текущая запись была удалена.

    Cancel()Отменяет последний асинхронный вызов Open(), если процесс ещё не завершён.
    FieldsСодержит коллекцию полей (объектов Field). Свойства и методы коллекции — см. раздел «Коллекция полей Fields».
    PropertiesСодержит коллекцию динамических свойств объекта (объектов Property). Подробнее — см. раздел «Динамические свойства объектов». Доступно для открытого объекта Recordset.
    CursorLocationОпределяет расположение курсора (на сервере или на клиенте). Доступно для установки только до осуществления подключения к источнику данных. Возможные значения:

    • adUseNone(1) — не использовать курсор (устарело; только ради совместимости).
    • adUseServer(2) — по умолчанию. Курсор на стороне сервера.
    • adUseClient(3) — курсор на стороне клиента. Может обеспечивать дополнительные возможности (например, сортировку).

    SortСтрока, содержащая одно или более имен полей, по которым следует отсортировать Recordset, и порядок сортировки (по возрастанию или по убыванию). Каждое имя поля отделяется запятой и произвольно сопровождается пробелом и ключевым словом ASC, которое сортирует в возрастающем порядке, или DESC, которое сортирует по убыванию. По умолчанию сортировка происходит в возрастающем порядке. Это свойство требует, чтобы свойство CursorLocation было установлено в adUseClient(3). Это свойство имеет приоритет перед предложением ORDER BY, включенным в инструкцию SQL. Установка свойства к пустой строке сбросит строки к их первоначальному порядку.
    CompareBookmarks(Bookmark1, Bookmark2)Сравнивает относительную позицию двух закладок (см. свойство Bookmark) и возвращает результат сравнения. Возвращаемые значения:

    • adCompareLessThan(0) — первая закладка перед второй.
    • adCompareEqual(1) — закладки равны.
    • adCompareGreaterThan(2) — первая закладка после второй.
    • adCompareNotEqual(3) — закладки не равны и не упорядочены.
    • adCompareNotComparable(4) — закладки не могут быть сравнены.

    Закладки должны принадлежать одному и тому же объекту Recordset, или его клону.
    NextRecordset(RecordsAffected)Используйте этот метод, чтобы получить результаты следующей команды в составной инструкции, которая возвращает множественные результаты. Если вы открываете объект Recordset, основанный на составной инструкции (например, «SELECT * FROM table1; SELECT * FROM table2»), использование метода Open() возвращает результаты только первой команды. Если результатов следующей команды нет, Recordset будет установлен в Nothing. При непосредственном режиме модификации перед использованием метода NextRecordset следует вызвать Update() или CancelUpdate(), т.к. модификации должны быть завершены. Метод возвращает объект Recordset. В необязательном параметре RecordsAffected возвращается число записей, затронутых операцией.
    Supports(CursorOptions)Определяет, поддерживает ли текущий курсор Recordset специфический тип функциональных возможностей и возвращает булево значение. Параметр CursorOptions состоит из одного или более значений:

    • adAddNew(0x1000400) — поддерживает метод AddNew() для добавления записей.
    • adApproxPosition(0x4000) — поддерживает свойства AbsolutePosition и AbsolutePage.
    • adBookmark(0x2000) — поддерживает свойство Bookmark.
    • adDelete(0x1000800) — поддерживает метод Delete() для удаления записей.
    • adFind(0x80000) — поддерживает метод Find() для определения местонахождения строки в Recordset.
    • adHoldRecords(0x100) — отыскивает записи или изменяет позицию, не передавая все ожидающие разрешения изменения.
    • adIndex(0x100000) — поддерживает свойство Index.
    • adMovePrevious(0x200) — поддерживает методы MoveFirst() и MovePrevious(), методы Move() и GetRows() для перемещения текущей позиции назад, не требуя закладок.
    • adNotify(0x40000) — указывает, что провайдер данных поддерживает события объекта Recordset (в данной статье события не рассматриваются).
    • adResync(0x20000) — поддерживает метод Resync.
    • adSeek(0x200000) — поддерживает метод Seek() для определения местонахождения строки в Recordset.
    • adUpdate(0x1008000) — поддерживает метод Update().
    • adUpdateBatch(0x10000) — поддерживает методы UpdateBatch() и CancelBatch().


    Find(Criteria, SkipRows, SearchDirection, Start)Ищет в Recordset строку, которая удовлетворяет указанным критериям. Если строка найдена, она становится текущей. Иначе, текущая позиция устанавливается на конец (или начало) Recordset. Перед вызовом метода текущая позиция должна быть установлена. Параметры:

    • Criteria — строка, которая содержит инструкцию, определяющую имя столбца, оператор сравнения и значение. Может быть определено имя только единственного столбца. Оператором сравнения может быть , =, =, <> или «like». Значение может быть строкой, числом с плавающей запятой или датой. Cтроки берутся в одинарные кавычки или # (знаки номера). Даты ограничиваются знаками номера и могут содержать часы, минуты и секунды, но не миллисекунды. Для оператора «like» значение строки может содержать звездочку (*). Звездочка может использоваться только в конце строки значения, или в начале и конце строки одновременно, и никак иначе. Пример: «start_date > #7/22/97#».
    • SkipRows — необязательный. Целое число (long), значение по умолчанию которого является нулевым, которое определяет смещение строки от текущей строки или закладки Start (см. ниже), чтобы начать поиск. По умолчанию, поиск начнётся с текущей строки.
    • SearchDirection — необязательный. Определяет направление поиска. Возможные значения:
      • adSearchBackward(-1) — Поиск назад. Если соответствие не найдено, указатель текущей записи будет установлен в BOF.
      • adSearchForward(1) — Поиск вперёд. Если соответствие не найдено, указатель текущей записи будет установлен в EOF.
    • Start — необязательный. Закладка (Bookmark), которая используется как начальная позиция для поиска.

    GetRows(Rows, Start, Fields)Помещает записи объекта Recordset в массив. Возвращает двумерный массив. Параметры:

    • Rows — необязательный. Единственно возможное значение и значение по умолчанию — adGetRowsRest(-1). Отыскивает все записи Recordset от текущей позиции или от закладки, указанной параметром Start.
    • Start — необязательный. Закладка (Bookmark), которая используется как начальная позиция для поиска.
    • Fields — необязательный. Имя или порядковая позиция поля, либо массив имен или порядковых позиций полей. ADO возвращает только данные из этих полей.

    GetString(StringFormat, NumRows, ColumnDelimiter, RowDelimiter, NullExpr)Возвращает Recordset как строку. Параметры:

    • StringFormat — формат строки. Единственно возможное значение — adClipString(2) — разграничивает строки, столбцы и пустые значения с помощью параметров RowDelimiter, ColumnDelimiter и NullExpr.
    • NumRows — необязательный. Число строк, которые будут возвращены из Recordset. Если NumRows не определён или превышает общее количество строк в Recordset, будут возвращены все строки.
    • ColumnDelimiter — необязательный. Разделитель столбцов. Если не определено, cимвол табуляции.
    • RowDelimiter — необязательный. Разделитель строк. Если не определено, символ возврата каретки.
    • NullExpr — необязательный. Выражение, используемое вместо пустого значения (Null). Если не определено, пустая строка.

    Коллекция полей Fields

    Коллекция полей Fields является свойством объекта Recordset и поддерживает следующие свойства и методы:

    Описание
    CountСодержит количество объектов в коллекции.
    Item(index)Возвращает элемент коллекции по имени или порядковому номеру.
    Append(Name, Type, DefinedSize, Attrib)Создаёт и добавляет новый объект Field в коллекцию. Поля следует добавлять к закрытому Recordset’у. Параметры:

    • Name — уникальное имя поля.
    • Type — тип поля. Возможные значения — см. описание свойства «Type» объекта «Parameter».
    • DefinedSize — необязательный. Размер поля в символах или байтах.
    • Attrib — необязательный. Атрибуты поля. Возможные значения — см. в MSDN описание перечисления FieldAttributeEnum.

    Delete(Field)Удаляет объект Field из коллекции, что соответствует удалению поля из набора записей. Параметр Field задаёт имя объекта Field или его порядковый номер. Метод может использоваться только для закрытого набора записей.

    Объект Field

    Объект Field представляет собой столбец данных одного типа, т.е. поле набора записей. Кроме того, объект Field может представлять собой поле единичной записи (объекта Record, который не рассматривается в данной статье). Свойства объекта Field:

    Описание
    Name Содержит имя поля.
    Value Содержит значение поля.
    OriginalValue Содержит значение поля после последнего вызова Update() или UpdateBatch(). Это то значение, которое используют методы CancelUpdate() и CancelBatch().
    UnderlyingValue Содержит текущее значение поля из источника данных.
    DefinedSize Содержит максимальный размер поля.
    ActualSize Содержит размер фактического значения поля.
    Type Содержит тип поля. Возможные значения — см. описание свойства «Type» объекта «Parameter».
    Precision Содержит степень точности для числовых значений поля (максимальное количество цифр).
    NumericScale Содержит масштаб числовых значений поля (количество десятичных знаков справа от запятой).
    Properties Содержит коллекцию динамических свойств объекта (объектов Property). Подробнее — см. раздел «Динамические свойства объектов».

    Пример «независимого» использования объекта Recordset:

    Программное создание базы данных с помощью ADOX. Часть 1

    Что такое ADOX

    Microsoft? ActiveX? Data Objects Extensions for Data Definition Language and Security (ADOX) — это официальное название от Microsoft. На практике это дополнение к объектной и программной модели ADO. В девичестве ADOX как я понимаю был DAO, хотя одно другого не отменяет. Просто библиотека ADOX более современная, поддерживает работу с современными базами данных MS SQL, Oracle и т.д. через ODBC и OLE DB и позволяет управлять не только структурой базы данных но и ее безопасностью (Группами и пользователями).

    Из представленной обектной модели видно, что ADOX позволяет работать с пятью сущностями современной реляционной базы данных Таблицы(Tables), Группы(Groups), Пользователи(Users), Процедуры(Procedures) и Представления(Views).
    Не будем пока заострять внимание на каждой из этих сущностей. Подробно о них можно узнать обратившись к документации по ADO Цель данной статьи показать основные этапы по программному созданию и модификации базы данных средствами ADOX.

    Программируем с ADOX

    Необходимые ссылки и объекты

    Для начала работы с ADOX необходимо проставить ссылку в Project — > References текущего проекта на библиотеку Microsoft ADO Ext. 2.x for DDL and Security. Где х в номере врсии может быть 5,6 или 7 в зависимости от версии ADO с которой вы работаете. ADOX поставляется с дистрибутивом MDAC (Microsoft Data Access Components) начиная с версии 2.5

    Самый главный объект

    Самым главным объектом, как это видно в объектной модели, является объект Catalog. Он является по сути синонимом понятия база данных, поскольку является родительским объектом для таблиц, процедур, представлений и т.д. В коде вашего проекта следует создать и инициировать объект ADOX.Catalog. К примеру так:

    где нибудь в Form_Load()

    Создание базы данных

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

    В приведенном примере создается новая база MS Access с именем new, в корне диска c:. Следует отметить две важных детали. В случае если поставщик доступа к данным (Provider) не поддерживает операцию создания нового каталога (в нашем контексте базы данных) произойдет ошибка. И второе, после успешного создания базы данных свойство ActiveConnection нашего объекта oCat будет содержать ссылку на объект ADODB.Connection соединения с вновь созданной базой данных.

    Открытие существующей базы данных

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

    Данная процедура откроет базу данных new.mdb расположенную в корне диска с:.

    Работа с таблицами Таблиц


    Добавление

    Добавление таблицы к базе данных выполняется методом Append коллекции Tables объекта Catalog (мощно ввернул, внушает . )
    Иными словами пишем в коде

    Где NewTable это объект Table.
    Теперь превратим это сумбурное описание в процедуру.

    Изменение

    Для изменения свойств таблицы надо найти ее в коллекции oCat.Tables. Это можно сделать указав в качестве индекса ее номер, который определить сложно, или ее имя, что конечно более удобно.

    Кроме свойства Name для изменения также доступны коллекции:

    Indexes
    Keys
    Columns

    Удаление

    Чтобы удалить таблицу необходимо вызвать метод Delete коллекции Tables передав в качестве параметра имя таблицы.

    Работа с полями


    Добавление

    Поля таблицы доступны через коллекцию Columns объекта Table. Для добавления поля в таблицу испоьзуется метод Append колекции Columns. Методу передаются один обязательный параметр, Имя поля и два необязательных, его Тип и Размер. Значение по умолчанию для типа adVarWchar. Значение по умолчанию для размера 0. Добавим в созданную нами таблицу одно поле:

    Ниже преведена таблица допустимых типов:

    Константа Значение Описание
    adBigInt 20 Indicates an eight-byte signed integer (DBTYPE_I8).
    adBinary 128 Indicates a binary value (DBTYPE_BYTES).
    adBoolean 11 Indicates a boolean value (DBTYPE_BOOL).
    adBSTR 8 Indicates a null-terminated character string (Unicode) (DBTYPE_BSTR).
    adChapter 136 Indicates a four-byte chapter value that identifies rows in a child rowset (DBTYPE_HCHAPTER).
    adChar 129 Indicates a string value (DBTYPE_STR).
    adCurrency 6 Indicates a currency value (DBTYPE_CY). Currency is a fixed-point number with four digits to the right of the decimal point. It is stored in an eight-byte signed integer scaled by 10,000.
    adDate 7 Indicates a date value (DBTYPE_DATE). A date is stored as a double, the whole part of which is the number of days since December 30, 1899, and the fractional part of which is the fraction of a day.
    adDBDate 133 Indicates a date value (yyyymmdd) (DBTYPE_DBDATE).
    adDBTime 134 Indicates a time value (hhmmss) (DBTYPE_DBTIME).
    adDBTimeStamp 135 Indicates a date/time stamp (yyyymmddhhmmss plus a fraction in billionths) (DBTYPE_DBTIMESTAMP).
    adDecimal 14 Indicates an exact numeric value with a fixed precision and scale (DBTYPE_DECIMAL).
    adDouble 5 Indicates a double-precision floating-point value (DBTYPE_R8).
    adEmpty Specifies no value (DBTYPE_EMPTY).
    adError 10 Indicates a 32-bit error code (DBTYPE_ERROR).
    adFileTime 64 Indicates a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (DBTYPE_FILETIME).
    adGUID 72 Indicates a globally unique identifier (GUID) (DBTYPE_GUID).
    adIDispatch 9 Indicates a pointer to an IDispatch interface on a COM object (DBTYPE_IDISPATCH).
    Note This data type is currently not supported by ADO. Usage may cause unpredictable results.
    adInteger 3 Indicates a four-byte signed integer (DBTYPE_I4).
    adIUnknown 13 Indicates a pointer to an IUnknown interface on a COM object (DBTYPE_IUNKNOWN).
    Note This data type is currently not supported by ADO. Usage may cause unpredictable results.
    adLongVarBinary 205 Indicates a long binary value (Parameter object only).
    adLongVarChar 201 Indicates a long string value (Parameter object only).
    adLongVarWChar 203 Indicates a long null-terminated Unicode string value (Parameter object only).
    adNumeric 131 Indicates an exact numeric value with a fixed precision and scale (DBTYPE_NUMERIC).
    adPropVariant 138 Indicates an Automation PROPVARIANT (DBTYPE_PROP_VARIANT).
    adSingle 4 Indicates a single-precision floating-point value (DBTYPE_R4).
    adSmallInt 2 Indicates a two-byte signed integer (DBTYPE_I2).
    adTinyInt 16 Indicates a one-byte signed integer (DBTYPE_I1).
    adUnsignedBigInt 21 Indicates an eight-byte unsigned integer (DBTYPE_UI8).
    adUnsignedInt 19 Indicates a four-byte unsigned integer (DBTYPE_UI4).
    adUnsignedSmallInt 18 Indicates a two-byte unsigned integer (DBTYPE_UI2).
    adUnsignedTinyInt 17 Indicates a one-byte unsigned integer (DBTYPE_UI1).
    adUserDefined 132 Indicates a user-defined variable (DBTYPE_UDT).
    adVarChar 204 Indicates a binary value (Parameter object only).
    adVariant 200 Indicates a string value (Parameter object only).
    adVarNumeric 12 Indicates an Automation Variant (DBTYPE_VARIANT).
    Note This data type is currently not supported by ADO. Usage may cause unpredictable results.
    adVarWChar 139 Indicates a numeric value (Parameter object only).
    adWChar 202 Indicates a null-terminated Unicode character string (Parameter object only).
    adVarBinary 130 Indicates a null-terminated Unicode character string (DBTYPE_WSTR).

    Изменение

    Для изменения характеристик поля используется объект Column:

    Свойства Type и DefaultSize открыты только для чтения после того, как поле было добавлено в коллекцию.

    Удаление

    Удалить поле из таблицы можно выполнив метод Delete коллекции Columns нужной таблицы, передав в качестве параметра имя поля.

    Работа с индексами и ключами

    Рассмотрим работу с этими объектами на следующем примере:

    Создаем объект типа Key. Под объектами key подразумеваются первичные и внешние ключи. Primary и Foreign соответственно.

    так же доступны типы: adKeyPrimary и adKeyUnique
    Далее указывается ссылка на связанную таблицу


    adRINone — ни каких действий каскадно не производится. (по умолчанию)
    adRISetDefault — значение внешнего ключевого поля выставляется в значение по умолчанию.
    adRISetNull — значение внешнего ключевого поля выставляется в Null

    Так же можно установиь правила для каскадного удаления свойству:

    Подобным же образом осущестляется работа с управлением индексами.

    Можно особо отметить следующую особенность:

    У таблицы есть коллекция индексов. А уже у каждого индекса есть коллекция колонок т.е. полей входящих в этот индекс. Для простых индексов состоящих из одного поля, в коллекции колонок содержится одна колонка, для составных индексов в коллекции колонок индекса содержаться колонки входящие в этот индекс. Опять мощьно ввернул! Вот пример. Добавим к таблице составной индекс из двух полей Field1 и Filed2:

    Для удаления индекса как и везде используем метод Delete:

    ADOdb

    Database Abstraction Layer for PHP

    User Tools

    Site Tools

    Resources
    Supported Databases

    ADOdb — Database Abstraction Layer for PHP

    ADOdb is a fast, easy to use, popular database abstraction layer for PHP. It allows the same code to be used when accessing a wide range of databases. It has been actively maintained since 2000 by the project’s founder and numerous community contributors. ADOdb contains components for querying and updating databases, as well as an Object Orientated Active Record library, schema management and performance monitoring. It also contains the following standalone extensions:

    Note that ADOdb is not a replacement for the native PHP database extensions, but is built on top of them. This means that the corresponding driver(s) must be installed and correctly configured for ADOdb to work.

    ADOdb runs on all active versions of PHP including PHP 7

    Current Production Release
    Latest Documentation

    Настройка и использование PDO — расширения PHP Data Objects для работы с базами данных

    PDO (PHP Data Objects) — расширение PHP, которое реализует взаимодействие с базами данных при помощи объектов. Профит в том, что отсутствует привязка к конкретной системе управления базами данных.

    Предоставляемый интерфейс поддерживает, среди прочих, такие популярные СУБД:

    В этом руководстве представлен обзор PDO:

    Для работы потребуются:

    • базовые знания MySQL и опыт использования команды mysql в консоли;
    • понимание основ объектно-ориентированного программирования;
    • PHP >= 5.1;
    • рабочая СУБД MySQL/MariaDB.

    Создание тестовой базы данных и таблицы

    Для начала создадим базу данных для этого руководства:

    Пользователю с логином testuser и паролем testpassword предоставили полные права доступа к базе solar_system .

    Теперь создадим таблицу и заполним данными, астрономическая точность которых не подразумевается:

    Описание соединения

    Теперь, когда создана база, определим DSN (Data Source Name) — сведения для подключения к базе, представленные в виде строки. Синтаксис описания отличается в зависимости от используемой СУБД. В примере работаем с MySQL/MariaDB, поэтому указываем:

    • тип драйвера;
    • имя хоста, где расположена СУБД;
    • порт (необязательно, если используется стандартный порт 3306 );
    • имя базы данных;
    • кодировку (необязательно).

    Строка DSN в этом случае выглядит следующим образом:

    Первым указывается database prefix . В примере — mysql . Префикс отделяется от остальной части строки двоеточием, а каждый следующий параметр — точкой с запятой.

    Создание PDO-объекта

    Теперь, когда строка DSN готова, создадим PDO-объект. Конструктор на входе принимает следующие параметры:

    1. Строку DSN.
    2. Имя пользователя, имеющего доступ к базе данных.
    3. Пароль этого пользователя.
    4. Массив с дополнительными параметрами (необязательно).

    Дополнительные параметры можно также определить после создания объекта с помощью метода SetAttribute :

    Определение метода выборки по умолчанию

    PDO::DEFAULT_FETCH_MODE — важный параметр, который определяет метод выборки по умолчанию. Указанный метод используется при получении результата выполнения запроса.

    PDO::FETCH_BOTH

    Режим по умолчанию. Результат выборки индексируется как номерами (начиная с 0), так и именами столбцов:

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

    PDO::FETCH_ASSOC

    Результат сохраняется в ассоциативном массиве, в котором ключ — имя столбца, а значение — соответствующее значение строки:

    В результате получим:

    PDO::FETCH_NUM

    При использовании этого режима результат представляется в виде массива, индексированного номерами столбцов (начиная с 0):

    PDO::FETCH_COLUMN

    Этот вариант полезен, если нужно получить перечень значений одного поля в виде одномерного массива, нумерация которого начинается с 0. Например:

    В результате получим:

    PDO::FETCH_KEY_PAIR

    Используем этот вариант, если нужно получить перечень значений двух полей в виде ассоциативного массива. Ключи массива — это данные первого столбца выборки, значения массива — данные второго столбца. Например:


    В результате получим:

    PDO::FETCH_OBJECT

    При использовании PDO::FETCH_OBJECT для каждой извлеченной строки создаётся анонимный объект. Его общедоступные (public) свойства — имена столбцов выборки, а результаты запроса используются в качестве их значений:

    В результате получим:

    PDO::FETCH_CLASS

    В этом случае, как и в предыдущем, значения столбцов становятся свойствами объекта. Однако требуется указать существующий класс, который будет использоваться для создания объекта. Рассмотрим это на примере. Для начала создадим класс:

    Обратите внимание, что у класса Planet закрытые (private) свойства и нет конструктора. Теперь выполним запрос.

    Если используется метод fetch с PDO::FETCH_CLASS , перед отправкой запроса на получение данных нужно применить метод setFetchMode :

    Первый параметр, который передаем методу setFetchMode , — константа PDO::FETCH_CLASS . Второй параметр — имя класса, который будет использоваться при создании объекта. Теперь выполним:

    В результате получим объект Planet :

    Значения, полученные в результате запроса, назначены соответствующим свойствам объекта, даже закрытым.

    Определение свойств после выполнения конструктора

    В классе Planet нет явного конструктора, поэтому проблем при назначении свойств не будет. При наличии у класса конструктора, в котором свойство было назначено или изменено, они будут перезаписаны.

    При использовании константы FETCH_PROPS_LATE значения свойств будут присваиваться после выполнения конструктора:

    Мы изменили класс Planet , добавив конструктор, который принимает на входе два аргумента: name (имя) и color (цвет). Значения этих полей по умолчанию: moon (луна) и gray (серый) соответственно.

    Если не использовать FETCH_PROPS_LATE , при создании объекта свойства будут перезаписаны значениями по умолчанию. Проверим это. Сначала выполним запрос:

    В результате получим:

    Как и ожидалось, извлеченные из базы данных значения перезаписаны. Теперь рассмотрим решение задачи с помощью FETCH_PROPS_LATE (запрос аналогичный):

    В результате получим то, что нужно:

    Если у конструктора класса нет значений по умолчанию, а они нужны, параметры конструктора задаются при вызове метода setFetchMode третьим аргументом в виде массива. Например:

    Аргументы конструктора обязательны, поэтому выполним:

    Входящие параметры выступают также в роли значений по умолчанию, которые нужны для инициализации. В дальнейшем они будут перезаписаны значениями из базы данных.

    Получение нескольких объектов

    Множественные результаты извлекаются в виде объектов с помощью метода fetch внутри цикла while :

    Или путём выборки всех результатов сразу. Во втором случае используется метод fetchAll , причём режим указывается в момент вызова:

    PDO::FETCH_INTO

    При выборе этого варианта выборки PDO не создаёт новый объект, а обновляет свойства существующего. Однако это возможно только для общедоступных (public) свойств или при использовании в объекте «магического» метода __set .

    Подготовленные и прямые запросы

    В PDO два способа выполнения запросов:

    • прямой, который состоит из одного шага;
    • подготовленный, который состоит из двух шагов.

    Прямые запросы

    Существует два метода выполнения прямых запросов:

    • query используется для операторов, которые не вносят изменения, например SELECT . Возвращает объект PDOStatemnt , из которого с помощью методов fetch или fetchAll извлекаются результаты запроса;
    • exec используется для операторов вроде INSERT , DELETE или UPDATE . Возвращает число обработанных запросом строк.

    Прямые операторы используются только в том случае, если в запросе отсутствуют переменные и есть уверенность, что запрос безопасен и правильно экранирован.

    Подготовленные запросы

    PDO поддерживает подготовленные запросы (prepared statements), которые полезны для защиты приложения от SQL-инъекций: метод prepare выполняет необходимые экранирования.

    Рассмотрим пример. Требуется вставить свойства объекта Planet в таблицу Planets . Сначала подготовим запрос:

    Используем метод prepare , который принимает как аргумент SQL-запрос с псевдопеременными (placeholders). Псевдопеременные могут быть двух типов: неименнованые и именованные.

    Неименованные псевдопеременные

    Неименованные псевдопеременные (positional placeholders) отмечаются символом ? . Запрос в результате получается компактным, но требуется предоставить значения для подстановки, размещенные в том же порядке. Они передаются в виде массива через метод execute :

    Именованные псевдопеременные

    При использовании именованных псевдопеременных (named placeholders) порядок передачи значений для подстановки не важен, но код в этом случае становится не таким компактным. В метод execute данные передаются в виде ассоциативного массива, в котором каждый ключ соответствует имени псевдопеременной, а значение массива — значению, которое требуется подставить в запрос. Переделаем предыдущий пример:

    Методы prepare и execute используются как при выполнении запросов на изменение, так и при выборке.

    А информацию о количестве обработанных строк при необходимости предоставит метод rowCount .

    Управление поведением PDO при ошибках

    Параметр выбора режима ошибок PDO::ATTR_ERRMODE используется для определения поведения PDO в случае ошибок. Доступно три варианта: PDO::ERRMODE_SILENT , PDO::ERRMODE_EXCEPTION и PDO::ERRMODE_WARNING .

    PDO::ERRMODE_SILENT

    Вариант по умолчанию. PDO просто запишет информацию об ошибке, которую помогут получить методы errorCode и errorInfo.

    PDO::ERRMODE_EXCEPTION

    Это предпочтительный вариант, при котором в дополнение к информации об ошибке PDO выбрасывает исключение (PDOException). Исключение прерывает выполнение скрипта, что полезно при использовании транзакций PDO. Пример приведён ниже при описании транзакций.

    PDO::ERRMODE_WARNING

    В этом случае PDO также записывает информацию об ошибке. Поток выполнения скрипта не прерывается, но выдаются предупреждения.

    Методы bindValue и bindParam


    Для подстановки значений в запросе можно также использовать методы bindValue и bindParam . Первый связывает значение переменной с псевдопеременной, которая использована при подготовке запроса:

    Связали значение переменной $planet->name с псевдопеременной :name . Обратите внимание, что при использовании методов bindValue и bindParam как третий аргумент указывается тип переменной, используя соответствующие константы PDO. В примере — PDO::PARAM_STR .

    Метод bindParam привязывает переменную к псевдопеременной. В этом случае переменная связана с псевдопеременной ссылкой, а значение будет подставлено в запрос только после вызова метода execute . Рассмотрим на примере:

    Транзакции в PDO

    Транзакции позволяют сохранить на некоторое время и организовать выполнение нескольких запросов «пакетом». Запросы, включённые в транзакцию, применяются только в том случае, если при выполнении отсутствуют ошибки. Транзакции поддерживаются не всеми СУБД и работают не со всеми SQL-конструкциями, так как некоторые из них вызывают неявное выполнение. Список таких конструкций можно найти на сайте MariaDB.

    Представим необычный пример. Пользователю требуется выбрать список планет, причём каждый раз при выполнении запроса текущие данные удаляются из базы, а потом вставляются новые. Если после удаления произойдёт ошибка, то следующий пользователь получит пустой список. Чтобы этого избежать, используем транзакции:

    Метод beginTransaction отключает автоматическое выполнение запросов, а внутри конструкции try-catch запросы выполняются в нужном порядке. Если не возникнет исключений PDOException , запросы выполнятся с помощью метода commit . В противном случае откатятся с помощью метода rollback , а автоматическое выполнение запросов восстановится.

    Таким образом появилась согласованность выполнения запросов. Очевидно, что для этого параметру PDO::ATTR_ERRMODE необходимо установить значение PDO::ERRMODE_EXCEPTION .

    Заключение

    Теперь, когда работа с PDO описана, отметим его основные преимущества:

    • с PDO легко перенести приложение на другие СУБД;
    • поддерживаются все популярные СУБД;
    • встроенная система управления ошибками;
    • разнообразные варианты представления результатов выборки;
    • поддерживаются подготовленные запросы, которые сокращают код и делают его устойчивым к SQL-инъекциям;
    • поддерживаются транзакции, которые помогают сохранить целостность данных и согласованность запросов при параллельной работе пользователей.

    Объекты данных PHP

    User Contributed Notes 25 notes

    Please note this:

    Won’t work:
    $sth = $dbh->prepare(‘SELECT name, colour, calories FROM ? WHERE calories prepare(‘SELECT name, colour, calories FROM fruit WHERE calories

    I decided to create a singleton wrapper for PDO that ensures only one instance is ever used.
    It uses PHP 5.3.0’s __callStatic functionality to pass on statically called methods to PDO.

    This means you can just call it statically from anywhere without having to initiate or define the object.

    :: exec ( «DELETE FROM Blah» );

    foreach( DB :: query ( «SELECT * FROM Blah» ) as $row ) <
    print_r ( $row );
    >
    ?>

    Code:

    private static $objInstance ;

    /*
    * Class Constructor — Create a new database connection if one doesn’t exist
    * Set to private so no-one can create a new instance via ‘ = new DB();’
    */
    private function __construct () <>

    /*
    * Like the constructor, we make __clone private so nobody can clone the instance
    */
    private function __clone () <>

    /*
    * Returns DB instance or create initial connection
    * @param
    * @return $objInstance;
    */
    public static function getInstance ( ) <

    if(! self :: $objInstance ) <
    self :: $objInstance = new PDO ( DB_DSN , DB_USER , DB_PASS );
    self :: $objInstance -> setAttribute ( PDO :: ATTR_ERRMODE , PDO :: ERRMODE_EXCEPTION );
    >

    return self :: $objInstance ;

    /*
    * Passes on any static calls to this class onto the singleton PDO instance
    * @param $chrMethod, $arrArguments
    * @return $mix
    */
    final public static function __callStatic ( $chrMethod , $arrArguments ) <

    $objInstance = self :: getInstance ();

    return call_user_func_array (array( $objInstance , $chrMethod ), $arrArguments );

    This works to get UTF8 data from MSSQL:

    = new PDO ( ‘dblib:host=your_hostname;dbname=your_db;charset=UTF-8’ , $user , $pass );
    ?>

    When using prepared statements there is no official PDO feature to show you the final query string that is submitted to a database complete with the parameters you passed.

    Use this simple function for debugging. The values you are passing may not be what you expect.

    //Sample query string
    $query = «UPDATE users SET name = :user_name WHERE > ;

    //Sample parameters
    $params = [ ‘:user_name’ => ‘foobear’ , ‘:user_id’ => 1001 ];

    function build_pdo_query ( $string , $array ) <
    //Get the key lengths for each of the array elements.
    $keys = array_map ( ‘strlen’ , array_keys ( $array ));

    //Sort the array by string length so the longest strings are replaced first.
    array_multisort ( $keys , SORT_DESC , $array );

    foreach( $array as $k => $v ) <
    //Quote non-numeric values.
    $replacement = is_numeric ( $v ) ? $v : «‘ < $v >‘» ;

    //Replace the needle.
    $string = str_replace ( $k , $replacement , $string );
    >

    echo build_pdo_query ( $query , $params ); //UPDATE users SET name = ‘foobear’ WHERE > ?>

    I wanted to extend PDO class to store statistics of DB usage, and I faced some problems. I wanted to count number of created statements and number of their executings. So PDOStatement should have link to PDO that created it and stores the statistical info. The problem was that I didn’t knew how PDO creates PDOStatement (constructor parameters and so on), so I have created these two classes:

    /**
    * PHP Document Object plus
    *
    * PHP Document Object plus is library with functionality of PDO, entirely written
    * in PHP, so that developer can easily extend it’s classes with specific functionality,
    * such as providing database usage statistics implemented in v1.0b
    *
    * @author Peter Pokojny
    * @license http://opensource.org/licenses/gpl-license.php GNU Public License
    */
    class PDOp <
    protected $PDO ;
    public $numExecutes ;
    public $numStatements ;
    public function __construct ( $dsn , $user = NULL , $pass = NULL , $driver_options = NULL ) <
    $this -> PDO = new PDO ( $dsn , $user , $pass , $driver_options );
    $this -> numExecutes = 0 ;
    $this -> numStatements = 0 ;
    >
    public function __call ( $func , $args ) <
    return call_user_func_array (array(& $this -> PDO , $func ), $args );
    >
    public function prepare () <
    $this -> numStatements ++;

    $args = func_get_args ();
    $PDOS = call_user_func_array (array(& $this -> PDO , ‘prepare’ ), $args );

    return new PDOpStatement ( $this , $PDOS );
    >
    public function query () <
    $this -> numExecutes ++;
    $this -> numStatements ++;

    $args = func_get_args ();
    $PDOS = call_user_func_array (array(& $this -> PDO , ‘query’ ), $args );

    return new PDOpStatement ( $this , $PDOS );
    >
    public function exec () <
    $this -> numExecutes ++;

    $args = func_get_args ();
    return call_user_func_array (array(& $this -> PDO , ‘exec’ ), $args );
    >
    >
    class PDOpStatement implements IteratorAggregate <
    protected $PDOS ;
    protected $PDOp ;
    public function __construct ( $PDOp , $PDOS ) <
    $this -> PDOp = $PDOp ;
    $this -> PDOS = $PDOS ;
    >
    public function __call ( $func , $args ) <
    return call_user_func_array (array(& $this -> PDOS , $func ), $args );
    >
    public function bindColumn ( $column , & $param , $type = NULL ) <
    if ( $type === NULL )
    $this -> PDOS -> bindColumn ( $column , $param );
    else
    $this -> PDOS -> bindColumn ( $column , $param , $type );
    >
    public function bindParam ( $column , & $param , $type = NULL ) <
    if ( $type === NULL )
    $this -> PDOS -> bindParam ( $column , $param );
    else
    $this -> PDOS -> bindParam ( $column , $param , $type );
    >
    public function execute () <
    $this -> PDOp -> numExecutes ++;
    $args = func_get_args ();
    return call_user_func_array (array(& $this -> PDOS , ‘execute’ ), $args );
    >
    public function __get ( $property ) <
    return $this -> PDOS -> $property ;
    >
    public function getIterator () <
    return $this -> PDOS ;
    >
    >
    ?>

    Classes have properties with original PDO and PDOStatement objects, which are providing the functionality to PDOp and PDOpStatement.
    From outside, PDOp and PDOpStatement look like PDO and PDOStatement, but also are providing wanted info.

    Example 5:
    try <
    $dbh = new PDO ( ‘odbc:SAMPLE’ , ‘db2inst1’ , ‘ibmdb2’ ,
    array( PDO :: ATTR_PERSISTENT => true ));
    .
    > catch ( Exception $e ) <
    $dbh -> rollBack ();
    echo «Failed: » . $e -> getMessage ();
    >
    ?>

    We must change the last two lines to catch the error connecting to the database:

    > catch (Exception $e) <
    echo «Failed: » . $e->getMessage();
    $dbh->rollBack();
    >
    ?>

    If you need to get Output variable from MSSQL stored procedure, try this :

    — PROCEDURE
    CREATE PROCEDURE spReturn_Int @err int OUTPUT
    AS
    SET @err = 11
    GO

    $sth = $dbh->prepare(«EXECUTE spReturn_Int ?»);
    $sth->bindParam(1, $return_value, PDO::PARAM_INT|PDO::PARAM_INPUT_OUTPUT);
    $sth->execute();
    print «procedure returned $return_value\n»;

    Won’t work:
    $sth = $dbh->prepare(‘SELECT name, colour, calories FROM fruit WHERE ? prepare(‘SELECT name, colour, calories FROM fruit WHERE calories

    Merge the prepare() and execute() in one function like a sprintf().
    And like sprintf, I choose to use unnamed args (?) 😉


    you could still use old insecure query() ( not prepared ) with renamed function 🙂

    class MyPDO extends PDO <

    const PARAM_host = ‘localhost’ ;
    const PARAM_port = ‘3306’ ;
    const PARAM_db_name = ‘test’ ;
    const PARAM_user = ‘root’ ;
    const PARAM_db_pass = » ;

    public function __construct ( $options = null ) <
    parent :: __construct ( ‘mysql:host=’ . MyPDO :: PARAM_host . ‘;port=’ . MyPDO :: PARAM_port . ‘;dbname=’ . MyPDO :: PARAM_db_name ,
    MyPDO :: PARAM_user ,
    MyPDO :: PARAM_db_pass , $options );
    >

    public function query ( $query ) < //secured query with prepare and execute
    $args = func_get_args ();
    array_shift ( $args ); //first element is not an argument but the query itself, should removed

    $reponse = parent :: prepare ( $query );
    $reponse -> execute ( $args );
    return $reponse ;

    $db = new MyPDO ();
    $db -> setAttribute ( PDO :: ATTR_DEFAULT_FETCH_MODE , PDO :: FETCH_OBJ );

    $t1 = isset( $_GET [ «t1» ])? $_GET [ «t1» ]: 1 ; // need to be securised for injonction
    $t2 = isset( $_GET [ «t2» ])? $_GET [ «t2» ]: 2 ; // need to be securised for injonction
    $t3 = isset( $_GET [ «t3» ])? $_GET [ «t3» ]: 3 ; // need to be securised for injonction

    $ret = $db -> query ( «SELECT * FROM table_test WHERE t1=? AND t2=? AND t3=?» , $t1 , $t2 , $t3 );
    //$ret = $db->insecureQuery(«SELECT * FROM table_test WHERE t1=».$db->quote($t1));

    while ( $o = $ret -> fetch ())
    <
    echo $o -> nom . PHP_EOL ;
    >
    ?>

    Подключение к базе данных через ADODB (статья)

    Подключение к базе данных через ADODB.

    Предположим, что у нас есть база данных которую мы создали в Microsoft Access версии 2010 или 2003 или более ранних, значения не имеет. В базе данных имеется 1 (одна) таблица с именем «Клиенты». Структура таблицы в базе данных следующая:

    Код Фамилия Имя Отчество Дата рождения

    Где:

    1. Код — имеет тип данных: Счетчик (размер поля длинное целое)
    2. Фамилия — имеет тип данных: Текстовый (размер поля 50 символов)
    3. Имя — имеет тип данных: Текстовый (размер поля 50 символов)
    4. Отчество — имеет тип данных: Текстовый (размер поля 50 символов)
    5. Дата рождения — имеет тип данных: Дата/время (формат поля краткий формат даты)

    Созданную базу данных для удобства поместим в каталог с нашей программой. Назовем ее к примеру «DataBase». Теперь создадим новый проект на Visual Basic 6.0, сохраним его в каталог с программой. В проекте создадим 1 (одну) форму и 1 (один) модуль. Имя формы оставим по умолчанию «Form1», имя модуля тоже оставим по умолчанию «Module1». Следующим шагом, подключим библиотеку под названием «Microsoft ActiveX Data Objects 2.8 Library». Подключение выполняем нажав на меню «Project»«References» в открывшемся окне находим «Microsoft ActiveX Data Objects 2.8 Library» ставим галочку рядом с названием нажимаем на кнопку «OK».

    Следующим шагом будет объявление переменных для ADODB.Connection и ADODB.Recordset. Откроем наш созданный модуль «Module1» и в самый верх модуля, вставим следующие строки кода:

    Получается следующие, что переменная connADODB.Connection будет отвечать за соединение с базой данных и выполнения команд поступающих от программы к базе данных в виде SQL запроса. Переменная rsADODB.Recordset является набором записей, она будет содержать в себе набор записей которая вернет база данных при выполнении того или иного запроса во время работы программы.

    После объявления переменных спустимся ниже на пару строк и вставим следующие строки кода:

    Visual Basic

    Наша программа будет начинать работу с процедуры «Sub Main». То есть нам надо вернуться в настройки программы, а именно сюда: на панели меню проекта выберите «Project»«Project1 Properties» в открывшемся окне на вкладке «General» выберем из списка «Startup Object»«Sub Main», нажмем кнопку «ОК». В созданном коде получается следующие:

    1. При запуске программы, происходит обращение к процедуре под именем «OpenDB».
    2. Открывается Form1, созданная нами ранее.

    Теперь спустимся еще на пару строк ниже и вставим код процедуры «OpenDB».

    Visual Basic

    Тут переменная «conn» получает строку соединения:

    далее выполняется соединение. Если соединение установлено, тогда параметр conn.State получает свойство = 1, по созданному условию мы предупреждаем пользователя о выполненном с базой данных:

    Visual Basic

    После чего по коду выше открывается Form1. В форме, вставляем следующий код:

    Visual Basic

    При открытии формы происходит обращение в процедуру: «Call UpdateConnect» в которой создается SQL запрос к базе данных, после чего созданная переменная rs — ADODB.Recordset получает набор записей который возвращает база данных после выполнения SQL запроса. DataGr — «Components», в списке найдите «Microsoft DataGrid Control 6.0 (SP6) (OLEDB)» ставим галочку рядом с названием нажимаем на кнопку «OK». На панели инструментов появится объект в форме сетки, выберите его и нарисуйте его на форме по нужным вам размерам. Теперь попробуйте запустите проект, если все сделали правильно вы увидите отображенные записи в DataGrid на форме. На всякий случай выкладываю исходник проекта.

    Я конечно не мастер написания статей, сильно не ругайте!

    Вложения

    Visual Basic
    DataBase.rar (18.4 Кб, 941 просмотров)
    09.02.2013, 11:22

    Подключение к удаленной базе данных
    На сервере есть файл MDB. Как с помощью ADO или DAO подключиться к нему с машины клиента не.

    Подключение к базе MS Access 2003 из кода через ADO
    Люди, разъясните, pls, начинающему, как же все-таки подключиться к базе данных MS Access из кода.

    Подключение к базе данных MSSQL из Classic ASP дает ошибку 80040e21
    Доброго времени суток. Изучаю ASP. Такая ситуация: Пользуюсь операционной системой Windows 8.1, .

    Программное подключение элемента управления данными Adodc к базе данных SQL Server
    Привет всем! Подскажите пожалуйста, как правильно реализовать подключение элемента управления.

    phpDoc и phpDocumentor

    Здравствуйте, уважаемые читатели блога LifeExample, хочу поделиться с вами замечательным способом документирования своих php скриптов и веб-проектов.

    Возможно, вам также как и мне, рано или поздно придется составлять мануал по использованию своих программ, и тогда вы сможете использовать для этих целей генератор документаций phpDocumentor и формат оформления комментариев phpDoc.

    Генератор phpDocumentor представляет собой отдельную PHP библиотеку доступную в наборе PEAR.

    Чтобы получить возможность генерировать, на основе phpDoc комментариев, документацию проекта, нам необходимо скачать и установить набор библиотек PEAR.

    Если вы никогда не устанавливали PEAR, то советую прочесть статью «как установить PEAR»

    Как пользоваться PHPdoc

    Прелесть phpDocumentor ‘а заключается в его использовании, для того чтобы быстро сгенерировать файл справки, нам нужно своевременно и скрупулёзно вести phpDoc комментарии ко всем классам, методам, и функциям скриптов.

    Комментируя код проекта нужно придерживаться определенных правил форматирования комментариев и помещать их в так называемые Doc-блоки.

    Doc-блоки скрипта должны быть выделены таким образом:

    Либо несколькими строками:

    /**
    * Этот класс является примером использования doc-блоков phpDoc
    */
    class SomeClass
    <
    /** @type string|null Текст приветствия */
    protected $weclome = null ;

    /**
    * Этот метод задает текст приветствия.
    *
    * @param string $text текст приветствия, максимум 255 символов.
    *
    * @return void
    */
    public function setWeclomeText ( $text )
    <
    $this -> weclome = $text ;
    >
    >

    Справочник по параметрам блоков, будет приведен ниже.

    Снабдив код обильными phpDoc комментариями, мы можем успешно воспользоваться PEAR библиотекой – phpDocumentor, получив готовый справочник-документацию по всем файлам проекта.

    Как сгенерировать документацию через phpDocumentor

    Как я уже говорил phpDocumentor – это PEAR библиотека, которая позволяет создавать документацию к файлам в автоматическом режиме. Чтобы сделать это, необходимо иметь установленный инструментарий для работы с PEAR, и с помощью него загрузить phpDocumentor.


    В статье «как установить PEAR» приведен пример, установки библиотеки phpDocumentor, результатом, которого должна создаться директория C:\WebServers\usr\local\php5\data\PhpDocumentor , заполненная файлами генератора, в своей совокупности, представляющих web систему.

    В соответствии с инструкцией, используя набор программ денвера, создайте новую директорию C:\WebServers\home\phpdocumentor.ru\www и скопируйте в туда файлы генератора документаций из
    C:\WebServers\usr\local\php5\data\PhpDocumentor .

    Внимание! Эти действия нужно самостоятельно интерпретировать под ваш WAMP (Windows, Apache, MySQL, PHP), если денвер не используется.

    После того как вы настроили новый виртуальный хост для тестирования генератора phpDocumentor, вам станет доступен веб-интерфейс генерации справочника, по адресу phpdocumentor.ru.

    Когда вы оформите свой проект phpDoc блоками, запустите веб интерфейс phpdocumentor.ru и перейдите во вкладку «OutPut».

    В первом поле «Target» укажите путь к директории, в которой будет создана документация. Затем перейдите во вкладку «Files».

    В поле «Directory to parse» задайте путь к корню вашего проекта.

    Жмите кнопку «Create» в правом нижнем углу страницы, и ждите, пока завершится процесс создания мануала.
    Перейдя в папку указанную во вкладке «OutPut», вы увидите множество файлов и папок, все они представляют документацию к заданному проекту. Прочесть документацию можно открыв файл index.html .

    При моих настройках я получил справочник такого вида.

    Кроме документации в виде набора html файлов, также phpDocumentor позволяет создавать мануалы в PDF, CHM, XML форматах.

    Чтобы максимально хорошо и понятно составить документацию своего проекта, нужно знать phpDoc параметры, с помощью которых и задается вся разметка документации.

    Справочник phpDoc

    @api – помечает структурный элемент, используемый сторонними программами, и являющийся частью API.

    @author – задает имя автора.

    @copyright — копирайтинг.

    @deprecated – тег для пометки элементов на удаление в будущих версиях.

    @example — пример использования метода или класса.

    @filesource – сообщает в phpDocumentor, что нужно включить исходный код в текущий файл для разбора.

    @global — описывает глобальные переменные.

    @ignore – сообщает в phpDocumentor, что следующий структурный элемент обрабатывать не надо.

    @internal – говорит, что элемент является внутренним элементом этого приложения или библиотеки.

    @license – описывает соответствие лицензии.

    @link — связывает структурный элемент с сайтом, откуда он взят.

    @method – указывает какие магические (не явные) методы класса можно вызвать.

    /**
    * @method string getString()
    * @method void setInteger(integer $integer)
    * @method setString(integer $integer)
    */
    class Child extends Parent
    < >

    @package – классификация структурных элементов в логических подразделениях.

    @param – описывает тип и имя параметра передаваемого в функцию.

    @property — аналогичен тегу @method. Позволяет классу знать какие можно использовать магические свойства.

    /**
    * @property string $myProperty
    */

    class Child extends Parent
    < >

    @property-read — указывает какие можно использовать магические свойства, только для чтения.

    /**
    * @property-read string $myProperty
    */
    class Child extends Parent
    < >

    @property-write — указывает какие можно использовать магические свойства, только для записи.

    /**
    * @property-write string $myProperty
    */
    class Child extends Parent
    < >

    @return – описывает возвращаемое значение функцией или методом.

    @see — задает ссылку из структурного элемента, на веб-сайт или другой элемент.

    @since – говорит о том, что структурный элемент стал доступен с заданной версии пакета.

    @subpackage – описывает под-пакет основного пакета, используется вместе с тегом @package.

    @todo – документирует задачи, которые необходимо выполнить в ближайшем будущем.

    @uses – показывает ссылку на документацию по этому элементу, и создает обратную ссылку в других документациях элементов на него.

    @var — указывает описание для свойств класса.

    class > <
    /**
    * пример документирования переменной
    * @var string
    */
    var $variable ;
    /**
    * пример документирования переменной с описанием
    * @var string содержит информацию о class1
    */
    var $variable_with_desc ;

    @version — версия документа.

    Ознакомившись со всеми тегами из справочника по phpDocumentor, не рекомендую вам в изобилии снабжать ими phpDoc блоки. На мой взгляд, в большинстве случаев достаточно лишь нескольких из доступных таких как:

    Но это не значит что остальные phpDoc параметры, являются бесполезными. Для каждой ситуации, нужно в индивидуальном порядке указывать тот или иной дескриптор.

    Поддержка UTF-8 в phpDocumentor

    Все здорово, но данное чудо генерации документаций не поддерживает кодировку UTF-8 а следовательно кириллица будет отображаться кракозябрами.

    Чтобы подружить phpDocumentor с UTF-8, скачиваем следующий архив

    Теперь распакуем скачанный архив в директорию с PEAR: c:\WebServers\usr\local\php5\PEAR\ , заменив при этом имеющуюся в ней папку PhpDocumentor.

    Если phpDocumentor поднимается на linux, то распакуем скачанный архив в директорию с PEAR: /usr/share/php/PhpDocumentor/ , заменив при этом имеющуюся в ней папку PhpDocumentor.

    Следующим шагом закомментируем в файле c:\WebServers\usr\local\php5\data\­PhpDocumentor\docbuilder\includes\utilities.php все, что встречается до функции showImage() .

    После данных действий можно генерировать документацию с поддержкой кириллицы и кодировки UTF-8.

    Русификатор шаблона phpDocumentor

    Кстати, если хотите поправить верстку шаблона, или русифицировать его, то сделать это можно в директории: c:\WebServers\usr\local\php5\PEAR\PhpDocumentor\phpDocumentor\Converters\­HTML\frames\templates\DOM\earthli\templates\ (это пример директории к шаблону DOM::earthli)

    Спасибо за внимание, надеюсь информация будет вам полезна!

    Мастер Йода рекомендует:  Как создать таблицу в HTML тег table
    Добавить комментарий