README

什么是 EKATТE?

R. Bulgaria的居民点列表，按区域和区镇排序，按EKATTE（统一行政-领土和领土单位分类）排序，适用于PHP环境。

谁需要这样的东西？

从事

• 电子商务
• 保险服务
• 所有其他需要处理居民点（用户和/或管理员）的开发工作。

使用 EKATTE 需要什么？

• php >= 5.3.0 - 由于存在命名空间、闭包等。
• ext-zip - PHP 插件，用于处理 .zip 归档。EKATTE 的 update 功能从 NСИ（国家统计研究所）网站下载 .zip 归档，该归档需要处理。
• nuovo/spreadsheet-reader - PHP 包，帮助读取 Excel 文件。NSI 归档中包含 .xls 格式的电子表格，需要读取，然后将信息转换为便于使用的形式。

如何安装 EKATTE？

如果您全局安装了 composer（即 composer 已安装在系统中），只需在项目的文件夹（在命令行 - Terminal、Konsole、Command Prompt）中执行以下命令（在 Windows 中 cd път\до\папката），其中您想使用 EKATTE：

    composer require abpam/ekatte

如果您使用的是本地 composer（每个项目中的 composer 归档）-

    composer.phar require abpam/ekatte 

在项目文件夹中。

如何使用 EKATTE？

首先，您需要更新数据库到 NСИ的最新数据。这可以通过 vendor/abpam/ekatte/updater.php 文件完成。通过命令行到达 път/до/проекта/vendor/abpam/ekatte 文件夹，并执行以下操作：

php updater.php

如果一切顺利，结果应该是

100%[==================================================>]

Обновено...

注意

如果在更新过程中脚本返回与文件编码（encoding）相关的错误，这是 nuovo/spreadsheet-reader 包读取 .xls 文件时的问题。通过将文件 /vendor/nuovo/spreadsheet-reader/php-excel-reader/excel_reader2.php 的第 917 行替换为

    $this->setUTFEncoder('iconv');

为

    $this->setUTFEncoder('mb');

如果尚未这样做，请指示项目使用 composer 文件

<?php
    require_once __DIR__.'/vendor/autoload.php'; 

然后我们可以获取 R. Bulgaria 所有地区的列表

    use Ekatte\Oblast;

    $oblast = new Oblast();
    $oblastiList = $oblast->getOblastiList();

    var_dump($oblastiList);

getOblastiList() 函数用于提取所有地区的列表。它返回一个二维数组。第一个索引表示各个地区，第二个索引表示每个地区的参数

• 0 - 地区的三字母代码；
• 1 - 以该地区为中心的居民点的 ЕКАТТЕ 编号；
• 2 - 地区名称；
• 3 - 地区所属的区域的代码；
• 4 - 记录地区最后行政领土变更的文件编号；
• 5 - 按字母顺序排列的地区序号）。

getOblast() 函数用于提取特定地区的详细信息。它需要一个字符串参数，即地区的三字母代码，并返回一个一维数组，索引对应于上面提到的。例如，如果我们想获取“Veliko Tarnovo”地区的详细信息，需要按以下方式调用该函数

    use Ekatte\Oblast;

    $oblast = new Oblast();
    $oblast = $oblast->getOblast('VTR');
    
    var_dump($oblast);

具有相同格式的函数还涉及区镇。如果需要获取特定地区内所有区镇列表，需要使用 getObshtiniList()，并传递地区名称作为参数。例如，如果我们需要获取“Vratsa”地区内所有区镇的列表

    use Ekatte\Obshtina;
    
    $obshtini = new Obshtina();
    $obshtini = $obshtini->getObshtiniList('VRC');
    
    var_dump($obshtini);

函数返回一个二维数组，第一个索引表示特定的区镇，第二个索引表示该区镇的参数

• 0 - 5个字符的社区代码，由表示所在地区的三字母缩写和表示社区在地区中顺序的两位数组成；
• 1 - 社区的ЕКАТТЕ代码，社区的中心；
• 2 - 社区的名称；
• 3 - 社区的类别（确定类别的标准在《保加利亚行政领土组织法》中描述）；
• 4 - 记录社区最后一次行政领土变更的文件编号；
• 5 - 按字母顺序排列的序号；

类似地区功能，对于社区也有一个功能，返回关于特定社区的信息 - getObshtina()。该函数接受一个参数（社区的5个字符代码）作为文本字符串（string）并返回一个一维数组，其索引与从getObshtiniList()返回的第二个索引相对应；

    $obshtina = new Obshtina();
    $obshtina = $obshtina->getObshtina('LOV02');
    
    var_dump($obshtina);

最后，我们来解释一下关于聚居地（城市和村庄）的功能。要获取某个社区内的聚居地列表，我们可以使用getSelishtaList()函数，它接受两个参数 - 作为文本字符串（string）的三字母地区代码和5个字符的社区代码，也作为文本字符串（string）。例如，要获取斯维什科夫市（维利科特罗沃州）的所有聚居地列表

    $selishta = new Selishte();
    $selishta = $selishta->getSelishtaList('VTR', 'VTR28');
    
    var_dump($selishta);

必须指出，函数的第二个参数不是必需的。换句话说，如果我们想获取某个地区的所有聚居地列表（例如布尔加斯），我们不需要指定社区；

    $selishta = new Selishte();
    $selishta = $selishta->getSelishtaList('BGS');
    
    var_dump($selishta);

这两个函数返回一个数组，其索引对应于ЕКАТТЕ的聚居地编号，而两个元素分别是聚居地的名称和市政府的编号。

如果我们需要关于某个聚居地的更详细的信息，可以使用getSelishte()函数，它接受一个参数（作为文本字符串的string） - 根据ЕКАТТЕ的聚居地识别号。

关于佩什尼克村（维丁）的信息请求如下

    $selishte = new Selishte();
    $selishte = $selishte->getSelishte('56753');

因为佩什尼克村（维丁州）的ЕКАТТЕ识别号是56753。

这是使用本包所需的基本信息。如有任何问题，请发送电子邮件至 avramov.emil@gmail.com 或在Twitter上关注@ABPAM。