Hooks (actions and filters)

Hooks (acciones y filtros) para ampliar y modificar el comportamiento del plugin. Todos usan el espacio de nombres polski/.

Hooks de desistimiento

polski/withdrawal/days

Filtra el número de días para el desistimiento del contrato.

/**
 * @param int $days Number of days for withdrawal (default 14)
 */
apply_filters('polski/withdrawal/days', int $days): int;

Ejemplo:

add_filter('polski/withdrawal/days', function (int $days): int {
    return 30; // Extend to 30 days
});

polski/withdrawal/excluded_categories

Filtra las categorías de productos excluidas del derecho de desistimiento.

/**
 * @param array $categories Array of category IDs
 */
apply_filters('polski/withdrawal/excluded_categories', array $categories): array;

Ejemplo:

add_filter('polski/withdrawal/excluded_categories', function (array $categories): array {
    $categories[] = 15; // "Digital products" category ID
    $categories[] = 22; // "Hygiene products" category ID
    return $categories;
});

polski/withdrawal/form_fields

Filtra los campos del formulario de desistimiento.

/**
 * @param array $fields Array of form fields
 */
apply_filters('polski/withdrawal/form_fields', array $fields): array;

Ejemplo:

add_filter('polski/withdrawal/form_fields', function (array $fields): array {
    $fields['reason'] = [
        'type'     => 'textarea',
        'label'    => 'Withdrawal reason',
        'required' => false,
    ];
    return $fields;
});

polski/withdrawal/email_sent

Acción que se dispara tras enviar el correo de confirmación de desistimiento.

/**
 * @param int   $order_id  Order ID
 * @param array $form_data Form data
 */
do_action('polski/withdrawal/email_sent', int $order_id, array $form_data): void;

Ejemplo:

add_action('polski/withdrawal/email_sent', function (int $order_id, array $form_data): void {
    // Log withdrawals to external system
    wp_remote_post('https://api.crm.pl/withdrawals', [
        'body' => wp_json_encode([
            'order_id' => $order_id,
            'date'     => current_time('mysql'),
        ]),
    ]);
}, 10, 2);

Hooks de precio

polski/price/unit_format

Filtra el formato de visualización del precio por unidad.

/**
 * @param string $format     Unit price format
 * @param float  $unit_price Unit price
 * @param string $unit       Unit of measurement (kg, l, m, pcs)
 * @param int    $product_id Product ID
 */
apply_filters('polski/price/unit_format', string $format, float $unit_price, string $unit, int $product_id): string;

Ejemplo:

add_filter('polski/price/unit_format', function (string $format, float $unit_price, string $unit, int $product_id): string {
    return sprintf('%s / %s', wc_price($unit_price), $unit);
}, 10, 4);

polski/price/vat_notice

Filtra el HTML del aviso de IVA junto al precio (aviso del tipo o texto de la exención del art. 113).

/**
 * @param string     $html    Notice HTML
 * @param WC_Product $product Product
 */
apply_filters('polski/price/vat_notice', string $html, WC_Product $product): string;

Devolver una cadena vacía oculta el aviso.

add_filter('polski/price/vat_notice', function (string $html, WC_Product $product): string {
    return $product->is_type('simple') ? $html : '';
}, 10, 2);

Hooks de Omnibus

polski/omnibus/lowest_price

Filtra el precio más bajo de los últimos 30 días (Directiva Omnibus).

/**
 * @param float $price      Lowest price
 * @param int   $product_id Product ID
 * @param int   $days       Number of days back
 */
apply_filters('polski/omnibus/lowest_price', float $price, int $product_id, int $days): float;

Ejemplo:

add_filter('polski/omnibus/lowest_price', function (float $price, int $product_id, int $days): float {
    // Skip products from the "Outlet" category
    if (has_term('outlet', 'product_cat', $product_id)) {
        return 0.0; // Do not display Omnibus price
    }
    return $price;
}, 10, 3);

polski/omnibus/display_format

Filtra el formato de visualización del precio Omnibus.

/**
 * @param string $html       HTML with price
 * @param float  $price      Lowest price
 * @param int    $product_id Product ID
 */
apply_filters('polski/omnibus/display_format', string $html, float $price, int $product_id): string;

Ejemplo:

add_filter('polski/omnibus/display_format', function (string $html, float $price, int $product_id): string {
    return sprintf(
        '<small class="omnibus-price">Lowest price from 30 days: %s</small>',
        wc_price($price)
    );
}, 10, 3);

polski/omnibus/price_recorded

Acción que se dispara tras guardar un precio en el historial de Omnibus.

/**
 * @param int   $product_id Product ID
 * @param float $price      Saved price
 */
do_action('polski/omnibus/price_recorded', int $product_id, float $price): void;

Hooks de KSeF

Ambos hooks residen en polski/src/Service/KSeFReadyService.php. Solo se ejecutan cuando el módulo KSeF Ready está activado en Polski > Módulos, y ambos se disparan desde woocommerce_checkout_order_processed, justo después de realizar el pedido. Marcan el pedido como sujeto a factura en KSeF. Ninguno de los dos envía nada a KSeF.

polski/ksef/is_required

Filtra si el pedido requiere una factura en KSeF. El valor de entrada es true cuando el pedido tiene un NIP en la clave meta _billing_nip o _polski_billing_nip, y false en caso contrario. El valor devuelto se convierte a bool y se guarda en el pedido en la clave meta _polski_ksef_required como yes o no.

/**
 * @param bool     $required Whether the order requires a KSeF invoice
 * @param WC_Order $order    Order object
 */
apply_filters('polski/ksef/is_required', bool $required, WC_Order $order): bool;

Ejemplo:

add_filter('polski/ksef/is_required', function (bool $required, WC_Order $order): bool {
    // Also require a KSeF invoice when the customer asked for one.
    if ($order->get_meta('_wants_invoice') === 'yes') {
        return true;
    }
    return $required;
}, 10, 2);

polski/ksef/invoice_ready

Acción que se dispara cuando un pedido ha quedado marcado como sujeto a factura en KSeF. Solo se ejecuta si el valor filtrado anterior es true, y únicamente después de guardar _polski_ksef_required en el pedido.

/**
 * @param WC_Order $order Order marked as requiring a KSeF invoice
 */
do_action('polski/ksef/invoice_ready', WC_Order $order): void;

Ejemplo:

add_action('polski/ksef/invoice_ready', function (WC_Order $order): void {
    $order->add_order_note('Order flagged for KSeF invoicing.');
    $order->save();
});

Hooks de DSA

polski/dsa/report_fields

Filtra los campos del formulario de denuncia DSA.

/**
 * @param array $fields Form fields
 */
apply_filters('polski/dsa/report_fields', array $fields): array;

Ejemplo:

add_filter('polski/dsa/report_fields', function (array $fields): array {
    $fields['screenshot'] = [
        'type'     => 'file',
        'label'    => 'Screenshot',
        'required' => false,
        'accept'   => '.jpg,.png,.pdf',
    ];
    return $fields;
});

polski/dsa/report_submitted

Acción que se dispara tras enviar una denuncia DSA.

/**
 * @param int   $report_id Report ID
 * @param array $data      Report data
 */
do_action('polski/dsa/report_submitted', int $report_id, array $data): void;

Hooks de DOI - double opt-in

polski/doi/verification_email

Filtra el contenido del correo de verificación DOI.

/**
 * @param string $message Email content
 * @param string $email   Email address to verify
 * @param string $url     Verification URL
 */
apply_filters('polski/doi/verification_email', string $message, string $email, string $url): string;

Ejemplo:

add_filter('polski/doi/verification_email', function (string $message, string $email, string $url): string {
    return sprintf(
        'Hello! Confirm your registration by clicking: <a href="%s">Confirm account</a>',
        esc_url($url)
    );
}, 10, 3);

polski/doi/verified

Acción que se dispara tras la verificación DOI correcta.

/**
 * @param int    $user_id User ID
 * @param string $email   Email address
 */
do_action('polski/doi/verified', int $user_id, string $email): void;

Hooks de caché

polski/cache/should_flush

Filtra la decisión sobre el vaciado de la caché del plugin.

/**
 * @param bool   $should_flush Whether to flush cache
 * @param string $group        Cache group (omnibus, badges, search)
 */
apply_filters('polski/cache/should_flush', bool $should_flush, string $group): bool;

Ejemplo:

add_filter('polski/cache/should_flush', function (bool $should_flush, string $group): bool {
    // Do not flush search cache during import
    if ($group === 'search' && defined('WP_IMPORTING') && WP_IMPORTING) {
        return false;
    }
    return $should_flush;
}, 10, 2);

polski/cache/ttl

Filtra el tiempo de vida (TTL) de la caché en segundos.

/**
 * @param int    $ttl   Time in seconds
 * @param string $group Cache group
 */
apply_filters('polski/cache/ttl', int $ttl, string $group): int;

Hooks de casillas

polski/checkboxes/render

Filtra el HTML renderizado de la casilla.

/**
 * @param string $html     Checkbox HTML
 * @param array  $checkbox Checkbox data
 * @param string $location Location (checkout, registration, contact)
 */
apply_filters('polski/checkboxes/render', string $html, array $checkbox, string $location): string;

polski/checkboxes/validated

Acción que se dispara tras la validación de las casillas.

/**
 * @param array $checkboxes Validated checkboxes
 * @param bool  $valid      Validation result
 */
do_action('polski/checkboxes/validated', array $checkboxes, bool $valid): void;

Hooks de correo electrónico

polski/email/template

Filtra la ruta de la plantilla de correo electrónico.

/**
 * @param string $template Template path
 * @param string $type     Email type (withdrawal, doi, waitlist)
 */
apply_filters('polski/email/template', string $template, string $type): string;

Ejemplo:

add_filter('polski/email/template', function (string $template, string $type): string {
    if ($type === 'withdrawal') {
        return get_stylesheet_directory() . '/polski/emails/withdrawal.php';
    }
    return $template;
}, 10, 2);

polski/email/headers

Filtra los encabezados del correo electrónico.

/**
 * @param array  $headers Email headers
 * @param string $type    Email type
 */
apply_filters('polski/email/headers', array $headers, string $type): array;

Hooks de páginas legales

polski/legal_page/template_data

Filtra los datos insertados en la plantilla de la página legal.

/**
 * @param array  $data Template data
 * @param string $type Page type (terms, privacy, withdrawal, dsa_report)
 */
apply_filters('polski/legal_page/template_data', array $data, string $type): array;

Ejemplo:

add_filter('polski/legal_page/template_data', function (array $data, string $type): array {
    if ($type === 'terms') {
        $data['delivery_info'] = 'Delivery within 2-5 business days.';
    }
    return $data;
}, 10, 2);

polski/legal_page/created

Acción que se dispara tras generar una página legal.

/**
 * @param int    $page_id Page ID
 * @param string $type    Page type
 */
do_action('polski/legal_page/created', int $page_id, string $type): void;

Buenas prácticas

1. Usa tipos - declara los tipos de los parámetros y de los valores de retorno en los callbacks
2. Prioridad - la prioridad predeterminada es 10, usa una más alta (p. ej. 20) para sobrescribir el comportamiento predeterminado
3. Espacio de nombres - no crees hooks en el espacio de nombres polski/ en tus plugins para evitar conflictos
4. Compatibilidad - comprueba la existencia del hook antes de usarlo: has_filter('polski/omnibus/lowest_price')
5. Documentación - documenta tus callbacks con comentarios PHPDoc

Informar de problemas: github.com/wppoland/polski/issues

Esta página tiene únicamente carácter informativo y no constituye asesoramiento jurídico. Consulta a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.