strong/bitrix-models

维护者

详细信息

github.com/Strong/bitrix-models

主页

源代码

安装: 44

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 0

分支: 37

0.9.3 2023-04-15 20:18 UTC

Requires

Requires (Dev)

Suggests

MIT 68e61c8a2203ba3e102f70bddaf80d5534cf10ee

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

modelsbitrix

This package is auto-updated.

Last update: 2024-09-15 23:37:53 UTC

README

Latest Stable Version Total Downloads

Bitrix模型

简介

本包引入了Model Layer到Bitrix中。该层逻辑上分为两部分：

  1. Bitrix实体模型（以下简称“Bitrix模型”），通过Bitrix的API（如CIBlockElement等）工作，并在其之上构建。从外部来看，这个构建类似于Eloquent。
  2. 适用于任意表的模型，通过illuminate/database和Eloquent实现。

安装

  1. composer require strong/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) 和 ->getByEmail($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() 不同，它不会将数据转换为 html 安全格式，也不会将 DETAIL_PAGE_URL、SECTION_PAGE_URL 转换为实际的元素和分类的 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() 在幕后，缓存是通过 Bitrix d7 的标准机制实现的。缓存键取决于模型和所有查询参数。

访问器

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

方法命名规则 - $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 的常规实体一样处理 D7Model，也可以处理高负载块。

高负载块示例

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使用PDO作为PHP扩展来访问mysql，而不是mysql/mysqli。这意味着

  1. 需要安装和配置PDO
  2. 每次请求都会创建两个数据库连接。

备注：问题：为什么在一个包中有Eloquent，如果已经有了D7Model？哪个更好？回答：选择取决于项目条件和个人偏好。Eloquent比Bitrix和D7Model中的任何功能都更方便、功能更强大。例如，它支持通过中间表建立模型之间的完整关系等。另一方面，这是一个较大的外部依赖，有自己的要求

缺点

安装

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

<?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-块 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 模型之间的关系。

高负载块和 Eloquent 模型的多属性

高负载块的多属性实现得有些巧妙。数据存储在两个地方

  1. 直接在高负载块表中以序列化的形式。
  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 有所谓的 模型事件，这允许在模型的某个工作时刻插入。整体上与 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']);

分页导航

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'的字段，根据这个字段进行过滤非常常见。在Hayloaddblock和自定义表中默认没有这样的字段，但此包提供了一个trait，可以帮助创建类似的功能。它是如何工作的

  1. 在表/Hayloaddblock中添加一个UF_DEACTIVATED_AT类型的datetime字段。

  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()。