Kowal_CheckoutComment

Description

Kowal_CheckoutComment adds a customer comment field to Magento 2 checkout, persists the value on quote and order, exposes it in the Admin order grid, and injects it into email template variables as order_comment.

Target Audience

  • Magento developers implementing custom checkout data flow
  • DevOps/release engineers deploying modules with checkout and database schema changes
  • Store administrators configuring checkout comment behavior per scope

Features

  • Adds checkout UI component under checkout payment section (afterMethods) via LayoutProcessor plugin.
  • Uses frontend mixin for Magento_Checkout/js/action/place-order to pass checkout_comment to payment extension attributes.
  • Declares extension attributes for:
    • Magento\Quote\Api\Data\PaymentInterface
    • Magento\Quote\Api\Data\CartInterface
    • Magento\Sales\Api\Data\OrderInterface
  • Persists comment to quote through plugins on:
    • Magento\Quote\Api\PaymentMethodManagementInterface::savePaymentInformationAndPlaceOrder
    • Magento\Quote\Model\PaymentMethodManagement::set
    • Magento\Quote\Model\QuoteRepository::save
  • Copies comment from quote to order in observer for sales_model_service_quote_submit_before.
  • Adds checkout_comment columns in DB (declarative schema) for:
    • quote
    • sales_order
    • sales_order_grid
  • Extends order grid resource model column mapping and adds UI grid column in Admin.
  • Adds Data Patch that marks order attribute grid-enabled and backfills sales_order_grid.checkout_comment from sales_order.
  • Adds order_comment variable to order emails through plugins on SenderBuilder, TransportBuilder, and TransportBuilderByStore.
  • Optional fallback for email comment source from order status history controlled by config flag checkout_comment/general/all_frontend_comments.

Installation

* = in production please use the --keep-generated option

Type: Composer

  1. Add the composer repository to the configuration:

    
composer config repositories.checkout.comment vcs https://github.com/kowalco/magento-2-checkout-comment

  2. Add an access token for the private GitLab repository:

    
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>

  3. Install the module using Composer:

    
composer require kowal/module-checkoutcomment

  4. Enable the module:

    
php bin/magento module:enable Kowal_CheckoutComment

  5. Apply database updates:

    
php bin/magento setup:upgrade

  6. Flush the cache:

    
php bin/magento cache:flush

Configuration

  • Admin path (system config): Stores > Configuration > kowal > Checkout Comment (section id: checkout_comment, group: general).
  • Fields:
    • checkout_comment/general/enable (Yes/No)
    • checkout_comment/general/all_frontend_comments (Yes/No)
  • Scope availability in system.xml: default, website, store view (all enabled).
  • Runtime read scope in helper: store scope (ScopeInterface::SCOPE_STORE).
  • Default values (etc/config.xml):
    • enable = 1
    • all_frontend_comments = 0
  • Admin menu entries are defined in etc/adminhtml/menu.xml (including parent under Kowal_Base::kowal_modules).
  • ACL note: this module references ACL resources (Kowal_CheckoutComment::config, ::root, ::general) but does not provide etc/acl.xml locally.

Deployment and Operations

  • Run php bin/magento setup:upgrade for declarative schema + data patch execution.
  • Run php bin/magento setup:di:compile in production mode (plugins, extension attributes, interceptors).
  • Run static content deployment in production mode to publish frontend assets from view/frontend.
  • Flush caches after deployment (config, layout, block_html, full page cache as needed).
  • Verify checkout rendering:
    • Checkout payment step displays comment textarea.
    • Placing order with comment stores value on order.
  • Verify Admin:
    • Sales order grid contains Checkout Comment column.
  • Verify email templates:
    • order_comment variable is available (template snippet is provided in README Configuration section).

Deployment Checklist

  • Module package installed through Composer.
  • Module enabled (Kowal_CheckoutComment).
  • setup:upgrade executed successfully.
  • DB columns exist in quote, sales_order, sales_order_grid.
  • Data patch AddCheckoutCommentToGrid applied.
  • DI compilation and static content deployment completed (production).
  • Cache flushed.
  • Config reviewed per required scope (default/website/store view).
  • Checkout comment persisted from storefront to order.
  • Order grid and email variables validated.
  • Dependency kowal/base present and active.

CI/CD and Environments

  • No custom cron jobs, message queue consumers, or custom indexers are defined in this module.
  • Recommended pipeline steps:
    • composer install
    • php bin/magento module:enable Kowal_CheckoutComment (when not pre-enabled)
    • php bin/magento setup:upgrade
    • php bin/magento setup:di:compile (production)
    • php bin/magento setup:static-content:deploy (production)
    • php bin/magento cache:flush
  • Environment validation should include end-to-end checkout + email template smoke tests.

Rollback

  • Code rollback: revert Composer package version and deploy previous lockfile.
  • Database note: this module introduces schema columns; rollback requires explicit migration strategy if removing module.
  • After rollback, run standard Magento deployment commands (setup:upgrade, cache refresh) according to target state.

Requirements / Notes

  • Composer dependency: kowal/base.
  • Module sequence dependency: Magento_Checkout.
  • Email template rendering requires template-level usage of order_comment; module only injects variable.
  • Source contains extensive debug logging (error/debug) in checkout and email plugins.
  • Observer/Frontend/Checkout/SubmitAllAfter.php exists but is not wired in etc/events.xml.
  • Data model includes both declarative schema (db_schema.xml) and data patch logic for grid-related behavior.

Compatibility

  • Module type: Magento 2 module (type: magento2-module).
  • No explicit Magento version constraint is declared in this package.
  • Frontend implementation targets standard Magento 2 Knockout checkout architecture.

FAQ

Is there only Composer-based installation?

Yes. README provides only Composer installation flow.

Where exactly is config scope controlled?

system.xml exposes default/website/store view. Runtime checks use store scope reads.

Does this module define its own ACL file?

No etc/acl.xml is present in this module.

Does the module define cron, queue, or custom indexers?

No custom cron, queue, or indexer definitions were found.

Are there any gaps that require manual verification?

Yes:

  • README installation code blocks are not properly closed in source text.
  • README mentions a "private GitLab repository" while command targets GitHub OAuth and GitHub URL.
  • Because ACL definitions are not present locally, permissions behavior should be verified in target environment.