CraueGeoBundle 技术文档

1. 安装指南

1.1 获取 Bundle

通过 Composer 下载并安装 Bundle：

composer require craue/geo-bundle

1.2 启用 Bundle

如果你没有使用 Symfony Flex，需要手动注册 Bundle：

// 在 config/bundles.php 中
return [
    // ...
    Craue\GeoBundle\CraueGeoBundle::class => ['all' => true],
];

或者对于 Symfony 3.4：

// 在 app/AppKernel.php 中
public function registerBundles() {
    $bundles = [
        // ...
        new Craue\GeoBundle\CraueGeoBundle(),
    ];
    // ...
}

1.3 准备地理数据表

如果你打算使用 GEO_DISTANCE_BY_POSTAL_CODE 函数，需要先在数据库中添加一些地理数据。

1.3.1 创建表

GeoPostalCode 实体包含了地理数据的结构。你可以通过以下命令导入：

# 在 shell 中
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

或者

# 在 shell 中
php bin/console doctrine:schema:update

1.3.2 导入地理数据

这是最繁琐的步骤：存储你需要的所有邮政编码及其地理坐标。幸运的是，获取这些信息并导入数据库并不难。

访问 GeoNames 下载你需要的国家的压缩包。例如，下载 DE.zip 并解压出 DE.txt 文件，例如解压到 /tmp/DE.txt。

创建一个继承自提供的基类的 fixture 类：

// MyCompany/MyBundle/Doctrine/Fixtures/CraueGeo/MyGeonamesPostalCodeData.php
namespace MyCompany\MyBundle\Doctrine\Fixtures\CraueGeo;

use Craue\GeoBundle\Doctrine\Fixtures\GeonamesPostalCodeData;
use Doctrine\Common\Persistence\ObjectManager;

class MyGeonamesPostalCodeData extends GeonamesPostalCodeData {

    public function load(ObjectManager $manager) {
        $this->clearPostalCodesTable($manager);
        $this->addEntries($manager, '/tmp/DE.txt');
    }

}

备份你的数据库！如果出现问题，不要责怪任何人。然后导入 fixture，记得使用 --append 参数。

根据你使用的 DoctrineFixturesBundle 版本，选择以下步骤：

DoctrineFixturesBundle < 3.0

# 在 shell 中
php bin/console doctrine:fixtures:load --append --fixtures="src/MyCompany/MyBundle/Doctrine/Fixtures/CraueGeo"

DoctrineFixturesBundle >= 3.1

1. 注册 fixture 为服务并指定一个组。

# 在 app/config/config.yml 中
services:
    my_geonames_postal_code_data:
        class: MyCompany\MyBundle\Doctrine\Fixtures\CraueGeo\MyGeonamesPostalCodeData
        public: false
        tags:
         - { name: doctrine.fixture.orm, group: my_geo_data }

2. 加载该组的 fixture。

# 在 shell 中
php bin/console doctrine:fixtures:load --append --group=my_geo_data

2. 项目使用说明

假设你有一个包含国家和邮政编码的实体 Poi。现在你希望找到所有在特定地理距离内（半径为 $radiusInKm）的实体，并按距离排序。

use MyCompany\MyBundle\Entity\Poi;

// 示例值，可能来自表单，记得先验证/清理
$country = 'DE';
$postalCode = '10115';
$radiusInKm = 10;

// 创建查询构建器
$queryBuilder = $this->getDoctrine()->getEntityManager()->getRepository(Poi::class)->createQueryBuilder('poi');

// 构建查询
$queryBuilder
    ->select('poi, GEO_DISTANCE_BY_POSTAL_CODE(:country, :postalCode, poi.country, poi.postalCode) AS HIDDEN distance')
    ->having('distance <= :radius')
    ->setParameter('country', $country)
    ->setParameter('postalCode', $postalCode)
    ->setParameter('radius', $radiusInKm)
    ->orderBy('distance')
;

3. 项目 API 使用文档

3.1 GEO_DISTANCE

该函数计算两个地理坐标之间的距离，单位为公里。

参数：

• latitude1: 起点的纬度
• longitude1: 起点的经度
• latitude2: 终点的纬度
• longitude2: 终点的经度

返回值：

• 距离（单位：公里）

3.2 GEO_DISTANCE_BY_POSTAL_CODE

该函数通过邮政编码计算两个地点之间的距离，单位为公里。

参数：

• country1: 起点国家代码
• postalCode1: 起点邮政编码
• country2: 终点国家代码
• postalCode2: 终点邮政编码

返回值：

• 距离（单位：公里）

4. 项目安装方式

4.1 通过 Composer 安装

composer require craue/geo-bundle

4.2 手动注册 Bundle

// 在 config/bundles.php 中
return [
    // ...
    Craue\GeoBundle\CraueGeoBundle::class => ['all' => true],
];

或者对于 Symfony 3.4：

// 在 app/AppKernel.php 中
public function registerBundles() {
    $bundles = [
        // ...
        new Craue\GeoBundle\CraueGeoBundle(),
    ];
    // ...
}

4.3 准备地理数据表

按照上述步骤创建和导入地理数据表。