@mytechtoday/augment-extensions 0.1.2 → 0.4.0

package/augment-extensions/coding-standards/php/rules/testing.md

@@ -0,0 +1,403 @@
+# Testing Standards
+
+## Overview
+
+Comprehensive testing is essential for maintaining code quality and preventing regressions. This document defines standards for unit testing, integration testing, and test organization using PHPUnit.
+
+---
+
+## Unit Testing
+
+### PHPUnit Setup
+
+**Rules:**
+- Use PHPUnit for all PHP testing
+- Organize tests to mirror source code structure
+- Aim for at least 80% code coverage
+
+**Directory Structure:**
+```
+project/
+├── src/
+│   └── Services/
+│       └── UserService.php
+└── tests/
+    └── Unit/
+        └── Services/
+            └── UserServiceTest.php
+```
+
+### Test Class Structure
+
+**Rules:**
+- Test classes MUST extend `PHPUnit\Framework\TestCase`
+- Test class names MUST end with `Test`
+- Test method names MUST start with `test` or use `@test` annotation
+- Use descriptive test method names
+
+**Examples:**
+```php
+// ✅ Good
+use PHPUnit\Framework\TestCase;
+
+class UserServiceTest extends TestCase
+{
+    public function testCreateUserWithValidData(): void
+    {
+        // Test implementation
+    }
+    
+    public function testCreateUserThrowsExceptionForInvalidEmail(): void
+    {
+        // Test implementation
+    }
+    
+    /** @test */
+    public function it_updates_user_successfully(): void
+    {
+        // Test implementation
+    }
+}
+
+// ❌ Bad
+class UserService extends TestCase  // Missing 'Test' suffix
+{
+    public function create_user(): void  // Doesn't start with 'test'
+    {
+        // Test implementation
+    }
+}
+```
+
+### AAA Pattern (Arrange-Act-Assert)
+
+**Rules:**
+- Structure tests using Arrange-Act-Assert pattern
+- Keep tests focused on single behavior
+- Use blank lines to separate AAA sections
+
+**Examples:**
+```php
+// ✅ Good
+public function testCalculateTotalPrice(): void
+{
+    // Arrange
+    $items = [
+        ['price' => 10.00, 'quantity' => 2],
+        ['price' => 5.00, 'quantity' => 3],
+    ];
+    $calculator = new PriceCalculator();
+    
+    // Act
+    $total = $calculator->calculateTotal($items);
+    
+    // Assert
+    $this->assertEquals(35.00, $total);
+}
+
+// ❌ Bad - Mixed concerns
+public function testMultipleThings(): void
+{
+    $calc = new PriceCalculator();
+    $this->assertEquals(35.00, $calc->calculateTotal($items1));
+    $this->assertEquals(50.00, $calc->calculateTotal($items2));
+    $this->assertTrue($calc->isValid());
+}
+```
+
+### Assertions
+
+**Rules:**
+- Use specific assertions over generic ones
+- Include meaningful assertion messages
+- Use type-specific assertions
+
+**Common Assertions:**
+```php
+// ✅ Good - Specific assertions
+$this->assertTrue($result);
+$this->assertFalse($result);
+$this->assertEquals($expected, $actual);
+$this->assertSame($expected, $actual);  // Strict comparison
+$this->assertNull($value);
+$this->assertNotNull($value);
+$this->assertEmpty($array);
+$this->assertCount(3, $array);
+$this->assertInstanceOf(User::class, $user);
+$this->assertStringContainsString('error', $message);
+$this->assertArrayHasKey('email', $data);
+
+// ✅ Good - With messages
+$this->assertEquals(100, $total, 'Total price should be 100');
+
+// ❌ Bad - Generic assertion
+$this->assertTrue($user instanceof User);  // Use assertInstanceOf instead
+```
+
+### Test Doubles (Mocks and Stubs)
+
+**Rules:**
+- Use mocks to verify behavior
+- Use stubs to provide test data
+- Mock external dependencies
+- Don't mock the system under test
+
+**Examples:**
+```php
+// ✅ Good - Mock external dependency
+public function testSendEmailNotification(): void
+{
+    // Arrange
+    $mailer = $this->createMock(MailerInterface::class);
+    $mailer->expects($this->once())
+        ->method('send')
+        ->with($this->equalTo('user@example.com'));
+    
+    $notifier = new EmailNotifier($mailer);
+    
+    // Act
+    $notifier->notify('user@example.com', 'Test message');
+    
+    // Assert - Verification happens via expects()
+}
+
+// ✅ Good - Stub for test data
+public function testProcessUserData(): void
+{
+    // Arrange
+    $repository = $this->createStub(UserRepositoryInterface::class);
+    $repository->method('findById')
+        ->willReturn(new User(1, 'John Doe'));
+    
+    $service = new UserService($repository);
+    
+    // Act
+    $result = $service->processUser(1);
+    
+    // Assert
+    $this->assertEquals('John Doe', $result->name);
+}
+```
+
+### Data Providers
+
+**Rules:**
+- Use data providers for testing multiple scenarios
+- Keep data providers focused and readable
+- Name data sets descriptively
+
+**Examples:**
+```php
+// ✅ Good
+/**
+ * @dataProvider emailValidationProvider
+ */
+public function testEmailValidation(string $email, bool $expected): void
+{
+    $validator = new EmailValidator();
+    $result = $validator->isValid($email);
+    $this->assertEquals($expected, $result);
+}
+
+public function emailValidationProvider(): array
+{
+    return [
+        'valid email' => ['user@example.com', true],
+        'invalid - no @' => ['userexample.com', false],
+        'invalid - no domain' => ['user@', false],
+        'invalid - empty' => ['', false],
+    ];
+}
+```
+
+---
+
+## Integration Testing
+
+### Database Testing
+
+**Rules:**
+- Use transactions for test isolation
+- Reset database state between tests
+- Use test fixtures for consistent data
+
+**Examples:**
+```php
+// ✅ Good - Transaction-based test
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+class UserRepositoryTest extends TestCase
+{
+    use RefreshDatabase;
+    
+    public function testFindUserById(): void
+    {
+        // Arrange
+        $user = User::factory()->create([
+            'email' => 'test@example.com'
+        ]);
+        
+        $repository = new UserRepository();
+        
+        // Act
+        $found = $repository->findById($user->id);
+        
+        // Assert
+        $this->assertNotNull($found);
+        $this->assertEquals('test@example.com', $found->email);
+    }
+}
+```
+
+### API Testing
+
+**Rules:**
+- Test request/response contracts
+- Verify HTTP status codes
+- Validate response structure
+- Test authentication and authorization
+
+**Examples:**
+```php
+// ✅ Good - API endpoint test
+public function testGetUserEndpoint(): void
+{
+    // Arrange
+    $user = User::factory()->create();
+    
+    // Act
+    $response = $this->getJson("/api/users/{$user->id}");
+    
+    // Assert
+    $response->assertStatus(200)
+        ->assertJson([
+            'id' => $user->id,
+            'email' => $user->email,
+        ])
+        ->assertJsonStructure([
+            'id',
+            'email',
+            'created_at',
+            'updated_at',
+        ]);
+}
+
+public function testUnauthorizedAccess(): void
+{
+    $response = $this->getJson('/api/admin/users');
+    $response->assertStatus(401);
+}
+```
+
+---
+
+## Test Organization
+
+### Test Naming
+
+**Rules:**
+- Use descriptive test names that explain what is being tested
+- Include the expected outcome in the name
+- Use snake_case or camelCase consistently
+
+**Examples:**
+```php
+// ✅ Good - Descriptive names
+public function testCreateUserWithValidDataReturnsUser(): void
+public function testCreateUserWithInvalidEmailThrowsException(): void
+public function testDeleteUserRemovesFromDatabase(): void
+
+// ❌ Bad - Vague names
+public function testUser(): void
+public function testCreate(): void
+```
+
+### Test Coverage
+
+**Rules:**
+- Aim for at least 80% code coverage
+- Focus on critical business logic
+- Don't chase 100% coverage at the expense of test quality
+
+**Generate Coverage Report:**
+```bash
+# ✅ Good
+./vendor/bin/phpunit --coverage-html coverage/
+```
+
+### Setup and Teardown
+
+**Rules:**
+- Use `setUp()` for common test initialization
+- Use `tearDown()` for cleanup
+- Keep setup minimal and focused
+
+**Examples:**
+```php
+// ✅ Good
+class UserServiceTest extends TestCase
+{
+    private UserService $service;
+    private UserRepositoryInterface $repository;
+    
+    protected function setUp(): void
+    {
+        parent::setUp();
+        
+        $this->repository = $this->createMock(UserRepositoryInterface::class);
+        $this->service = new UserService($this->repository);
+    }
+    
+    protected function tearDown(): void
+    {
+        parent::tearDown();
+        // Cleanup if needed
+    }
+    
+    public function testSomething(): void
+    {
+        // Test uses $this->service
+    }
+}
+```
+
+---
+
+## Best Practices
+
+### Test Independence
+
+**Rules:**
+- Tests MUST be independent of each other
+- Tests MUST NOT rely on execution order
+- Each test MUST set up its own state
+
+### Fast Tests
+
+**Rules:**
+- Keep unit tests fast (< 100ms each)
+- Mock external services
+- Use in-memory databases for integration tests when possible
+
+### Readable Tests
+
+**Rules:**
+- Tests should be easy to understand
+- Use helper methods to reduce duplication
+- Avoid complex logic in tests
+
+**Examples:**
+```php
+// ✅ Good - Helper method
+private function createTestUser(array $attributes = []): User
+{
+    return User::factory()->create($attributes);
+}
+
+public function testUserCreation(): void
+{
+    $user = $this->createTestUser(['email' => 'test@example.com']);
+    $this->assertEquals('test@example.com', $user->email);
+}
+```
+

package/augment-extensions/coding-standards/php/rules/type-declarations.md

@@ -0,0 +1,331 @@
+# Type Declarations
+
+## Overview
+
+Modern PHP (8.0+) provides robust type declaration features. This document defines standards for using type hints, return types, and strict typing to improve code safety and clarity.
+
+---
+
+## Strict Types
+
+### Enable Strict Types
+
+**Rule:**
+- All PHP files SHOULD declare strict types at the top
+- Place immediately after opening `<?php` tag
+
+**Example:**
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+class UserService
+{
+    // ...
+}
+```
+
+**Benefits:**
+- Prevents implicit type coercion
+- Catches type errors early
+- Improves code reliability
+
+---
+
+## Function and Method Type Hints
+
+### Parameter Type Declarations
+
+**Rules:**
+- Parameters SHOULD have type declarations
+- Use scalar types: `int`, `float`, `string`, `bool`
+- Use class/interface names for objects
+- Use `array` for arrays (or specific array shapes in PHPDoc)
+- Use `callable` for callbacks
+- Use `iterable` for arrays or Traversable objects
+
+**Examples:**
+```php
+// ✅ Good
+function processUser(int $id, string $name, bool $isActive): void
+{
+    // ...
+}
+
+function saveOrder(Order $order, PaymentGatewayInterface $gateway): bool
+{
+    // ...
+}
+
+function filterItems(array $items, callable $callback): array
+{
+    return array_filter($items, $callback);
+}
+
+// ❌ Bad
+function processUser($id, $name, $isActive)  // No type hints
+{
+    // ...
+}
+```
+
+### Return Type Declarations
+
+**Rules:**
+- Return types SHOULD be declared for all methods
+- Use `void` for methods that don't return a value
+- Use specific types instead of `mixed` when possible
+- Use `never` for methods that always throw or exit (PHP 8.1+)
+
+**Examples:**
+```php
+// ✅ Good
+function getUserById(int $id): ?User
+{
+    return User::find($id);
+}
+
+function calculateTotal(array $items): float
+{
+    return array_sum(array_column($items, 'price'));
+}
+
+function logMessage(string $message): void
+{
+    error_log($message);
+}
+
+function throwError(): never
+{
+    throw new RuntimeException('Fatal error');
+}
+
+// ❌ Bad
+function getUserById(int $id)  // No return type
+{
+    return User::find($id);
+}
+```
+
+---
+
+## Nullable Types
+
+### Nullable Type Syntax
+
+**Rules:**
+- Use `?Type` syntax for nullable types
+- Nullable types indicate the value can be `null`
+- Place `?` before the type name
+
+**Examples:**
+```php
+// ✅ Good
+function findUser(int $id): ?User
+{
+    return User::find($id) ?: null;
+}
+
+function processData(?string $input): string
+{
+    return $input ?? 'default';
+}
+
+class User
+{
+    public function __construct(
+        public string $name,
+        public ?string $email = null,
+        public ?DateTime $birthDate = null
+    ) {}
+}
+
+// ❌ Bad
+function findUser(int $id): User  // Should be nullable
+{
+    return User::find($id) ?: null;  // Can return null
+}
+```
+
+---
+
+## Union Types (PHP 8.0+)
+
+### Union Type Syntax
+
+**Rules:**
+- Use `Type1|Type2` syntax for union types
+- Union types allow multiple possible types
+- Order types from most specific to least specific
+- Use when a parameter or return can be multiple types
+
+**Examples:**
+```php
+// ✅ Good
+function formatValue(int|float $value): string
+{
+    return number_format($value, 2);
+}
+
+function processInput(string|array $data): array
+{
+    return is_array($data) ? $data : [$data];
+}
+
+function findRecord(int|string $identifier): ?User
+{
+    return is_int($identifier)
+        ? User::find($identifier)
+        : User::where('email', $identifier)->first();
+}
+
+// Union with null (alternative to nullable syntax)
+function getValue(): int|string|null
+{
+    // ...
+}
+
+// ❌ Bad
+function formatValue($value): string  // Should specify int|float
+{
+    return number_format($value, 2);
+}
+```
+
+---
+
+## Intersection Types (PHP 8.1+)
+
+### Intersection Type Syntax
+
+**Rules:**
+- Use `Type1&Type2` syntax for intersection types
+- Intersection types require all types to be satisfied
+- Commonly used with interfaces
+
+**Examples:**
+```php
+// ✅ Good
+interface Loggable
+{
+    public function log(): void;
+}
+
+interface Cacheable
+{
+    public function cache(): void;
+}
+
+function processEntity(Loggable&Cacheable $entity): void
+{
+    $entity->log();
+    $entity->cache();
+}
+```
+
+---
+
+## Property Type Declarations (PHP 7.4+)
+
+### Typed Properties
+
+**Rules:**
+- Class properties SHOULD have type declarations
+- Typed properties enforce type at assignment
+- Uninitialized typed properties throw error if accessed
+
+**Examples:**
+```php
+// ✅ Good
+class User
+{
+    private int $id;
+    private string $name;
+    private ?string $email = null;
+    private array $roles = [];
+    private DateTime $createdAt;
+    
+    public function __construct(int $id, string $name)
+    {
+        $this->id = $id;
+        $this->name = $name;
+        $this->createdAt = new DateTime();
+    }
+}
+
+// ❌ Bad
+class User
+{
+    private $id;  // No type
+    private $name;  // No type
+    private $email;  // No type
+}
+```
+
+### Readonly Properties (PHP 8.1+)
+
+**Rules:**
+- Use `readonly` for properties that should not change after initialization
+- Readonly properties can only be initialized once
+- Readonly properties must have a type declaration
+
+**Examples:**
+```php
+// ✅ Good
+class User
+{
+    public function __construct(
+        public readonly int $id,
+        public readonly string $name,
+        public readonly DateTime $createdAt
+    ) {}
+}
+
+// ❌ Bad - trying to modify readonly
+$user = new User(1, 'John', new DateTime());
+$user->name = 'Jane';  // Error: Cannot modify readonly property
+```
+
+---
+
+## Constructor Property Promotion (PHP 8.0+)
+
+**Rules:**
+- Use promoted properties to reduce boilerplate
+- Combine parameter declaration with property declaration
+- Works with visibility modifiers and type declarations
+
+**Examples:**
+```php
+// ✅ Good (PHP 8.0+)
+class User
+{
+    public function __construct(
+        private int $id,
+        private string $name,
+        private ?string $email = null,
+        private array $roles = []
+    ) {}
+}
+
+// ❌ Verbose (old style)
+class User
+{
+    private int $id;
+    private string $name;
+    private ?string $email;
+    private array $roles;
+    
+    public function __construct(int $id, string $name, ?string $email = null, array $roles = [])
+    {
+        $this->id = $id;
+        $this->name = $name;
+        $this->email = $email;
+        $this->roles = $roles;
+    }
+}
+```
+