siganushka/region-bundle

Region bundle for symfony.

1.0.0 2025-05-08 05:46 UTC

Requires

• php: >=8.1
• siganushka/doctrine-contracts: ^v1.0
• siganushka/generic-bundle: ^v1.0
• symfony/form: ^6.4|^7.0
• symfony/framework-bundle: ^6.4|^7.0
• symfony/http-client: ^6.4|^7.0

Requires (Dev)

• symfony/serializer: ^6.4|^7.0

MIT

• siganushka

• symfony-ux
• region-bundle

README

国内行政区划四级联动 Bundle，数据来源 Administrative-divisions-of-China

说明

• 一级：省、自治区、直辖市
• 二级：市、县、自治州、自治县
• 三级：区、县
• 四级：乡镇/街道

安装

$ composer require siganushka/region-bundle

使用

更新数据库映射信息：

$ php bin/console doctrine:schema:update --force

导入行政区划数据：

$ php bin/console siganushka:region:update

默认导入 3 级数据，可使用 --level=2/3/4 参数自定义数据等级。

导入路由：

# ./config/routes.yaml

siganushka_region:
    resource: "@SiganushkaRegionBundle/config/routes.php"
    prefix: /api

导入后可通过 php bin/console debug:route 查看已导入路由。

示例

实体对象：

// src/Entity/UserAddress.php

use Siganushka\RegionBundle\Entity\Region;

class UserAddress
{
    #[ORM\ManyToOne]
    #[ORM\JoinColumn('province_code', referencedColumnName: 'code')]
    private ?Region $province = null;

    #[ORM\ManyToOne]
    #[ORM\JoinColumn('city_code', referencedColumnName: 'code')]
    private ?Region $city = null;

    #[ORM\ManyToOne]
    #[ORM\JoinColumn('district_code', referencedColumnName: 'code')]
    private ?Region $district = null;

    #[ORM\ManyToOne]
    #[ORM\JoinColumn('street_code', referencedColumnName: 'code')]
    private ?Region $street = null;

    // ...
}

注意 Region 主键为 code，同时为保证独立和可复用性，关联时必需为单向关系，不要指定 inversedBy 参数。

表单类型：

// src/Form/UserAddressType.php

use Siganushka\RegionBundle\Form\Type\RegionType;

class UserAddressType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('province', RegionType::class, [
                'cascader_target' => 'city',
            ])
            ->add('city', RegionType::class, [
                'cascader_target' => 'district',
            ])
            ->add('district', RegionType::class, [
                'cascader_target' => 'street',
            ])
            ->add('street', RegionType::class)
        ;
    }

    // ...
}

选项 cascader_target 指定了要联动的下一级字段，不管是二级、三级还是四级，只需要指定该参数即可。前端联动效果由 AssetMapper 和 StimulusBundle 实现。