Toda la documentación · Información del plugin

Hooks y referencia para desarrolladores

Documentación de la versión 1.0.4.

Se aplica a la candidata local 0.1.0-alpha.1 . Estos son los contratos actuales del código, no una promesa de que una API alfa sin publicar nunca vaya a cambiar. Los espacios de nombres PHP conservan la grafía heredada HoockSpark; los hooks públicos utilizan hs_po_. No cambies los nombres de las claves persistentes al personalizar.

Cómo llega una opción al pedido

El repositorio selecciona los grupos activos según el producto, la variación y el visitante determinados por el servidor. El motor valida la configuración, evalúa las dependencias de campos anteriores, normaliza los valores elegidos y calcula los suplementos. Se omiten los campos ocultos. Los adaptadores del carrito vuelven a evaluar los precios del catálogo en lugar de confiar en los importes enviados por el navegador. El adaptador de pago guarda metadatos legibles del artículo y una instantánea privada _hs_po_snapshot con las opciones compradas y su suplemento de precio.

Nunca sustituyas el cálculo del servidor por modificaciones de precios en el navegador. Nunca escribas directamente en hs_po_groups_v1 desde una solicitud pública. Las rutas del editor comprueban permisos y nonces. El almacenamiento utiliza una revisión optimista para evitar la pérdida de cambios. Las clases internas no son una API pública general de persistencia.

Hooks de extensión PHP

El primer argumento de un filtro es su resultado actual. Consérvalo para las definiciones que tu proveedor no gestione. Establece expresamente el número de argumentos admitidos al registrar la función de respuesta.

Las funciones de respuesta de valores de campos personalizados reciben una cadena sin espacios iniciales ni finales. Los valores obligatorios vacíos se rechazan antes de llamar a la función; los opcionales vacíos se omiten. El esquema común sigue validando el identificador, la etiqueta, la obligatoriedad y los precios y límites estándar del campo. Cada proveedor personalizado debe validar las propiedades adicionales que introduzca.

$context contiene actualmente los datos proporcionados por el servidor product_id y group_id cuando se llama mediante Quote. Las llamadas directas al motor y las vistas previas sin guardar pueden proporcionar un contexto vacío. Si tu proveedor necesita un contexto fiable, rechaza su ausencia en lugar de leer identificadores de $_POST. El cuarto argumento es adicional: los proveedores existentes registrados con tres argumentos siguen funcionando.

$base es el precio unitario del catálogo con su base fiscal, antes de los extras de Product Options & Add-Ons. WooCommerce sigue siendo responsable de los impuestos y los totales mostrados. Repetir el cálculo con los mismos datos debe producir el mismo resultado; no incrementes un precio de producto ya modificado.

Ejemplo: un código de referencia validado

el proveedor completo que aparece a continuación. Colócalo en un plugin específico del sitio que se cargue junto a Product Options & Add-Ons; no edites el paquete de Product Options & Add-Ons. Acepta letras, dígitos y guiones hasta un máximo de 32 caracteres, los normaliza a mayúsculas y muestra un campo de texto nativo.

Una definición de campo que utiliza este proveedor es:

array(
    'id'       => 'reference',
    'type'     => 'acme_reference',
    'label'    => 'Project reference',
    'required' => true,
    'price'    => 2,
)

Con un precio de catálogo de 20, la referencia abc-42 se convierte en ABC-42. Dos unidades cuestan 44 antes de los efectos de impuestos y descuentos del carrito. Se rechazan la ausencia de referencia, los espacios, el marcado y las cadenas de más de 32 caracteres. El ejemplo se prueba directamente mediante development/tests/product-options/documented-hook-native.php; no guarda ajustes.

Esto registra un proveedor, no una nueva opción de tipo de campo en el menú del editor. También debes ampliar el editor para crear la definición. Evita configuraciones de campos que la tienda pueda mostrar, pero que el comerciante no pueda entender o editar.

Eventos de extensión del editor

Los eventos se emiten en document. Registra los escuchadores antes de que se inicialice el editor de Free. El paquete Pro utiliza una dependencia de script explícita para garantizar ese orden.

Utiliza textContent para las etiquetas controladas por usuarios y controles nativos con etiqueta. Un proveedor de condiciones del navegador también necesita los filtros correspondientes de configuración y visibilidad en el servidor. JavaScript por sí solo no puede autorizar una compra.

Solicitudes REST y persistencia

Espacio de nombres: hs-product-options/v1. Utiliza la autenticación por cookies de WordPress con X-WP-Nonce y una cuenta con permiso para gestionar WooCommerce. No incrustes credenciales de administrador en scripts públicos de la tienda.

Las rutas actuales incluyen grupos, búsqueda y vista previa del borrador; Pro añade exportación e import-preview. La vista previa de importación devuelve borradores desactivados o requires_mapping para referencias entre sitios. Se valida cada destino de asignación antes de devolver los grupos de borrador. La vista previa de importación no guarda datos.

Gestiona los conflictos de revisión recargando el estado guardado y conservando el borrador del comerciante para revisarlo. No reintentes automáticamente con una revisión nueva sobrescribiendo el trabajo de otro editor. Los límites de tamaño de solicitud se aplican antes del procesamiento.

Integraciones de archivos protegidos

Los archivos no son adjuntos multimedia públicos. Las opciones de producto contienen una referencia opaca vinculada en el servidor a la sesión propietaria y al producto, grupo y campo exactos. La asociación con el pedido se guarda por separado para que los reintentos de pago no consuman una referencia pendiente del carrito. Las descargas de pedidos requieren un comerciante autenticado, un nonce de pedido y artículo, metadatos coincidentes y permiso sobre el pedido.

No muestres referencias de subida en bruto en correos, no expongas el contenido binario de la base de datos mediante un punto de conexión público propio ni consideres que poseer una referencia concede permiso. El archivo se guarda actualmente de forma privada en la base de datos. Eliminar un pedido definitivamente libera los archivos sin referencias; moverlo a la papelera los conserva. Las descargas del comerciante requieren permisos de pedido y una asociación válida al artículo. Las referencias privadas no son URL multimedia públicas.

Desactivación de Pro y límites de integración

Si falta el proveedor de un campo Pro, un precio avanzado, una condición compuesta o un diseño por pasos, la validación del esquema bloquea el uso de esa configuración. Se conservan las definiciones. Una compra afectada no debe descartar sin aviso una personalización obligatoria ni volver a un precio inferior. La desactivación y reactivación reales en red han superado las comprobaciones de compra de Free y bloqueo seguro de Pro sin pérdida de datos. La interfaz completa de recuperación para el comerciante sigue siendo una comprobación de publicación pendiente; esto no afirma que todos los grupos Free puedan comprarse en cualquier configuración mixta.

La integración con Dynamic Pricing utiliza su filtro hs_pricing_catalog_unit_price para proporcionar la base recién calculada con los extras de opciones después de restaurar los totales anteriores. No vuelvas a añadir esos extras en otro filtro de precio. Min/Max sigue validando las cantidades e importes del carrito de WooCommerce. Las afirmaciones de compatibilidad requieren pruebas con versiones exactas de los plugins.

Contrato de respuesta REST de administración

PUT sustituye todo el conjunto de grupos, no un solo grupo. Lee la instantánea actual, conserva los grupos ajenos al cambio, edita una copia local y envía su revisión original junto con el conjunto completo. Nunca envíes un conjunto vacío como prueba de conexión: una solicitud válida y autorizada eliminaría todos los grupos guardados. En un error 422, data.fields asocia las rutas de campos con códigos de error. Conserva el borrador y vincula los mensajes a sus controles. En un error 409, ofrece comparar o recargar en vez de sobrescribir sin aviso el trabajo de otro editor.

El ejemplo completo de proveedor se volvió a ejecutar con el entorno local actual: siete comprobaciones superadas de aceptación del esquema, valor normalizado en mayúsculas, total de 44, valores inválidos y nombres del control generado. Las seis rutas de administración también rechazan solicitudes HTTP anónimas reales con 401. Esto no verifica los nonces autenticados ni todas las combinaciones de perfiles.

Evaluación multipart de archivos del borrador

El punto de conexión de vista previa también admite datos de formulario multipart: una cadena draft JSON con los datos habituales de la vista previa y archivos subidos indexados por identificador de campo. Los límites son de 1 MiB para JSON, 10 archivos y 10 MiB de tamaño total subido, además de la política de cada campo y los límites de PHP y del servidor. La autenticación y los permisos de producto no cambian.

Solo este punto de conexión proporciona el contexto interno draft_preview/draft_files al motor. El proveedor Pro de subida requiere is_uploaded_file() y reutiliza UploadPolicy. Devuelve un valor de visualización efímero para el cálculo, no una referencia de subida reutilizable en la tienda. Los archivos no se trasladan al almacenamiento, a la biblioteca de medios ni a los pedidos. No aceptes estos indicadores de contexto desde los valores públicos del carrito; las integraciones de campos personalizados deben mantener esa distinción. Las pruebas autenticadas de multipart y navegador verificaron una subida PNG correcta, el rechazo de contenido inválido y la recuperación el 20 de septiembre de 2026.

Ejemplo completo de proveedor

<?php
/** Example custom field provider for HS Product Options & Add-Ons. */
namespace Acme\ProductOptionsExample;

defined( 'ABSPATH' ) || exit;

add_filter('hs_po_field_configuration_error', static function ($error, array $field) {
    return 'acme_reference' === ($field['type'] ?? '') ? null : $error;
}, 10, 2);

add_filter('hs_po_field_value', static function ($result, array $field, string $value, array $context = array()) {
    if ('acme_reference' !== ($field['type'] ?? '')) {
        return $result;
    }
    if (!preg_match('/^[A-Za-z0-9-]{1,32}$/D', $value)) {
        return array('error' => 'invalid_reference');
    }
    $normalized = strtoupper($value);
    return array('value' => $normalized, 'display' => $normalized);
}, 10, 4);

add_action('hs_po_render_field', static function (array $field, string $id, string $name): void {
    if ('acme_reference' !== ($field['type'] ?? '')) {
        return;
    }
    echo '<label for="' . esc_attr($id) . '">' . esc_html($field['label']) . '</label>';
    echo '<input type="text" id="' . esc_attr($id) . '" name="' . esc_attr($name) . '" maxlength="32" pattern="[A-Za-z0-9-]{1,32}"' . (!empty($field['required']) ? ' required' : '') . '>';
}, 10, 3);

Índice del manual · Prueba los ejemplos →