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_label

Filtra la etiqueta de IVA mostrada junto al precio.

/**
 * @param string $label      Label text
 * @param string $tax_status Product tax status
 */
apply_filters('polski/price/vat_label', string $label, string $tax_status): string;

Ejemplo:

add_filter('polski/price/vat_label', function (string $label, string $tax_status): string {
    if ($tax_status === 'taxable') {
        return 'gross (incl. VAT)';
    }
    return 'VAT exempt';
}, 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

polski/ksef/invoice_data

Filtra los datos de la factura antes de enviarla a KSeF.

/**
 * @param array    $data  Invoice data
 * @param WC_Order $order Order object
 */
apply_filters('polski/ksef/invoice_data', array $data, WC_Order $order): array;

Ejemplo:

add_filter('polski/ksef/invoice_data', function (array $data, WC_Order $order): array {
    $data['additional_info'] = 'Automatically generated invoice';
    return $data;
}, 10, 2);

polski/ksef/invoice_sent

Acción que se dispara tras enviar correctamente una factura a KSeF.

/**
 * @param int    $order_id   Order ID
 * @param string $ksef_id    KSeF reference number
 * @param array  $response   KSeF API response
 */
do_action('polski/ksef/invoice_sent', int $order_id, string $ksef_id, array $response): void;

Ejemplo:

add_action('polski/ksef/invoice_sent', function (int $order_id, string $ksef_id, array $response): void {
    update_post_meta($order_id, '_ksef_reference', $ksef_id);
    $order = wc_get_order($order_id);
    $order->add_order_note(sprintf('Invoice sent to KSeF: %s', $ksef_id));
}, 10, 3);

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/generated

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/generated', 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.