@mytechtoday/augment-extensions 0.1.1 → 0.2.0

package/augment-extensions/domain-rules/wordpress/rules/woocommerce.md

@@ -0,0 +1,441 @@
+# WooCommerce Customization Workflow
+
+## Overview
+
+This document provides workflows for customizing WooCommerce, the most popular WordPress eCommerce plugin.
+
+## Workflow 1: Template Overrides
+
+### Step 1: Locate WooCommerce Template
+
+WooCommerce templates are located in:
+```
+wp-content/plugins/woocommerce/templates/
+```
+
+Common templates:
+- `single-product.php` - Single product page
+- `archive-product.php` - Product archive
+- `cart/cart.php` - Shopping cart
+- `checkout/form-checkout.php` - Checkout form
+- `myaccount/my-account.php` - My Account page
+
+### Step 2: Copy Template to Theme
+
+Create directory structure in your theme:
+```
+your-theme/
+└── woocommerce/
+    ├── single-product.php
+    ├── archive-product.php
+    ├── cart/
+    │   └── cart.php
+    └── checkout/
+        └── form-checkout.php
+```
+
+Copy the template from WooCommerce plugin to your theme:
+```bash
+cp wp-content/plugins/woocommerce/templates/single-product.php \
+   wp-content/themes/your-theme/woocommerce/single-product.php
+```
+
+### Step 3: Customize Template
+
+Edit the copied template in your theme. WordPress will use your theme's version instead of the plugin's version.
+
+**Example - Customize single product title**:
+```php
+<?php
+/**
+ * Single Product Title
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+    exit;
+}
+
+the_title( '<h1 class="product_title entry-title custom-product-title">', '</h1>' );
+```
+
+## Workflow 2: Add Custom Product Fields
+
+### Step 1: Add Custom Field to Product
+
+**functions.php**:
+```php
+/**
+ * Add custom field to product general tab
+ */
+function add_custom_product_field() {
+    woocommerce_wp_text_input(
+        array(
+            'id'          => '_custom_product_field',
+            'label'       => __( 'Custom Field', 'your-theme' ),
+            'placeholder' => __( 'Enter custom value', 'your-theme' ),
+            'desc_tip'    => true,
+            'description' => __( 'This is a custom field.', 'your-theme' ),
+        )
+    );
+}
+add_action( 'woocommerce_product_options_general_product_data', 'add_custom_product_field' );
+```
+
+### Step 2: Save Custom Field
+
+```php
+/**
+ * Save custom field value
+ */
+function save_custom_product_field( $post_id ) {
+    $custom_field = isset( $_POST['_custom_product_field'] ) ? sanitize_text_field( $_POST['_custom_product_field'] ) : '';
+    update_post_meta( $post_id, '_custom_product_field', $custom_field );
+}
+add_action( 'woocommerce_process_product_meta', 'save_custom_product_field' );
+```
+
+### Step 3: Display Custom Field on Frontend
+
+```php
+/**
+ * Display custom field on product page
+ */
+function display_custom_product_field() {
+    global $post;
+    
+    $custom_field = get_post_meta( $post->ID, '_custom_product_field', true );
+    
+    if ( $custom_field ) {
+        echo '<div class="custom-product-field">';
+        echo '<strong>' . esc_html__( 'Custom Field:', 'your-theme' ) . '</strong> ';
+        echo esc_html( $custom_field );
+        echo '</div>';
+    }
+}
+add_action( 'woocommerce_single_product_summary', 'display_custom_product_field', 25 );
+```
+
+## Workflow 3: Customize Checkout
+
+### Add Custom Checkout Field
+
+```php
+/**
+ * Add custom field to checkout
+ */
+function add_custom_checkout_field( $fields ) {
+    $fields['billing']['billing_custom_field'] = array(
+        'type'        => 'text',
+        'label'       => __( 'Custom Field', 'your-theme' ),
+        'placeholder' => __( 'Enter value', 'your-theme' ),
+        'required'    => true,
+        'class'       => array( 'form-row-wide' ),
+        'clear'       => true,
+        'priority'    => 100,
+    );
+    
+    return $fields;
+}
+add_filter( 'woocommerce_checkout_fields', 'add_custom_checkout_field' );
+```
+
+### Validate Custom Checkout Field
+
+```php
+/**
+ * Validate custom checkout field
+ */
+function validate_custom_checkout_field() {
+    if ( empty( $_POST['billing_custom_field'] ) ) {
+        wc_add_notice( __( 'Please enter a value for Custom Field.', 'your-theme' ), 'error' );
+    }
+}
+add_action( 'woocommerce_checkout_process', 'validate_custom_checkout_field' );
+```
+
+### Save Custom Checkout Field
+
+```php
+/**
+ * Save custom checkout field to order meta
+ */
+function save_custom_checkout_field( $order_id ) {
+    if ( ! empty( $_POST['billing_custom_field'] ) ) {
+        update_post_meta( $order_id, '_billing_custom_field', sanitize_text_field( $_POST['billing_custom_field'] ) );
+    }
+}
+add_action( 'woocommerce_checkout_update_order_meta', 'save_custom_checkout_field' );
+```
+
+### Display Custom Field in Admin Order
+
+```php
+/**
+ * Display custom field in admin order
+ */
+function display_custom_field_in_admin_order( $order ) {
+    $custom_field = get_post_meta( $order->get_id(), '_billing_custom_field', true );
+    
+    if ( $custom_field ) {
+        echo '<p><strong>' . esc_html__( 'Custom Field:', 'your-theme' ) . '</strong> ' . esc_html( $custom_field ) . '</p>';
+    }
+}
+add_action( 'woocommerce_admin_order_data_after_billing_address', 'display_custom_field_in_admin_order' );
+```
+
+## Workflow 4: Customize Email Templates
+
+### Step 1: Copy Email Template to Theme
+
+Create directory structure:
+```
+your-theme/
+└── woocommerce/
+    └── emails/
+        ├── customer-completed-order.php
+        └── admin-new-order.php
+```
+
+Copy template:
+```bash
+cp wp-content/plugins/woocommerce/templates/emails/customer-completed-order.php \
+   wp-content/themes/your-theme/woocommerce/emails/customer-completed-order.php
+```
+
+### Step 2: Customize Email Template
+
+Edit the template to add custom content:
+
+```php
+<?php
+/**
+ * Customer completed order email
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+    exit;
+}
+
+do_action( 'woocommerce_email_header', $email_heading, $email );
+
+?>
+
+<p><?php esc_html_e( 'Hi there. Your order has been completed!', 'your-theme' ); ?></p>
+
+<!-- Custom content here -->
+<div class="custom-email-section">
+    <h2><?php esc_html_e( 'Thank you for your purchase!', 'your-theme' ); ?></h2>
+    <p><?php esc_html_e( 'We appreciate your business.', 'your-theme' ); ?></p>
+</div>
+
+<?php
+
+do_action( 'woocommerce_email_order_details', $order, $sent_to_admin, $plain_text, $email );
+do_action( 'woocommerce_email_order_meta', $order, $sent_to_admin, $plain_text, $email );
+do_action( 'woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email );
+do_action( 'woocommerce_email_footer', $email );
+```
+
+### Step 3: Add Custom Content to Emails
+
+```php
+/**
+ * Add custom content to order emails
+ */
+function add_custom_email_content( $order, $sent_to_admin, $plain_text, $email ) {
+    if ( $plain_text ) {
+        echo "\n" . __( 'Custom message for plain text emails', 'your-theme' ) . "\n";
+    } else {
+        echo '<div class="custom-email-content">';
+        echo '<p>' . esc_html__( 'Custom message for HTML emails', 'your-theme' ) . '</p>';
+        echo '</div>';
+    }
+}
+add_action( 'woocommerce_email_before_order_table', 'add_custom_email_content', 10, 4 );
+```
+
+## Workflow 5: Payment Gateway Integration
+
+### Create Custom Payment Gateway
+
+**includes/class-custom-gateway.php**:
+```php
+<?php
+/**
+ * Custom Payment Gateway
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+    exit;
+}
+
+class WC_Custom_Gateway extends WC_Payment_Gateway {
+    
+    /**
+     * Constructor
+     */
+    public function __construct() {
+        $this->id                 = 'custom_gateway';
+        $this->icon               = '';
+        $this->has_fields         = true;
+        $this->method_title       = __( 'Custom Gateway', 'your-theme' );
+        $this->method_description = __( 'Custom payment gateway description', 'your-theme' );
+        
+        // Load settings
+        $this->init_form_fields();
+        $this->init_settings();
+        
+        // Get settings
+        $this->title       = $this->get_option( 'title' );
+        $this->description = $this->get_option( 'description' );
+        $this->enabled     = $this->get_option( 'enabled' );
+        
+        // Actions
+        add_action( 'woocommerce_update_options_payment_gateways_' . $this->id, array( $this, 'process_admin_options' ) );
+    }
+    
+    /**
+     * Initialize form fields
+     */
+    public function init_form_fields() {
+        $this->form_fields = array(
+            'enabled' => array(
+                'title'   => __( 'Enable/Disable', 'your-theme' ),
+                'type'    => 'checkbox',
+                'label'   => __( 'Enable Custom Gateway', 'your-theme' ),
+                'default' => 'no',
+            ),
+            'title' => array(
+                'title'       => __( 'Title', 'your-theme' ),
+                'type'        => 'text',
+                'description' => __( 'Payment method title', 'your-theme' ),
+                'default'     => __( 'Custom Payment', 'your-theme' ),
+                'desc_tip'    => true,
+            ),
+            'description' => array(
+                'title'       => __( 'Description', 'your-theme' ),
+                'type'        => 'textarea',
+                'description' => __( 'Payment method description', 'your-theme' ),
+                'default'     => __( 'Pay with custom gateway', 'your-theme' ),
+            ),
+        );
+    }
+    
+    /**
+     * Process payment
+     */
+    public function process_payment( $order_id ) {
+        $order = wc_get_order( $order_id );
+        
+        // Process payment here
+        // ...
+        
+        // Mark order as processing or completed
+        $order->payment_complete();
+        
+        // Reduce stock levels
+        wc_reduce_stock_levels( $order_id );
+        
+        // Remove cart
+        WC()->cart->empty_cart();
+        
+        // Return success
+        return array(
+            'result'   => 'success',
+            'redirect' => $this->get_return_url( $order ),
+        );
+    }
+}
+```
+
+### Register Payment Gateway
+
+**functions.php**:
+```php
+/**
+ * Add custom payment gateway
+ */
+function add_custom_payment_gateway( $gateways ) {
+    $gateways[] = 'WC_Custom_Gateway';
+    return $gateways;
+}
+add_filter( 'woocommerce_payment_gateways', 'add_custom_payment_gateway' );
+
+/**
+ * Load custom gateway class
+ */
+function load_custom_gateway_class() {
+    require_once get_template_directory() . '/includes/class-custom-gateway.php';
+}
+add_action( 'plugins_loaded', 'load_custom_gateway_class' );
+```
+
+## Workflow 6: Customize Product Loop
+
+### Modify Products Per Page
+
+```php
+/**
+ * Change number of products per page
+ */
+function custom_products_per_page( $cols ) {
+    return 12;
+}
+add_filter( 'loop_shop_per_page', 'custom_products_per_page', 20 );
+```
+
+### Modify Product Loop Columns
+
+```php
+/**
+ * Change number of product columns
+ */
+function custom_product_columns( $columns ) {
+    return 4;
+}
+add_filter( 'loop_shop_columns', 'custom_product_columns' );
+```
+
+### Add Custom Content to Product Loop
+
+```php
+/**
+ * Add custom badge to products on sale
+ */
+function add_sale_badge() {
+    global $product;
+    
+    if ( $product->is_on_sale() ) {
+        echo '<span class="sale-badge">' . esc_html__( 'Sale!', 'your-theme' ) . '</span>';
+    }
+}
+add_action( 'woocommerce_before_shop_loop_item_title', 'add_sale_badge', 10 );
+```
+
+## Best Practices
+
+### DO
+
+✅ Use child themes for customizations  
+✅ Copy templates to theme, don't modify plugin files  
+✅ Use WooCommerce hooks and filters  
+✅ Sanitize and validate all input  
+✅ Escape all output  
+✅ Test with WooCommerce updates  
+✅ Follow WooCommerce coding standards  
+✅ Use translation functions  
+✅ Check WooCommerce is active before using functions  
+✅ Document customizations
+
+### DON'T
+
+❌ Modify WooCommerce plugin files directly  
+❌ Ignore template version compatibility  
+❌ Skip input validation  
+❌ Hardcode values  
+❌ Use deprecated WooCommerce functions  
+❌ Forget to test checkout process  
+❌ Ignore mobile responsiveness  
+❌ Skip security best practices  
+❌ Forget to handle edge cases
+

package/augment-extensions/domain-rules/wordpress-plugin/README.md

@@ -0,0 +1,139 @@
+# WordPress Plugin Development Module
+
+## Overview
+
+This module provides comprehensive guidelines for WordPress plugin development, optimized for AI-assisted development workflows in VS Code using Augment Code AI, OpenSpec, and Beads task management.
+
+## Key Benefits
+
+- **Plugin Structure Detection**: Automatically detect WordPress plugin projects and apply appropriate guidelines
+- **Architecture Patterns**: 7 proven plugin architecture patterns from simple procedural to enterprise-level
+- **Security First**: Built-in security best practices (nonces, sanitization, escaping, capability checks)
+- **Performance Optimized**: Caching strategies, query optimization, and performance guidelines
+- **WordPress.org Ready**: Submission preparation and compliance guidelines
+- **AI-Assisted Development**: Optimized for AI code generation with clear patterns and examples
+
+## Installation
+
+### With CLI (Future)
+```bash
+augx link domain-rules/wordpress-plugin
+```
+
+### Manual Installation
+Copy the contents of this module to your project's `.augment/` directory or reference it from the Augment Extensions repository.
+
+## Directory Structure
+
+```
+augment-extensions/domain-rules/wordpress-plugin/
+├── module.json                          # Module metadata
+├── README.md                            # This file
+├── rules/                               # Detailed guidelines
+│   ├── plugin-structure.md              # Plugin detection and structure
+│   ├── plugin-architecture.md           # Architecture patterns
+│   ├── activation-hooks.md              # Activation/deactivation/uninstall
+│   ├── admin-interface.md               # Settings pages, meta boxes
+│   ├── frontend-functionality.md        # CPT, taxonomies, shortcodes, widgets
+│   ├── gutenberg-blocks.md              # Block development
+│   ├── rest-api.md                      # REST API endpoints
+│   ├── ajax-handlers.md                 # AJAX implementation
+│   ├── database-management.md           # Custom tables, queries
+│   ├── cron-jobs.md                     # Scheduled tasks
+│   ├── security-best-practices.md       # Security guidelines
+│   ├── performance-optimization.md      # Performance best practices
+│   ├── internationalization.md          # i18n/l10n
+│   ├── asset-management.md              # Scripts and styles
+│   ├── woocommerce-integration.md       # WooCommerce extensions
+│   ├── testing-patterns.md              # PHPUnit, integration tests
+│   ├── documentation-standards.md       # PHPDoc, readme.txt
+│   └── wordpress-org-submission.md      # Submission process
+└── examples/                            # Complete code examples
+    ├── simple-procedural-plugin.md
+    ├── object-oriented-plugin.md
+    ├── mvc-plugin.md
+    ├── singleton-plugin.md
+    ├── custom-post-type-plugin.md
+    ├── gutenberg-block-plugin.md
+    ├── rest-api-plugin.md
+    ├── settings-page-plugin.md
+    ├── ajax-plugin.md
+    ├── woocommerce-extension.md
+    └── complete-plugin-example.md
+```
+
+## Core Workflows
+
+### 1. Plugin Scaffolding
+Create new WordPress plugins with proper structure, headers, and boilerplate code.
+
+### 2. Feature Development
+Add functionality: custom post types, Gutenberg blocks, REST endpoints, admin interfaces.
+
+### 3. Security Hardening
+Implement security best practices: nonces, sanitization, escaping, capability checks.
+
+### 4. Performance Optimization
+Apply caching, query optimization, and performance best practices.
+
+### 5. WordPress.org Submission
+Prepare plugins for WordPress.org directory submission.
+
+## Usage
+
+### For AI Agents
+
+When working on WordPress plugin development:
+
+1. **Detect Plugin Context**: Check for plugin header in PHP files
+2. **Apply Architecture Pattern**: Choose appropriate pattern based on plugin complexity
+3. **Follow Security Rules**: Always sanitize input, escape output, verify nonces
+4. **Optimize Performance**: Use transients, object caching, query optimization
+5. **Document Code**: PHPDoc blocks, inline comments, readme.txt
+
+### Example AI Prompts
+
+**Create Custom Post Type:**
+```
+Create a WordPress plugin for a Portfolio custom post type with:
+- Custom taxonomy (Portfolio Categories)
+- Meta box for project URL
+- Archive and single templates
+- Shortcode to display portfolio items
+```
+
+**Add Gutenberg Block:**
+```
+Add a Gutenberg block to display testimonials with:
+- Author name and image
+- Quote text
+- Block controls for styling
+```
+
+## Character Count
+
+**Total**: ~344,186 characters
+
+## Contents
+
+- **19 Rule Files**: Comprehensive guidelines for all aspects of plugin development
+  - WooCommerce Integration
+  - Testing Patterns
+- **1 Example File**: Simple Procedural Plugin (complete working example)
+- **Security Focus**: Critical security rules and patterns
+- **Performance Focus**: Optimization strategies and caching patterns
+- **WordPress.org Ready**: Submission guidelines and checklist
+
+## Related Modules
+
+- `workflows/wordpress-plugin` - Plugin development workflows
+- `domain-rules/wordpress` - General WordPress development (themes, core)
+
+## Version
+
+**1.1.0** - Added WooCommerce Integration and Testing Patterns
+
+## License
+
+MIT
+