README

用于从ФИАС安装数据的symfony扩展包。

使用FIAS时，会使用xml文件，这些文件通过FIAS信息服务提供的链接来获取。

安装

该扩展包通过composer安装，遵循标准结构，因此在symfony >=4.2的情况下将自动安装。

使用composer安装包

composer require liquetsoft/fias-symfony

由于FIAS数据量巨大，Doctrine实体不是立即在项目中注册的。每个实体都提供了一个MappedSuperclass，可以用来只为项目需要的实体获取字段更新。此外，这还可以允许修改或扩展表结构。例如，为了添加地址列表
```
<?php
// src/Entity/AddressObject.php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\AddrObj as LiquetsoftAddrObj;

/**
 * Адреса.
 *
 * @ORM\Entity(repositoryClass="App\Repository\AddressObjectRepository")
 */
class AddrObj extends LiquetsoftAddrObj
{
}
```
可用超级类列表
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\AddrObj
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\AddrObjDivision
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\AddrObjTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\AdmHierarchy
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\Apartments
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\ApartmentTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\Carplaces
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\ChangeHistory
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\Houses
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\HouseTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\MunHierarchy
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\NormativeDocs
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\NormativeDocsKinds
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\NormativeDocsTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\ObjectLevels
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\OperationTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\Param
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\ParamTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\ReestrObjects
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\Rooms
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\RoomTypes
- Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\Steads

应单独创建用于管理项目上安装的FIAS版本（用于更新的）的实体

<?php
// src/Entity/FiasVersion.php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Entity\FiasVersion as LiquetsoftFiasVersion;

/**
 * Сущность, которая хранит текущую версию ФИАС.
 *
 * @ORM\Entity
 */
class FiasVersion extends LiquetsoftFiasVersion
{
}

创建所有实体后，应创建相应的迁移，并应用它们
```
bin/console make:migration
```
```
bin/console doctrine:migration:migrate
```

需要向扩展包指定使用哪些实体（对于没有指定转换类的实体将不会使用）以及转换为哪些对象（重要的是理解，项目侧的实体可以是任何实体，甚至不是从超级类继承的，symfony的标准序列化器会尝试将xml转换为指定的对象）

# config/packages/liquetsoft_fias.yaml
liquetsoft_fias:
    # сущность, которая хранит версии ФИАС
    version_manager_entity: App\Entity\FiasVersion
    # массив, в котором указывается какие сущности в какой объект преобразовывать
    entity_bindings:
        ADDR_OBJ: App\Entity\AddrObj
        ADDR_OBJ_DIVISION: App\Entity\AddrObjDivision
        ADDR_OBJ_TYPES: App\Entity\AddrObjTypes
        ADM_HIERARCHY: App\Entity\AdmHierarchy
        APARTMENTS: App\Entity\Apartments
        APARTMENT_TYPES: App\Entity\ApartmentTypes
        CARPLACES: App\Entity\Carplaces
        CHANGE_HISTORY: App\Entity\ChangeHistory
        HOUSES: App\Entity\Houses
        HOUSE_TYPES: App\Entity\HouseTypes
        MUN_HIERARCHY: App\Entity\MunHierarchy
        NORMATIVE_DOCS: App\Entity\NormativeDocs
        NORMATIVE_DOCS_KINDS: App\Entity\NormativeDocsKinds
        NORMATIVE_DOCS_TYPES: App\Entity\NormativeDocsTypes
        OBJECT_LEVELS: App\Entity\ObjectLevels
        OPERATION_TYPES: App\Entity\OperationTypes
        PARAM: App\Entity\Param
        PARAM_TYPES: App\Entity\ParamTypes
        REESTR_OBJECTS: App\Entity\ReestrObjects
        ROOMS: App\Entity\Rooms
        ROOM_TYPES: App\Entity\RoomTypes
        STEADS: App\Entity\Steads

由于使用Doctrine写入数据库，需要禁用请求日志记录，否则脚本会因内存溢出而崩溃

# config/packages/doctrine.yaml
doctrine:
    dbal:
        logging: false # отключаем логгирование
        profiling: false # отключаем профилирование

使用

扩展包定义了几个重要的控制台命令

从零开始安装FIAS
```
bin/console liquetsoft:fias:install
```
通过增量更新FIAS（安装仅在第一次运行时启动，而更新应设置为cron任务）
```
bin/console liquetsoft:fias:update
```
当前FIAS服务器的状态（信息服务或文件服务器可能由于各种原因不可用）
```
bin/console liquetsoft:fias:status
```
可供安装和更新的FIAS版本列表
```
bin/console liquetsoft:fias:versions
```

下载并解压包含完整FIAS版本的存档

bin/console liquetsoft:fias:download /path/to/download full --extract

从指定目录安装FIAS

bin/console liquetsoft:fias:install_from_folder /path/to/extracted/fias

从指定目录更新FIAS

bin/console liquetsoft:fias:update_from_folder /path/to/extracted/fias

强制安装当前FIAS版本号

bin/console liquetsoft:fias:version_set 20160101

性能

有几种方法可以使用扩展包设置来加快导入

删除未使用的实体；例如，如果不需要停车场信息，则可以禁用CARPLACES的对应关系

# config/packages/liquetsoft_fias.yaml
liquetsoft_fias:
    entity_bindings:
        # CARPLACES: App\Entity\Carplaces

由于所有数据在GAR格式中按地区文件夹划分，因此可以排除未使用地区的文件处理

# config/packages/liquetsoft_fias.yaml
liquetsoft_fias:
    files_filter:
        - "#^.+/extracted/30/AS_.+$#" # разрешает все данные для региона
        - "#^.+/extracted/AS_.+$#"    # разрешает общие словари
        # все остальные файлы будут проигнорированы

添加批处理记录；默认情况下，包使用 Doctrine，这可能相当慢，尽管它允许使用所有其优势，例如事件；作为替代，可以连接到 BulkInsertDoctrineStorage，它要快得多，但不使用事件

# config/services.yaml
services:
    # заменяем сервис для записи на сервис, который использует bulk insert
    liquetsoft_fias.storage.doctrine_storage:
        class: Liquetsoft\Fias\Symfony\LiquetsoftFiasBundle\Storage\BulkInsertDoctrineStorage
        arguments:
            - '@doctrine.orm.entity_manager'
            - '%liquetsoft_fias.insert_batch_count%'
            - '@logger'
        tags:
            - { name: 'liquetsoft_fias.storage' }

Elasticsearch

包支持 Elasticsearch 以存储 FIAS 数据。

安装 Elasticsearch 包装器
```
composer req liquetsoft/fias-elastic
```

在配置中激活 Elasticsearch

# config/packages/liquetsoft_fias.yaml
liquetsoft_fias:
    elasticsearch_enable: true
    elasticsearch_hosts:
        - 'https://elasticsearch'

替换应保存到 Elasticsearch 的实体的对应关系
```
# config/packages/liquetsoft_fias.yaml
liquetsoft_fias:
    elasticsearch_enable: true
    elasticsearch_hosts:
        - 'https://elasticsearch'
    entity_bindings:
        ADDR_OBJ: App\Entity\AddrObj                                      # для сохранения будет использована Doctrine
        ADDR_OBJ_DIVISION: Liquetsoft\Fias\Elastic\Entity\AddrObjDivision # для сохранения будет использован Elasticsearch
```
可用实体的列表
- Liquetsoft\Fias\Elastic\Entity\AddrObj
- Liquetsoft\Fias\Elastic\Entity\AddrObjDivision
- Liquetsoft\Fias\Elastic\Entity\AddrObjTypes
- Liquetsoft\Fias\Elastic\Entity\AdmHierarchy
- Liquetsoft\Fias\Elastic\Entity\Apartments
- Liquetsoft\Fias\Elastic\Entity\ApartmentTypes
- Liquetsoft\Fias\Elastic\Entity\Carplaces
- Liquetsoft\Fias\Elastic\Entity\ChangeHistory
- Liquetsoft\Fias\Elastic\Entity\Houses
- Liquetsoft\Fias\Elastic\Entity\HouseTypes
- Liquetsoft\Fias\Elastic\Entity\MunHierarchy
- Liquetsoft\Fias\Elastic\Entity\NormativeDocs
- Liquetsoft\Fias\Elastic\Entity\NormativeDocsKinds
- Liquetsoft\Fias\Elastic\Entity\NormativeDocsTypes
- Liquetsoft\Fias\Elastic\Entity\ObjectLevels
- Liquetsoft\Fias\Elastic\Entity\OperationTypes
- Liquetsoft\Fias\Elastic\Entity\Param
- Liquetsoft\Fias\Elastic\Entity\ParamTypes
- Liquetsoft\Fias\Elastic\Entity\ReestrObjects
- Liquetsoft\Fias\Elastic\Entity\Rooms
- Liquetsoft\Fias\Elastic\Entity\RoomTypes
- Liquetsoft\Fias\Elastic\Entity\Steads

创建所需的索引

php bin/console liquetsoft:fias:create_elastic_indicies

索引的描述可以在相应的 mapper 类中找到。例如，Liquetsoft\Fias\Elastic\IndexMapper\AddrObjIndexMapper 对于 Liquetsoft\Fias\Elastic\Entity\AddrObj。

库还提供了用于访问数据的存储库。

<?php

declare(strict_types=1);

namespace App\Fias;

use Liquetsoft\Fias\Elastic\IndexMapper\AddrObjIndexMapper;
use Liquetsoft\Fias\Elastic\Entity\AddrObj;
use Liquetsoft\Fias\Elastic\ElasticSearchRepository\ElasticSearchRepository;

class ActualStatusService
{
    private ElasticSearchRepository $repo;

    private AddrObjIndexMapper $mapper;

    public function __construct(
        ElasticSearchRepository $repo,
        AddrObjIndexMapper $mapper
    ) {
        $this->repo = $repo;
        $this->mapper = $mapper;
    }

    public function findById(int $id): ?AddrObj
    {
        $query = $this->mapper->query()->term('id', $id);

        return $this->repo->one($query, AddrObj::class);
    }
}

liquetsoft / fias-symfony

维护者

详细信息

README

安装

使用

性能

Elasticsearch