@mytechtoday/augment-extensions 0.2.0 → 0.5.0

package/augment-extensions/coding-standards/php/README.md

@@ -0,0 +1,248 @@
+# PHP Coding Standards Module
+
+## Overview
+
+Comprehensive PHP coding standards module for Augment Extensions, providing guidelines for modern PHP development following PSR standards and best practices across various project types.
+
+**Version:** 1.0.0  
+**Character Count:** ~186,539
+
+---
+
+## Key Benefits
+
+✅ **PSR Compliance** - Full coverage of PSR-1, PSR-12, PSR-4, PSR-7, PSR-11, PSR-15, PSR-18  
+✅ **Category-Specific Rules** - Tailored guidelines for web, API, CLI, CMS, e-commerce, and legacy projects  
+✅ **Security-First** - OWASP PHP security best practices built-in  
+✅ **Modern PHP** - PHP 8+ features including typed properties, union types, attributes  
+✅ **Quality Tools** - Integration with PHPStan, Psalm, PHP-CS-Fixer, PHPUnit  
+✅ **Flexible Configuration** - Category selection system for project-specific needs  
+
+---
+
+## Installation
+
+### With CLI (Future)
+
+```bash
+augx link coding-standards/php
+```
+
+### Manual Setup
+
+1. Copy module contents to your project's `.augment/` folder
+2. Create configuration file at `.augment/php-config.json`
+3. Configure categories for your project type
+
+---
+
+## Configuration
+
+Create `.augment/php-config.json` in your project root:
+
+```json
+{
+  "php_categories": ["web", "api"],
+  "psr_standards": ["PSR-1", "PSR-12", "PSR-4", "PSR-7"],
+  "php_version": "8.2",
+  "strict_types": true,
+  "static_analysis": {
+    "tool": "phpstan",
+    "level": 8
+  },
+  "code_style": {
+    "tool": "php-cs-fixer",
+    "ruleset": "PSR-12"
+  }
+}
+```
+
+### Supported Categories
+
+- **web** - Web applications (MVC, template engines, form handling)
+- **api** - RESTful APIs (HTTP methods, authentication, response formatting)
+- **cli** - Command-line tools (Symfony Console, argument handling)
+- **cms** - CMS integrations (WordPress, Drupal plugins/themes)
+- **ecommerce** - E-commerce systems (shopping carts, payment gateways, WooCommerce)
+- **legacy** - Legacy code migration (refactoring, namespace introduction, type hints)
+
+---
+
+## Directory Structure
+
+```
+augment-extensions/coding-standards/php/
+├── module.json                      # Module metadata and configuration
+├── README.md                        # This file
+├── rules/                           # Rule files
+│   ├── psr-standards.md            # PSR-1, PSR-12, PSR-4, PSR-7, PSR-11
+│   ├── naming-conventions.md       # Variables, functions, classes, constants
+│   ├── type-declarations.md        # Type hints, return types, strict types
+│   ├── error-handling.md           # Exceptions, logging, retry patterns
+│   ├── security.md                 # OWASP guidelines, input validation, XSS/SQL injection
+│   ├── performance.md              # OPcache, database optimization, caching
+│   ├── testing.md                  # PHPUnit, unit tests, integration tests
+│   ├── documentation.md            # PHPDoc standards, inline comments
+│   ├── code-quality.md             # PHPStan, PHP-CS-Fixer, Composer
+│   ├── category-configuration.md   # Category selection and configuration
+│   ├── web-applications.md         # MVC, template engines, form handling
+│   ├── api-development.md          # RESTful design, authentication, responses
+│   ├── cli-tools.md                # Symfony Console, argument handling
+│   ├── cms-integration.md          # WordPress, Drupal hooks and security
+│   ├── ecommerce.md                # Shopping carts, payment gateways, WooCommerce
+│   └── legacy-migration.md         # Refactoring strategies, type hints, DI
+└── examples/                        # Code examples
+    ├── web-application-example.php
+    ├── api-endpoint-example.php
+    ├── cli-command-example.php
+    ├── wordpress-plugin-example.php
+    ├── woocommerce-extension-example.php
+    └── legacy-refactoring-example.php
+```
+
+---
+
+## Core Workflows
+
+### 1. New PHP Project
+
+```json
+{
+  "php_categories": ["web"],
+  "php_version": "8.2",
+  "strict_types": true,
+  "static_analysis": {
+    "tool": "phpstan",
+    "level": 8
+  }
+}
+```
+
+### 2. RESTful API
+
+```json
+{
+  "php_categories": ["api"],
+  "psr_standards": ["PSR-1", "PSR-12", "PSR-4", "PSR-7"],
+  "php_version": "8.2",
+  "strict_types": true
+}
+```
+
+### 3. WordPress Plugin
+
+```json
+{
+  "php_categories": ["cms"],
+  "php_version": "7.4",
+  "strict_types": false,
+  "static_analysis": {
+    "tool": "phpstan",
+    "level": 4
+  }
+}
+```
+
+### 4. Legacy Migration
+
+```json
+{
+  "php_categories": ["legacy"],
+  "php_version": "7.4",
+  "strict_types": false,
+  "static_analysis": {
+    "tool": "phpstan",
+    "level": 2
+  }
+}
+```
+
+---
+
+## Universal Rules (Applied to All Categories)
+
+1. **PSR Standards** - PSR-1, PSR-12, PSR-4, PSR-7, PSR-11
+2. **Naming Conventions** - camelCase, PascalCase, UPPER_SNAKE_CASE
+3. **Type Declarations** - Strict types, type hints, return types
+4. **Error Handling** - Exceptions, PSR-3 logging, retry patterns
+5. **Security** - OWASP guidelines, input validation, XSS/SQL injection prevention
+6. **Performance** - OPcache, database optimization, caching strategies
+7. **Testing** - PHPUnit, AAA pattern, mocks and stubs
+8. **Documentation** - PHPDoc blocks, inline comments
+9. **Code Quality** - PHPStan, PHP-CS-Fixer, Composer best practices
+
+---
+
+## Category-Specific Rules
+
+### Web Applications
+- MVC architecture patterns
+- Template engine usage (Twig, Blade)
+- Form handling and CSRF protection
+- Session management
+
+### API Development
+- RESTful design principles
+- HTTP method semantics
+- Authentication (OAuth 2.0, JWT)
+- Response formatting and pagination
+
+### CLI Tools
+- Symfony Console component
+- Argument and option handling
+- Exit codes and error handling
+- Progress bars for long operations
+
+### CMS Integration
+- WordPress/Drupal coding standards
+- Hook and filter usage
+- Nonce verification
+- Shortcode implementation
+
+### E-commerce
+- Shopping cart management
+- Payment gateway integration (PCI DSS)
+- Order processing with transactions
+- WooCommerce hooks and classes
+
+### Legacy Migration
+- Incremental refactoring strategies
+- Namespace introduction
+- Type hint addition
+- Dependency injection patterns
+
+---
+
+## Contents
+
+- **15 rule files** covering all aspects of PHP development
+- **6 code examples** demonstrating best practices for each category
+- **Configuration system** for category selection
+- **Conflict detection** for overlapping rules
+- **PSR compliance** for all major standards
+
+---
+
+## Dependencies
+
+### Recommended Composer Packages
+
+```json
+{
+  "require-dev": {
+    "phpunit/phpunit": "^10.0",
+    "phpstan/phpstan": "^1.10",
+    "friendsofphp/php-cs-fixer": "^3.0"
+  }
+}
+```
+
+---
+
+## Links
+
+- [PHP-FIG PSR Standards](https://www.php-fig.org/psr/)
+- [PHPStan Documentation](https://phpstan.org/)
+- [PHP-CS-Fixer Documentation](https://cs.symfony.com/)
+- [OWASP PHP Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/PHP_Configuration_Cheat_Sheet.html)
+

package/augment-extensions/coding-standards/php/examples/api-endpoint-example.php

@@ -0,0 +1,204 @@
+<?php
+
+/**
+ * RESTful API Endpoint Example - Product Resource CRUD
+ * 
+ * This example demonstrates best practices for PHP API development including:
+ * - RESTful design with proper HTTP methods
+ * - PSR-7 compliant responses
+ * - JWT authentication
+ * - API Resources for consistent response formatting
+ * - HATEOAS links
+ * - Proper HTTP status codes
+ * - Input validation
+ * - Error handling
+ * - Rate limiting
+ * - Pagination
+ */
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Requests\Api\StoreProductRequest;
+use App\Http\Requests\Api\UpdateProductRequest;
+use App\Http\Resources\ProductResource;
+use App\Http\Resources\ProductCollection;
+use App\Models\Product;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+
+/**
+ * Product API Controller
+ * 
+ * @OA\Tag(name="Products", description="Product management endpoints")
+ */
+class ProductController extends Controller
+{
+    public function __construct()
+    {
+        $this->middleware('auth:api');
+        $this->middleware('throttle:60,1'); // Rate limiting: 60 requests per minute
+    }
+    
+    /**
+     * List all products with pagination
+     * 
+     * @OA\Get(
+     *     path="/api/v1/products",
+     *     summary="Get list of products",
+     *     tags={"Products"},
+     *     @OA\Parameter(
+     *         name="page",
+     *         in="query",
+     *         description="Page number",
+     *         required=false,
+     *         @OA\Schema(type="integer")
+     *     ),
+     *     @OA\Parameter(
+     *         name="per_page",
+     *         in="query",
+     *         description="Items per page",
+     *         required=false,
+     *         @OA\Schema(type="integer", default=20)
+     *     ),
+     *     @OA\Response(
+     *         response=200,
+     *         description="Successful operation"
+     *     ),
+     *     security={{"bearerAuth": {}}}
+     * )
+     */
+    public function index(Request $request): JsonResponse
+    {
+        $perPage = $request->input('per_page', 20);
+        $products = Product::with('category')
+            ->paginate($perPage);
+        
+        return (new ProductCollection($products))
+            ->response()
+            ->setStatusCode(200);
+    }
+    
+    /**
+     * Get a single product
+     * 
+     * GET /api/v1/products/{id}
+     */
+    public function show(int $id): JsonResponse
+    {
+        $product = Product::with(['category', 'reviews'])
+            ->findOrFail($id);
+        
+        return (new ProductResource($product))
+            ->response()
+            ->setStatusCode(200);
+    }
+    
+    /**
+     * Create a new product
+     * 
+     * POST /api/v1/products
+     */
+    public function store(StoreProductRequest $request): JsonResponse
+    {
+        $product = Product::create($request->validated());
+        
+        return (new ProductResource($product))
+            ->response()
+            ->setStatusCode(201)
+            ->header('Location', route('api.v1.products.show', $product));
+    }
+    
+    /**
+     * Update an existing product (full replacement)
+     * 
+     * PUT /api/v1/products/{id}
+     */
+    public function update(UpdateProductRequest $request, int $id): JsonResponse
+    {
+        $product = Product::findOrFail($id);
+        $product->update($request->validated());
+        
+        return (new ProductResource($product))
+            ->response()
+            ->setStatusCode(200);
+    }
+    
+    /**
+     * Partially update a product
+     * 
+     * PATCH /api/v1/products/{id}
+     */
+    public function patch(Request $request, int $id): JsonResponse
+    {
+        $product = Product::findOrFail($id);
+        
+        $validated = $request->validate([
+            'name' => 'sometimes|string|max:255',
+            'price' => 'sometimes|numeric|min:0',
+            'stock' => 'sometimes|integer|min:0'
+        ]);
+        
+        $product->update($validated);
+        
+        return (new ProductResource($product))
+            ->response()
+            ->setStatusCode(200);
+    }
+    
+    /**
+     * Delete a product
+     * 
+     * DELETE /api/v1/products/{id}
+     */
+    public function destroy(int $id): Response
+    {
+        $product = Product::findOrFail($id);
+        $product->delete();
+        
+        return response()->noContent(); // 204 No Content
+    }
+}
+
+// ============================================================================
+// API Resource - Response Formatting with HATEOAS
+// ============================================================================
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class ProductResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array with HATEOAS links
+     */
+    public function toArray($request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'description' => $this->description,
+            'price' => [
+                'amount' => $this->price,
+                'currency' => 'USD',
+                'formatted' => '$' . number_format($this->price, 2)
+            ],
+            'stock' => $this->stock,
+            'category' => [
+                'id' => $this->category->id,
+                'name' => $this->category->name
+            ],
+            'created_at' => $this->created_at->toIso8601String(),
+            'updated_at' => $this->updated_at->toIso8601String(),
+            
+            // HATEOAS links
+            'links' => [
+                'self' => route('api.v1.products.show', $this->id),
+                'category' => route('api.v1.categories.show', $this->category_id),
+                'reviews' => route('api.v1.products.reviews.index', $this->id)
+            ]
+        ];
+    }
+}
+

package/augment-extensions/coding-standards/php/examples/cli-command-example.php

@@ -0,0 +1,206 @@
+<?php
+
+/**
+ * CLI Command Example - Data Migration Script
+ * 
+ * This example demonstrates best practices for PHP CLI tools including:
+ * - Symfony Console component usage
+ * - Argument and option handling with validation
+ * - Progress bars for long-running operations
+ * - Proper error handling and exit codes
+ * - Idempotency (can be run multiple times safely)
+ * - Database transactions
+ * - Logging
+ */
+
+namespace App\Console\Commands;
+
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\Helper\ProgressBar;
+use Symfony\Component\Console\Question\ConfirmationQuestion;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * Migrate user data from legacy system to new system
+ * 
+ * Usage:
+ *   php artisan users:migrate legacy_users.csv --batch-size=100 --dry-run
+ */
+class MigrateUsersCommand extends Command
+{
+    protected static $defaultName = 'users:migrate';
+    protected static $defaultDescription = 'Migrate users from legacy CSV file to new system';
+    
+    private int $successCount = 0;
+    private int $errorCount = 0;
+    private int $skippedCount = 0;
+    
+    protected function configure(): void
+    {
+        $this
+            ->setDescription('Migrate users from a CSV file to the new database')
+            ->setHelp('This command migrates user data from a legacy CSV file...')
+            ->addArgument(
+                'file',
+                InputArgument::REQUIRED,
+                'Path to the CSV file containing user data'
+            )
+            ->addOption(
+                'batch-size',
+                'b',
+                InputOption::VALUE_REQUIRED,
+                'Number of records to process in each batch',
+                100
+            )
+            ->addOption(
+                'dry-run',
+                null,
+                InputOption::VALUE_NONE,
+                'Run without making any changes to the database'
+            )
+            ->addOption(
+                'force',
+                'f',
+                InputOption::VALUE_NONE,
+                'Skip confirmation prompt'
+            );
+    }
+    
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $filename = $input->getArgument('file');
+        $batchSize = (int) $input->getOption('batch-size');
+        $isDryRun = $input->getOption('dry-run');
+        $force = $input->getOption('force');
+        
+        // Validate file exists
+        if (!file_exists($filename)) {
+            $output->writeln("<error>File not found: {$filename}</error>");
+            return Command::FAILURE;
+        }
+        
+        // Validate file is readable
+        if (!is_readable($filename)) {
+            $output->writeln("<error>File is not readable: {$filename}</error>");
+            return Command::FAILURE;
+        }
+        
+        // Count total records
+        $totalRecords = $this->countRecords($filename);
+        
+        $output->writeln("<info>Found {$totalRecords} records to migrate</info>");
+        
+        if ($isDryRun) {
+            $output->writeln("<comment>DRY RUN MODE - No changes will be made</comment>");
+        }
+        
+        // Confirmation prompt
+        if (!$force && !$isDryRun) {
+            $helper = $this->getHelper('question');
+            $question = new ConfirmationQuestion(
+                'Continue with migration? (y/n) ',
+                false
+            );
+            
+            if (!$helper->ask($input, $output, $question)) {
+                $output->writeln('<comment>Migration cancelled</comment>');
+                return Command::SUCCESS;
+            }
+        }
+        
+        // Create progress bar
+        $progressBar = new ProgressBar($output, $totalRecords);
+        $progressBar->setFormat(' %current%/%max% [%bar%] %percent:3s%% %elapsed:6s%/%estimated:-6s% %memory:6s%');
+        $progressBar->start();
+        
+        // Process file in batches
+        try {
+            $this->processFile($filename, $batchSize, $isDryRun, $progressBar);
+            
+            $progressBar->finish();
+            $output->writeln('');
+            
+            // Display summary
+            $this->displaySummary($output, $isDryRun);
+            
+            // Log completion
+            Log::info('User migration completed', [
+                'file' => $filename,
+                'success' => $this->successCount,
+                'errors' => $this->errorCount,
+                'skipped' => $this->skippedCount,
+                'dry_run' => $isDryRun
+            ]);
+            
+            return Command::SUCCESS;
+            
+        } catch (\Exception $e) {
+            $progressBar->finish();
+            $output->writeln('');
+            $output->writeln("<error>Migration failed: {$e->getMessage()}</error>");
+            
+            Log::error('User migration failed', [
+                'file' => $filename,
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString()
+            ]);
+            
+            return Command::FAILURE;
+        }
+    }
+    
+    private function countRecords(string $filename): int
+    {
+        $count = 0;
+        $handle = fopen($filename, 'r');
+        
+        // Skip header
+        fgetcsv($handle);
+        
+        while (fgetcsv($handle) !== false) {
+            $count++;
+        }
+        
+        fclose($handle);
+        return $count;
+    }
+    
+    private function processFile(
+        string $filename,
+        int $batchSize,
+        bool $isDryRun,
+        ProgressBar $progressBar
+    ): void {
+        $handle = fopen($filename, 'r');
+        
+        // Read header
+        $header = fgetcsv($handle);
+        
+        $batch = [];
+        
+        while (($row = fgetcsv($handle)) !== false) {
+            $data = array_combine($header, $row);
+            $batch[] = $data;
+            
+            if (count($batch) >= $batchSize) {
+                $this->processBatch($batch, $isDryRun);
+                $progressBar->advance(count($batch));
+                $batch = [];
+            }
+        }
+        
+        // Process remaining records
+        if (!empty($batch)) {
+            $this->processBatch($batch, $isDryRun);
+            $progressBar->advance(count($batch));
+        }
+        
+        fclose($handle);
+    }
+}
+