Coffee Subscriptions

Plugin para WordPress, WooCommerce y WooCommerce Subscriptions. PHP >= 8.1. Composer carga las clases PSR-4; src/Plugin.php crea el contenedor PHP-DI, resuelve los servicios por constructor y registra sus hooks una sola vez. El archivo principal WordPress llama al singleton en plugins_loaded.

Instalacion

Desde esta carpeta:

composer install --no-dev --optimize-autoloader

Activar WooCommerce, WooCommerce Subscriptions y despues Coffee Subscriptions. En despliegues hay que incluir vendor/ o ejecutar Composer en el servidor. El lock fija las versiones. No requiere construir JavaScript. El plugin no crea productos, modifica precios ni cambia ajustes al activarse.

Pack especialidad

1. Crear una suscripcion simple o variable en WooCommerce, con precio, frecuencia, impuestos, peso y envio configurados. Tambien se puede usar una variacion concreta, sin atributos de tipo "Cualquier...".
2. En WooCommerce > Suscripciones de cafe > General elegir ese producto y la URL del catalogo. Aqui se activa tambien el boton automatico.
3. En Formulario editar, anadir o reordenar los pasos. Cada paso necesita una clave estable, titulo y opciones. Cada opcion tiene texto, icono SVG, color y valor de atributo opcional. Todos los pasos son obligatorios.
4. Insertar [coffee_subscription_form] en una pagina o widget Shortcode.

La primera pantalla permite ir al catalogo o elegir el pack. Por defecto hay tueste, maquina, cantidad y grano/molido. Los pasos sin atributo son preferencias de preparacion: NO modifican precio, peso de envio ni cantidad de carrito. Cada pack anade una unidad del producto o variacion resueltos. El precio y frecuencia del resumen proceden de WooCommerce Subscriptions, incluidas sus condiciones de alta, prueba y duracion cuando correspondan. Sin JavaScript los pasos del pack se muestran juntos y siguen validandose.

Pack variable

Seleccionar el padre de suscripcion variable en General. En Formulario asignar a cada atributo de variacion un paso y el valor exacto de cada opcion. Ejemplo: paso cantidad, atributo pa_peso, texto 500 g, valor 500-g. Para atributos globales se utiliza el slug; para atributos personalizados, el valor exacto de WooCommerce. Todos los atributos de variacion deben estar mapeados una sola vez. Los demas pasos se guardan como preferencias. Si la combinacion no existe, no esta disponible o tiene atributos abiertos de tipo "Cualquier...", la compra se bloquea con un aviso y permite reintentar. La variacion se resuelve otra vez al anadir al carrito: no se confia en precios ni identificadores enviados desde el navegador.

Diseno

Las opciones iniciales se reparten verticalmente el espacio disponible al 50%. Los pasos reparten la altura entre sus opciones, a ancho completo. Al elegir se avanza automaticamente; la flecha superior izquierda conserva las respuestas al retroceder. El resumen permite revisar todo antes de comprar.

Se heredan las fuentes globales de Elementor de wake.test (Titulos y Textos). Los iconos Lucide SVG se sirven localmente desde assets/icons/, con su licencia. No se admite subir SVG arbitrario: se elige de una biblioteca cerrada. Los pasos antiguos reciben iconos y colores por defecto sin cambiar sus opciones.

Variables en assets/frontend.css: --coffee-accent (#F0591C), --coffee-brown (#593B2B), --coffee-brown-dark, --coffee-font-heading, --coffee-font-body, --coffee-title-size, --coffee-option-size, --coffee-icon-size, --coffee-space, --coffee-radius y --coffee-motion. --coffee-header-offset permite descontar una cabecera fija del alto de pantalla. Los colores de cada opcion usan --coffee-option-color desde los ajustes. Se respeta la preferencia de movimiento reducido y la navegacion con teclado. Los dos paneles del administrador permanecen montados para guardar juntos.

Cafes y variaciones

Esta version usa productos de suscripcion reales vinculados. No convierte dinamicamente un producto normal en recurrente ni reinventa el motor de cobro.

• Cafe simple: en Datos del producto > General elegir Producto de suscripcion.
• Cafe variable: enlazar su padre con una suscripcion variable que utilice los mismos nombres y valores de atributos; se resuelve la variacion en servidor.
• Alternativamente enlazar cada variacion original a una suscripcion simple o variacion de suscripcion concreta. El enlace de variacion tiene prioridad.
• Los destinos concretos no admiten atributos vacios de tipo "Cualquier...". Un padre variable no se puede vincular a una suscripcion simple generica.

Se muestra automaticamente un formulario Comprar como suscripcion bajo la compra normal en fichas clasicas de WooCommerce. Sus opciones son independientes de la compra puntual. Consulta el precio recurrente de la combinacion antes de habilitar la compra y respeta los controles de carrito de WooCommerce. Para maquetadores o plantillas que no ejecuten el hook de resumen, usar:

[coffee_subscription_button]
[coffee_subscription_button product_id="123"]

Se puede desactivar el boton automatico en los ajustes. Solo se representa una compra recurrente por producto y peticion para evitar duplicados.

Carrito emergente

Con Woo Custom Cart cargado, ambos formularios (pack y cafe) envian la compra por AJAX a coffee_subscription_add, sin navegar a la pagina del carrito. El endpoint reutiliza las validaciones de producto, variacion y respuestas, conserva los metadatos y devuelve los fragmentos de WooCommerce y el hash. Tras el alta se emite added_to_cart, que el plugin de carrito ya escucha para actualizar el contador y abrir su popup con el carrito actual.

Los controles se bloquean durante el envio para evitar solicitudes simultaneas. Los errores se muestran en el formulario, sin abrir el popup ni redirigir. No se reintenta automaticamente una compra fallida. Si el carrito custom no esta disponible, o no hay JavaScript, se conserva el envio normal de WooCommerce. No es necesario modificar Woo Custom Cart ni configurar un shortcode adicional.

Importante: precio, impuestos, envio, stock y frecuencia pertenecen al producto de suscripcion de destino. No se sincronizan con el cafe original. Si ambos consumen el mismo inventario hay que configurar stock compartido (por ejemplo mediante el gestor de stock por atributos instalado) y probarlo. Duplicar productos exige mantener ambos catalogos. Si se prefiere un unico inventario/producto, conviene adoptar planes nativos sobre productos normales o una extension compatible; esta version no depende de esas APIs de planes.

Datos y renovaciones

Las elecciones se validan contra las opciones configuradas, nunca contra precios o destinos enviados por el cliente. Se guardan por linea de carrito, por lo que dos packs distintos no se fusionan. Las selecciones identicas pueden agruparse como varias unidades, conforme al comportamiento de WooCommerce.

En cada linea del pedido Y de la suscripcion se persiste _coffee_subscription con modalidad, identificador/nombre del cafe original (cuando procede) y las claves, etiquetas y respuestas. Tambien se guardan metadatos legibles para administracion, emails y cuenta del cliente. Los datos son una instantanea: cambiar las preguntas no cambia pedidos existentes.

Se usa woocommerce_checkout_create_order_line_item, que WooCommerce Subscriptions tambien ejecuta al crear las lineas de suscripcion. Sus renovaciones copian las lineas y sus metadatos mediante el motor nativo. No se crean cobros propios. Se usan APIs CRUD de WooCommerce y se declara compatibilidad con HPOS.

Operacion y limites

• Requiere una pasarela y configuracion compatibles con WooCommerce Subscriptions para cobros automaticos. Un boton por si solo no programa cargos.
• No almacena informacion de tarjetas ni credenciales.
• Excluir las paginas con formularios de caches HTML largas: contienen nonces. Si caducan, el servidor pide recargar. Excluir carrito y checkout de cache.
• El checkout clasico y el de bloques usan las lineas de WooCommerce; probar la pasarela y las renovaciones en staging antes de produccion.
• Los titulos y opciones se configuran en un solo idioma. No hay traduccion automatica de ajustes por Polylang ni adaptadores de otros motores.
• No incluye descuentos por suscripcion, gestion de permanencia propia, formulas de precio propias ni sincronizacion de stock. Las respuestas mapeadas eligen una variacion con los precios definidos en WooCommerce.
• Desactivar conserva configuracion y enlaces. No se eliminan pedidos ni suscripciones; WooCommerce Subscriptions sigue gestionando su ciclo de vida.

Estructura y pruebas

Admin/: ajustes y enlaces. Settings/: persistencia y saneado. Catalog/: resolucion de productos/variaciones. Form/: validacion. Frontend/: shortcodes. Cart/: solicitudes y metadatos. templates/ y assets/: presentacion sin dependencias de compilacion.

composer validate --no-check-publish
composer lint
composer test
node --check assets/frontend.js
node --check assets/admin.js
wp eval-file tests/integration.php --skip-themes

tests/run.php usa dobles de WordPress/WooCommerce sin BD y comprueba la validacion, los enlaces, la pertenencia de variaciones, disponibilidad, saneado y persistencia de metadatos. No sustituye una compra de extremo a extremo. composer test incluye tambien tests/pack.php, tests/popup.php y tests/visual-settings.php: 168 casos de comportamiento, seleccion variable, compra AJAX sin redireccion y saneado de ajustes visuales. La prueba de integracion ejecuta el checkout real sobre pedidos y suscripciones en memoria; comprueba los metadatos y no guarda objetos en la base de datos.

Vista local de la plantilla con un producto en memoria, sin guardarlo:

php -S 127.0.0.1:8097 -t . tests/preview.php

Abrir http://127.0.0.1:8097. Requiere esta instalacion WordPress operativa. Administracion de prueba: http://127.0.0.1:8097/admin-preview. La demo usa variaciones en memoria a 24/39/65 EUR, nunca cambia el catalogo. Solo prueba presentacion, navegacion y cotizaciones, no pedidos ni cobros. El texto de periodicidad utiliza el idioma de WooCommerce Subscriptions. El archivo devuelve 404 fuera del servidor CLI de PHP; no debe usarse como pagina de tienda.

Antes de vender: probar compra puntual, cafe simple recurrente, todas las variaciones recurrentes, pack, dos packs con respuestas diferentes, stock compartido, impuestos/envio, checkout utilizado, email y una renovacion en staging.