JTable - работа с таблицами базы данных

Joomla CRUD

Joomla! предоставляет нам мощный абстрактный класс JTable; при этом мы можем выполнять все основные функции по работе с таблицей. Для каждой таблицы, которую мы хотим использовать в классе JTable, мы должны создать новый подкласс.

При создании подкласса JTable, мы должны придерживаться некоторых правил. Эти правила позволят нам интегрировать наше расширение в Фреймворк Joomla.

Итак, каждый подкласс JTable должен быть расположен в отдельном файле в каталоге tables (в административной части компонента). Имя создаваемого класса должно иметь префикс table. Имя файла обязательно должно быть в единственном числе.

Используем описанную выше схему таблицы, чтобы показать на примере как работать с классом JTable.

Класс должен называться Table[Название класса], например, TableMyData и расположен в каталоге  JPATH_COMPONENT_ADMINISTRATOR.DS.'tables'.DS.'mydata.php'.  При первом использовании нашего класса мы должны определить глобальные свойства. Глобальные свойства соответствуют полям таблицы и должны иметь такие же названия. Мы используем эти свойства как буфер для хранения отдельных записей.

Во-вторых, в целях использования метода JTable::getInstance() мы должны определить конструктор.

В-третьих, нам нужно переопределить метод check(). Этот метод проверяет содержимое буфера и возвращает булево значение. Если метод вернул значение false, то используем метод setError() для пояснения ошибки.

class TableMyData extends JTable
{
    /** @var int Primary key */ 
    var $id = null;

    /** @var string Content */ 
    var $content = null;

    /** @var int Checked-out owner */ 
    var $checked_out = null;

    /** @var string Checked-out time */ 
    var $checked_out_time = null;

    /** @var string Parameters */ 
    var $params = null;

    /** @var int Order position */ 
    var $ordering = null;

    /** @var int Number of views */ 
    var $hits = null;

    /**
    * Constructor
    *
    * @param database Database object
    */
    function __construct( &$db )
    {
        parent::__construct('#__myextension_mydata', 'id', $db);
    }
    
    /**
    * Проверка
    *
    * @return boolean True if buffer is valid
    */
    function check()
    {
        if(!$this->content)
        {
            $this->setError(JText::_('Ошибка'));
            return false;
        }
        return true;
    }
}

Теперь, когда мы создали TableMyData класс нужно инстанцировать объект с помощью статического метода JTable:: getInstance().

JTable::addIncludePath(JPATH_COMPONENT_ADMINISTRATOR.DS.'tables');
$table = JTable::getInstance('mydata', 'Table');

Заметьте, что мы подключаем не mydata.php а только каталог с таблицами. Когда JTable начинает инстанцировать TableMyData на объект, автоматически подключается mydata.php.

CRUD

CRUD (Create Read Update Delete) - это общее название основных задач по управлению таблицей. 
Все CRUD примеры $table ссылаются на класс TableMyData и $id ссылается на идентификатор записи которую мы в данный момент обрабатываем. В этом примере мы создаем новую запись; $table - экземпляр класса TableMyData.

$table->reset();
$table->set('content', "Наш контент");
$table->set('ordering', $table->getNextOrder());
if ($table->check())
{
    if (!$table->store())
    {
        // обработчик ошибок записи
        // используем $table->getError()
    }
} else {
    // обработчик ошибки проверки буфера
    // тоже используем $table->getError()
}

Метод reset() очищает наш буфер и приводит значения всех свойств к значениям по-умолчанию. Метод getNextOrder() определяет следующий по порядку вложенности элемент. Если запись не существующая, то он ставит значение 1.

Давайте рассмотрим наш пример подробнее. Некоторые из полей имели значение по-умолчанию, и после записи, значение даты будет пустым. После выполнения предыдущего примера буфер $table выглядит так:

array (
    'id' => '1',
    'content' => 'Наш контент',
    'checked_out' => '',
    'checked_out_time' => '',
    'params' => '',
    'ordering' => '1',
    'hits' => '0'
);

После выполнения метода store() (сохранения записи), мы можем загрузить его:

<samp>$table->load($table->id);</samp>

Теперь наш буфер выглядит так:

array (
    'id' => '1',
    'content' => 'Наш контент',
    'checked_out' => '0',
    'checked_out_time' => '0000-00-00 00:00:00',
    'params' => '',
    'ordering' => '1',
    'hits' => '0',
); 

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

Однако некоторые значения по-умолчанию зависят от типа данных. Поэтому нам нужно переопределить метод reset(). Для примера значение checked_out_time будет равно $db->getNullDate(). Итак для загрузки конкретной записи используем метод:

if (!$table->load($id))
{
    // обработчик загрузки
    // используем $table->getError() для ловли ошибок
}

Для обновления записи в буфере мы можем использовать два метода: первый - это загрузить запись из БД, второй - это установить конкретные значения для свойств буфера.

В этом примере покажем как обновить запись:

// установка значений
$table->reset();
$table->setVar('id', $id);
$table->setVar('content', JRequest::getString('content'));
if ($table->check())
{
    if (!$table->store())
    {
        // обрабатываем ошибки записи с помощью $table->getError()
    }
} else {
    // обрабатываем ошибки ввода в буфер $table->getError()
}

Последнее что мы рассмотрим - это удаление записи:

if (!$table->delete($id))
{
    // обрабатываем ошибки
}

Если мы не указываем в методе delete() номер id, то id будет браться из буфера.

Если наша запись в таблице имеет родственные записи с другими таблицами, то мы должны сначала выполнить проверку методом canDelete(). Этот метод имеет всего один параметр в виде двумерного массива. Внутри массива должно быть несколько ключей - idfield, name, joinfield, и label. idfield - это имя первичного ключа в соответствующей таблице. name - это название самой таблицы. joinfield - это имя внешнего ключа соответствующей таблицы. label - это описание отношения между таблицами, для вывода сообщения об ошибке, если родственных связей не найдено.

Представьте что есть еще одна таблица #__myextension_children. Эта таблица имеет первичный ключ childid и внешний ключ primary, который ссылается на запись в таблице #__myextension_mydata. В этом примере мы проверим нет ли зависимости между записями таблицами #__myextension_children и #__myextension_mydata, перед удалением записи из таблицы #__myextension_mydata.

$join1 = array(
    'idfield'   => 'childid', 
    'name'      => '#__myextension_children', 
    'joinfield' => 'parent', 
    'label'     => 'Children'
);
 
$joins = array($join1);
if ($table->canDelete($id, $joins))
{
    if (!$table->delete($id))
    {
        // обрабатываем ошибки удаления
    }
} else {
    // обрабатываем в случае нахождения зависимостей
}

Мы можем определить более одной межтабличной связи. Допустим еще существует таблица #__myextension_illegitimate_children:

$join1 = array(
    'idfield'   => 'childid', 
    'name'      => '#__myextension_children', 
    'joinfield' => 'parent', 
    'label'     => 'Children');
$join2 = array(
    'idfield'   => 'ichildid', 
    'name'      => '#__myextension_illegitimate_children', 
    'joinfield' => 'parent', 
    'label'     => 'illegitimate Children');
$joins = array($join1, $join2);

Управление зарезервированными полями

Наша таблица содержит все зарезервированные поля, которыми мы можем управлять с помощью методов класса JTable. Рассмотрим управление этими полями подробнее.

Publishing

Для публикации и снятия с публикации мы можем использовать метод publish(). Если таблица содержит поле checked_ out, то мы можем быть уверены что запись таблицы не редактируется другим пользователем. Приведем пример публикации:

$publishIds = array($id);
$user =& JFactory::getUser();
if (!$table->publish($publishIds, 1, $user->get('id')))
{
    // обрабатываем ошибки
}

Первый параметр - это массив из id записей, которые нужно опубликовать или снять с публикации. Второй параметр необязательный, и указывает публикуем мы запись (значение 1), или снимаем с публикации (значение 0). По-умолчанию имеет значение 1. Последний параметр используется только в случае, если существует поле checked_out, и указывает id пользователя редактирующего запись. Метод возвращает значение true если все прошло успешно.

Hits

Произвести инкремент над записью можно с помощью метода hit(). Для примера мы установим id записи и выполним инкремент.

$table->set('id', $id);
$table->hit();

Также мы можем указать в параметре метода hit() нужный нам id. Но мы должны помнить что при этом обновиться буфер.

$table->hit($id);

Checking Out

Перед тем как мы начнем блокировать наши записи, мы должны убедиться что запись уже не заблокирована. Это нужно, чтобы не получилось, что несколько пользователей одновременно редактируют одну запись. Для этого мы можем использовать метод isCheckOut(). В этом примере мы выполняем проверку:

$table->load($id);
$user =& JFactory::getUser();
if ($table->isCheckedOut($user->get('id')))
{
    // выполняем действия если запись заблокирована
}

Далее мы блокируем запись под пользователя:

$table->load($id);
$user =& JFactory::getUser();
if (!$table->checkout($user->get('id')))
{
    // обрабатываем ошибки
}

Для того чтобы обрабатывать запись используем следующий метод:

$table->load($id);
$user =& JFactory::getUser();
if (!$table->checkin($user->get('id')))
{
    // обрабатываем ошибки
}

Запомните, что эти методы можно использовать только для залогенных пользователей.

Ordering

Когда мы хотим расположить элементы в определенном порядке, JTable предоставляет нам для этого набор методов. Первый из рассмотренных нами методов будет reorder(). Этот метод исправляет ошибки в порядке расположения записей в таблице.

$table->reorder();

В более сложных таблицах записи обычно разбиты по группам, и для этого в метод reorder() нужно дописать дополнительный параметр. Представим, что в нашей таблице есть поле group. В этом примере мы упорядочим записи в группе 1.

$db =& $table::getDBO();
$where = $db->nameQuote('group').' = 1';
$table->reorder($where);

Заметьте, что мы получаем объект базы данных не из JFactory, а из таблицы!
Ранее мы уже использовали метод getNextOrder(). Метод выдает нам следующую позицию в порядке упорядочивания. Как и в случае с reorder(), мы имеем возможность определения групп. Например, получим следующий номер порядка для группы 1.

$db =& $table::getDBO();
$where = $db->nameQuote('group').' = 1';
$nextPosition = $table->getNextOrder($where);

И последний метод - это move(). Он нужен для перемещения записи на одну позицию вверх или вниз. Переместим на примере запись вверх.
$table->load($id); $table->move(-1); Опять у нас есть возможность для указания групп. Покажем это на примере:

$db =& $table::getDBO();
$where = $db->nameQuote('group').' = 1';
$table->load($id);
$table->move(1, $where);

Поле параметров params

Класс JTable не имеет каких-то специальных методов по управлению параметрами INI. Буфер JTable предназначен для хранения RAW данных параметров, которые необходимо сохранить.

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

Класс JParameter расширяет класс JRegistry. В этом примере мы рассмотрим как можно парсить параметры используя класс JParameter.

$params = new JParameter($table->params);

Как только мы получили доступ к параметрам, мы можем изменять их используя методы get() и set().

$value = $params->get('someValue');
$params->set('someValue', ++$value);

Также мы можем получить данные в виде INI строки используя метод toString().

$table->params = $params->toString();

Мы также можем сами создать строку параметров. Для этого нужно указать сами параметры и путь к XML файлу манифеста.

$params = new JParameter('foo=bar', $pathToXML_File);

Для вывода параметров на экран в виде формы используется метод render().

echo $params->render('params');

Поля даты

При сохранении даты, очень важно чтобы она была в правильном формате. Для MySql мы должны сохранять дату в виде YYYY-MM-DD HH:MM:SS. Самый простой способ сделать это - использовать класс JDate. В этом классе нам потребуется метод toMySQL(), для приведения даты к правильному виду.

// import JDate class
jimport('joomla.utilities.date');
// получаем текущую дату и время
$myDate = gmdate();
// создаем новый объект JDate
// для joomla 1.5.0 надо было писать $jdate = new JDate($myDate);
$jdate = & JFactory::getDate($myDate);
// создаем запрос используя toMySQL()
$query = 'SELECT * FROM #__example WHERE date < '.$jdate->toMySQL();

$myDate - это дата в формате UNIX (timestamp).

• MySQL не поддерживает кодировку UTF-8, что делать?
• Безопасные SQL запросы
• Примеры MySQL запросов для Joomla
• Создание MVC компонента Joomla 1.5 - Шаг 3, База данных
• Создание MVC компонента Joomla 1.5 - Шаг 6, добавляем действия к Модели