OrderComments

Let customers tell you exactly what they need — before the order is placed. BlueFairy Order Comments adds a configurable dropdown and free-text field to your Magento 2 checkout, capturing special instructions, order types, and fulfilment preferences at the point of sale. No back-and-forth emails. No missed requirements. Just clean, structured order data that flows straight to your team.

---

Two Comment Fields, Fully Configurable

Choose one or both comment fields — each independently enabled, labelled, and controlled per store view.

• Dropdown Comment — Pre-defined options you control. Use it for order types ("Express Handling", "Bulk Order", "Gift"), fulfilment preferences, or any structured categorisation your team needs to filter and action orders. Options are configurable per store view with custom values and labels.
• Text Comment — Free-form textarea for customer instructions. Configure the label, set a character limit (or remove it entirely), and mark it required if you need it. A live character counter updates on every keystroke. Multibyte-aware — works correctly with emoji, CJK, and Arabic characters.

Both fields are optional by default. Mark either required to gate the Place Order button — useful when structured input is non-negotiable for your fulfilment process.

Appears Everywhere It Should

Comments entered at checkout flow through the entire order lifecycle automatically.

• Checkout — Payment step, before the Place Order button (Luma and Hyva)
• Cart page — Optional early capture with debounced auto-save (Hyva)
• Admin order detail — Dedicated "Order Comments" section (hidden when empty)
• Admin order grid — Sortable, filterable columns for both fields — with a database index on the dropdown column for fast filtering at scale
• Order confirmation email — After order totals, in both customer and guest templates
• Customer account — My Orders → View Order, with ownership validation

Hyva Theme — Alpine.js, No Page Reload

The companion BlueFairy_OrderCommentsHyva module delivers a fully reactive Hyva checkout experience using Alpine.js.

• Integrates via the official Hyva checkout:payment:before-submit event bus
• Character counter updates reactively on each keystroke
• Cart page save is debounced (800ms) with "Saving…" → "Saved" feedback states
• Styled with Tailwind CSS utility classes — consistent with your theme out of the box
• Zero custom JavaScript beyond the Alpine component — no RequireJS, no jQuery

GraphQL & REST — Fully Headless Ready

The companion BlueFairy_OrderCommentsGraphQl module exposes both fields to headless and PWA storefronts.

• Write via setPaymentMethodOnCart — pass order_comment_dropdown and order_comment_text as optional input fields alongside your payment method. Works for both logged-in and guest carts.
• Read via customerOrders — both comment fields are returned on every order item automatically.
• Full REST API support via extension attributes on PaymentInterface (write) and OrderInterface (read)
• Server-side validation — strip_tags, character limit enforcement — applied on every API path

---

Secure by Default

• Ownership validation — Customer order detail verifies the order belongs to the logged-in customer before rendering comments
• HTML sanitization — strip_tags() applied in both the checkout plugin and the quote→order observer (dual-pass defensive approach)
• Output escaping — escapeHtml() on all frontend and admin output; nl2br(escapeHtml()) preserves line breaks safely
• CSRF protection — Cart save AJAX endpoint validates form key
• ACL — Admin configuration locked behind BlueFairy_OrderComments::config resource

Production-Grade Test Coverage

Tested at every layer of the stack — not just happy paths.

• Unit tests — All plugins, observers, ViewModels, and config provider covered with PHPUnit mocks
• Integration tests — Real database: quote→order persistence, OrderRepository extension attributes, ViewModel ownership validation
• MFTF functional tests — Luma checkout (dropdown, text, both fields, required validation, guest checkout, admin grid filtering)
• Playwright tests — Hyva checkout, GraphQL mutation + query, guest checkout, cross-browser (Chromium, Firefox, WebKit)

---

Technical Highlights

• Three-module architecture — Core, Hyva, and GraphQL as separate composable packages
• Declarative DB schema — db_schema.xml with BTREE index on dropdown column for admin grid performance
• Observer-based transfer — Single observer on sales_model_service_quote_submit_before covers all checkout flows (standard, PayPal Express, headless)
• ViewModel pattern — No logic in templates; all data resolution in typed ViewModel classes
• Store view scoped — All config (labels, options, limits) configurable independently per store
• PHP 8.3+, strict types, PSR-12, full constructor injection
• Magento 2.4.x compatible

Configuration at a Glance

All settings at Stores → Configuration → Sales → Checkout → Order Comments:

• Master enable/disable switch
• Show on cart page toggle (Hyva)
• Dropdown: enable, required, label, placeholder, option rows (value + label per row)
• Text: enable, required, label, character limit (0 = unlimited)

Installation Requirements

• Magento 2.4.x
• PHP 8.3+
• BlueFairy_OrderCommentsHyva — requires Hyva theme
• BlueFairy_OrderCommentsGraphQl — requires Magento_GraphQl

Three Composer Packages

• bluefairy/module-order-comments — Core (Luma + REST)
• bluefairy/module-order-comments-hyva — Hyva theme companion
• bluefairy/module-order-comments-graph-ql — GraphQL companion