arrilot/bitrix-models

该软件包已被废弃且不再维护。未建议替代软件包。

维护者

详细信息

github.com/arrilot/bitrix-models

主页

源代码

问题

安装: 16,299

依赖者: 2

建议者: 0

安全: 0

星标: 118

关注者: 21

分支: 37

公开问题: 7

0.8.0 2020-06-19 20:09 UTC

Requires

Requires (Dev)

Suggests

MIT 4582b0ca0f2dfc7f2eadb5033a0c7ede90fc59d8

  • Nekrasov Ilya <nekrasov.ilya90.woop@gmail.com>

modelsbitrix

This package is auto-updated.

Last update: 2023-01-17 12:28:50 UTC

README

Latest Stable Version Total Downloads Build Status Scrutinizer Quality Score

该软件包不再积极支持

原因是我们不再在项目中使用Bitrix。如果您对这个项目感兴趣并想参与维护，请将其分叉并在此存储库中创建一个Issue，以便我们在此处放置分叉的链接。

分叉

Bitrix models

介绍

该软件包将Model Layer引入Bitrix。此层逻辑上由两部分组成

  1. 为Bitrix实体创建的模型（以下将它们称为“Bitrix模型”），在Bitrix API内部运行（例如CIBlockElement等），并作为其扩展。从外部看，这个扩展类似于Eloquent。
  2. 为任意表格创建的模型，通过illuminate/database和特别地通过Eloquent进行。

安装

  1. composer require arrilot/bitrix-models
  2. 在init.php中注册软件包 - Arrilot\BitrixModels\ServiceProvider::register();

使用Bitrix模型

以下模型可用于继承

Arrilot\BitrixModels\Models\ElementModel
Arrilot\BitrixModels\Models\SectionModel
Arrilot\BitrixModels\Models\UserModel
Arrilot\BitrixModels\Models\D7Model

以下示例将使用信息块元素的模型（ElementModel）。对于其他实体，API几乎相同。

ElementModel完全支持第二版信息块（存储属性在单独的表中）。对于第一版，由于CIBlockElement::GetList()的工作方式，某些方面可能无法正确工作。最大问题是：如果信息块中存在多个属性，则limit()、take()和first()请求将执行不正确，并且获取到的元素比所需少，并且没有完整的多个属性集合。如果您确实打算使用ElementModel与第一版信息块一起使用，请务必在模型内部设置const IBLOCK_VERSION = 1;。

创建一个商品信息块的模型。

<?php

use Arrilot\BitrixModels\Models\ElementModel;

class Product extends ElementModel
{
    /**
     * Corresponding iblock id.
     *
     * @return int
     */
    const IBLOCK_ID = 1;
}

要使用模型，只需在常数中设置信息块的ID。对于用户来说，这也不需要。

如果您不想依赖于信息块的ID，可以在模型中重写public static iblockId()方法并从中获取ID，例如按代码。这提供了更大的灵活性，但您可能需要执行额外的数据库查询。

接下来，我们将以静态和动态方式使用我们的Product类。

添加产品

// $fields - массив, аналогичный передаваемому в CIblockElement::Add(), но IBLOCK_ID в нём можно не указывать.
$product = Product::create($fields);

注意：如果后续将字段$product用作某种用途，则建议立即通过新的数据库查询更新对象。这是由于CIblockElement::Add()和CIblockElement::GetList()中字段格式不匹配100%造成的。操作如下

$product = Product::create($fields)
$product->refresh();

更新

// вариант 1
$product['NAME'] = 'Новое имя продукта';
$product->save();

// вариант 2
$product->update(['NAME' => 'Новое имя продукта']);

模型实例化无需查询数据库。

对于一些操作，不需要从数据库获取信息，只需对象ID即可。在这种情况下，只需将ID传递给构造函数来实例化模型对象。

$product = new Product($id);

//теперь есть возможно работать с моделью, допустим
$product->deactivate();

从数据库获取对象字段

$product = new Product($id);

// метод `load` обращается к базе, только если информация еще не была получена.
$product->load();

// Если мы хотим принудительно обновить информацию из базы даже если она уже была получена ранее
$product->refresh();

// После любого из этих методов, мы можем работать с полученными полями (`echo $product['CODE'];`)

//Для текущего пользователья есть отдельный хэлпер
$user = User::current();
// В итоге мы получаем инстанс User с заполненными полями. 
// Сколько бы раз мы не вызывали `User::current()` в рамках работы скрипта, запрос в базу происходит только один раз - первый.
// `User::freshCurrent()` - то же самое, но получает данные из базы каждый раз.

所述方法在模型类实例内部保存数据库中的数据。模型对象实现ArrayAccess接口，因此可以像数组一样处理它们。

$product->load();
if ($product['CODE'] === 'test') {
    $product->deactivate();
}

模型转换为数组/json

$array = $product->toArray();
$json = $product->toJson();

默认情况下，所有模型字段都可用于数组，但这并不总是希望的。模型有特殊的属性 protected $visible = []; 和 protected $hidden = [];，可以用来定义要转换为数组/json的字段的白名单/黑名单。

从数据库获取信息

使用模型进行操作的最常见场景是从数据库获取元素/列表。用于构建查询的是“Fluent API”，它内部使用标准的Bitrix API。

开始构建查询使用静态方法 ::query()。该方法返回查询构建器对象（ElementQuery、SectionQuery 或 UserQuery），通过它构建查询链。

简单示例

$products = Product::query()->select('ID')->getList();

实际上，此示例主要用于理解，有更方便的视图，它使用 __callStatic 将控制权传递给查询对象。

$products = Product::select('ID')->getList();

任何查询链必须以以下方法之一结束

  1. ->getList() - 获取对象集合（见 https://laravel.net.cn/docs/master/collections）。默认情况下，每个元素的键是其ID。
  2. ->getById($id) - 根据ID获取对象。
  3. ->first() - 获取满足查询参数的一个（第一个）对象。
  4. ->count() - 获取对象数量。
  5. ->paginate() 或 ->simplePaginate() - 获取分页列表及其元数据（见 https://laravel.net.cn/docs/master/pagination）
  6. 用于单个实体的方法：->getByLogin($login) 和 ->getEmail($email) - 获取具有指定登录/email的第一个用户。 ->getByCode($code) 和 ->getByExternalId($id) - 获取具有给定CODE/EXTERNAL_ID的第一个元素或分区。

查询管理

  1. ->sort($array) - 类似于 $arSort（CIBlockElement::GetList 的第一个参数）

示例

->sort(['NAME' => 'ASC', 'ID' => 'DESC'])

->sort('NAME', 'DESC') // = ->sort(['NAME' => 'DESC'])

->sort('NAME') // = ->sort(['NAME' => 'ASC'])

  1. ->filter($array) - 类似于 $arFilter
  2. ->navigation($array)
  3. ->select(...) - 类似于 $arSelect

示例

->select(['ID', 'NAME'])

->select('ID', 'NAME')

select() 支持两个额外的值 - 'FIELDS'（选择所有字段），'PROPS'（选择所有属性）。对于用户还可以指定 'GROUPS'（将用户组添加到选择中）。默认情况下，对于 ElementModel - ['FIELDS', 'PROPS']

  1. ->limit($int)、->take($int)、->page($int)、->forPage($page, $perPage) - 用于导航

Fetch и GetNext

默认情况下，在模型中迭代从数据库获取的元素/部分/用户时，使用高效的 ->Fetch() 方法。与 ->GetNext() 不同，它不会将数据转换为HTML安全格式，也不会将 DETAIL_PAGE_URL、SECTION_PAGE_URL 转换为元素和类别的实际链接。如果在查询结果中需要这些转换，则可以切换到该方法。

  1. 可以通过给模型设置属性来直接切换整个模型。

        public static $fetchUsing = 'GetNext';

    // полная форма, если нужно менять параметры.
    public static $fetchUsing = [
        'method' => 'GetNext',
        'params' => [true, true],
    ];

  2. 也可以仅针对单个查询进行切换。

         Products::query()->filter(['ACTIVE' => 'Y'])->fetchUsing('GetNext')->getList()`
     // вместо строки `'GetNext'` можно как и в первом случае использовать массив.

一些额外的注意事项

  1. 为了限制选择，增加了别名 limit($value)（对应 nPageSize）和 page($num)（对应 iNumPage）。
  2. 在某些地方，API 比 Bitrix 本身更友好。例如，在按用户过滤时，不一定要使用 'GROUP_IDS'。在传递 'GROUP_ID'（Bitrix 需要的键，例如在创建用户时）或 'GROUPS' 时，结果将是相同的。
  3. 在创建或更新信息块元素和部分时，Bitrix 会重建搜索索引，并允许在调用 Add/Update 时跳过此重建以提高性能。在模型中，您可以通过直接在模型类中设置 protected static $updateSearch = false; 或在添加/更新之前调用单独的静态方法 Product::setUpdateSearch(false) 来达到相同的效果。
  4. 对于 CIBlockElement::Add/Update，也可以以类似的方式管理标志 $bWorkFlow 和 $bResizePictures。

查询作用域

可以通过向模型添加 "查询作用域" 来扩展查询构建器。为此，需要创建一个以 scope 开头的方法。

示例 "查询作用域" 已在包中存在。

    /**
     * Scope to get only active items.
     *
     * @param BaseQuery $query
     *
     * @return BaseQuery
     */
    public function scopeActive($query)
    {
        $query->filter['ACTIVE'] = 'Y';
    
        return $query;
    }

...

$products = Product::filter(['SECTION_ID' => $secId])
                    ->active()
                    ->getList();

在 "查询作用域" 中也可以传递额外的参数。

    /**
     * @param ElementQuery $query
     * @param string|array $category
     *
     * @return ElementQuery
     */
    public function scopeFromSectionWithCode($query, $category)
    {
        $query->filter['SECTION_CODE'] = $category;

        return $query;
    }

...
$users = Product::fromSectionWithCode('sale')->getList();

这些作用域已在包中存在，可以使用它们。

停止操作

有时需要停止从数据库中提取查询作用域。为此，只需返回 false 即可。示例

    public function scopeFromCategory($query, $category)
    {
        if (!$category) {
            return false;
        }
        
        $query->filter['SECTION_CODE'] = $category;

        return $query;
    }
...

结果将不会对数据库进行查询 - getList() 将返回空集合，getById() 将返回 false，而 count() 将返回 0。

也可以通过调用方法 ->stopQuery() 来达到相同的效果。

查询缓存

对于所有上述 Bitrix 模型，都有简单的内置缓存机制。只需在调用链中添加 ->cache($minutes)-> 即可，然后从数据库的选择结果将被缓存指定的时间。例如：$products = Products::query()->cache(30)->filter(['ACTIVE' => 'Y'])->getList()。在幕后，缓存使用 d7 Bitrix 的标准机制。缓存键取决于模型和所有查询参数。

访问器

有时需要在从数据库提取数据到模型获取数据之间修改数据。为此，使用访问器。同样，为了添加访问器，需要在相应的模型中添加方法。

方法命名规则为 $methodName = "get".camelCase($field)."Attribute"。示例

    public function getXmlIdAttribute($value)
    {
        return (int) $value;  
    }
    
    // теперь в $product['XML_ID'] всегда будет целочисленное значение

应谨慎使用此方法，因为原始值将变得不可用。

也可以为不存在的（虚拟）字段创建访问器，例如

    public function getFullNameAttribute()
    {
        return $this['NAME']." ".$this['LAST_NAME'];
    }
    
    ...
    
    echo $user['NAME']; // John
    echo $user['LAST_NAME']; // Doe
    echo $user['FULL_NAME']; // John Doe

为了使这些虚拟访问器在 toArray() 和 toJson() 中显示，必须明确在模型字段 $appends 中指定它们。

    protected $appends = ['FULL_NAME'];

语言访问器

对于多语言网站，通常的做法是为每种语言创建一个属性，例如，UF_TITLE_RU，UF_TITLE_BY。在这种情况下，可以为每个这样的字段创建一个访问器。

// используем далее $section['UF_TITLE'];
public function getUfTitleAttribute()
{
    return $this['UF_TITLE_' . strtoupper(LANGUAGE_ID)];
}

// используем далее $element['PROPERTY_TITLE'];
public function getPropertyTitleAttribute()
{
    return $this['PROPERTY_TITLE_' . strtoupper(LANGUAGE_ID) . '_VALUE'];
}

由于这些访问器类型相同并且具有污染模型的不愉快特性，因此可以为他们使用特殊的简短语法。

class Product extends ElementModel
{
    protected $languageAccessors = [
        'PROPERTY_TITLE',
        'PROPERTY_FOO'
    ];
}

模型事件（Model Events）

事件允许在模型的各个生命周期点插入并执行任意代码。例如，在创建元素时自动设置符号代码。模型事件不使用Bitrix的事件模型（无论是旧内核还是D7），仅涉及模型内部发生的事情。使用Bitrix事件覆盖了更多用例。

事件处理器通过在模型类中重定义相应的方法来设置。

class News extends ElementModel
{
    /**
     * Hook into before item create or update.
     *
     * @return mixed
     */
    protected function onBeforeSave()
    {
        $this['CODE'] = CUtil::translit($this['NAME'], "ru");
    }

    /**
     * Hook into after item create or update.
     *
     * @param bool $result
     *
     * @return void
     */
    protected function onAfterSave($result)
    {
        //
    }
}

其他事件处理器的签名与上面提供的一致。

可用事件列表

  1. onBeforeCreate - 在添加记录之前
  2. onAfterCreate(bool $result) - 在添加记录之后
  3. onBeforeUpdate - 在更新记录之前
  4. onAfterUpdate(bool $result) - 在更新记录之后
  5. onBeforeSave - 在添加或更新记录之前
  6. onAfterSave(bool $result) - 在添加或更新记录之后
  7. onBeforeDelete - 在删除记录之前
  8. onAfterDelete(bool $result) - 在删除记录之后

如果从onBefore...()事件处理器中返回return false;，则后续操作将被取消。在处理器中可以通过当前模型对象属性获取更多信息。例如，在onBefore...()处理器中，所有字段都可通过$this->fields访问。在所有onAfter...()中，通过$this->eventErrors获取错误数组；在onBeforeUpdate()和onBeforeSave()中，通过$this->fieldsSelectedForSave获取数组，其中包含我们打算更新的字段键。

D7模型

与之前的模型相比，D7Model有一些特别之处。它使用D7作为后端而不是旧的GetList等，因此可以用来操作D7的普通实体以及高负载块。

高负载块的示例

class Subscriber extends D7Model
{
    public static function tableClass()
    {
        $hlBlock = HighloadBlockTable::getRowById(1);
    
        return HighloadBlockTable::compileEntity($hlBlock)->getDataClass();
    }
}

获取高负载块类的逻辑可以是任意的，但重要的是不要忘记编译它，否则它将无法工作。最方便的方法是使用辅助包https://github.com/arrilot/bitrix-iblock-helper/。有了它，我们可以得到以下内容

class Subscriber extends D7Model
{
    public static function tableClass()
    {
        return highloadblock_class('app_subscribers');
    }
}

如果我们不是与高负载块一起工作，而是与完整的D7 ORM实体一起工作，那么只需在这个方法中返回该实体的完整类名即可。D7Model的调用链和命名方法与之前的模型相同。传递给这些方法的任何内容都将传递到D7中。

获取所有名为John的订阅者并缓存5分钟的示例

$subscribers = Subscriber::query()->cache(5)->filter(['=NAME'=>'John])->getList();

完整的方法列表如下

/**
 * static int count()
 *
 * D7Query methods
 * @method static D7Query runtime(array|\Bitrix\Main\Entity\ExpressionField $fields)
 * @method static D7Query enableDataDoubling()
 * @method static D7Query disableDataDoubling()
 * @method static D7Query cacheJoins(bool $value)
 *
 * BaseQuery methods
 * @method static Collection getList()
 * @method static D7Model first()
 * @method static D7Model getById(int $id)
 * @method static D7Query sort(string|array $by, string $order='ASC')
 * @method static D7Query order(string|array $by, string $order='ASC') // same as sort()
 * @method static D7Query filter(array $filter)
 * @method static D7Query addFilter(array $filters)
 * @method static D7Query resetFilter()
 * @method static D7Query navigation(array $filter)
 * @method static D7Query select($value)
 * @method static D7Query keyBy(string $value)
 * @method static D7Query limit(int $value)
 * @method static D7Query offset(int $value)
 * @method static D7Query page(int $num)
 * @method static D7Query take(int $value) // same as limit()
 * @method static D7Query forPage(int $page, int $perPage=15)
 * @method static \Illuminate\Pagination\LengthAwarePaginator paginate(int $perPage = 15, string $pageName = 'page')
 * @method static \Illuminate\Pagination\Paginator simplePaginate(int $perPage = 15, string $pageName = 'page')
 * @method static D7Query stopQuery()
 * @method static D7Query cache(float|int $minutes)
 */

有关详细信息，请参阅vendor/arrilot/bitrix-models/src/Models/D7Model.php和vendor/arrilot/bitrix-models/src/Queries/D7Query.php

模型间关系（Relations）

除了处理单独的Bitrix模型之外，还可以在模型之间建立关系，这使得它们可以通过主要数据对象轻松获取。例如，商品与商品问题相关联。通过声明这种关系，您可以使用表达式$product->questions获取模型问题对象，它以Question类（BaseBitrixModel的子类）的对象集合的形式返回有关问题的信息。

声明关系

/**
 * Class Product
 *
 * @property Brand $brand
 * @property ProductQuestion $questions
 * @property Storage $storages
 */
class Product extends ElementModel
{
    ...
    
    /**
     * ID Brand записан в текущую модель в свойтво PROPERTY_BRAND_VALUE (не множественное)
     * (у товара может быть только один бренд, но у бренда много товаров)
     */
    public function brand()
    {
        return $this->hasOne(Brand::class, 'ID', 'PROPERTY_BRAND_VALUE');
    }
    
    /**
     * У ProductQuestion в свойтве PROPERTY_PRODUCT_VALUE записан ID текущей модели
     * (у товара может быть много вопросов, но вопрос относится только к одному товару)
     *
     * Но это будет так же работать, если PROPERTY_PRODUCT_VALUE будет множественным
     */
    public function questions()
    {
        return $this->hasMany(ProductQuestion::class, 'PROPERTY_PRODUCT_VALUE', 'ID');
    }
    
    /**
     * ID Storage записан в текущую модель в свойтво PROPERTY_STORAGE_VALUE (множественное)
     * (у товара может быть много складов, на складе может быть много товаров)
     */
    public function storages()
    {
        return $this->hasMany(Storage::class, 'ID', 'PROPERTY_STORAGE_VALUE');

    }
}

关系名称对大小写敏感。

在声明关联时，您需要指定以下信息：

  • 关联的次数：通过调用 hasMany() 方法或 hasOne() 方法来指定。
  • 关联类的名称：作为 hasMany() / hasOne() 方法的第一个参数指定。
  • 两种数据类型之间的关联：第二个参数是外部模型中的字段，第三个参数是内部模型中的字段（默认为 ID）。
  • 与其它 ORM 不同，多对多关系不使用中间（pivot）表。而是使用 Bitrix 的多属性。

访问关联数据

声明关联后，您可以通过关联名称访问关联数据。访问是通过对象的属性来完成的。属性名称 = 关联方法的名称（但去掉方法括号）

$product = Product::getById(1);

// В этот момент используются магические методы и выполняются sql запросы в БД за данными.
$product->brand; // Объект класса Brand
$product->questions; // Collection объектов класса ProductQuestion

// Запросы в базу выполняются лишь один раз. При повторном обращении к переменной возвращаются данные получененные при первом запросе. 
$product->brand;
$product->questions;

延迟和贪婪加载

上述示例中使用了延迟加载（数据在第一次访问时加载）。当处理数据数组时，会收到循环中的查询请求，出现 n + 1 问题。

$products = Product::getList();

foreach($products as $product) {
    // Выполняется запрос
    $product->brand;
}

为了避免这个问题，需要使用贪婪加载

// Выполняется один дополнительный запрос который получит все бренды для всех полученных продуктов.
$products = Product::query()->with('brand')->getList();

foreach($products as $product) {
    // Запрос не выполняется
    $product->brand;
}
  • with 方法可以多次调用。
  • 作为参数接受一个字符串 - 关联名称或多个字符串/字符串数组 ->with('brand', 'questions')/->with(['brand', 'questions'])。
  • 您还可以指定嵌套关联 ->with('questions.answers')（在这种情况下，将同时加载问题和每个问题的答案列表。总共 3 个查询 - 对商品、问题和答案的查询）。
  • 为了修改查询，可以使用回调。例如，为了只加载活动问题，并为它们加载答案
->with([
    'questions' => function ($query) {
        $query->filter(['ACTIVE' => 'Y'])
    },
    'questions.answers'
])

使用 Eloquent 模型

包的第二个部分是 ORM Eloquent 的集成，用于 Bitrix 中的用户表，即手动创建的，而不是随系统提供的。实际上，这是直接对数据库查询、D7 ORM 和此包中的 D7Model 的替代品。

通过 Eloquent 可以不仅与用户表工作，还可以与 Highload-块工作，这非常方便。在这种情况下，我们与 Highload-块的表工作，而不通过任何 Bitrix API。

需要注意的是，与 Bitrix 不同，Eloquent 使用 PHP 扩展来访问 mysql，不是 mysql/mysqli，而是 PDO。这意味着

  1. 需要确保 PDO 已安装和配置
  2. 在请求时将创建两个数据库连接。

注意事项：问题：为什么在一个包中包含 Eloquent，如果已经有 D7Model？哪个更好？回答：选择取决于项目条件和个人偏好。Eloquent 比Bitrix 和 D7Model 中的所有功能都更方便和功能丰富。例如，那里有通过中间表之间的完整模型关系等。另一方面，这是一个大的外部依赖，有自己的要求

缺点

安装

首先需要安装另一个依赖项 - composer require illuminate/database 然后，在 init.php 中添加一行 - Arrilot\BitrixModels\ServiceProvider::registerEloquent(); 现在，您已经可以创建 Eloquent 模型，并从 EloquentModel 继承

<?php

use Arrilot\BitrixModels\Models\EloquentModel;

class Product extends EloquentModel
{
    protected $table = 'app_products';
}

如果表名为 products（类的复数形式名称），则可以省略 protected $table = 'products'; - 这是 Eloquent 的标准行为。非标准

  1. 主键是 ID，而不是 id
  2. 用于创建和更新记录的字段称为 UF_CREATED_AT 和 UF_UPDATED_AT，而不是 created_at 和 updated_at

如果您决定不在表中添加字段 UF_CREATED_AT 和 UF_UPDATED_AT，则需要在模型中设置 public $timestamps = false;

通过 Eloquent 操作 Highload 块

假设我们已经为品牌创建了一个 Highload 块 Brands，为其设置了表 brands 并添加了属性 UF_NAME。那么为其创建的模型类将如下所示

<?php

use Arrilot\BitrixModels\Models\EloquentModel;

class Brand extends EloquentModel
{
    public $timestamps = false;
}

要向其中添加新记录，只需以下代码

$brand = new Brand();
$brand['UF_NAME'] = 'Nike';
$brand->save();

// либо даже такого если настроены $fillable поля.
$brand = Brand::create(['UF_NAME' => 'Nike']);

要完整地使用 Eloquent 模型，了解该 ORM 的官方文档非常重要 (链接再次提供)

最后，请注意，尽管 Bitrix 模型和 Eloquent 模型的 API 非常相似（这在很大程度上是因为 Bitrix 模型是在 Eloquent 的影响下开发的），但它们确实是不同的事物，并且它们在内部是完全独立的。例如，不能将 Eloquent 模型与 Bitrix 模型建立关联。

Highload 块和 Eloquent 模型的多重属性

在 Highload 块中实现多重属性的方式有些巧妙。数据存储在两个地方

  1. 直接在 Highload 块的表中以序列化形式存储。
  2. 在用于该属性的多余表中。幸运的是，该包可以相当不错地解决这个问题。添加多重属性时，只需将模型的此属性代码添加到模型的 $multipleHighloadBlockFields 字段数组中即可。例如 public $multipleHighloadBlockFields = ['UF_SOME_MULTIPLE_FIELD']; 之后
  3. $model['UF_SOME_MULTIPLE_FIELD'] 将返回反序列化后的数组
  4. 添加/更新字段值时，也只需将数组放入 $model['UF_SOME_MULTIPLE_FIELD'] 中，无需手动序列化。
  5. 添加/更新字段值时，更改将自动应用于辅助表。无需手动更改。要使最后一点生效，需要安装额外的依赖项 - composer require illuminate/events。如果没有这个依赖项，辅助表将不会更新。有关它的更多详细信息将在下一段中说明。

Eloquent 模型中的事件

Eloquent 有所谓的 模型事件 / Model events，它允许在模型的某个工作阶段插入。总体上类似于 Bitrix 的事件 OnBeforeIblockElementUpdate 等。如果需要它们，则需要安装 illuminate/database 依赖项，并安装 illuminate/events

composer require illuminate/events

查询构建器

当我们连接 Eloquent 时，我们免费获得 Laravel 的 Query Builder https://laravel.net.cn/docs/master/queries，这对于需要直接与数据库交互，而不通过模型层抽象非常有用。它比 $DB->Query() 和其他方式更方便，也更安全。

例如，通过全局可访问的类 DB 来处理构建器。例如，将品牌元素添加到 HL 块的代码如下所示

DB::table('brands')->insert(['UF_NAME' => 'Nike']);

分页导航 (pagination)

Bitrix 模型和 Eloquent 模型都支持 ->paginate() 和 ->simplePaginate()（见 https://laravel.net.cn/docs/master/pagination）。为了然后通过 ->links() 显示分页导航，需要

  1. 安装 https://github.com/arrilot/bitrix-blade/
  2. 将默认视图从 https://github.com/laravel/framework/tree/master/src/Illuminate/Pagination/resources/views 复制到 local/views/pagination

之后可以修改这些视图或创建新的视图。

连接到多个数据库，详细的连接设置。

默认情况下，连接到数据库使用的是与Bitrix一起工作的标准配置。例如，它可能看起来像这样（文件 .settings.php）。

'connections' => [
    'value' => [
        'default' => [
            'className' => '\\Bitrix\\Main\\DB\\MysqliConnection',
            'host' => 'localhost',
            'database' => 'db',
            'login' => 'login',
            'password' => 'password',
            'options' => 2,
        ],
    ],
    'readonly' => true,
]

为了能够使用Eloquent的所有功能，需要向.settings.php文件添加包含连接描述的数组bitrix-models.illuminate-database。

[
    ...
    'bitrix-models.illuminate-database' => [
        'value' => [
                'default' => 'mysql',
                'connections' => [
                    'mysql' => [
                        'driver' => 'mysql',
                        'url' => getenv('DB_MYSQL_URL'),
                        'host' => getenv('DB_MYSQL_HOST'),
                        'port' => getenv('DB_MYSQL_PORT'),
                        'database' => getenv('DB_MYSQL_DATABASE'),
                        'username' => getenv('DB_MYSQL_USERNAME'),
                        'password' => getenv('DB_MYSQL_PASSWORD'),
                        'unix_socket' => getenv('DB_MYSQL_SOCKET'),
                        'charset' => 'utf8',
                        'collation' => 'utf8_unicode_ci',
                        'prefix' => '',
                        'prefix_indexes' => true,
                        'strict' => false,
                        'engine' => null,
                        'options' => [],
                    ],
                    'mysql_2' => [
                        ...
                    ],
                ],
            ],
        'readonly' => true,
    ],
]

注意！如果指定了bitrix-models.illuminate-database数组，那么Eloquent的数据库连接设置将仅从该数组中获取，而标准设置将被忽略。

更多连接设置示例（connections）：https://github.com/laravel/laravel/blob/5.7/config/database.php

D7Model/EloquentModel中的元素活动

在Bitrix的信息块中有一个ACTIVE = 'Y'/'N'字段，根据这个字段进行过滤是经常使用的。在HighloadBlock和自定义表中默认没有这样的字段，但这个包提供了一个帮助创建类似功能的trait。它是如何工作的

  1. 将字段UF_DEACTIVATED_AT类型datetime添加到表/HighloadBlock。

  2. 向D7Model/EloquentModel添加trait use \Arrilot\BitrixModels\Models\Traits\DeactivationTrait;

  3. 现在模型中可用以下方法

    3.1. $model->deactivate() 和 $model->activate() - 在数据库中禁用或激活元素。

    3.2. $model->markForDeactivation() 和 $model->markForActivation() - 同样，但只更改php变量，不执行 ->save(). 如果需要激活时对表格进行其他更改，而不想执行额外的数据库请求，这很有用。

    3.3. 范围 ->active() 和 ->deactivated()。例如 SomeD7Model::query()->active()->getList()。