Работа с полями и индексами

По правилам синтаксиса SQL, у каждого поля таблицы может присутствовать набор дополнительных атрибутов, таких, как NOT NULL, AUTO_INCREMENT и тому подобное. PHP Compiler поддерживает некоторые из них. Кроме того, движок рекомендует указывать атрибут NOT NULL у всех новых полей (за исключением случаев, когда вам действительно нужны значения NULL в таблице), поскольку поля с этим атрибутом работают несколько быстрее и экономичнее.

Набор атрибутов указывается при создании нового поля или редактировании имеющегося (методы addColumn и modifyColumn соответственно). Для указания атрибутов поля достаточно взять одну или несколько перечисленных ниже констант и объединить их оператором +, | или or. По умолчанию поле не имеет никаких атрибутов.

• ColumnAttributeNull: может ли поле принимать значение NULL. Если данный атрибут указан, поле может принимать значение NULL, и объявляется как NULL. Если атрибут отсутствует, поле не может принимать значение NULL, и объявляется как NOT NULL.
• ColumnAttributeBinary: нужно ли сравнивать строки, как бинарные. Если данный атрибут указан (он поддерживается только для строковых полей), значения полей будут сравниваться как бинарные, с учетом различий в регистре символов. Если атрибут отсутствует, строки сравниваются без учета регистра.
• ColumnAttributeUnsigned: является ли поле беззнаковым. Если данный атрибут указан (он поддерживается только для числовых полей), значения полей не могут быть меньше нуля. Если атрибут отсутствует, поле может принимать и отрицательные значения.
• ColumnAttributeZerofill: нужно ли дополнять число слева нулями, чтобы значение поля всегда имело фиксированную длину. Используется редко.
• ColumnAttributeCounter: является ли поле счетчиком, т.е. имеет ли оно атрибут AUTO_INCREMENT.

bool addColumn ( string table, string column, string type [, int attrs [, mixed position [, string default]]] )

Метод добавляет в таблицу table новое поле с именем column и типом type. Имя создаваемого поля должно состоять из латинских букв и цифр; использование заглавных букв не рекомендуется. Тип поля указывается по правилам SQL, например, INT для целочисленного поля, DOUBLE для вещественного и так далее. Кроме имени и типа, можно указать полю набор необязательных дополнительных параметров:

• attrs: дополнительные атрибуты поля, битовая маска, составленная из констант ColumnAttributeXxx. По умолчанию данный параметр равен 0, что означает атрибут NOT NULL.
• position: куда добавлять новое поле. Данный параметр может принимать как целочисленные, так и строковые значения. Если в качестве параметра position указано число, оно означает номер позиции в списке уже имеющихся полей. Например, значение 0 означает "добавлять новое поле в начало", значение 1 означает "добавлять новое поле сразу после первого поля", и так далее. Если в качестве параметра position указана строка, она означает название поля, после которого будет добавлено новое поле. Если данный параметр не указан или указано значение false, новое поле будет добавлено в конец списка.
• default: значение поля по умолчанию. Если данный параметр не указан, поле будет иметь по умолчанию значение "пустая строка" для строковых типов, и 0 для числовых типов.

Метод возвращает значение true, если новое поле было успешно добавлено в таблицу, и false в противном случае.

Пример:

// Добавление нового поля "жанр" в таблицу альбомов
$success=$database->addColumn("music","genre","TINYTEXT");
if($success) echo "Поле добавлено успешно.";

// Добавление нового поля "вес" в таблицу товаров
// Поле может принимать значения NULL, является беззнаковым,
// и добавляется не в конец списка полей, а после поля "цена"
$attrs=ColumnAttributeNull+ColumnAttributeUnsigned;
$database->addColumn("products","weight","INT",$attrs,"price");

bool addIndex ( string table, string name, bool unique, array fields )

Метод добавляет новый индекс с названием name и набором полей fields в таблицу table. Параметр unique указывает, должен новый индекс быть уникальным или нет. Название создаваемого индекса может быть опущено (заменено пустой строкой), в этом случае подходящее название будет выбрано автоматически.

Наиболее важным параметром здесь является массив fields. Он определяет набор полей, которые будет покрывать индекс. Каждый элемент массива может либо являться строкой (название поля без указания дополнительных параметров), либо в свою очередь являться ассоциативным массивом с ключами name и size, название поля и его длина в индексе соответственно. Если вы добавляете индекс с полями типа TEXT, этим полям надо обязательно указывать длину, желательно − небольшую (не более 50 байт на поле), чтобы индекс не расходовал память.

Метод возвращает значение true, если индекс был успешно создан, и false в противном случае.

Пример:

// Делаем в таблице альбомов поле "группа" индексированным
$fields=array(array("name"=>"band","size"=>50));
$success=$database->addIndex("music","",false,$fields);
if($success) echo "Индекс создан успешно.";

bool modifyColumn ( string table, string column, string name, string type [, int attrs [, string default]] )

Метод переименовывает поле column в таблице table, а также задает полю новый тип, набор дополнительных атрибутов и значение по умолчанию. Новое имя поля указывается параметром name, новый тип поля − параметром type. При необходимости можно также указать новые атрибуты поля и новое значение поля по умолчанию, опциональными параметрами attrs и default соответственно. Более подробно о параметрах type, attrs и default можно прочитать в описании метода addColumn.

Обратите внимание, что у данного метода нет параметра position, то есть метод не позволяет менять порядок следования полей. Это связано с ограничениями стандарта SQL, который не позволяет перемещать уже созданное поле из одной позиции в другую. Единственный способ переместить поле или поменять два поля местами − это временно переименовать старое поле, создать новое поле с исходным именем и расположенное где надо, затем скопировать в него все данные из старого поля и затем удалить старое поле.

Метод возвращает значение true, если поле было успешно отредактировано, и false в противном случае.

Пример:

// Изменение типа поля "название альбома" на многострочный
$success=$database->modifyColumn("music","album","album","LONGTEXT");
if($success) echo "Поле изменено успешно.";

bool deleteColumn ( string table, string column )

Метод удаляет поле с именем column из таблицы table. Будьте осторожны, удаление поля приведет к потере всех данных, которые хранились в этом поле. Метод возвращает значение true, если поле было успешно удалено, и false в противном случае.

Пример:

// Удаление поля "жанр" из таблицы альбомов
$database->deleteColumn("music","genre");

bool deleteIndex ( string table, string name )

Метод удаляет индекс с названием name из таблицы table. Удаление индекса не влечет за собой никакой потери данных, и его можно снова создать позже. Метод возвращает значение true, если индекс был успешно удален, и false в противном случае.

Пример:

// Удаление индекса band, покрывающего одноименное поле
$database->deleteIndex("music","band");

int getSupportedAttributes ( void )

Метод возвращает список дополнительных атрибутов поля, которые поддерживаются данным типом СУБД, в виде битовой маски. MySQL поддерживает все пять дополнительных атрибутов, перечисленных в PHPC, поэтому при использовании MySQL данный метод возвращает значение 31 (0x1F).

string getColumnType ( string meaning )

Метод конвертирует внутренний тип данных PHPC, который передается параметром meaning, в стандартный тип данных SQL, и возвращает его в качестве результата.

Следует помнить, что преобразование, которое делает данный метод, строго говоря, необратимо, потому что разные типы данных PHPC конвертируются в одни и те же типы данных SQL. Например, и тип int (целочисленный), и тип datetime (дата-время) превращаются в один и тот же стандартный тип INT. Поэтому рекомендуется везде, где это требуется, сохранять именно типы данных PHPC, множество которых более разнообразно, и пользоваться данным методом непосредственно перед вызовом метода addColumn или modifyColumn.

Метод удобен для работы со Smart-формами в панели управления, особенно когда добавление или удаление записи в одной таблице влечет за собой добавление или удаление поля в другой таблице. Так реализовано, например, при управлении полями профайла и правами доступа в плагине пользователей.

Ниже приведены некоторые из PHPC-типов данных, и соответствующие им SQL-типы данных.

Пример:

// Добавление нового поля "жанр" в таблицу альбомов
$type=$database->getColumnType("input"); // TINYTEXT
$success=$database->addColumn("music","genre",$type);

string getColumnMeaning ( string type )

Данный метод является дополнением к методу getColumnType: он конвертирует стандартный SQL-тип данных обратно в тип данных PHPC. Обратите внимание, что из-за ограниченности набора SQL-типов данных метод не всегда возвращает ожидаемый результат. Например, если превратить PHPC-тип password в SQL-тип, мы получим значение TINYTEXT, но если превратить этот тип обратно в PHPC-тип, мы получим уже тип input. Поэтому рекомендуется сохранять для дальнейшего использования именно PHPC-типы данных.

Пример:

$meaning=$database->getColumnMeaning("TINYTEXT");
echo $meaning; // input

$meaning=$database->getColumnMeaning("LONGTEXT");
echo $meaning; // textarea

$meaning=$database->getColumnMeaning("TINYINT(1)");
echo $meaning; // yesno 

array getFieldsList ( string table )

Метод возвращает список полей таблицы table в виде обычного массива. Примечание: если вам нужен не только список полей, но и подробная информация о каждом поле, воспользуйтесь методом getTableInformation.

Пример:

// Список полей таблицы музыкальных альбомов
$fields=$database->getFieldsList("music");
foreach($fields as $field) echo $field; // id band album year tracks 

bool isFieldPresent ( string table, string field )

Метод проверяет, есть ли в таблице table поле с именем field, и возвращает true, если такое поле присутствует, и false в противном случае.

Пример:

// Храним ли мы информацию о жанрах?
$hasGenres=$database->isFieldPresent("music","genre");
if(!$hasGenres) die("Извините, данные о жанрах отсутствуют.");

bool isLocalizedFieldPresent ( string table, string field )

Метод проверяет, есть ли в таблице table локализованное поле с именем field, и возвращает true, если такое поле присутствует, и false в противном случае. Локализованное поле − это такое поле, которое хранит данные на одном языке, например, на русском. Название локализованного поля формируется по простому правилу: к названию обычного поля добавляется идентификатор локали. Например, для поля "заголовок" (title) и русского языка (локаль ru) локализованное поле будет называться titleru.

Пример:

// Есть ли в таблице "страницы" локализованный заголовок страницы?
$hasTitle=$database->isLocalizedFieldPresent("pages","title");
echo $hasTitle?"true":"false"; // true 

array getKeyFields ( string table )

Метод возвращает список полей таблицы table, которые составляют первичный ключ таблицы. Если первичный ключ является простым, то есть состоящим из одного поля (почти всегда это так), метод возвращает массив из одного элемента. Если первичный ключ является составным, метод вернет массив из нескольких элементов. Если первичный ключ не определен, метод возвращает пустой массив.

Пример:

// Первичный ключ таблицы музыкальных альбомов
$keys=$database->getKeyFields("music");
foreach($keys as $key) echo $key; // id