ima-claude 2.9.0

package/plugins/ima-claude/skills/php-fp-wordpress/references/plugin-architecture.md

@@ -0,0 +1,295 @@
+# Plugin Complexity Patterns
+
+## Table of Contents
+1. [Complexity Decision Guide](#complexity-decision-guide)
+2. [Simple Plugin (<500 lines)](#simple-plugin-500-lines)
+3. [Medium Plugin (500-2000 lines)](#medium-plugin-500-2000-lines)
+4. [Complex Plugin (2000+ lines)](#complex-plugin-2000-lines)
+5. [File Organization](#file-organization)
+
+---
+
+## Complexity Decision Guide
+
+| Plugin Size | Lines | Pattern | When to Use |
+|-------------|-------|---------|-------------|
+| Simple | <500 | Namespaced functions | Single feature, few hooks |
+| Medium | 500-2000 | Classes + pure functions | Multiple features, some state |
+| Complex | 2000+ | DI Container + Services | Many features, shared dependencies |
+
+**Rule**: Start simple, add complexity only when needed.
+
+---
+
+## Simple Plugin (<500 lines)
+
+**Use**: Namespaced functions with direct hook usage.
+
+```php
+<?php
+/**
+ * Plugin Name: Simple Analytics Tracker
+ */
+
+namespace SimpleAnalytics;
+
+// Pure function - testable without WordPress
+function calculate_page_views(array $logs): int {
+    return count(array_filter($logs, fn($log) => $log['type'] === 'page_view'));
+}
+
+function format_analytics_data(array $logs): array {
+    return [
+        'page_views' => calculate_page_views($logs),
+        'unique_visitors' => count(array_unique(array_column($logs, 'visitor_id'))),
+        'last_updated' => date('Y-m-d H:i:s')
+    ];
+}
+
+// WordPress integration with security
+add_action('wp_footer', function() {
+    if (!current_user_can('edit_posts')) return;
+
+    $logs = get_option('analytics_logs', []);
+    $data = format_analytics_data($logs);
+
+    echo '<div id="analytics">' . esc_html($data['page_views']) . ' page views</div>';
+});
+
+add_action('wp_ajax_get_analytics', function() {
+    if (!current_user_can('manage_options')) {
+        wp_send_json_error('Unauthorized', 403);
+    }
+    check_ajax_referer('analytics_nonce');
+
+    $logs = get_option('analytics_logs', []);
+    wp_send_json_success(format_analytics_data($logs));
+});
+```
+
+---
+
+## Medium Plugin (500-2000 lines)
+
+**Use**: Classes for features + pure functions for logic.
+
+```php
+<?php
+namespace MediumPlugin;
+
+// Pure functions in separate file (includes/functions.php)
+function calculate_shipping_cost(float $weight, string $zone): float {
+    $rates = ['domestic' => 5.00, 'international' => 15.00];
+    $base = $rates[$zone] ?? 10.00;
+    return $base + ($weight * 0.50);
+}
+
+function validate_shipping_address(array $address): array {
+    $errors = [];
+    if (empty($address['street'])) $errors[] = 'Street required';
+    if (empty($address['city'])) $errors[] = 'City required';
+    if (empty($address['zip'])) $errors[] = 'ZIP required';
+
+    return empty($errors)
+        ? ['valid' => true]
+        : ['valid' => false, 'errors' => $errors];
+}
+
+// Class for WordPress integration
+class ShippingCalculator {
+    public function __construct() {
+        add_filter('woocommerce_shipping_cost', [$this, 'apply_calculation'], 10, 2);
+        add_action('wp_ajax_validate_address', [$this, 'handle_validation']);
+    }
+
+    public function apply_calculation($cost, $package) {
+        $weight = $package['contents_weight'];
+        $zone = $package['destination']['country'] === 'US' ? 'domestic' : 'international';
+
+        return calculate_shipping_cost($weight, $zone);
+    }
+
+    public function handle_validation() {
+        if (!current_user_can('edit_shop_orders')) {
+            wp_send_json_error('Unauthorized', 403);
+        }
+        check_ajax_referer('shipping_nonce');
+
+        $address = array_map('sanitize_text_field', $_POST['address']);
+        $result = validate_shipping_address($address);
+
+        if ($result['valid']) {
+            wp_send_json_success('Address valid');
+        } else {
+            wp_send_json_error($result['errors']);
+        }
+    }
+}
+
+// Initialize
+new ShippingCalculator();
+```
+
+---
+
+## Complex Plugin (2000+ lines)
+
+**Use**: Dependency Injection Container + Service Architecture.
+
+### DI Container
+
+```php
+<?php
+namespace ComplexPlugin;
+
+class Container {
+    private array $services = [];
+    private array $resolved = [];
+
+    public function register(string $name, callable $resolver): void {
+        $this->services[$name] = $resolver;
+    }
+
+    public function get(string $name) {
+        if (!isset($this->resolved[$name])) {
+            $this->resolved[$name] = ($this->services[$name])($this);
+        }
+        return $this->resolved[$name];
+    }
+}
+```
+
+### Service Classes
+
+```php
+<?php
+namespace ComplexPlugin\Services;
+
+class OrderService {
+    private PaymentService $payment;
+
+    public function __construct(PaymentService $payment) {
+        $this->payment = $payment;
+    }
+
+    public function process(array $order_data): array {
+        // Use pure function for calculation
+        $total = \ComplexPlugin\BusinessLogic\calculate_order_total(
+            $order_data['items'],
+            $order_data['discounts']
+        );
+
+        // Side effect: process payment
+        $payment_result = $this->payment->charge($total);
+
+        return [
+            'order_id' => uniqid('order_'),
+            'total' => $total,
+            'payment' => $payment_result
+        ];
+    }
+}
+
+class PaymentService {
+    public function charge(float $amount): array {
+        // Payment gateway integration
+        return ['success' => true, 'transaction_id' => uniqid('txn_')];
+    }
+}
+```
+
+### Main Plugin Class
+
+```php
+<?php
+namespace ComplexPlugin;
+
+class Plugin {
+    private Container $container;
+
+    public function __construct() {
+        $this->container = new Container();
+        $this->setup_services();
+        $this->init_hooks();
+    }
+
+    private function setup_services(): void {
+        $this->container->register('payment', fn($c) =>
+            new Services\PaymentService()
+        );
+        $this->container->register('order', fn($c) =>
+            new Services\OrderService($c->get('payment'))
+        );
+    }
+
+    private function init_hooks(): void {
+        add_action('wp_ajax_process_order', [$this, 'handle_order']);
+    }
+
+    public function handle_order(): void {
+        // Security
+        if (!current_user_can('edit_shop_orders')) {
+            wp_send_json_error('Unauthorized', 403);
+        }
+        check_ajax_referer('process_order');
+
+        // Sanitize
+        $order_data = [
+            'items' => array_map(function($item) {
+                return [
+                    'id' => absint($item['id']),
+                    'price' => floatval($item['price']),
+                    'quantity' => absint($item['quantity'])
+                ];
+            }, $_POST['items']),
+            'discounts' => []
+        ];
+
+        // Process via service
+        $result = $this->container->get('order')->process($order_data);
+
+        wp_send_json_success($result);
+    }
+}
+```
+
+---
+
+## File Organization
+
+### Simple Plugin
+```
+simple-plugin/
+├── simple-plugin.php     # Everything in one file
+└── readme.txt
+```
+
+### Medium Plugin
+```
+medium-plugin/
+├── medium-plugin.php     # Bootstrap, hooks
+├── includes/
+│   ├── functions.php     # Pure business logic
+│   └── class-feature.php # WordPress integration
+└── tests/
+    └── test-functions.php
+```
+
+### Complex Plugin
+```
+complex-plugin/
+├── complex-plugin.php
+├── includes/
+│   ├── class-container.php
+│   ├── class-plugin.php
+│   └── functions.php          # Pure business logic
+├── services/
+│   ├── class-order-service.php
+│   └── class-payment-service.php
+├── admin/
+│   ├── settings.php
+│   └── ajax-handlers.php
+└── tests/
+    ├── unit/                  # Pure function tests
+    └── integration/           # WordPress tests
+```

package/plugins/ima-claude/skills/php-fp-wordpress/references/security-examples.md

@@ -0,0 +1,203 @@
+# WordPress Security Patterns - Detailed Examples
+
+## Table of Contents
+1. [Capability Checks](#1-capability-checks)
+2. [Nonce Verification](#2-nonce-verification)
+3. [Input Sanitization](#3-input-sanitization)
+4. [Output Escaping](#4-output-escaping)
+5. [Prepared SQL Statements](#5-prepared-sql-statements)
+6. [Security Function Reference](#security-function-reference)
+
+---
+
+## 1. Capability Checks
+
+**Prevents 53% of XSS vulnerabilities.**
+
+```php
+<?php
+// ALWAYS check permissions FIRST
+add_action('wp_ajax_delete_user_data', 'handle_delete_user_data');
+function handle_delete_user_data() {
+    // Check capability before ANY operation
+    if (!current_user_can('delete_users')) {
+        wp_send_json_error('Insufficient permissions', 403);
+        return;
+    }
+
+    // Then proceed
+    delete_user_data($_POST['user_id']);
+}
+
+// NEVER allow operations without capability check
+function delete_user_data_UNSAFE() {
+    wp_delete_user($_POST['user_id']); // Any authenticated user can delete!
+}
+```
+
+### Common Capabilities
+| Capability | Use For |
+|------------|---------|
+| `manage_options` | Plugin settings, admin-only operations |
+| `edit_posts` | Content creation |
+| `delete_users` | User management |
+| `upload_files` | File uploads |
+
+---
+
+## 2. Nonce Verification
+
+**Prevents 15-17% CSRF attacks.**
+
+```php
+<?php
+// ALWAYS verify nonces
+add_action('admin_post_save_settings', 'save_plugin_settings');
+function save_plugin_settings() {
+    // Verify nonce before processing
+    if (!isset($_POST['settings_nonce']) ||
+        !wp_verify_nonce($_POST['settings_nonce'], 'save_settings_action')) {
+        wp_die('Security check failed');
+    }
+
+    // Then save
+    update_option('plugin_settings', $_POST['settings']);
+}
+
+// NEVER process forms without nonce
+function save_settings_UNSAFE() {
+    update_option('plugin_settings', $_POST['settings']); // CSRF vulnerable!
+}
+```
+
+### Nonce Functions
+| Function | Purpose |
+|----------|---------|
+| `wp_nonce_field('action', 'field_name')` | Generate hidden form field |
+| `wp_verify_nonce($_POST['field'], 'action')` | Verify form submission |
+| `check_ajax_referer('action', 'nonce')` | Verify AJAX nonce |
+| `wp_create_nonce('action')` | Create nonce for JS |
+
+---
+
+## 3. Input Sanitization
+
+**Required for ALL user input.**
+
+```php
+<?php
+// ALWAYS sanitize based on data type
+function process_form_submission() {
+    $name = sanitize_text_field($_POST['name']);
+    $email = sanitize_email($_POST['email']);
+    $content = wp_kses_post($_POST['content']); // Allow safe HTML
+    $url = esc_url_raw($_POST['website']);
+    $number = absint($_POST['count']);
+
+    save_to_database($name, $email, $content, $url, $number);
+}
+
+// NEVER use raw input
+function process_form_UNSAFE() {
+    save_to_database($_POST['name'], $_POST['email']); // Injection risk!
+}
+```
+
+### Sanitization Functions
+| Function | Use For |
+|----------|---------|
+| `sanitize_text_field()` | Plain text, single line |
+| `sanitize_textarea_field()` | Multi-line text |
+| `sanitize_email()` | Email addresses |
+| `absint()` | Positive integers |
+| `wp_kses_post()` | HTML (post content allowed tags) |
+| `esc_url_raw()` | URLs for database storage |
+
+---
+
+## 4. Output Escaping
+
+**Context-specific escaping required.**
+
+```php
+<?php
+// ALWAYS escape based on context
+function render_user_profile($user) {
+    // HTML context
+    echo '<h2>' . esc_html($user->name) . '</h2>';
+
+    // Attribute context
+    echo '<img src="' . esc_url($user->avatar) . '" alt="' . esc_attr($user->name) . '">';
+
+    // JavaScript context
+    echo '<script>var userName = ' . wp_json_encode($user->name) . ';</script>';
+
+    // URL context
+    echo '<a href="' . esc_url($user->website) . '">Website</a>';
+}
+
+// NEVER output unescaped data
+function render_profile_UNSAFE($user) {
+    echo '<h1>' . $user->name . '</h1>'; // XSS if name contains <script>
+}
+```
+
+### Escaping Functions
+| Function | Context |
+|----------|---------|
+| `esc_html()` | HTML body text |
+| `esc_attr()` | HTML attributes |
+| `esc_url()` | URLs in href/src |
+| `esc_js()` | Inline JavaScript strings |
+| `wp_json_encode()` | JSON data in scripts |
+
+---
+
+## 5. Prepared SQL Statements
+
+**Prevents SQL injection.**
+
+```php
+<?php
+// ALWAYS use prepared statements
+function get_user_posts($user_id) {
+    global $wpdb;
+
+    $posts = $wpdb->get_results($wpdb->prepare(
+        "SELECT * FROM {$wpdb->posts} WHERE post_author = %d AND post_status = %s",
+        $user_id,
+        'publish'
+    ));
+
+    return $posts;
+}
+
+// NEVER use string concatenation
+function get_posts_UNSAFE($user_id) {
+    global $wpdb;
+    return $wpdb->get_results("SELECT * FROM {$wpdb->posts} WHERE post_author = $user_id");
+}
+```
+
+### Prepared Statement Placeholders
+| Placeholder | Type |
+|-------------|------|
+| `%d` | Integer |
+| `%f` | Float |
+| `%s` | String |
+
+---
+
+## Security Function Reference
+
+### Quick Lookup Table
+
+| Input Type | Sanitize | Escape (Output) |
+|------------|----------|-----------------|
+| Plain text | `sanitize_text_field()` | `esc_html()` |
+| HTML content | `wp_kses_post()` | Already safe |
+| Email | `sanitize_email()` | `esc_html()` |
+| URL | `esc_url_raw()` | `esc_url()` |
+| Integer | `absint()` | `absint()` |
+| Filename | `sanitize_file_name()` | `esc_html()` |
+| SQL | `$wpdb->prepare()` | N/A |