ge1i0n/bitrix-models

维护者

详细信息

github.com/Ge1i0N/bitrix-models

主页

源代码

安装: 496

依赖者: 0

建议者: 0

安全: 0

星标: 12

关注者: 1

分支: 37

0.10.0 2023-10-09 14:58 UTC

Requires

Requires (Dev)

Suggests

MIT e63c4b20ee64f3bd97c6fa72c7f010dcfd68ae51

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

modelsbitrix

This package is auto-updated.

Last update: 2024-09-09 17:03:37 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 ge1i0n/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

默认情况下，在模型内部，用于迭代从数据库获取的元素/部分/用户时使用高效的方法 ->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();

这些数据范围已经存在于包中，可以使用它们。

停止操作

有时需要停止从数据库中查询 query scope。为此，只需返回 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。与旧的GetList等不同，它使用D7作为后端。通过它可以操作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 扩展 PDO 来访问 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 操作高负荷模块

假设我们为品牌创建了高负荷模块 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 有所谓的 模型事件 / 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']);

分页导航

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. 在表/HighloadBlock 中添加字段 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()。