siganushka/region-bundle

Region bundle for symfony.

0.6.1 2024-07-01 02:48 UTC

Requires

• php: >=7.4
• doctrine/doctrine-bundle: ^2.8
• doctrine/orm: ^2.11
• siganushka/doctrine-contracts: ^0.1
• siganushka/generic-bundle: ^0.6
• symfony/form: ^5.4|^6.0
• symfony/framework-bundle: ^5.4|^6.0
• symfony/http-client: ^5.4|^6.0
• symfony/serializer: ^5.4|^6.0

Requires (Dev)

• symfony/phpunit-bridge: ^6.0
• vimeo/psalm: ^5.0

MIT

• siganushka

• region-bundle

README

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

说明

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

安装

$ composer require siganushka/region-bundle dev-main

使用

更新数据库映射信息：

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

导入行政区划数据：

$ php bin/console siganushka:region:update

默认仅导入三级，使用 --with-street 参数可导入四级数据。

导入路由：

# ./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(targetEntity=Region::class)
     */
    private ?Region $province = null;

    /**
     * @ORM\ManyToOne(targetEntity=Region::class)
     */
    private ?Region $city = null;

    /**
     * @ORM\ManyToOne(targetEntity=Region::class)
     */
    private ?Region $district = null;

    /**
     * @ORM\ManyToOne(targetEntity=Region::class)
     */
    private ?Region $street = null;

    // ...
}

为保证此 bundle 的独立、可复用性，你的实体关联到 Region::class 时必需为单向关系，不要指定 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 实现。