Usando el modelo de Higgs

Modelos 

El modelo de Higgs proporciona características de conveniencia y funcionalidad adicional. que la gente usa comúnmente para hacer más conveniente trabajar con una tabla única en su base de datos.

Sale de la caja con ayudante. métodos para muchas de las formas estándar que necesitaría para interactuar con una tabla de base de datos, incluida la búsqueda de registros, actualizar registros, eliminar registros y más.

Accediendo a modelos 

Los modelos normalmente se almacenan en el directorio app/Models. Deben tener un espacio de nombres que coincida con su ubicación dentro del directorio, como espacio de nombres App\Models.

Puede acceder a los modelos dentro de sus clases creando una nueva instancia o usando la función auxiliar model().

<?php

// Create a new class manually.
$userModel = new \App\Models\UserModel();

// Create a shared instance of the model.
$userModel = model('UserModel');
// or
$userModel = model('App\Models\UserModel');
// or
$userModel = model(\App\Models\UserModel::class);

// Create a new class with the model() function.
$userModel = model('UserModel', false);

// Create shared instance with a supplied database connection.
$db        = db_connect('custom');
$userModel = model('UserModel', true, $db);

El model() usa Factories::models() internamente. Consulte Cargando clases para obtener detalles sobre el primer parámetro.

Modelo de Higgs 

Higgs proporciona una clase de modelo que proporciona algunas características interesantes, que incluyen:

conexión automática a la base de datos
métodos CRUD básicos
validación en el modelo
paginación automática
y más

Esta clase proporciona una base sólida desde la cual construir tus propios modelos, permitiéndote Desarrolle rápidamente la capa de modelo de su aplicación.

Creando tu modelo 

Para aprovechar el modelo de Higgs, simplemente crearía una nueva clase de modelo. que extiende Higgs\Model:

<?php

namespace App\Models;

use Higgs\Model;

class UserModel extends Model
{
    // ...
}

Esta clase vacía proporciona acceso conveniente a la conexión de la base de datos, el Generador de consultas, y una serie de métodos de conveniencia adicionales.

initialize()

Si necesita configuración adicional en su modelo, puede extender el método initialize() que se ejecutará inmediatamente después del constructor del modelo. Esto le permite realizar pasos adicionales sin repetir los parámetros del constructor, por ejemplo extendiendo otros modelos:

<?php

namespace App\Models;

use Modules\Authentication\Models\UserAuthModel;

class UserModel extends UserAuthModel
{
    /**
     * Called during initialization. Appends
     * our custom field to the module's model.
     */
    protected function initialize()
    {
        $this->allowedFields[] = 'middlename';
    }
}

Conexión a la base de datos 

Cuando se crea una instancia de la clase por primera vez, si no se pasa ninguna instancia de conexión de base de datos al constructor, y si no configura la propiedad $DBGroup en su clase de modelo, se conectará automáticamente al grupo de base de datos predeterminado, según lo establecido en la configuración de la base de datos.

Puede modifique qué grupo se utiliza según el modelo agregando la propiedad $DBGroup a su clase. Esto garantiza que dentro del modelo cualquier referencia a $this->db se realice a través del canal apropiado. conexión.

<?php

namespace App\Models;

use Higgs\Model;

class UserModel extends Model
{
    protected $DBGroup = 'group_name';
}

Reemplazaría «nombre_grupo» con el nombre de un grupo de base de datos definido de la base de datos. archivo de configuración.

Configurando su modelo 

La clase modelo tiene algunas opciones de configuración que se pueden configurar para permitir los métodos de la clase. para trabajar sin problemas para usted. Los dos primeros son utilizados por todos los métodos CRUD para determinar qué tabla usar y cómo podemos encontrar los registros requeridos:

<?php

namespace App\Models;

use Higgs\Model;

class UserModel extends Model
{
    protected $table      = 'users';
    protected $primaryKey = 'id';

    protected $useAutoIncrement = true;

    protected $returnType     = 'array';
    protected $useSoftDeletes = true;

    protected $allowedFields = ['name', 'email'];

    protected bool $allowEmptyInserts = false;

    // Dates
    protected $useTimestamps = false;
    protected $dateFormat    = 'datetime';
    protected $createdField  = 'created_at';
    protected $updatedField  = 'updated_at';
    protected $deletedField  = 'deleted_at';

    // Validation
    protected $validationRules      = [];
    protected $validationMessages   = [];
    protected $skipValidation       = false;
    protected $cleanValidationRules = true;

    // Callbacks
    protected $allowCallbacks = true;
    protected $beforeInsert   = [];
    protected $afterInsert    = [];
    protected $beforeUpdate   = [];
    protected $afterUpdate    = [];
    protected $beforeFind     = [];
    protected $afterFind      = [];
    protected $beforeDelete   = [];
    protected $afterDelete    = [];
}

$table 

Especifica la tabla de base de datos con la que trabaja principalmente este modelo. Esto sólo se aplica a la métodos CRUD incorporados. No está restringido a utilizar únicamente esta tabla por su cuenta. consultas.

$primaryKey 

Este es el nombre de la columna que identifica de forma única los registros de esta tabla. Este no necesariamente tiene que coincidir con la clave principal especificada en la base de datos, pero se usa con métodos como find() para saber con qué columna hacer coincidir el valor especificado.

Nota

All Models must have a primaryKey specified to allow all of the features to work como se esperaba.

$useAutoIncrement 

Especifica si la tabla utiliza una función de incremento automático para $primaryKey. Si se establece en «falso» entonces usted es responsable de proporcionar el valor de la clave principal para cada registro de la tabla. Este La característica puede ser útil cuando queremos implementar una relación 1:1 o usar UUID para nuestro modelo. El El valor predeterminado es «verdadero».

Nota

If you set $useAutoIncrement to false, then make sure to set your primary clave en la base de datos a único. De esta manera te asegurarás de que todas las características del modelo seguirá funcionando igual que antes.

$returnType 

Los métodos CRUD del modelo le quitarán un paso de trabajo y regresarán automáticamente los datos resultantes, en lugar del objeto Resultado. Esta configuración le permite definir el tipo de datos que se devuelven. Los valores válidos son “array” (el valor predeterminado), “object” o completamente nombre calificado de una clase que se puede usar con getCustomResultObject() del objeto Result método. El uso de la constante especial ::class de la clase permitirá que la mayoría de los IDE Complete automáticamente el nombre y permita funciones como refactorización para comprender mejor su código.

$useSoftDeletes 

Si es verdadero, entonces cualquier llamada al método delete() establecerá deleted_at en la base de datos, en lugar de en realidad eliminando la fila. Esto puede preservar datos cuando se pueda hacer referencia a ellos en otro lugar, o puede mantener una «papelera de reciclaje» de objetos que se pueden restaurar, o incluso simplemente conservarla como parte de un rastro de seguridad. Si es verdadero, los métodos find*() solo devolverán filas no eliminadas, a menos que el método withDeleted() se llama antes de llamar al método find*().

Esto requiere un campo DATETIME o INTEGER en la base de datos según el modelo. Configuración $dateFormat. El nombre del campo predeterminado es deleted_at sin embargo este nombre puede ser configurado con cualquier nombre de su elección utilizando la propiedad $deletedField.

Importante

The deleted_at field must be nullable.

$allowedFields 

Esta matriz debe actualizarse con los nombres de los campos que se pueden configurar durante save(), insert() o Métodos actualizar(). Cualquier nombre de campo distinto de estos se descartará. Esto ayuda a proteger en contra de simplemente tomar información de un formulario y arrojarla toda al modelo, lo que resulta en posibles vulnerabilidades de asignación masiva.

Nota

The $primaryKey field should never be an allowed field.

$allowEmptyInserts 

Nuevo en la versión 7.0.0.

Ya sea para permitir la inserción de datos vacíos. El valor predeterminado es «falso», lo que significa que si intentas insertar datos vacíos, se producirá una excepción con «No hay datos para insertar.» elevará.

También puede cambiar esta configuración con el método allowEmptyInserts().

fechas 

$useTimestamps

Este valor booleano determina si la fecha actual se agrega automáticamente a todas las inserciones. y actualizaciones. Si es true, establecerá la hora actual en el formato especificado por $dateFormat. Este requiere que la tabla tenga columnas denominadas created_at, updated_at y deleted_at en el formato apropiado. tipo de datos. Consulte también $createdField, $updatedField y $deletedField.

$dateFormat

Este valor funciona con $useTimestamps y $useSoftDeletes para garantizar que se utilice el tipo correcto de El valor de fecha se inserta en la base de datos. De forma predeterminada, esto crea valores DATETIME, pero Las opciones válidas son: 'datetime', 'date' o 'int' (una marca de tiempo UNIX). Usando $useSoftDeletes o $useTimestamps con un $dateFormat no válido o faltante provocará una excepción.

$createdField

Especifica qué campo de base de datos usar para la marca de tiempo de creación del registro de datos. Establezca una cadena vacía ('') para evitar actualizarla (incluso si $useTimestamps está habilitado).

$updatedField

Especifica qué campo de base de datos se debe utilizar para mantener la marca de tiempo de actualización del registro de datos. Establezca una cadena vacía ('') para evitar actualizarla (incluso $useTimestamps está habilitado).

$deletedField

Especifica qué campo de base de datos usar para eliminaciones temporales. Consulte $useSoftDeletes.

Validación 

$validationRules

Contiene una matriz de reglas de validación como se describe en How to Save Your Rules o una cadena que contiene el nombre de un grupo de validación, como se describe en la misma sección. Se describe con más detalle a continuación.

$validationMessages

Contiene una serie de mensajes de error personalizados que deben usarse durante la validación, como descrito en Setting Custom Error Messages. Se describe con más detalle a continuación.

$skipValidation

Si se debe omitir la validación durante todas las inserciones y actualizaciones. El valor por defecto El valor es «falso», lo que significa que los datos siempre intentarán ser validados. Esto es utilizado principalmente por el método skipValidation(), pero puede cambiarse a true para que este modelo nunca se validará.

$cleanValidationRules

Si se deben eliminar las reglas de validación que no existen en los datos pasados. Esto se usa en actualizaciones. El valor predeterminado es «verdadero», lo que significa que las reglas de validación para los campos que no estén presentes en los datos pasados se eliminarán (temporalmente) antes de la validación. Esto es para evitar errores de validación al actualizar solo algunos campos.

También puede cambiar el valor mediante el método cleanRules().

Nota

Prior to v7.2.7, $cleanValidationRules did not work due to a bug.

Devoluciones de llamada 

$allowCallbacks

Si se deben utilizar las devoluciones de llamada definidas a continuación. Ver Eventos modelo.

$beforeInsert

$afterInsert

$beforeUpdate

$afterUpdate

$beforeFind

$afterFind

$beforeDelete

$afterDelete

$beforeInsertBatch

$afterInsertBatch

$beforeUpdateBatch

$afterUpdateBatch

Estas matrices le permiten especificar métodos de devolución de llamada que se ejecutarán en los datos en el hora especificada en el nombre de la propiedad. Ver Eventos modelo.

Trabajar con datos 

Encontrar datos 

Se proporcionan varias funciones para realizar trabajo CRUD básico en sus tablas, incluyendo find(), insertar(), actualizar(), eliminar() y más.

find()

Devuelve una sola fila donde la clave principal coincide con el valor pasado como primer parámetro:

<?php

$user = $userModel->find($user_id);

El valor se devuelve en el formato especificado en $returnType.

Puede especificar más de una fila para devolver pasando una matriz de valores de clave primaria en su lugar. de solo uno:

<?php

$users = $userModel->find([1, 2, 3]);

Nota

If no parameters are passed in, find() will return all rows in that model’s table, actuando efectivamente como findAll(), aunque menos explícito.

findColumn()

Devuelve nulo o una matriz indexada de valores de columna:

<?php

$user = $userModel->findColumn($column_name);

$column_name debe ser el nombre de una sola columna; de lo contrario, obtendrá la DataException.

findAll()

Devuelve todos los resultados:

<?php

$users = $userModel->findAll();

Esta consulta se puede modificar intercalando comandos del Generador de consultas según sea necesario antes de llamar a este método:

<?php

$users = $userModel->where('active', 1)->findAll();

Puede pasar valores de límite y compensación como el primero y el segundo parámetros, respectivamente:

<?php

$users = $userModel->findAll($limit, $offset);

first()

Devuelve la primera fila del conjunto de resultados. Es mejor utilizarlo en combinación con el generador de consultas.

<?php

$user = $userModel->where('deleted', 0)->first();

withDeleted()

Si $useSoftDeletes es verdadero, entonces los métodos find*() no devolverán ninguna fila donde deleted_at NO ES NULO. Para anular esto temporalmente, puede utilizar el método withDeleted() antes de llamar al método find*().

<?php

// Only gets non-deleted rows (deleted = 0)
$activeUsers = $userModel->findAll();

// Gets all rows
$allUsers = $userModel->withDeleted()->findAll();

onlyDeleted()

Mientras que withDeleted() devolverá filas eliminadas y no eliminadas, este método modifica los siguientes métodos find*() para devolver solo filas eliminadas temporalmente:

<?php

$deletedUsers = $userModel->onlyDeleted()->findAll();

Guardar datos 

insert()

El primer parámetro es una matriz asociativa de datos para crear una nueva fila de datos en la base de datos. Si se pasa un objeto en lugar de una matriz, intentará convertirlo en una matriz.

Las claves de la matriz deben coincidir con el nombre de las columnas en $table, mientras que los valores de la matriz son los valores que se guardarán para esa clave.

El segundo parámetro opcional es de tipo booleano y, si se establece en falso, el método devolverá un valor booleano. que indica el éxito o fracaso de la consulta.

Puede recuperar la clave principal de la última fila insertada utilizando el método getInsertID().

<?php

$data = [
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];

// Inserts data and returns inserted row's primary key
$userModel->insert($data);

// Inserts data and returns true on success and false on failure
$userModel->insert($data, false);

// Returns inserted row's primary key
$userModel->getInsertID();

allowEmptyInserts()

Nuevo en la versión 7.0.0.

Puede utilizar el método allowEmptyInserts() para insertar datos vacíos. El modelo genera una excepción cuando intenta insertar datos vacíos de forma predeterminada. Pero si llama a este método, la verificación ya no se realizará.

<?php

$userModel->allowEmptyInserts()->insert([]);

También puede cambiar esta configuración con la propiedad $allowEmptyInserts.

Puede habilitar la verificación nuevamente llamando a allowEmptyInserts(false).

update()

Actualiza un registro existente en la base de datos. El primer parámetro es $primaryKey del registro a actualizar. Se pasa una matriz asociativa de datos a este método como segundo parámetro. Las claves de la matriz deben coincidir con el nombre. de las columnas en una $table, mientras que los valores de la matriz son los valores a guardar para esa clave:

<?php

$data = [
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];

$userModel->update($id, $data);

Importante

Since v7.3.0, this method raises a DatabaseException si genera una declaración SQL sin una cláusula WHERE. En versiones anteriores, si se llama sin $primaryKey especificada y se generó una declaración SQL sin una cláusula WHERE, la consulta aún ejecutar y todos los registros de la tabla se actualizarán.

Se pueden actualizar varios registros con una sola llamada pasando una matriz de claves primarias como primer parámetro:

<?php

$data = [
    'active' => 1,
];

$userModel->update([1, 2, 3], $data);

Cuando necesite una solución más flexible, puede dejar los parámetros vacíos y funciona como el Generador de consultas. comando de actualización, con el beneficio adicional de validación, eventos, etc.:

<?php

$userModel
    ->whereIn('id', [1, 2, 3])
    ->set(['active' => 1])
    ->update();

save()

Este es un contenedor de los métodos insert() y update() que manejan la inserción o actualización del registro. automáticamente, en función de si encuentra una clave de matriz que coincida con el valor de clave principal:

<?php

// Defined as a model property
$primaryKey = 'id';

// Does an insert()
$data = [
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];

$userModel->save($data);

// Performs an update, since the primary key, 'id', is found.
$data = [
    'id'       => 3,
    'username' => 'darth',
    'email'    => 'd.vader@theempire.com',
];
$userModel->save($data);

El método save también puede simplificar mucho el trabajo con objetos de resultados de clases personalizados al reconocer un objeto no simple. objeto y tomando sus valores públicos y protegidos en una matriz, que luego se pasa al directorio apropiado método de inserción o actualización. Esto le permite trabajar con clases de Entidad de una manera muy limpia. Las clases de entidad son clases simples que representan una única instancia de un tipo de objeto, como un usuario, una publicación de blog, trabajo, etc. La clase es responsable de mantener la lógica de negocios que rodea al objeto en sí, como el formateo. elementos de cierta manera, etc. No deberían tener idea de cómo se guardan en la base de datos. En su más simples, podrían verse así:

<?php

namespace App\Entities;

class Job
{
    protected $id;
    protected $name;
    protected $description;

    public function __get($key)
    {
        if (property_exists($this, $key)) {
            return $this->{$key};
        }
    }

    public function __set($key, $value)
    {
        if (property_exists($this, $key)) {
            $this->{$key} = $value;
        }
    }
}

Un modelo muy sencillo con el que trabajar podría verse así:

<?php

namespace App\Models;

use Higgs\Model;

class JobModel extends Model
{
    protected $table         = 'jobs';
    protected $returnType    = \App\Entities\Job::class;
    protected $allowedFields = [
        'name', 'description',
    ];
}

Este modelo funciona con datos de la tabla jobs y devuelve todos los resultados como una instancia de App\Entities\Job. Cuando necesite conservar ese registro en la base de datos, deberá escribir métodos personalizados o utilizar el método save() del modelo para inspeccionar la clase, tomar las propiedades públicas y privadas y guardarlas en la base de datos:

<?php

// Retrieve a Job instance
$job = $model->find(15);

// Make some changes
$job->name = 'Foobar';

// Save the changes
$model->save($job);

Nota

If you find yourself working with Entities a lot, Higgs provides a built-in Entity class que proporciona varias funciones útiles que simplifican el desarrollo de entidades.

Eliminar datos 

delete()

Toma un valor de clave principal como primer parámetro y elimina el registro coincidente de la tabla del modelo:

<?php

$userModel->delete(12);

Si el valor $useSoftDeletes del modelo es verdadero, esto actualizará la fila para establecer deleted_at en el valor actual. fecha y hora. Puede forzar una eliminación permanente configurando el segundo parámetro como verdadero.

Se puede pasar una matriz de claves primarias como primer parámetro para eliminar varios registros a la vez:

<?php

$userModel->delete([1, 2, 3]);

Si no se pasan parámetros, actuará como el método de eliminación del Generador de consultas, lo que requerirá una llamada a dónde. previamente:

<?php

$userModel->where('id', 12)->delete();

purgeDeleted()

Limpia la tabla de la base de datos eliminando permanentemente todas las filas que tienen “deleted_at IS NOT NULL”.

<?php

$userModel->purgeDeleted();

Validación en el modelo 

Validación de datos 

Para muchas personas, validar los datos en el modelo es la forma preferida de garantizar que los datos se mantengan en un único estándar, sin duplicar código. La clase Modelo proporciona una manera de validar automáticamente todos los datos. antes de guardar en la base de datos con los métodos insert(), update() o save().

Importante

When you update data, by default, the validation in the model class only valida los campos proporcionados. Esto es para evitar errores de validación al actualizar solo algunos campos.

Pero esto significa que las reglas obligatorias* no funcionan como se esperaba al actualizar. Si desea verificar los campos obligatorios, puede cambiar el comportamiento mediante configuración. Consulte $cleanValidationRules para obtener más detalles.

Establecer reglas de validación 

El primer paso es completar la propiedad de clase $validationRules con los campos y reglas que deben se aplicado. Si tiene mensajes de error personalizados que desea utilizar, colóquelos en la matriz $validationMessages:

<?php

namespace App\Models;

use Higgs\Model;

class UserModel extends Model
{
    protected $validationRules = [
        'username'     => 'required|max_length[30]|alpha_numeric_space|min_length[3]',
        'email'        => 'required|max_length[254]|valid_email|is_unique[users.email]',
        'password'     => 'required|max_length[255]|min_length[8]',
        'pass_confirm' => 'required_with[password]|max_length[255]|matches[password]',
    ];
    protected $validationMessages = [
        'email' => [
            'is_unique' => 'Sorry. That email has already been taken. Please choose another.',
        ],
    ];
}

Si prefiere organizar sus reglas y mensajes de error dentro del archivo de configuración de Validación, puede hacerlo y simplemente establezca $validationRules con el nombre del grupo de reglas de validación que creó:

<?php

namespace App\Models;

use Higgs\Model;

class UserModel extends Model
{
    protected $validationRules = 'users';
}

La otra forma de establecer las reglas de validación de campos por funciones,

class Higgs\Model

Higgs\Model::setValidationRule($field, $fieldRules)

Parámetros:

$campo (string) –
$fieldRules (matriz) –

Esta función establecerá las reglas de validación del campo.

Ejemplo de uso:

<?php

$fieldName  = 'username';
$fieldRules = 'required|max_length[30]|alpha_numeric_space|min_length[3]';

$model->setValidationRule($fieldName, $fieldRules);

Higgs\Model::setValidationRules($validationRules)

Matriz de parámetros $reglas de validación:

Esta función establecerá las reglas de validación.

Ejemplo de uso:

<?php

$validationRules = [
    'username' => 'required|max_length[30]|alpha_numeric_space|min_length[3]',
    'email'    => [
        'rules'  => 'required|max_length[254]|valid_email|is_unique[users.email]',
        'errors' => [
            'required' => 'We really need your email.',
        ],
    ],
];
$model->setValidationRules($validationRules);

La otra forma de configurar el mensaje de validación de campos por funciones,

Higgs\Model::setValidationMessage($field, $fieldMessages)

Parámetros:

$campo (string) –
$fieldMessages (matriz) –

Esta función establecerá los mensajes de error de campo.

Ejemplo de uso:

<?php

$fieldName              = 'name';
$fieldValidationMessage = [
    'required' => 'Your name is required here',
];
$model->setValidationMessage($fieldName, $fieldValidationMessage);

Higgs\Model::setValidationMessages($fieldMessages)

Parámetros:

$fieldMessages (matriz) –

Esta función configurará los mensajes de campo.

Ejemplo de uso:

<?php

$fieldValidationMessage = [
    'name' => [
        'required'   => 'Your baby name is missing.',
        'min_length' => 'Too short, man!',
    ],
];
$model->setValidationMessages($fieldValidationMessage);

Obtener el resultado de la validación 

Ahora, cada vez que llame a los métodos insert(), update() o save(), los datos serán validados. Si falla, el modelo devolverá un valor booleano falso.

Obtener errores de validación 

Puede utilizar el método errors() para recuperar los errores de validación:

<?php

if ($model->save($data) === false) {
    return view('updateUser', ['errors' => $model->errors()]);
}

Esto devuelve una matriz con los nombres de los campos y sus errores asociados que se puede usar para mostrar todos los errores en la parte superior del formulario, o para mostrarlos individualmente:

<?php if (! empty($errors)): ?>
    <div class="alert alert-danger">
    <?php foreach ($errors as $field => $error): ?>
        <p><?= esc($error) ?></p>
    <?php endforeach ?>
    </div>
<?php endif ?>

Recuperar reglas de validación 

Puede recuperar las reglas de validación de un modelo accediendo a sus validationRules propiedad:

<?php

$rules = $model->validationRules;

También puede recuperar solo un subconjunto de esas reglas llamando al descriptor de acceso método directamente, con opciones:

<?php

$rules = $model->getValidationRules($options);

El parámetro $options es una matriz asociativa con un elemento, cuya clave es 'excepto' o 'solo', y que tiene como valorar una serie de nombres de campos de interés:

<?php

// get the rules for all but the "username" field
$rules = $model->getValidationRules(['except' => ['username']]);
// get the rules for only the "city" and "state" fields
$rules = $model->getValidationRules(['only' => ['city', 'state']]);

Marcadores de posición de validación 

El modelo proporciona un método simple para reemplazar partes de sus reglas en función de los datos que se le pasan. Este Suena bastante oscuro pero puede ser especialmente útil con la regla de validación is_unique. Los marcadores de posición son simplemente el nombre del campo (o clave de matriz) que se pasó como $data entre llaves. Será reemplazado por el valor del campo entrante coincidente. Un ejemplo debería aclarar esto:

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected $validationRules = [
        'id'    => 'max_length[19]|is_natural_no_zero',
        'email' => 'required|max_length[254]|valid_email|is_unique[users.email,id,{id}]',
    ];
}

Nota

Since v7.3.5, you must set the validation rules for the placeholder campo (id).

En este conjunto de reglas, se establece que la dirección de correo electrónico debe ser única en la base de datos, excepto en la fila que tiene una identificación que coincide con el valor del marcador de posición. Suponiendo que los datos del formulario POST tuvieran lo siguiente:

<?php

$_POST = [
    'id'    => 4,
    'email' => 'foo@example.com',
];

entonces el marcador de posición {id} se reemplazaría con el número 4, dando esta regla revisada:

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected $validationRules = [
        'id'    => 'max_length[19]|is_natural_no_zero',
        'email' => 'required|max_length[254]|valid_email|is_unique[users.email,id,4]',
    ];
}

Por lo tanto, ignorará la fila en la base de datos que tiene id=4 cuando verifique que el correo electrónico sea único.

Nota

Since v7.3.5, if the placeholder (id) value does not pass the validación, el marcador de posición no sería reemplazado.

Esto también se puede utilizar para crear reglas más dinámicas en tiempo de ejecución, siempre y cuando tenga cuidado de que cualquier dinámica Las claves pasadas no entran en conflicto con los datos de su formulario.

Protegiendo campos 

Para ayudar a protegerse contra ataques de asignación masiva, la clase Modelo requiere que enumere todos los nombres de los campos. que se puede cambiar durante las inserciones y actualizaciones en la propiedad de clase $allowedFields. Cualquier dato proporcionado Además, estos se eliminarán antes de llegar a la base de datos. Esto es excelente para garantizar que las marcas de tiempo, o las claves primarias no se cambian.

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected $allowedFields = ['name', 'email', 'address'];
}

Ocasionalmente, encontrarás ocasiones en las que necesitarás poder cambiar estos elementos. Esto ocurre a menudo durante pruebas, migraciones o semillas. En estos casos, puedes activar o desactivar la protección:

<?php

$model->protect(false)
    ->insert($data)
    ->protect(true);

Cambios en el tipo de devolución en tiempo de ejecución 

Puede especificar el formato en el que se deben devolver los datos cuando se utilizan los métodos find*() como propiedad de clase, `$tiporetorno`_. Sin embargo, es posible que en ocasiones desees recibir los datos en un formato diferente. El modelo proporciona métodos que le permiten hacer precisamente eso.

Nota

These methods only change the return type for the next find*() method call. After that, se restablece a su valor predeterminado.

asArray()

Devuelve datos del siguiente método find*() como matrices asociativas:

<?php

$users = $userModel->asArray()->where('status', 'active')->findAll();

asObject()

Devuelve datos del siguiente método find*() como objetos estándar o instancias de clase personalizadas:

<?php

// Return as standard objects
$users = $userModel->asObject()->where('status', 'active')->findAll();

// Return as custom class instances
$users = $userModel->asObject('User')->where('status', 'active')->findAll();

Procesamiento de grandes cantidades de datos 

A veces, es necesario procesar grandes cantidades de datos y se corre el riesgo de quedarse sin memoria. Para simplificar esto, puede utilizar el método chunk() para obtener fragmentos de datos más pequeños que luego pueda haz tu trabajo. El primer parámetro es el número de filas que se recuperarán en un solo fragmento. El segundo El parámetro es un cierre que se llamará para cada fila de datos.

Esto se utiliza mejor durante cronjobs, exportaciones de datos u otras tareas grandes.

<?php

$userModel->chunk(100, static function ($data) {
    // do something.
    // $data is a single row of data.
});

Trabajar con el generador de consultas 

Obteniendo el generador de consultas para la tabla del modelo 

El modelo Higgs tiene una instancia del Generador de consultas para la conexión de base de datos de ese modelo. Puede obtener acceso a la instancia compartida del Generador de consultas en cualquier momento que lo necesite:

<?php

$builder = $userModel->builder();

Este constructor ya está configurado con la $table del modelo.

Nota

Once you get the Query Builder instance, you can call methods of the Generador de consultas. Sin embargo, dado que Query Builder no es un modelo, no puede llamar a métodos del modelo.

Obtener el generador de consultas para otra tabla 

Si necesita acceso a otra tabla, puede obtener otra instancia del Generador de consultas. Pase el nombre de la tabla como parámetro, pero tenga en cuenta que esto no devolverá una instancia compartida:

<?php

$groupBuilder = $userModel->builder('groups');

Métodos combinados de generador de consultas y modelo 

También puede utilizar los métodos del Generador de consultas y los métodos CRUD del modelo en la misma llamada encadenada, lo que permite uso muy elegante:

<?php

$users = $userModel->where('status', 'active')
    ->orderBy('last_login', 'asc')
    ->findAll();

En este caso, opera en la instancia compartida del Generador de consultas que posee el modelo.

Importante

The Model does not provide a perfect interface to the Query Builder. El modelo y el generador de consultas son clases separadas con propósitos diferentes. No se debe esperar que devuelvan los mismos datos.

Si el Generador de consultas devuelve un resultado, se devuelve tal cual. En ese caso, el resultado puede ser diferente al devuelto por el método del modelo. y puede que no sea lo que se esperaba. Los eventos del modelo no se activan.

Para evitar comportamientos inesperados, no utilice métodos del Generador de consultas que devuelvan resultados. y especifique el método del modelo al final del encadenamiento de métodos.

Nota

You can also access the model’s database connection seamlessly:

<?php

$user_name = $userModel->escape($name);

Eventos modelo 

Hay varios puntos dentro de la ejecución del modelo en los que puede especificar múltiples métodos de devolución de llamada para ejecutar. Estos métodos se pueden utilizar para normalizar datos, hacer hash de contraseñas, guardar entidades relacionadas y mucho más.

La siguiente Los puntos en la ejecución del modelo pueden verse afectados, cada uno a través de una propiedad de clase:

`$antes de Insertar`_, `$después de Insertar`_
`$antes de la actualización`_, `$después de la actualización`_
`$antes de buscar`_, `$después de buscar`_
`$antes de eliminar`_, `$después de eliminar`_
`$antes de InsertarBatch`_, `$después de InsertarBatch`_
`$antes de ActualizarBatch`_, `$después de ActualizarBatch`_

Nota

$beforeInsertBatch, $afterInsertBatch, $beforeUpdateBatch and $afterUpdateBatch se puede utilizar desde la versión 7.0.0.

Definición de devoluciones de llamada 

Usted especifica las devoluciones de llamada creando primero un nuevo método de clase en su modelo para usar.

Este método de clase siempre recibirá una matriz $data como único parámetro.

El contenido exacto de la matriz $data variará entre eventos, pero siempre contener una clave llamada datos que contiene los datos primarios pasados al original método. En el caso de los métodos insert*() o update*(), eso será los pares clave/valor que se están insertando en la base de datos. Los $datos principales La matriz también contendrá los otros valores pasados al método y se detallará. en `Parámetros de evento`_.

El método de devolución de llamada debe devolver la matriz $data original para que otras devoluciones de llamada tener la información completa.

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected function hashPassword(array $data)
    {
        if (! isset($data['data']['password'])) {
            return $data;
        }

        $data['data']['password_hash'] = password_hash($data['data']['password'], PASSWORD_DEFAULT);
        unset($data['data']['password']);

        return $data;
    }
}

Especificación de devoluciones de llamada para ejecutar 

Usted especifica cuándo ejecutar las devoluciones de llamada agregando el nombre del método a la propiedad de clase apropiada ($beforeInsert, $afterUpdate, etc). Se pueden agregar varias devoluciones de llamada a un solo evento y se procesarán una tras otra. Puede use la misma devolución de llamada en múltiples eventos:

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected $beforeInsert = ['hashPassword'];
    protected $beforeUpdate = ['hashPassword'];
}

Además, cada modelo puede permitir (predeterminado) o denegar devoluciones de llamada en toda la clase configurando su propiedad $allowCallbacks:

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected $allowCallbacks = false;
}

También puedes cambiar esta configuración temporalmente para una llamada de modelo único usando el método allowCallbacks():

<?php

$model->allowCallbacks(false)->find(1); // No callbacks triggered
$model->find(1); // Callbacks subject to original property value

Parámetros del evento 

Dado que los datos exactos pasados a cada devolución de llamada varían un poco, aquí están los detalles sobre lo que hay en el parámetro $data pasado a cada evento: =================== ============================================================================================================= Evento $datos contenidos =================== ============================================================================================================= beforeInsert datos = los pares clave/valor que se están insertando. Si un objeto o clase de entidad se pasa al

Método insert(), primero se convierte en una matriz.

afterInsert id = la clave principal de la nueva fila, o 0 en caso de error.

datos = los pares clave/valor que se insertan. resultado = los resultados del método insert() utilizado a través del Generador de consultas.

beforeUpdate id = la matriz de claves principales de las filas que se actualizan.

datos = los pares clave/valor que se están actualizando. Si un objeto o clase de entidad se pasa al Método update(), primero se convierte en una matriz.

afterUpdate id = la matriz de claves principales de las filas que se actualizan.

datos = los pares clave/valor que se actualizan. resultado = los resultados del método update() utilizado a través del Generador de consultas.

beforeFind El nombre del método que realiza la llamada, si se solicitó un singleton y estos campos adicionales:

first() Sin campos adicionales
find() id = la clave principal de la fila que se busca.
findAll() límite = el número de filas a buscar.

desplazamiento = el número de filas que se omitirán durante la búsqueda.

afterFind Igual que beforeFind pero incluye las filas de datos resultantes, o nulo si no se encuentra ningún resultado. beforeDelete id = clave principal de la fila que se pasa al método delete().

purgar = booleano si las filas de eliminación temporal deben eliminarse definitivamente.

afterDelete id = clave principal de la fila que se pasa al método delete().: purgar = booleano si las filas de eliminación temporal deben eliminarse definitivamente. resultado = el resultado de la llamada delete() en el Generador de consultas. datos = sin usar.
beforeInsertBatch data = matriz asociativa de valores que se están insertando. Si un objeto o clase de entidad se pasa al: Método insertBatch(), primero se convierte en una matriz.
afterInsertBatch data = la matriz asociativa de valores que se insertan.: resultado = los resultados del método insertbatch() utilizado a través del Generador de consultas.
beforeUpdateBatch data = matriz asociativa de valores que se están actualizando. Si un objeto o clase de entidad se pasa al: Método updateBatch(), primero se convierte en una matriz.
afterUpdateBatch datos = los pares clave/valor que se actualizan.: resultado = los resultados del método updateBatch() utilizado a través del Generador de consultas.

Los métodos beforeFind y afterFind pueden devolver un conjunto de datos modificado para anular la respuesta normal. del modelo. Para afterFind, cualquier cambio realizado en data en la matriz de retorno se devolverá automáticamente al contexto de llamada. Para que beforeFind intercepte el flujo de trabajo de búsqueda, también debe devolver un booleano, datosderetorno:

<?php

namespace App\Models;

use Higgs\Model;

class MyModel extends Model
{
    protected $beforeFind = ['checkCache'];

    // ...

    protected function checkCache(array $data)
    {
        // Check if the requested item is already in our cache
        if (isset($data['id']) && $item = $this->getCachedItem($data['id'])) {
            $data['data']       = $item;
            $data['returnData'] = true;

            return $data;
        }

        // ...
    }
}

Creación manual de modelos 

No es necesario ampliar ninguna clase especial para crear un modelo para su aplicación. Todo lo que necesitas es conseguir un instancia de la conexión de la base de datos y listo. Esto le permite evitar las características de Higgs. Model le ofrece soluciones listas para usar y crea una experiencia totalmente personalizada.

<?php

namespace App\Models;

use Higgs\Database\ConnectionInterface;

class UserModel
{
    protected $db;

    public function __construct(ConnectionInterface $db)
    {
        $this->db = $db;
    }
}