Методы для экспорта и импорта данных

mixed customQuery ( string query [, bool onlyfirst [, bool assoc]] )

Метод выполняет произвольный SQL-запрос, указанный в качестве параметра query, и возвращает результат выборки либо значение false, если запрос не вернул никаких результатов. Обратите внимание, что пустая выборка также считается полноценным результатом, в этом случае метод возвращает пустой массив, а не значение false. Выборка возвращается в уже обработанной, т.н. "отфетченной" форме, то есть в виде обыкновенных массивов PHP. Ее не нужно как-либо дополнительно обрабатывать, чтобы получить доступ к данным.

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

Запрос "SELECT * FROM music" возвращает выборку со всеми тремя записями таблицы. Результат работы метода customQuery при этом будет иметь следующую форму:

array(
  array(
    "id"=>"1",
    "band"=>"Nightwish",
    "album"=>"Angels Falls First",
    "year"=>"1997"
  ),
  array(
    "id"=>"2",
    "band"=>"Nightwish",
    "album"=>"Century Child",
    "year"=>"2002"
  ),
  array(
    "id"=>"3",
    "band"=>"Tristania",
    "album"=>"World Of Glass",
    "year"=>"2001"
  )
)

Если указать значение true в качестве необязательного параметра onlyfirst, метод вернет только первую запись выборки, а результат превратится из двухмерного массива в одномерный:

array(
  "id"=>"1",
  "band"=>"Nightwish",
  "album"=>"Angels Falls First",
  "year"=>"1997"
)

По умолчанию значение параметра onlyfirst равно false, что означает "возвращать все записи".

Кроме того, есть возможность управления способом фетчинга данных, то есть управления способом разбора данных по массивам. Для управления фетчингом предназначен необязательный параметр assoc. Он поддерживает следующие способы:

• ассоциативный: каждая запись выборки превращается в ассоциативный массив, имена полей превращаются в ключи массива, данные − в значения массива. Для указания этого способа укажите параметру значение true.
• нумерованный: каждая запись выборки превращается в обычный нумерованный массив с данными выборки. Для указания этого способа укажите параметру assoc значение false.
• одно поле: каждая запись выборки превращается не в массив, а в простое значение. При этом используется значение только одного поля выборки, остальные просто игнорируются. Для указания этого способа укажите имя поля в строковом виде в качестве параметра assoc. Например, для запроса "SELECT album FROM music" и значения "album" в качестве параметра assoc, результат работы метода будет иметь вид:

array(
  "Angels Falls First",
  "Century Child",
  "World Of Glass"
)

• два поля: каждая запись выборки превращается не в массив, а в пару "ключ-значение", причем в качестве ключа будет использованы данные одного поля, а в качестве значения − данные другого поля. Остальные поля выборки игнорируются. Для указания этого способа укажите параметру assoc массив из двух строковых элементов, имя первого поля и имя второго поля соответственно. Например, для запроса "SELECT id,album FROM music" и значения array("id","album") в качестве параметра assoc, результат будет иметь вид:

array(
  1=>"Angels Falls First",
  2=>"Century Child",
  3=>"World Of Glass"
)

• номер поля: каждая запись выборки превращается не в массив, а в простое значение. При этом используется значение только одного поля выборки, остальные просто игнорируются. Этот способ отличается от способа "одно поле", описанного выше, тем, что указывается не название поля (иногда указывать название поля бывает неудобно), а его порядковый номер в выборке, начиная с нуля. Для указания этого способа укажите параметру assoc целочисленное значение. Это должно быть именно число − переменная, константа или выражение с типом int. Если вы укажете параметру assoc число, но строкой, например, "0", будет применен способ "одно поле", то есть метод попытается отфетчить результат выборки по полю с названием "0".

По умолчанию значение параметра assoc равно true, что означает ассоциативный способ.

Если указан некорректный SQL-запрос, или его выполнение невозможно в силу внутренних ограничений, метод генерирует фатальную ошибку и немедленно завершает работу скрипта. Если вам нужно менее строгое поведение, воспользуйтесь методом customQuerySilent или customQueryBoolean, которые в случае ошибочной ситуации просто возвращают значение false.

Пример:

// Выборка музыкальных альбомов
$albums=$database->customQuery("SELECT * FROM music");
// Вывод полученных данных
foreach($albums as $album)
  foreach($album as $field=>$value) echo "$field=$value";

mixed customQuerySilent ( string query, mixed &error [, bool onlyfirst [, bool assoc]] )

Метод работает аналогично предыдущему, за одним исключением: в случае некорректного или неудачно выполнившегося SQL-запроса метод не генерирует фатальную ошибку, а возвращает текст ошибки в переменной error. Если запрос выполнился успешно, значение переменной error сбрасывается в false.

Пример:

// Выборка из несуществующей таблицы
$data=$database->customQuerySilent("SELECT * FROM blablabla",$error);
if($error) die("Произошла ошибка: $error.");

bool customQueryBoolean ( string query )

Данный метод предназначен для выполнения SQL-запросов, которые не возвращают результата или выборки. Если запрос, переданный параметром query, выполнился успешно, метод возвращает значение true. Если запрос был некорректным или его выполнение невозможно в силу внутренних ограничений, метод возвращает значение false.

Пример:

// Создание полнотекстового индекса
$query="ALTER TABLE music ADD FULLTEXT (band,album)";
$success=$database->customQueryBoolean($query);
if($success) echo "Индекс создан успешно.";

array parseSQL ( string query )

Метод анализирует переданный ему дамп базы данных (параметр query) и разделяет его на отдельные SQL-запросы, пропуская все комментарии и правильно обрабатывая строковые константы. Чтобы минимизировать расход памяти при загрузке больших дампов данных, метод не возвращает отдельные запросы в качестве результата. Вместо этого метод возвращает массив, каждый элемент которого соответствует одному найденному SQL-запросу дампа, и в свою очередь является ассоциативным массивом с ключами offset и length − смещение начала запроса от начала дампа в байтах, и длина запроса в байтах, соответственно. Такой результат занимает очень немного памяти даже в случае объемных дампов, и в то же время позволяет выделить любой конкретный SQL-запрос при помощи функции substr, непосредственно перед его исполнением.

Пример:

// Импорт дампа с данными
$queries=$database->parseSQL($datadump);
foreach($queries as $query) {
  // Обработка отдельного SQL-запроса
  $queryText=substr($datadump,$query["offset"],$query["length"]);
  $success=$database->customQueryBoolean($queryText);
}

string exportTableStructure ( string table [, bool recreate] )

Метод возвращает SQL-запрос, выполнение которого приводит к созданию или пересозданию таблицы table. По сути, работа данного метода аналогична работе стандартного запроса SHOW CREATE TABLE, с тем отличием, что метод генерирует запрос самостоятельно, на основе данных о полях и индексах таблицы, что позволяет генерировать гораздо более "чистый" и аккуратный SQL-запрос.

По умолчанию запрос добавляет в начало запроса дополнительную инструкцию DROP TABLE IF EXISTS, что позволяет тихо пересоздавать уже имеющиеся таблицы при выполнении запроса. Если вам нужен запрос для создания таблицы в чистом виде, без предварительного ее удаления, укажите методу значение false в качестве необязательного параметра recreate.

Пример:

// Инструкция для создания таблицы shop
$query=$database->exportTableStructure("shop",false);
echo $query; // CREATE TABLE shop (id INT NOT NULL ... ); 

string exportTableLine ( string table, array values [, bool assoc [, bool replace]] )

Метод возвращает SQL-запрос, выполнение которого приводит к добавлению данных в таблицу table. Совместно с методом exportTableStructure, данный метод предназначен для генерирования дампов базы данных, и используется, например, в стандартном плагине "Управление БД". Метод генерирует только одну SQL-инструкцию, для добавления одной записи. Данные этой записи (в виде ассоциативного массива) передаются параметром values.

По умолчанию инструкция генерируется в стандартном формате, без указания названий полей. В большинстве случаев этого достаточно, да и запросы получаются компактнее. Если вам нужен расширенный формат SQL-инструкций, с перечислением списка полей, укажите необязательному параметру assoc значение true. Наконец, если вы хотите, чтобы инструкция формировалась в формате REPLACE вместо стандартного INSERT, укажите необязательному параметру replace значение true.

Пример:

// Инструкции для заполнения таблицы shop данными
$data=$database->getLines("shop");
$datadump="";
foreach($data as $values)
  $datadump.=$database->exportTableLine("shop",$values);
echo $datadump; // INSERT INTO shop VALUES (...); INSERT INTO shop...