OW Forms — Документација

Модерен, GDPR-нативен градител на формулари за WordPress. Автор: OptionWeb — Julien Daniel Страница на додатокот: https://optionweb.dev/mk/addons/ow-forms/ Лиценца: GPL-2.0-or-later Верзија покриена со овој документ: 1.0.2

---

Содржина

1. Преглед
2. Инсталација
3. Брз почеток — вашиот прв формулар
4. Типови на полиња
5. Анти-спам стек
6. GDPR функционалности
7. Известувања по е-пошта
8. Webhooks
9. Прикачување на датотеки
10. Рендерирање: shortcode, Gutenberg, REST
11. Увозник за Contact Form 7
12. Референца на поставки
13. REST API
14. Hooks за програмери (filters & actions)
15. Интеграција со OW Consent / OW Shield
16. Интернационализација
17. Решавање проблеми
18. ЧПП

---

Преглед

OW Forms е градител на формулари управуван од шема. Секој формулар е JSON документ кој ги опишува неговите полиња, валидацијата и однесувањето при испраќање. Додатокот ја рендерира таа шема како пристапен HTML, ги валидира испратените податоци на серверот, ги пушта низ четири-слоен анти-спам стек, ги зачувува податоците што ќе му дозволите, и испраќа известувања по е-пошта + webhook.

Што доаѓа со него (сè бесплатно, GPL-2):

• Машина за JSON шема со 17 типови на полиња
• 4-слоен анти-спам: honeypot, time-trap, CAPTCHA со повеќе провајдери, IP репутација
• Нативен GDPR пристанок + задржување + DSAR
• REST API (namespace owf/v1) — јавен submit + админ CRUD
• Gutenberg блок + shortcode + PHP API за рендерирање
• Излезни webhook-ови потпишани со HMAC
• Увозник за Contact Form 7 со еден клик
• Автоматски ги препознава токените на темата OW Canvas за визуелна конзистентност

Што намерно НЕ прави:

• Процесирање на плаќања (користете WooCommerce + посветен checkout)
• Повеќестранични волшебници надвор од едноставно следно/претходно (користете посветен wizard додаток)
• Визуелен градител со drag-and-drop во v1 (само JSON уредник; визуелен градител во roadmap)

---

Инсталација

Од WordPress.org (препорачано)

1. WordPress админ → Plugins → Add New
2. Пребарајте OW Forms
3. Кликнете Install Now, потоа Activate

Од .zip прикачување

1. Преземете ow-forms-1.0.2.zip од https://optionweb.dev/mk/addons/ow-forms/
2. Plugins → Add New → Upload Plugin
3. Изберете ја датотеката, кликнете Install Now, потоа Activate

Барања

• WordPress 6.0 или понов
• PHP 7.4 или понов (8.1+ препорачано)
• MySQL/MariaDB со поддршка за JSON колона (5.7+ / 10.2+)

Што се инсталира

При активирање, OW Forms создава три прилагодени табели:

• {prefix}_owf_submissions — payload-и на испраќања + spam метаподатоци
• {prefix}_owf_files — регистар на прикачени датотеки
• {prefix}_owf_log — audit trail на испраќањата

Плус Custom Post Type owf_form (не може јавно да се пребарува) што се користи за чување на шемите на формуларите.

---

Брз почеток

По активирањето, автоматски се создава стандарден "Контакт" формулар.

1. Одете на OW Forms → Forms во админ
2. Забележете го ID на стандардниот формулар (на пр. 1)
3. Во која било страница или објава, поставете го shortcode:

[owf_form id="1"]

…или вметнете го Gutenberg блокот OW Forms и изберете го формуларот од паѓачкото мени.

Тоа е сè. Формуларот се рендерира, прифаќа испраќања, испраќа админ е-пошта до admin_email, и го зачувува испраќањето во базата на податоци.

За да го прилагодите, отворете го формуларот во OW Forms → Forms → [Edit] и прилагодете ја директно JSON шемата. Визуелен градител е во v1.1 roadmap.

---

Типови на полиња

OW Forms поддржува 17 типови на полиња. Секое поле во шемата е објект со најмалку type и name; повеќето исто така прифаќаат label, help, required, placeholder, и опции специфични за типот.

Пример на шема

{
  "title": "Contact us",
  "fields": [
    {
      "type": "text",
      "name": "name",
      "label": "Your name",
      "required": true,
      "placeholder": "Jane Doe"
    },
    {
      "type": "email",
      "name": "email",
      "label": "Email",
      "required": true
    },
    {
      "type": "select",
      "name": "subject",
      "label": "How can we help?",
      "required": true,
      "options": [
        {"value": "quote",   "label": "Request a quote"},
        {"value": "support", "label": "Technical support"},
        {"value": "other",   "label": "Other"}
      ]
    },
    {
      "type": "textarea",
      "name": "message",
      "label": "Message",
      "required": true,
      "rows": 6
    }
  ],
  "submit": {
    "label": "Send",
    "success_message": "Thanks — we will reply within 24 hours.",
    "redirect_url": ""
  }
}

Вредностите name на полињата стануваат клучеви во зачуваниот payload и токени што може да ги користите во шаблоните за е-пошта ({{name}}, {{email}}, итн.).

---

Анти-спам стек

OW Forms извршува четири независни слоеви паралелно. Секој слој доделува придонес кон резултатот; испраќање со резултат ≥ 80 тивко се отфрла — не се враќа никаква порака за грешка, така што ботовите не можат да итерираат против заштитата.

1. Honeypot

Визуелно скриено текстуално поле што го пополнуваат ботовите, а луѓето не. Поставка:

• spam_honeypot_enabled (стандардно: true)

2. Time-trap

Ги одбива испраќањата завршени побрзо од конфигурабилен праг (типичните ботови прават POST моментално).

• spam_timetrap_enabled (стандардно: true)
• spam_timetrap_min_seconds (стандардно: 2)

3. CAPTCHA (повеќе провајдери)

Сервер-до-сервер валидација на токенот против API на провајдерот. Изберете еден од:

• turnstile — Cloudflare Turnstile (препорачано, приватност-прво, без challenge UX)
• recaptcha_v3 — Google reCAPTCHA v3 (невидлив)
• hcaptcha — hCaptcha (видлив widget)
• friendly_captcha — Friendly Captcha (self-hosted widget, MIT лиценциран, EU-friendly)

Поставете spam_captcha_provider, spam_captcha_site_key, и spam_captcha_secret_key во табот Анти-спам поставки. Стандардно е none.

Забелешка: JS на widget-ите Turnstile / reCAPTCHA / hCaptcha се вчитува од сопственото потекло на провајдерот (нивниот JS прави проверка на потпис на потеклото на серверот). Friendly Captcha е self-hosted под assets/js/vendor/.

4. IP репутација (опционално)

Кога OW Shield е инсталиран и активен, OW Forms ја користи неговата IP репутациска лента за да ги оценува испраќањата:

• spam_owshield_iprep (стандардно: true)
• spam_block_disposable_emails (стандардно: true) — одбива @mailinator, @tempmail, и ~120 други домени за еднократна употреба

Дополнителни хеуристики

• spam_min_words_per_text_area — бара најмалку N зборови во textareas
• spam_max_links_per_submission — одбива ако има повеќе од N URL-и во payload
• spam_blocklist_emails, spam_blocklist_words, spam_blocklist_ips — ваши сопствени списоци

Логирање

Секоја одлука за спам се логира со својата причина. Проверете OW Forms → Submissions → филтер "spam" за да ги дотерувате праговите без да летате слепо.

---

GDPR функционалности

GDPR усогласеноста е нативна. Стандардните вредности се конзервативни; разлабавете ги само ако имате правен совет за тоа.

Checkbox за пристанок

Checkbox за пристанок автоматски се вметнува на дното на секој формулар кога gdpr_consent_required е true (стандардно). Текстот е конфигурабилен:

'gdpr_consent_text' => __(
    'I agree that my data will be processed to respond to my inquiry, in accordance with the privacy policy.',
    'ow-forms'
)

Ако gdpr_auto_link_privacy е активен (стандардно), зборовите "privacy policy" / "политика за приватност" автоматски се поврзуваат со URL-то на политиката за приватност на OW Consent кога тој додаток е активен, или со вашата WP-конфигурирана страница за приватност во спротивно.

Режими за чување на IP

Поставка store_ip:

Чување на user agent

Поставка store_user_agent:

Задржување и чистење

Дневен cron ги чисти испраќањата постари од gdpr_retention_days (стандардно: 1095 денови — CNIL стандардот за податоци на потенцијални клиенти). Поставете на 0 за да го оневозможите автоматското чистење.

Ако gdpr_auto_delete_after_response е true, обележувањето на испраќање како "обработено" веднаш го брише заедно со сите прикачени датотеки.

DSAR — Пристап / бришење од субјектот на податоци

Е-поштите од формуларите се хешираат со wp_salt() при чувањето. Кога OW Consent е активен и се обработува DSAR бришење за е-пошта адреса, OW Forms автоматски ги брише соодветните испраќања по email_hash и активира:

do_action( 'owf_gdpr_erased_for_email', $hash, $count );

Без OW Consent, можете да го повикате бришењето рачно:

OWF_GDPR::erase_by_email( 'user@example.com' );  // returns int count

---

Известувања по е-пошта

Шаблони

И известувањето за админ и авто-одговорот за корисникот поддржуваат {{token}} замена:

Поставки

Прескокнување по формулар

Шемата на формуларот може да ги прескокне глобалните:

{
  "mail": {
    "recipient": "sales@example.com",
    "subject": "New lead — {{name}}",
    "body": "Lead: {{name}}\\nEmail: {{email}}\\nMessage: {{message}}",
    "autoreply": true,
    "autoreply_subject": "Thanks, {{name}}!",
    "autoreply_body": "Hi {{name}},\\n\\nWe got your message."
  }
}

---

Webhooks

Кога webhook_url е поставен, секое успешно испраќање активира HTTP POST.

Payload (JSON)

{
  "form_id": 1,
  "form_title": "Contact",
  "submission_id": 42,
  "received_at": "2026-05-13T14:32:18+00:00",
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "site": "https://example.com"
}

HMAC потпис

Ако webhook_secret е поставен, барањето вклучува:

X-OWF-Signature: sha256=<hex digest of HMAC-SHA256(body, secret)>

Верификација на страна на примачот (пример Node):

const expected = crypto
  .createHmac('sha256', SECRET)
  .update(rawBody)
  .digest('hex');
const provided = req.headers['x-owf-signature'].replace(/^sha256=/, '');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
  return res.status(401).end('bad sig');
}

Повторни обиди

Ако примачот враќа 5xx или истекува времето, OW Forms повторно обидува со експоненцијален backoff (60 s → 5 мин → 30 мин). По 3 неуспеси webhook-от се логира како трајно неуспешен, но не го блокира испраќањето.

---

Прикачување на датотеки

Кога allow_file_uploads е активен (стандардно true), секое поле од тип file се прифаќа. Pipeline-от:

1. Серверска валидација — големина на датотека (max_file_size_mb, стандардно 8 MB), allowlist на наставки (allowed_file_types), и finfo MIME проверка вкрстено-референцирана со wp_get_mime_types().
2. Чување — wp-content/uploads/owf-uploads/YYYY/MM/<sha256>.<ext> со deny-all .htaccess (Apache) и празен index.php (Nginx/IIS).
3. Регистар во база — метаподатоци на датотеката + SHA-256 хеш во {prefix}_owf_files, поврзан со ID на родителското испраќање.
4. Чистење — кога испраќање се брише (рачно, со задржување или со DSAR), сите поврзани датотеки се отстрануваат.

Важно: OW Forms користи прилагодена изолирана патека за прикачување, а не WordPress media библиотеката, така што прикачените датотеки не се откриваат преку стандардниот /wp-json/wp/v2/media endpoint и не се генерираат сликички. Ова е намерно — прилозите на формуларот се приватни за сопственикот на формуларот.

Дозволени типови на датотеки (стандардно)

pdf, jpg, jpeg, png, webp, doc, docx, xls, xlsx, csv, txt

За проширување:

add_filter( 'owf_settings', function( $s ) {
    $s['allowed_file_types'] = array_merge(
        (array) $s['allowed_file_types'],
        array( 'odt', 'ods', 'zip' )
    );
    return $s;
} );

---

Рендерирање

Shortcode

[owf_form id="42"]
[owf_form slug="contact"]

id (нумерички ID на објавата) или slug (slug на објавата) — едно е задолжително.

Gutenberg блок

Во уредникот на блокови, пребарајте "OW Forms" во вметнувачот на блокови и изберете го вашиот формулар од паѓачкото мени.

PHP

echo OWF_Form::render( 42 );
// or
echo do_shortcode( '[owf_form id="42"]' );

REST

Формуларот може и програмски да се испрати — видете REST API.

---

CF7 увозник

Ако Contact Form 7 е или беше инсталиран, OW Forms доаѓа со увозник со еден клик.

OW Forms → Tools → Import from Contact Form 7

Увозникот:

1. Скенира секоја објава wpcf7_contact_form во вашата база на податоци
2. Парсира секој CF7 формулар базиран на shortcode и ја гради еквивалентната OW Forms шема
3. Ги задржува примачот, темата, пораките за успех/грешка и типовите на полиња
4. Препишува секој shortcode [contact-form-7 id="..."] во сите ваши post_content (страници, објави, custom post types) во [owf_form id="..."]
5. Логира резултати: пронајдени формулари, увезени, прескокнати (веќе увезени)

CF7 додатокот потоа може да се деактивира и отстрани.

Увозникот е идемпотентен: извршувањето двапати не создава дупликати. Веќе увезените CF7 формулари се обележуваат преку meta key _owf_imported_from_cf7 и се прескокнуваат при последователни извршувања.

---

Референца на поставки

Сите поставки се чуваат во еден клуч за опција, owf_settings. Можете да ги читате или прескокнувате програмски:

$value = OWF_Core::setting( 'spam_timetrap_min_seconds' );
OWF_Core::update_settings( array( 'spam_timetrap_min_seconds' => 3 ) );

Целосни стандардни вредности

array(
    // General
    'default_recipient_email'        => '',     // empty = admin_email
    'from_name'                      => '',
    'from_email'                     => '',
    'sender_uses_dpo'                => true,

    // Anti-spam
    'spam_honeypot_enabled'          => true,
    'spam_timetrap_enabled'          => true,
    'spam_timetrap_min_seconds'      => 2,
    'spam_captcha_provider'          => 'none',
    'spam_captcha_site_key'          => '',
    'spam_captcha_secret_key'        => '',
    'spam_owshield_iprep'            => true,
    'spam_block_disposable_emails'   => true,
    'spam_min_words_per_text_area'   => 0,
    'spam_max_links_per_submission'  => 3,
    'spam_blocklist_emails'          => array(),
    'spam_blocklist_words'           => array(),
    'spam_blocklist_ips'             => array(),

    // GDPR
    'gdpr_consent_required'          => true,
    'gdpr_consent_text'              => '...',
    'gdpr_auto_link_privacy'         => true,
    'gdpr_retention_days'            => 1095,
    'gdpr_auto_delete_after_response' => false,

    // Storage
    'store_submissions'              => true,
    'store_ip'                       => 'pseudonymized',
    'store_user_agent'               => 'hashed',
    'allow_file_uploads'             => true,
    'max_file_size_mb'               => 8,
    'allowed_file_types'             => array( 'pdf', 'jpg', 'jpeg', 'png',
                                                'webp', 'doc', 'docx', 'xls',
                                                'xlsx', 'csv', 'txt' ),

    // Notifications
    'mail_html'                      => true,
    'mail_admin_subject'             => '[{{site_name}}] New message via {{form_title}}',
    'mail_admin_body'                => '',
    'mail_user_autoreply_enabled'    => true,
    'mail_user_subject'              => 'We have received your message',
    'mail_user_body'                 => '',
    'mail_failed_alert_email'        => '',
    'webhook_url'                    => '',
    'webhook_secret'                 => '',

    // Rendering
    'style_preset'                   => 'auto',
    'button_label_default'           => 'Send',
    'success_message_default'        => 'Your message has been sent. We will reply within 24 hours.',
    'error_message_default'          => 'An error occurred. Please try again or contact us directly.',
    'inherit_theme_tokens'           => true,

    // Analytics (opt-in)
    'track_conversions'              => false,
    'conversion_event_name'          => 'generate_lead',
    'conversion_value'               => 0,
    'conversion_currency'            => 'EUR',
);

---

REST API

Сите endpoint-и живеат под namespace owf/v1.

Јавен endpoint

Body:

{
  "form_id": 1,
  "fields": { "name": "Jane", "email": "jane@example.com", "message": "Hi" },
  "_owf_nonce": "<from wp_create_nonce('owf_submit_form')>",
  "_owf_time": 1736780000,
  "_owf_hp": ""
}

Одговор (200):

{ "ok": true, "id": 42, "message": "Your message has been sent." }

Одговор (422) кога валидацијата пропаѓа:

{
  "ok": false,
  "errors": { "email": "Please enter a valid email" },
  "message": "Please review the fields in error."
}

Админ endpoint-и (бараат manage_options)

Сите админ endpoint-и бараат и capability manage_options и валиден WP REST nonce.

---

Hooks (filters & actions)

Actions

/**
 * Fires after a submission has been processed and stored.
 *
 * @param int   $submission_id  Database ID (0 if not stored)
 * @param int   $form_id        Form ID
 * @param array $cleaned        Sanitized field payload
 * @param array $schema         Full form schema
 */
do_action( 'owf_submission_received', $submission_id, $form_id, $cleaned, $schema );

/**
 * Fires after a DSAR erasure has deleted matching submissions by email hash.
 *
 * @param string $email_hash   SHA-256(email + wp_salt())
 * @param int    $deleted_count
 */
do_action( 'owf_gdpr_erased_for_email', $email_hash, $deleted_count );

Filters

/**
 * Filter the resolved settings array (merged defaults + saved + per-request).
 */
apply_filters( 'owf_settings', array $settings );

/**
 * Whitelist of trusted reverse proxy IPs that may set X-Forwarded-For.
 * Without this OW Forms ignores proxy headers (to prevent IP spoofing).
 */
apply_filters( 'owf_trusted_proxies', array $proxies );

/**
 * List of disposable email domains rejected when `spam_block_disposable_emails`
 * is on.
 */
apply_filters( 'owf_disposable_domains', array $domains );

Препорачан pattern — прошири го списокот на еднократни домени

add_filter( 'owf_disposable_domains', function( $list ) {
    return array_merge( $list, array(
        'example-throwaway.com',
        'company-blocked-domain.net',
    ) );
} );

Препорачан pattern — испратете испраќања во CRM

add_action( 'owf_submission_received', function( $sid, $form_id, $cleaned ) {
    if ( $form_id !== 7 ) return;  // only the "Sales" form
    wp_remote_post( 'https://crm.example.com/leads', array(
        'headers' => array( 'Authorization' => 'Bearer ' . CRM_TOKEN ),
        'body'    => wp_json_encode( array(
            'email'   => $cleaned['email'],
            'name'    => $cleaned['name'],
            'message' => $cleaned['message'],
            'source'  => 'website-form',
        ) ),
        'headers' => array( 'Content-Type' => 'application/json' ),
    ) );
}, 10, 3 );

---

Интеграции

OW Canvas (тема)

Кога темата OW Canvas е активна, OW Forms ги наследува нејзините CSS прилагодени својства (--owc-ink, --owc-paper, --owc-accent, итн.) за визуелна конзистентност. Оневозможи со inherit_theme_tokens = false.

OW Consent

Кога OW Consent е активен:

• Линкот на checkbox за GDPR пристанок автоматски се насочува кон URL-то на вашата политика за приватност во OW Consent
• Испраќањата се поврзани со OW Consent записите (кога посетителот има cookie со ID за пристанок)
• DSAR бришечките текови од OW Consent автоматски ги чистат OW Forms испраќањата за истиот хеш на е-пошта

OW Shield

Кога OW Shield е активен и spam_owshield_iprep е вклучен, IP-то на секое испраќање се оценува против репутациската лента на OW Shield пред да биде прифатено.

---

Интернационализација

Изворниот јазик е англиски. Француски превод се испорачува под languages/ow-forms-fr_FR.po.

За преведувачи

.pot шаблонот е во languages/ow-forms.pot. Поднесете преводи преку translate.wordpress.org/projects/wp-plugins/ow-forms откако додатокот ќе биде одобрен на WP.org. За локална дистрибуција, ставете ow-forms-<locale>.mo во папката languages/.

Компајлирање на .mo локално

msgfmt languages/ow-forms-fr_FR.po -o languages/ow-forms-fr_FR.mo

---

Решавање проблеми

Формуларот се испраќа но не пристигнува е-пошта

1. Проверете дали вашиот сајт може воопшто да испраќа пошта — пробајте тест од контакт формуларот на која било друга додаток или со Mail Tester
2. Проверете OW Forms → Submissions за да потврдите дека испраќањето пристигна (ако да, проблемот е во испораката, а не во OW Forms)
3. Поставете mail_failed_alert_email на вашата адреса — OW Forms ќе ви испрати е-пошта кога wp_mail() ќе врати false
4. Инсталирајте SMTP додаток (Fluent SMTP, WP Mail SMTP, итн.) — стандардната PHP mail() функција се одбива од 95 % на серверите што примаат

CAPTCHA не се појавува

• Проверете дали spam_captcha_site_key и spam_captcha_secret_key се двата поставени
• Отворете ја страницата во DevTools — URL-то на vendor скриптата треба да се вчита со 200
• За reCAPTCHA, доменот на вашиот сајт мора да биде регистриран во Google админ
• За Turnstile, режимот на widget во Cloudflare админ мора да биде "Managed" или "Non-interactive"

Датотеките се прикачуваат но админот не може да ги преземе

Тоа е по дизајн — прикачените датотеки се сервираат од автентициран PHP handler, а не директно. Проверете дали сте најавени како корисник со manage_options.

CF7 увозникот вели "0 формулари пронајдени"

Увозникот го скенира post type wpcf7_contact_form. Ако CF7 е веќе деактивиран и објавите се избришани, нема ништо повеќе за увоз. Реактивирајте го CF7 само за увозот, потоа деактивирајте повторно.

Табелата за испраќања е огромна

• Намалете го gdpr_retention_days (стандардно 1095 / 3 години)
• Оневозможете го store_submissions ако ви треба само испорака на е-пошта, а не audit trail во база
• Поставете gdpr_auto_delete_after_response = true за бришење при "обработено"

---

ЧПП

Дали OW Forms е бесплатен? Да. GPL-2.0-or-later. Нема Pro верзија, нема лиценцен клуч, нема функција заклучена зад плаќање.

Дали работи на WordPress Multisite? Да — секој сајт има свои табели и библиотека на формулари, изолирани како што се очекува.

Дали поддржува формулари со повеќе чекори? Основната навигација следно/претходно работи преку групирање на полињата во шемата. Прворазредно wizard UX искуство е во v1.1 roadmap.

Како ги извезувам испраќањата? OW Forms → Submissions → Export CSV. Извозот ги почитува тековните филтри (формулар, опсег на датуми, статус).

Можам ли да ги хостирам формуларите зад paywall или најава? Да — обвиткајте го shortcode во gating логиката на кој било додаток за членство, или рендерирајте преку PHP внатре во проверка is_user_logged_in().

Се интегрира ли со алатки за е-пошта маркетинг / CRM? Од кутија: webhook-ови (HMAC потпишан POST до кој било endpoint), и примачи на е-пошта по формулар. За Brevo / Mailchimp / HubSpot / Pipedrive, hook-нете owf_submission_received и повикајте го REST API на провајдерот — видете го делот Hooks.

Дали додатокот е сертифициран за GDPR? Стандардните вредности на додатокот се усогласени со најдобрите практики на CNIL / GDPR, но сертификацијата е правен процес специфичен за вашата поставка на контролор на податоци. Ние ги обезбедуваме техничките алатки; вашиот DPO ја потврдува политиката.

Каде е поддршката?

• Портал за поддршка: https://optionweb.dev/mk/addons/support/
• Е-пошта: support@optionweb.dev
• Документација: https://optionweb.dev/mk/addons/ow-forms/

---

Изградено од OptionWeb — Julien Daniel, Châtelet, Белгија.