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

Модель представляет информацию (данные) приложения и правила для обработки этих данных. Модели в основном используются для управления правилами взаимодействия с соответствующей таблицей базы данных. В большинстве случаев каждая таблица в вашей базе данных будет соответствовать одной модели в вашем приложении. Большая часть бизнес-логики вашего приложения будет сконцентрирована в моделях.

Phalcon\Mvc\Model является основой для всех моделей в приложении Phalcon. Она обеспечивает независимость от базы данных, базовые функции CRUD, расширенные возможности поиска и возможность взаимосвязывать модели друг с другом, среди прочих функций. Phalcon\Mvc\Model позволяет избежать необходимости использования SQL-запросов, так как она динамически преобразует методы в операции соответствующего движка базы данных.

Модели предназначены для работы с базой данных на высоком уровне абстракции. Если вам нужно работать с базами данных на более низком уровне, ознакомьтесь с документацией компонента Phalcon\Db.

Создание моделей

Модель — это класс, который расширяет Phalcon\Mvc\Model. Имя класса должно быть в формате с использованием верблюжьего случая:

namespace Store\Toys;

use Phalcon\Mvc\Model;

class RobotParts extends Model
{

}

Если вы используете PHP 5.4/5.5, рекомендуется объявлять каждый столбец, который является частью модели, чтобы сохранить память и уменьшить выделение памяти.

По умолчанию модель «Store\Toys\RobotParts» будет ссылаться на таблицу «robot_parts». Если вы хотите вручную указать другое имя для сопоставляемой таблицы, вы можете использовать метод setSource():

namespace Store\Toys;

use Phalcon\Mvc\Model;

class RobotParts extends Model
{
    public function initialize()
    {
        $this->setSource("toys_robot_parts");
    }
}

Теперь модель RobotParts сопоставляется с таблицей «toys_robot_parts». Метод initialize() помогает настроить модель с настраиваемым поведением, т. е. с другой таблицей.

Метод initialize() вызывается только один раз во время запроса, он предназначен для выполнения инициализаций, которые применяются ко всем экземплярам модели, созданным в приложении. Если вы хотите выполнить задачи инициализации для каждого созданного экземпляра, вы можете использовать метод onConstruct():

namespace Store\Toys;

use Phalcon\Mvc\Model;

class RobotParts extends Model
{
    public function onConstruct()
    {
        // ...
    }
}

Публичные свойства по сравнению с методами set/get

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

namespace Store\Toys;

use Phalcon\Mvc\Model;

class Robots extends Model
{
    public $id;

    public $name;

    public $price;
}

Используя геттеры и сеттеры, вы можете контролировать, какие свойства видны публично, выполнять различные преобразования данных (что было бы невозможно в противном случае) и добавлять правила проверки данных, хранящихся в объекте:

namespace Store\Toys;

use InvalidArgumentException;
use Phalcon\Mvc\Model;

class Robots extends Model
{
    protected $id;

    protected $name;

    protected $price;

    public function getId()
    {
        return $this->id;
    }

    public function setName($name)
    {
        // The name is too short?
        if (strlen($name) < 10) {
            throw new InvalidArgumentException(
                "The name is too short"
            );
        }

        $this->name = $name;
    }

    public function getName()
    {
        return $this->name;
    }

    public function setPrice($price)
    {
        // Negative prices aren't allowed
        if ($price < 0) {
            throw new InvalidArgumentException(
                "Price can't be negative"
            );
        }

        $this->price = $price;
    }

    public function getPrice()
    {
        // Convert the value to double before be used
        return (double) $this->price;
    }
}

Публичные свойства обеспечивают меньшую сложность в разработке. Однако геттеры/сеттеры могут значительно повысить возможность тестирования, расширяемость и поддержку приложений. Разработчики могут решить, какая стратегия более подходит для создаваемого приложения. ORM совместим с обоими способами определения свойств.

Подчёркивания в именах свойств могут быть проблематичными при использовании геттеров и сеттеров.

Если вы используете подчёркивания в именах свойств, вы все равно должны использовать верблюжий регистр в объявлениях геттеров/сеттеров для использования с магическими методами. (например, $model->getPropertyName вместо $model->getProperty_name, $model->findByPropertyName вместо $model->findByProperty_name и т. д.). Поскольку большая часть системы ожидает верблюжий регистр, а подчёркивания обычно удаляются, рекомендуется называть свойства так, как показано в документации. Вы можете использовать карту столбцов (как описано выше), чтобы обеспечить правильное сопоставление ваших свойств с их базами данных.

Понимание преобразования записей в объекты

Каждый экземпляр модели представляет собой строку в таблице. Вы можете легко получить данные записи, прочитав свойства объекта. Например, для таблицы «robots» с записями:

mysql> select * from robots;
+----+------------+------------+------+
| id | name       | type       | year |
+----+------------+------------+------+
|  1 | Robotina   | mechanical | 1972 |
|  2 | Astro Boy  | mechanical | 1952 |
|  3 | Terminator | cyborg     | 2029 |
+----+------------+------------+------+
3 rows in set (0.00 sec)

Вы можете найти определённую запись по её первичному ключу и затем вывести её имя:

use Store\Toys\Robots;

// Find record with id = 3
$robot = Robots::findFirst(3);

// Prints "Terminator"
echo $robot->name;

После того, как запись находится в памяти, вы можете внести изменения в её данные и сохранить изменения:

use Store\Toys\Robots;

$robot = Robots::findFirst(3);

$robot->name = "RoboCop";

$robot->save();

Как видите, нет необходимости использовать чистые SQL-запросы. Phalcon\Mvc\Model предоставляет высокую абстракцию базы данных для веб-приложений.

Поиск записей

Phalcon\Mvc\Model также предлагает несколько методов для запроса записей. Следующие примеры покажут, как запрашивать одну или несколько записей из модели:

use Store\Toys\Robots;

// How many robots are there?
$robots = Robots::find();
echo "There are ", count($robots), "\n";

// How many mechanical robots are there?
$robots = Robots::find("type = 'mechanical'");
echo "There are ", count($robots), "\n";

// Get and print virtual robots ordered by name
$robots = Robots::find(
    [
        "type = 'virtual'",
        "order" => "name",
    ]
);
foreach ($robots as $robot) {
    echo $robot->name, "\n";
}

// Get first 100 virtual robots ordered by name
$robots = Robots::find(
    [
        "type = 'virtual'",
        "order" => "name",
        "limit" => 100,
    ]
);
foreach ($robots as $robot) {
   echo $robot->name, "\n";
}

Если вам нужно найти запись по внешним данным (таким как данные пользователя) или переменным данным, вы должны использовать Связывание параметров.

Вы также можете использовать метод findFirst() для получения только первой записи, соответствующей заданным критериям:

use Store\Toys\Robots;

// What's the first robot in robots table?
$robot = Robots::findFirst();
echo "The robot name is ", $robot->name, "\n";

// What's the first mechanical robot in robots table?
$robot = Robots::findFirst("type = 'mechanical'");
echo "The first mechanical robot name is ", $robot->name, "\n";

// Get first virtual robot ordered by name
$robot = Robots::findFirst(
    [
        "type = 'virtual'",
        "order" => "name",
    ]
);
echo "The first virtual robot name is ", $robot->name, "\n";

Оба метода find() и findFirst() принимают ассоциативный массив, определяющий критерии поиска:

use Store\Toys\Robots;

$robot = Robots::findFirst(
    [
        "type = 'virtual'",
        "order" => "name DESC",
        "limit" => 30,
    ]
);

$robots = Robots::find(
    [
        "conditions" => "type = ?1",
        "bind"       => [
            1 => "virtual",
        ]
    ]
);

Доступные параметры запроса:

Если вы предпочитаете, существует также способ создания запросов объектно-ориентированным способом вместо использования массива параметров:

use Store\Toys\Robots;

$robots = Robots::query()
    ->where("type = :type:")
    ->andWhere("year < 2000")
    ->bind(["type" => "mechanical"])
    ->order("name")
    ->execute();

Статический метод query() возвращает объект Phalcon\Mvc\Model\Criteria, который дружелюбен к автозаполнению IDE.

Все запросы обрабатываются как запросы PHQL. PHQL — это высокоуровневый, объектно-ориентированный язык, похожий на SQL. Этот язык предоставляет вам больше возможностей для выполнения запросов, таких как объединение других моделей, определение группировок, добавление агрегаций и т. д.

Наконец, есть метод findFirstBy<property-name>(). Этот метод расширяет метод findFirst(), упомянутый ранее. Он позволяет быстро извлекать данные из таблицы, используя имя свойства в самом методе и передавая параметр, содержащий данные, которые вы хотите найти в этом столбце. Для этого необходим пример, поэтому, беря нашу модель Robots, упомянутую ранее:

namespace Store\Toys;

use Phalcon\Mvc\Model;

class Robots extends Model
{
    public $id;

    public $name;

    public $price;
}

Здесь у нас есть три свойства для работы: $id, $name и $price. Скажем, вы хотите получить первую запись в таблице с именем «Terminator». Это можно записать так:

use Store\Toys\Robots;

$name = "Terminator";

$robot = Robots::findFirstByName($name);

if ($robot) {
    echo "The first robot with the name " . $name . " cost " . $robot->price . ".";
} else {
    echo "There were no robots found in our table with the name " . $name . ".";
}

Обратите внимание, что мы использовали «Name» в вызове метода и передали переменную $name в него, которая содержит имя, которое мы ищем в нашей таблице. Обратите также внимание, что при нахождении совпадения с нашим запросом, все остальные свойства также доступны нам.

Наборы результатов моделей

В то время как findFirst() возвращает напрямую экземпляр вызываемого класса (когда есть данные для возврата), метод find() возвращает Phalcon\Mvc\Model\Resultset\Simple. Это объект, который инкапсулирует все функции набора результатов, такие как проход, поиск определённых записей, подсчёт и т. д.

Эти объекты более мощные, чем обычные массивы. Одной из величайших особенностей набора результатов Phalcon\Mvc\Model\Resultset является то, что в любой момент времени в памяти находится только одна запись. Это значительно помогает в управлении памятью, особенно при работе с большими объёмами данных.

use Store\Toys\Robots;

// Get all robots
$robots = Robots::find();

// Traversing with a foreach
foreach ($robots as $robot) {
    echo $robot->name, "\n";
}

// Traversing with a while
$robots->rewind();

while ($robots->valid()) {
    $robot = $robots->current();

    echo $robot->name, "\n";

    $robots->next();
}

// Count the resultset
echo count($robots);

// Alternative way to count the resultset
echo $robots->count();

// Move the internal cursor to the third robot
$robots->seek(2);

$robot = $robots->current();

// Access a robot by its position in the resultset
$robot = $robots[5];

// Check if there is a record in certain position
if (isset($robots[3])) {
   $robot = $robots[3];
}

// Get the first record in the resultset
$robot = $robots->getFirst();

// Get the last record
$robot = $robots->getLast();

Наборы результатов Phalcon эмулируют прокручиваемые курсоры, вы можете получить любую строку, просто обратившись к её позиции или переместив внутренний указатель на определённую позицию. Обратите внимание, что некоторые системы баз данных не поддерживают прокручиваемые курсоры, это вынуждает повторно выполнить запрос, чтобы перемотать курсор в начало и получить запись в запрошенной позиции. Аналогично, если набор результатов проходит несколько раз, запрос должен выполняться такое же количество раз.

Поскольку хранение больших результатов запросов в памяти может потреблять много ресурсов, наборы результатов извлекаются из базы данных частями по 32 строки — уменьшая необходимость повторного выполнения запроса во многих случаях.

Обратите внимание, что наборы результатов могут быть сериализованы и сохранены в кэше. Phalcon\Cache может помочь в этом. Однако сериализация данных приводит к тому, что Phalcon\Mvc\Model извлекает все данные из базы данных в массив, таким образом потребляя больше памяти во время этого процесса.

// Query all records from model parts
$parts = Parts::find();

// Store the resultset into a file
file_put_contents(
    "cache.txt",
    serialize($parts)
);

// Get parts from file
$parts = unserialize(
    file_get_contents("cache.txt")
);

// Traverse the parts
foreach ($parts as $part) {
    echo $part->id;
}

Фильтрация наборов результатов

Самый эффективный способ фильтрации данных — это установка некоторых критериев поиска. Базы данных будут использовать индексы, установленные на таблицах, чтобы быстрее возвращать данные. Phalcon также позволяет фильтровать данные с помощью PHP, используя любые ресурсы, которые недоступны в базе данных:

$customers = Customers::find();

$customers = $customers->filter(
    function ($customer) {
        // Return only customers with a valid e-mail
        if (filter_var($customer->email, FILTER_VALIDATE_EMAIL)) {
            return $customer;
        }
    }
);

Связывание параметров

Связанные параметры также поддерживаются в Phalcon\Mvc\Model. Рекомендуется использовать эту методологию, чтобы исключить возможность того, что ваш код подвергнется атакам SQL-инъекции. Поддерживаются как строковые, так и целочисленные плейсхолдеры. Связывание параметров можно выполнить следующим образом:

use Store\Toys\Robots;

// Query robots binding parameters with string placeholders
// Parameters whose keys are the same as placeholders
$robots = Robots::find(
    [
        "name = :name: AND type = :type:",
        "bind" => [
            "name" => "Robotina",
            "type" => "maid",
        ],
    ]
);

// Query robots binding parameters with integer placeholders
$robots = Robots::find(
    [
        "name = ?1 AND type = ?2",
        "bind" => [
            1 => "Robotina",
            2 => "maid",
        ],
    ]
);

// Query robots binding parameters with both string and integer placeholders
// Parameters whose keys are the same as placeholders
$robots = Robots::find(
    [
        "name = :name: AND type = ?1",
        "bind" => [
            "name" => "Robotina",
            1      => "maid",
        ],
    ]
);

При использовании числовых плейсхолдеров необходимо определить их как целые числа, например, 1 или 2. В этом случае «1» или «2» рассматриваются как строки, а не числа, поэтому плейсхолдер не может быть успешно заменён.

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

Кроме того, можно установить параметр «bindTypes», который позволяет определить, как параметры должны быть связаны в соответствии с их типом данных:

use Phalcon\Db\Column;
use Store\Toys\Robots;

// Bind parameters
$parameters = [
    "name" => "Robotina",
    "year" => 2008,
];

// Casting Types
$types = [
    "name" => Column::BIND_PARAM_STR,
    "year" => Column::BIND_PARAM_INT,
];

// Query robots binding parameters with string placeholders
$robots = Robots::find(
    [
        "name = :name: AND year = :year:",
        "bind"      => $parameters,
        "bindTypes" => $types,
    ]
);

Поскольку тип связи по умолчанию Phalcon\Db\Column::BIND_PARAM_STR, нет необходимости указывать параметр «bindTypes», если все столбцы являются этого типа.

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

use Store\Toys\Robots;

$array = ["a","b","c"]; // $array: [[0] => "a", [1] => "b", [2] => "c"]

unset($array[1]); // $array: [[0] => "a", [2] => "c"]

// Now we have to renumber the keys
$array = array_values($array); // $array: [[0] => "a", [1] => "c"]

$robots = Robots::find(
    [
        'letter IN ({letter:array})',
        'bind' => [
            'letter' => $array
        ]
    ]
);

Связанные параметры доступны для всех методов запросов, таких как find() и findFirst(), а также для методов вычисления, таких как count(), sum(), average() и т. д.

Если вы используете «найди», связанные параметры автоматически используются для вас:

use Store\Toys\Robots;

// Explicit query using bound parameters
$robots = Robots::find(
    [
        "name = ?0",
        "bind" => [
            "Ultron",
        ],
    ]
);

// Implicit query using bound parameters
$robots = Robots::findByName("Ultron");

Инициализация/Подготовка извлеченных записей

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

namespace Store\Toys;

use Phalcon\Mvc\Model;

class Robots extends Model
{
    public $id;

    public $name;

    public $status;

    public function beforeSave()
    {
        // Convert the array into a string
        $this->status = join(",", $this->status);
    }

    public function afterFetch()
    {
        // Convert the string to an array
        $this->status = explode(",", $this->status);
    }

    public function afterSave()
    {
        // Convert the string to an array
        $this->status = explode(",", $this->status);
    }
}

Если вы используете геттеры/сеттеры вместо или вместе с общедоступными свойствами, вы можете инициализировать поле после того, как к нему обратятся:

namespace Store\Toys;

use Phalcon\Mvc\Model;

class Robots extends Model
{
    public $id;

    public $name;

    public $status;

    public function getStatus()
    {
        return explode(",", $this->status);
    }
}

Генерация вычислений

Вычисления (или агрегации) — это вспомогательные средства для часто используемых функций систем баз данных, таких как COUNT, SUM, MAX, MIN или AVG. Phalcon\Mvc\Model позволяет использовать эти функции непосредственно из экспонированных методов.

Примеры подсчёта:

// How many employees are?
$rowcount = Employees::count();

// How many different areas are assigned to employees?
$rowcount = Employees::count(
    [
        "distinct" => "area",
    ]
);

// How many employees are in the Testing area?
$rowcount = Employees::count(
    "area = 'Testing'"
);

// Count employees grouping results by their area
$group = Employees::count(
    [
        "group" => "area",
    ]
);
foreach ($group as $row) {
   echo "There are ", $row->rowcount, " in ", $row->area;
}

// Count employees grouping by their area and ordering the result by count
$group = Employees::count(
    [
        "group" => "area",
        "order" => "rowcount",
    ]
);

// Avoid SQL injections using bound parameters
$group = Employees::count(
    [
        "type > ?0",
        "bind" => [
            $type
        ],
    ]
);

Примеры суммирования:

// How much are the salaries of all employees?
$total = Employees::sum(
    [
        "column" => "salary",
    ]
);

// How much are the salaries of all employees in the Sales area?
$total = Employees::sum(
    [
        "column"     => "salary",
        "conditions" => "area = 'Sales'",
    ]
);

// Generate a grouping of the salaries of each area
$group = Employees::sum(
    [
        "column" => "salary",
        "group"  => "area",
    ]
);
foreach ($group as $row) {
   echo "The sum of salaries of the ", $row->area, " is ", $row->sumatory;
}

// Generate a grouping of the salaries of each area ordering
// salaries from higher to lower
$group = Employees::sum(
    [
        "column" => "salary",
        "group"  => "area",
        "order"  => "sumatory DESC",
    ]
);

// Avoid SQL injections using bound parameters
$group = Employees::sum(
    [
        "conditions" => "area > ?0",
        "bind"       => [
            $area
        ],
    ]
);

Примеры средних значений:

// What is the average salary for all employees?
$average = Employees::average(
    [
        "column" => "salary",
    ]
);

// What is the average salary for the Sales's area employees?
$average = Employees::average(
    [
        "column"     => "salary",
        "conditions" => "area = 'Sales'",
    ]
);

// Avoid SQL injections using bound parameters
$average = Employees::average(
    [
        "column"     => "age",
        "conditions" => "area > ?0",
        "bind"       => [
            $area
        ],
    ]
);

Примеры максимальных/минимальных значений:

// What is the oldest age of all employees?
$age = Employees::maximum(
    [
        "column" => "age",
    ]
);

// What is the oldest of employees from the Sales area?
$age = Employees::maximum(
    [
        "column"     => "age",
        "conditions" => "area = 'Sales'",
    ]
);

// What is the lowest salary of all employees?
$salary = Employees::minimum(
    [
        "column" => "salary",
    ]
);

Создание/обновление записей

Метод Phalcon\Mvc\Model::save() позволяет создавать/обновлять записи в зависимости от того, существуют ли они уже в таблице, связанной с моделью. Метод save вызывается внутренне методами create и update модели Phalcon\Mvc\Model. Для правильной работы необходимо правильно определить первичный ключ в сущности, чтобы определить, следует ли обновлять или создавать запись.

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

use Store\Toys\Robots;

$robot = new Robots();

$robot->type = "mechanical";
$robot->name = "Astro Boy";
$robot->year = 1952;

if ($robot->save() === false) {
    echo "Umh, We can't store robots right now: \n";

    $messages = $robot->getMessages();

    foreach ($messages as $message) {
        echo $message, "\n";
    }
} else {
    echo "Great, a new robot was saved successfully!";
}

Массив можно передать в «save», чтобы избежать ручного присвоения каждого столбца. Phalcon\Mvc\Model проверит, реализованы ли сеттеры для столбцов, переданных в массиве, отдавая предпочтение им вместо непосредственного присваивания значений атрибутов:

use Store\Toys\Robots;

$robot = new Robots();

$robot->save(
    [
        "type" => "mechanical",
        "name" => "Astro Boy",
        "year" => 1952,
    ]
);

Значения, присвоенные напрямую или через массив атрибутов, экранируются/очищаются в соответствии с типом данных связанного атрибута. Таким образом, вы можете передавать небезопасный массив, не беспокоясь о возможных атаках SQL-инъекции:

use Store\Toys\Robots;

$robot = new Robots();

$robot->save($_POST);

Без предосторожностей массовое присвоение может позволить злоумышленникам установить значение любого столбца базы данных. Используйте эту функцию только в том случае, если вы хотите разрешить пользователю вставлять/обновлять каждый столбец в модели, даже если эти поля отсутствуют в отправленной форме.

Вы можете установить дополнительный параметр в «save», чтобы установить белый список полей, которые должны учитываться при выполнении массового присвоения:

use Store\Toys\Robots;

$robot = new Robots();

$robot->save(
    $_POST,
    [
        "name",
        "type",
    ]
);

Создание/обновление с уверенностью

Когда приложение имеет много конкурентов, мы можем ожидать создания записи, но она фактически обновляется. Это может произойти, если мы используем Phalcon\Mvc\Model::save() для сохранения записей в базе данных. Если мы хотим быть абсолютно уверены, что запись создаётся или обновляется, мы можем изменить вызов save() на create() или update():

use Store\Toys\Robots;

$robot = new Robots();

$robot->type = "mechanical";
$robot->name = "Astro Boy";
$robot->year = 1952;

// This record only must be created
if ($robot->create() === false) {
    echo "Umh, We can't store robots right now: \n";

    $messages = $robot->getMessages();

    foreach ($messages as $message) {
        echo $message, "\n";
    }
} else {
    echo "Great, a new robot was created successfully!";
}

Эти методы «create» и «update» также принимают массив значений в качестве параметра.

Удаление записей

Метод Phalcon\Mvc\Model::delete() позволяет удалить запись. Вы можете использовать его следующим образом:

use Store\Toys\Robots;

$robot = Robots::findFirst(11);

if ($robot !== false) {
    if ($robot->delete() === false) {
        echo "Sorry, we can't delete the robot right now: \n";

        $messages = $robot->getMessages();

        foreach ($messages as $message) {
            echo $message, "\n";
        }
    } else {
        echo "The robot was deleted successfully!";
    }
}

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

use Store\Toys\Robots;

$robots = Robots::find(
    "type = 'mechanical'"
);

foreach ($robots as $robot) {
    if ($robot->delete() === false) {
        echo "Sorry, we can't delete the robot right now: \n";

        $messages = $robot->getMessages();

        foreach ($messages as $message) {
            echo $message, "\n";
        }
    } else {
        echo "The robot was deleted successfully!";
    }
}

Следующие события доступны для определения пользовательских бизнес-правил, которые могут выполняться при выполнении операции удаления:

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

namespace Store\Toys;

use Phalcon\Mvc\Model;

class Robots extends Model
{
    public function beforeDelete()
    {
        if ($this->status === "A") {
            echo "The robot is active, it can't be deleted";

            return false;
        }

        return true;
    }
}