Tutta la documentazione · Panoramica del plugin

Hook e riferimenti per sviluppatori

Documentazione della versione 1.0.4.

Si applica al candidato locale 0.1.0-alpha.1 . Sono i contratti del codice corrente, non una promessa che un’API alpha non pubblicata resti immutata. I namespace PHP mantengono la grafia storica HoockSpark; gli hook pubblici usano hs_po_. Non rinominare le chiavi persistenti durante le personalizzazioni.

Come un’opzione arriva all’ordine

Il repository seleziona i gruppi attivi usando prodotto, variante e visitatore verificati. Il motore valida la configurazione, valuta le dipendenze dai campi precedenti, normalizza i valori e calcola i prezzi extra. I campi nascosti sono omessi. Gli adattatori del carrello rivalutano i prezzi di catalogo invece di fidarsi degli importi inviati dal browser. L’adattatore checkout scrive metadati leggibili nella riga ordine e una copia privata _hs_po_snapshot con le opzioni acquistate e il relativo prezzo extra.

Non modificare mai i prezzi nel browser come sostituto del calcolo sul server. Non scrivere mai direttamente in hs_po_groups_v1 da una richiesta pubblica. Le rotte dell’editor verificano permessi e nonce; l’archivio usa una revisione ottimistica per impedire aggiornamenti persi. Le classi interne non sono un’API pubblica generale di persistenza.

Hook di estensione PHP

Il primo argomento di un filtro è il risultato corrente. Conservalo per le definizioni non gestite dal tuo componente. Registra la callback indicando esplicitamente quanti argomenti accetta.

Le callback dei valori dei campi personalizzati ricevono una stringa senza spazi iniziali e finali. I valori obbligatori vuoti vengono rifiutati prima della callback; quelli facoltativi vuoti sono omessi. Lo schema comune valida comunque ID, etichetta, obbligatorietà, prezzo e limiti standard del campo. Il componente personalizzato deve validare ogni proprietà aggiuntiva che introduce.

$context contiene attualmente dati forniti dal server: product_id e group_id quando viene chiamato tramite Quote. Chiamate dirette al motore e anteprime non salvate possono fornire un contesto vuoto. Se il componente richiede un contesto verificato, rifiutane l’assenza invece di leggere ID da $_POST. Il quarto argomento è aggiuntivo: i componenti esistenti registrati per tre argomenti continuano a funzionare.

$base è il prezzo unitario di catalogo sulla relativa base fiscale, prima degli extra di Product Options & Add-Ons. WooCommerce resta responsabile di imposte e totali mostrati. Ripetere il calcolo con gli stessi dati deve dare lo stesso risultato: non incrementare un prezzo prodotto già modificato.

Esempio: codice di riferimento validato

Il codice qui sotto è un esempio completo di componente. Inseriscilo in un plugin dedicato al sito, caricato insieme a Product Options & Add-Ons; non modificare il pacchetto del prodotto. Accetta lettere, cifre e trattini fino a 32 caratteri, li converte in maiuscolo e mostra un input di testo nativo.

Una definizione di campo che usa il componente è:

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

Con prezzo di catalogo 20, il riferimento abc-42 diventa ABC-42. Due unità costano 44 prima degli effetti di imposte e sconti del carrello. Riferimento mancante, spazi, markup e stringhe oltre 32 caratteri vengono rifiutati. L’esempio viene provato direttamente da development/tests/product-options/documented-hook-native.php; non scrive impostazioni.

Questo registra un componente, non una nuova voce nel menu dei tipi di campo dell’editor. Va esteso anche l’editor per creare la definizione. Evita configurazioni che il negozio può mostrare ma che il venditore non può comprendere o modificare.

Eventi di estensione dell’editor

Gli eventi vengono emessi su document. Registra i listener prima dell’inizializzazione dell’editor Free. Il pacchetto Pro usa una dipendenza esplicita degli script per garantire l’ordine.

Usa textContent per etichette controllate dagli utenti e controlli nativi con etichetta. Un componente di condizioni nel browser richiede anche i corrispondenti filtri di configurazione e visibilità sul server. JavaScript da solo non può autorizzare un acquisto.

Richieste REST e persistenza

Namespace: hs-product-options/v1. Usa l’autenticazione tramite cookie WordPress con X-WP-Nonce e un account autorizzato a gestire WooCommerce. Non incorporare credenziali amministrative negli script del frontend.

Le rotte correnti includono gruppi, ricerca e anteprima della bozza; Pro aggiunge esportazione e anteprima di importazione. Quest’ultima restituisce bozze disabilitate oppure requires_mapping per i riferimenti tra siti. Ogni associazione di destinazione viene validata prima di restituire le bozze. L’anteprima di importazione non è un salvataggio.

Gestisci i conflitti di revisione ricaricando lo stato salvato e conservando la bozza del venditore per il confronto. Non ritentare automaticamente con una nuova revisione sovrascrivendo il lavoro di un altro editor. I limiti di dimensione delle richieste vengono applicati prima dell’elaborazione.

Integrazioni dei file protetti

I file non sono allegati media pubblici. Le opzioni contengono un riferimento opaco legato alla titolarità della sessione sul server e al prodotto, gruppo e campo esatti. L’associazione all’ordine è separata, così i nuovi tentativi di checkout non consumano un riferimento pendente del carrello. Scaricare dall’ordine richiede un venditore autenticato, un nonce di ordine e articolo, metadati coerenti e permessi sull’ordine.

Non mostrare riferimenti grezzi dei caricamenti nelle email, non esporre contenuti binari del database tramite endpoint pubblici personalizzati e non considerare il possesso di un riferimento come autorizzazione. L’archivio corrente è privato nel database; l’eliminazione definitiva dell’ordine libera i file senza riferimenti, mentre il Cestino li conserva. I download del venditore richiedono permessi sull’ordine e un’associazione valida alla riga; i riferimenti privati non sono URL media pubblici.

Disattivazione di Pro e limiti delle integrazioni

Senza il componente necessario per campo Pro, prezzo avanzato, condizione composta o layout a passaggi, la validazione dello schema blocca l’operazione. Le definizioni restano. Un acquisto interessato non deve perdere senza avviso personalizzazioni obbligatorie o tornare a un prezzo inferiore. Le prove effettive di disattivazione e riattivazione in rete hanno superato i controlli di acquisto Free e blocco Pro senza perdita di dati. L’interfaccia completa di recupero per il venditore resta una verifica di rilascio; non si dichiara che ogni gruppo Free resti acquistabile in qualsiasi configurazione mista.

L’integrazione Dynamic Pricing usa il filtro hs_pricing_catalog_unit_price per fornire la base appena calcolata con gli extra delle opzioni dopo il ripristino dei totali precedenti. Non aggiungere gli stessi extra di nuovo in un altro filtro prezzo. Min/Max continua a validare quantità e importi del carrello Woo. Le dichiarazioni di compatibilità richiedono prove sulle versioni esatte.

Contratto delle risposte REST amministrative

PUT sostituisce l’intera raccolta dei gruppi, non un singolo gruppo. Leggi lo stato corrente, conserva i gruppi estranei alla modifica, lavora su una copia locale e invia la revisione originale con la raccolta completa. Non inviare mai una raccolta vuota per provare la connessione: una richiesta valida e autorizzata eliminerebbe tutti i gruppi salvati. Con 422, data.fields associa i percorsi dei campi ai codici di errore; conserva la bozza e collega i messaggi ai controlli. Con 409 offri confronto o ricaricamento invece di sovrascrivere senza avviso un altro editor.

L’esempio completo del componente è stato rieseguito sul runtime locale corrente: sette controlli superati per accettazione dello schema, valore normalizzato in maiuscolo, totale 44, valori non validi e nomi del rendering. Anche le sei rotte amministrative rifiutano richieste HTTP reali anonime (401); questo non verifica ogni combinazione di nonce autenticato o ruolo.

Valutazione multipart dei file nella bozza

L’endpoint di anteprima accetta anche dati di modulo multipart: una stringa JSON draft con il normale contenuto dell’anteprima e file caricati indicizzati per ID del campo. I limiti sono 1 MiB per JSON, 10 file e 10 MiB complessivi, oltre alle regole del campo e ai limiti PHP e server. Autenticazione e permessi sui prodotti non cambiano.

Soltanto questo endpoint fornisce il contesto interno del motore draft_preview/draft_files . Il componente di caricamento Pro richiede is_uploaded_file() e riusa UploadPolicy. Restituisce un valore temporaneo per visualizzazione e calcolo, non un riferimento riutilizzabile di caricamento nel negozio. I file non vengono spostati nell’archivio, nei media o negli ordini. Non accettare questi indicatori di contesto dai valori pubblici del carrello; le integrazioni personalizzate devono conservare la distinzione. L’accettazione multipart e nel browser autenticato ha verificato successo PNG, rifiuto di contenuto non valido e recupero il 20 settembre 2026.

Esempio completo di componente

<?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);

Indice del manuale · Prova gli esempi →