Filtros PHP para Agregar, Renombrar o Modificar Ciudades, Departamentos y Distritos (Guía mu-plugins)

Cuando operas tiendas de Pago Contra Entrega (COD) conectadas con transportadoras locales o plataformas logísticas como Dropi, Effi o Mastershop, es frecuente que necesites agregar corregimientos nuevos, estandarizar el nombre de una ciudad o personalizar la lista de departamentos, provincias y distritos de tu país.

Modal COD Form PRO expone 22 filtros nativos de WordPress (apply_filters) dentro de sus catálogos geográficos (includes/states/ e includes/places/) para los 11 países soportados.

1. Regla Técnica Crítica: ¿Por qué usar un mu-plugin en lugar de functions.php?

Antes de escribir tu código, es fundamental comprender el orden de carga de WordPress:

  1. WordPress carga primero los Must-Use Plugins (wp-content/mu-plugins/).
  2. Luego carga los plugins activos y ejecuta el hook plugins_loaded (donde Modal COD Form PRO inicializa PRCOD_States_Places_Colombia, PRCOD_States_Places_Mexico, etc., e incluye los archivos includes/states/*.php e includes/places/*.php).
  3. Recién después carga el archivo functions.php del tema activo.

Dado que los filtros cod_form_{pais}_states y cod_form_{pais}_places se evalúan en el momento exacto en que se incluyen los archivos de ubicaciones durante la inicialización del plugin, cualquier filtro registrado en el functions.php de tu tema llegará demasiado tarde. Por ello, siempre debes registrar estos filtros en un archivo dentro de wp-content/mu-plugins/ (por ejemplo, wp-content/mu-plugins/custom-cod-locations.php).

2. Tabla Completa de los 22 Filtros Geográficos por País

País (Código ISO) Filtro de Departamentos / Estados / Provincias Filtro de Ciudades / Municipios / Distritos
Colombia (CO) cod_form_colombia_states cod_form_colombia_places
México (MX) cod_form_mexico_states cod_form_mexico_places
Perú Estándar (PE) cod_form_peru_states cod_form_peru_places
Perú V2 3 Niveles (PEV2) cod_form_peru_states cod_form_peru_places (Estructura anidada Depto → Provincia → [Distritos])
Chile (CL) cod_form_chile_states cod_form_chile_places
Ecuador (EC) cod_form_ecuador_states cod_form_ecuador_places
Panamá (PA) cod_form_panama_states cod_form_panama_places
Guatemala (GT) cod_form_guatemala_states cod_form_guatemala_places
Costa Rica (CR) cod_form_costa_rica_states (en states/CR.php) / cod_form_cr_states (en places/CR.php) cod_form_costa_rica_places / cod_form_cr_places
República Dominicana (DO) cod_form_rd_states cod_form_rd_places
Paraguay (PY) cod_form_paraguay_states cod_form_paraguay_places
Estados Unidos (US) cod_form_us_states cod_form_us_places

3. Receta 1: Agregar Corregimientos o Renombrar Ciudades en Colombia (CO)

Crea el archivo wp-content/mu-plugins/custom-cod-locations.php y pega el siguiente código:

<?php
/**
 * Plugin Name: Custom Locations for Modal COD Form PRO
 * Description: Personaliza departamentos y ciudades para Pago Contra Entrega.
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * 1. Agregar nuevos corregimientos o renombrar ciudades en Colombia
 */
add_filter( 'cod_form_colombia_places', function( $places ) {
    // Agregar un corregimiento en Antioquia (ANT)
    if ( isset( $places['ANT'] ) && is_array( $places['ANT'] ) ) {
        $places['ANT'][] = 'San Antonio de Prado (Medellín)';
        $places['ANT'][] = 'Santa Elena (Medellín)';
        sort( $places['ANT'] );
    }

    // Estandarizar el nombre de una ciudad en Cundinamarca (CUN) para coincidir con transportadora
    if ( isset( $places['CUN'] ) && is_array( $places['CUN'] ) ) {
        $index = array_search( 'San Juan de Rioseco', $places['CUN'], true );
        if ( false !== $index ) {
            $places['CUN'][ $index ] = 'San Juan de Río Seco';
        }
    }

    return $places;
}, 10, 1 );

4. Receta 2: Personalizar Estados y Municipios en México (MX) o Ecuador (EC)

/**
 * Modificar etiquetas de estados en México y añadir colonias/municipios clave
 */
add_filter( 'cod_form_mexico_states', function( $states ) {
    if ( isset( $states['DF'] ) ) {
        $states['DF'] = 'Ciudad de México (CDMX)';
    }
    return $states;
}, 10, 1 );

add_filter( 'cod_form_mexico_places', function( $places ) {
    if ( isset( $places['JAL'] ) && is_array( $places['JAL'] ) ) {
        if ( ! in_array( 'Tlajomulco de Zúñiga Centro', $places['JAL'], true ) ) {
            $places['JAL'][] = 'Tlajomulco de Zúñiga Centro';
        }
    }
    return $places;
}, 10, 1 );

5. Receta 3: Trabajar con el Modo Perú V2 de 3 Niveles (Departamento → Provincia → Distrito)

Cuando activas la opción cod_form_peru_use_districts = yes en un sitio con país base Perú (PE), el plugin carga la clase especializada PRCOD_States_Places_Peru_V2 y los archivos includes/states/PEV2.php e includes/places/PEV2.php.

En este modo de 3 niveles, el array $places tiene una estructura asociativa de dos niveles: el primer índice es el código del Departamento (ej. 'LIM' para Lima), el segundo índice es la Provincia (ej. 'Lima'), y su valor es el listado de Distritos (que se guardan en el pedido bajo _billing_district):

/**
 * Agregar o personalizar un distrito en Perú V2 (3 niveles: Departamento -> Provincia -> Distrito)
 */
add_filter( 'cod_form_peru_places', function( $places ) {
    // Verificar si estamos en la estructura anidada de PEV2 (Provincia => array de Distritos)
    if ( isset( $places['LIM']['Lima'] ) && is_array( $places['LIM']['Lima'] ) ) {
        if ( ! in_array( 'Santa María de Huachipa', $places['LIM']['Lima'], true ) ) {
            $places['LIM']['Lima'][] = 'Santa María de Huachipa';
            sort( $places['LIM']['Lima'] );
        }
    }
    return $places;
}, 10, 1 );

6. Enlaces Relacionados

Compartir esta información

Aumenta tus ventas

Mejora tu conversión en tiendas WordPress y WooCommerce con pago contra-entrega.