moai-adk 0.8.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-lang-php/SKILL.md

@@ -1,123 +1,644 @@
 ---
 name: moai-lang-php
-version: 2.0.0
-created: 2025-10-22
-updated: 2025-10-22
+description: PHP 8.3+ development specialist covering Laravel 11, Symfony 7, Eloquent ORM, and modern PHP patterns. Use when developing PHP APIs, web applications, or Laravel/Symfony projects.
+version: 1.0.0
+updated: 2025-12-07
 status: active
-description: PHP 8.4+ best practices with PHPUnit 11, Composer, and PSR-12 standards.
-keywords: ['php', 'phpunit', 'composer', 'psr']
-allowed-tools:
-  - Read
-  - Bash
+allowed-tools: Read, Grep, Glob, Bash, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
 ---
 
-# Lang Php Skill
-
-## Skill Metadata
-
-| Field | Value |
-| ----- | ----- |
-| **Skill Name** | moai-lang-php |
-| **Version** | 2.0.0 (2025-10-22) |
-| **Allowed tools** | Read (read_file), Bash (terminal) |
-| **Auto-load** | On demand when keywords detected |
-| **Tier** | Language |
+## Quick Reference (30 seconds)
+
+PHP 8.3+ Development Specialist - Laravel 11, Symfony 7, Eloquent, Doctrine, and modern PHP patterns.
+
+Auto-Triggers: `.php` files, `composer.json`, `artisan`, `symfony.yaml`, Laravel/Symfony discussions
+
+Core Capabilities:
+- PHP 8.3 Features: readonly classes, typed properties, attributes, enums, named arguments
+- Laravel 11: Controllers, Models, Migrations, Form Requests, API Resources, Eloquent
+- Symfony 7: Attribute-based routing, Doctrine ORM, Services, Dependency Injection
+- ORMs: Eloquent (Laravel), Doctrine (Symfony)
+- Testing: PHPUnit, Pest, feature/unit testing patterns
+- Package Management: Composer with autoloading
+- Coding Standards: PSR-12, Laravel Pint, PHP CS Fixer
+- Docker: PHP-FPM, nginx, multi-stage builds
+
+### Quick Patterns
+
+Laravel Controller:
+```php
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\StoreUserRequest;
+use App\Http\Resources\UserResource;
+use App\Models\User;
+use Illuminate\Http\JsonResponse;
+
+class UserController extends Controller
+{
+    public function store(StoreUserRequest $request): JsonResponse
+    {
+        $user = User::create($request->validated());
+        return response()->json(new UserResource($user), 201);
+    }
+}
+```
+
+Laravel Form Request:
+```php
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class StoreUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'unique:users,email'],
+            'password' => ['required', 'min:8', 'confirmed'],
+        ];
+    }
+}
+```
+
+Symfony Controller:
+```php
+<?php
+
+namespace App\Controller;
+
+use App\Entity\User;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+#[Route('/api/users')]
+class UserController extends AbstractController
+{
+    #[Route('', methods: ['POST'])]
+    public function create(EntityManagerInterface $em): JsonResponse
+    {
+        $user = new User();
+        $em->persist($user);
+        $em->flush();
+        return $this->json($user, 201);
+    }
+}
+```
 
 ---
 
-## What It Does
-
-PHP 8.4+ best practices with PHPUnit 11, Composer, and PSR-12 standards.
-
-**Key capabilities**:
-- ✅ Best practices enforcement for language domain
-- ✅ TRUST 5 principles integration
-- ✅ Latest tool versions (2025-10-22)
-- ✅ TDD workflow support
+## Implementation Guide (5 minutes)
+
+### PHP 8.3 Modern Features
+
+Readonly Classes:
+```php
+<?php
+
+readonly class UserDTO
+{
+    public function __construct(
+        public int $id,
+        public string $name,
+        public string $email,
+        public ?DateTime $createdAt = null,
+    ) {}
+}
+```
+
+Typed Class Constants:
+```php
+<?php
+
+class Status
+{
+    public const string PENDING = 'pending';
+    public const string ACTIVE = 'active';
+    public const string INACTIVE = 'inactive';
+}
+```
+
+Enums with Methods:
+```php
+<?php
+
+enum OrderStatus: string
+{
+    case Pending = 'pending';
+    case Processing = 'processing';
+    case Completed = 'completed';
+    case Cancelled = 'cancelled';
+
+    public function label(): string
+    {
+        return match($this) {
+            self::Pending => 'Pending',
+            self::Processing => 'Processing',
+            self::Completed => 'Completed',
+            self::Cancelled => 'Cancelled',
+        };
+    }
+
+    public function canTransitionTo(self $status): bool
+    {
+        return match($this) {
+            self::Pending => in_array($status, [self::Processing, self::Cancelled]),
+            self::Processing => in_array($status, [self::Completed, self::Cancelled]),
+            self::Completed, self::Cancelled => false,
+        };
+    }
+}
+```
+
+Attributes:
+```php
+<?php
+
+#[Attribute(Attribute::TARGET_PROPERTY)]
+class Validate
+{
+    public function __construct(
+        public string $rule,
+        public ?string $message = null,
+    ) {}
+}
+
+class UserRequest
+{
+    #[Validate('required|email')]
+    public string $email;
+
+    #[Validate('required|min:8')]
+    public string $password;
+}
+```
+
+### Laravel 11 Patterns
+
+Eloquent Model with Relationships:
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+class Post extends Model
+{
+    use HasFactory;
+
+    protected $fillable = ['title', 'content', 'user_id', 'status'];
+
+    protected $casts = [
+        'status' => PostStatus::class,
+        'published_at' => 'datetime',
+    ];
+
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function comments(): HasMany
+    {
+        return $this->hasMany(Comment::class);
+    }
+
+    public function scopePublished($query)
+    {
+        return $query->where('status', PostStatus::Published);
+    }
+}
+```
+
+API Resource with Nested Data:
+```php
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class PostResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'title' => $this->title,
+            'content' => $this->content,
+            'status' => $this->status->value,
+            'author' => new UserResource($this->whenLoaded('user')),
+            'comments' => CommentResource::collection($this->whenLoaded('comments')),
+            'comments_count' => $this->whenCounted('comments'),
+            'created_at' => $this->created_at->toIso8601String(),
+            'updated_at' => $this->updated_at->toIso8601String(),
+        ];
+    }
+}
+```
+
+Migration with Foreign Keys:
+```php
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('posts', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained()->cascadeOnDelete();
+            $table->string('title');
+            $table->text('content');
+            $table->string('status')->default('draft');
+            $table->timestamp('published_at')->nullable();
+            $table->timestamps();
+            $table->softDeletes();
+
+            $table->index(['status', 'published_at']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('posts');
+    }
+};
+```
+
+Service Layer Pattern:
+```php
+<?php
+
+namespace App\Services;
+
+use App\Models\User;
+use App\DTOs\UserDTO;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\DB;
+
+class UserService
+{
+    public function create(UserDTO $dto): User
+    {
+        return DB::transaction(function () use ($dto) {
+            $user = User::create([
+                'name' => $dto->name,
+                'email' => $dto->email,
+                'password' => Hash::make($dto->password),
+            ]);
+
+            $user->profile()->create([
+                'bio' => $dto->bio ?? '',
+            ]);
+
+            return $user->load('profile');
+        });
+    }
+
+    public function update(User $user, UserDTO $dto): User
+    {
+        $user->update([
+            'name' => $dto->name,
+            'email' => $dto->email,
+        ]);
+
+        return $user->fresh();
+    }
+}
+```
+
+### Symfony 7 Patterns
+
+Entity with Doctrine Attributes:
+```php
+<?php
+
+namespace App\Entity;
+
+use App\Repository\UserRepository;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\Validator\Constraints as Assert;
+
+#[ORM\Entity(repositoryClass: UserRepository::class)]
+#[ORM\Table(name: 'users')]
+#[ORM\HasLifecycleCallbacks]
+class User
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private ?int $id = null;
+
+    #[ORM\Column(length: 255)]
+    #[Assert\NotBlank]
+    #[Assert\Length(max: 255)]
+    private ?string $name = null;
+
+    #[ORM\Column(length: 180, unique: true)]
+    #[Assert\Email]
+    private ?string $email = null;
+
+    #[ORM\Column]
+    private ?\DateTimeImmutable $createdAt = null;
+
+    #[ORM\PrePersist]
+    public function setCreatedAtValue(): void
+    {
+        $this->createdAt = new \DateTimeImmutable();
+    }
+
+    // Getters and setters...
+}
+```
+
+Repository with Custom Queries:
+```php
+<?php
+
+namespace App\Repository;
+
+use App\Entity\User;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+class UserRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, User::class);
+    }
+
+    public function findActiveUsers(): array
+    {
+        return $this->createQueryBuilder('u')
+            ->andWhere('u.isActive = :active')
+            ->setParameter('active', true)
+            ->orderBy('u.createdAt', 'DESC')
+            ->getQuery()
+            ->getResult();
+    }
+
+    public function findByEmailDomain(string $domain): array
+    {
+        return $this->createQueryBuilder('u')
+            ->andWhere('u.email LIKE :domain')
+            ->setParameter('domain', '%@' . $domain)
+            ->getQuery()
+            ->getResult();
+    }
+}
+```
+
+Service with Dependency Injection:
+```php
+<?php
+
+namespace App\Service;
+
+use App\Entity\User;
+use App\Repository\UserRepository;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Component\PasswordHasher\Hasher\UserPasswordHasherInterface;
+
+class UserService
+{
+    public function __construct(
+        private readonly EntityManagerInterface $entityManager,
+        private readonly UserRepository $userRepository,
+        private readonly UserPasswordHasherInterface $passwordHasher,
+    ) {}
+
+    public function createUser(string $email, string $password, string $name): User
+    {
+        $user = new User();
+        $user->setEmail($email);
+        $user->setName($name);
+        $user->setPassword($this->passwordHasher->hashPassword($user, $password));
+
+        $this->entityManager->persist($user);
+        $this->entityManager->flush();
+
+        return $user;
+    }
+}
+```
+
+### Testing Patterns
+
+PHPUnit Feature Test (Laravel):
+```php
+<?php
+
+namespace Tests\Feature;
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use Tests\TestCase;
+
+class UserApiTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_can_create_user(): void
+    {
+        $response = $this->postJson('/api/users', [
+            'name' => 'John Doe',
+            'email' => 'john@example.com',
+            'password' => 'password123',
+            'password_confirmation' => 'password123',
+        ]);
+
+        $response->assertStatus(201)
+            ->assertJsonStructure([
+                'data' => ['id', 'name', 'email', 'created_at'],
+            ]);
+
+        $this->assertDatabaseHas('users', [
+            'email' => 'john@example.com',
+        ]);
+    }
+
+    public function test_cannot_create_user_with_duplicate_email(): void
+    {
+        User::factory()->create(['email' => 'john@example.com']);
+
+        $response = $this->postJson('/api/users', [
+            'name' => 'John Doe',
+            'email' => 'john@example.com',
+            'password' => 'password123',
+            'password_confirmation' => 'password123',
+        ]);
+
+        $response->assertStatus(422)
+            ->assertJsonValidationErrors(['email']);
+    }
+}
+```
+
+Pest Test (Laravel):
+```php
+<?php
+
+use App\Models\User;
+use App\Models\Post;
+
+it('can create a post', function () {
+    $user = User::factory()->create();
+
+    $response = $this->actingAs($user)
+        ->postJson('/api/posts', [
+            'title' => 'My First Post',
+            'content' => 'This is the content.',
+        ]);
+
+    $response->assertStatus(201);
+    expect(Post::count())->toBe(1);
+});
+
+it('requires authentication to create post', function () {
+    $this->postJson('/api/posts', [
+        'title' => 'My Post',
+        'content' => 'Content here.',
+    ])->assertStatus(401);
+});
+
+dataset('invalid_posts', [
+    'missing title' => [['content' => 'content'], 'title'],
+    'missing content' => [['title' => 'title'], 'content'],
+    'title too short' => [['title' => 'ab', 'content' => 'content'], 'title'],
+]);
+
+it('validates post data', function (array $data, string $field) {
+    $user = User::factory()->create();
+
+    $this->actingAs($user)
+        ->postJson('/api/posts', $data)
+        ->assertStatus(422)
+        ->assertJsonValidationErrors([$field]);
+})->with('invalid_posts');
+```
 
 ---
 
-## When to Use
+## Advanced Implementation (10+ minutes)
 
-**Automatic triggers**:
-- Related code discussions and file patterns
-- SPEC implementation (`/alfred:2-run`)
-- Code review requests
+For comprehensive coverage including:
+- Production deployment patterns (Docker, Kubernetes)
+- Advanced Eloquent patterns (observers, accessors, mutators)
+- Doctrine advanced mapping (embeddables, inheritance)
+- Queue and job processing
+- Event-driven architecture
+- Caching strategies (Redis, Memcached)
+- Security best practices (OWASP patterns)
+- CI/CD integration patterns
 
-**Manual invocation**:
-- Review code for TRUST 5 compliance
-- Design new features
-- Troubleshoot issues
+See:
+- [reference.md](reference.md) - Complete reference documentation
+- [examples.md](examples.md) - Production-ready code examples
 
 ---
 
-## Tool Version Matrix (2025-10-22)
+## Context7 Library Mappings
 
-| Tool | Version | Purpose | Status |
-|------|---------|---------|--------|
-| **PHP** | 8.4.0 | Primary | ✅ Current |
-| **PHPUnit** | 11.5.0 | Primary | ✅ Current |
-| **Composer** | 2.8.0 | Primary | ✅ Current |
-
----
-
-## Inputs
-
-- Language-specific source directories
-- Configuration files
-- Test suites and sample data
-
-## Outputs
-
-- Test/lint execution plan
-- TRUST 5 review checkpoints
-- Migration guidance
-
-## Failure Modes
-
-- When required tools are not installed
-- When dependencies are missing
-- When test coverage falls below 85%
-
-## Dependencies
-
-- Access to project files via Read/Bash tools
-- Integration with `moai-foundation-langs` for language detection
-- Integration with `moai-foundation-trust` for quality gates
-
----
-
-## References (Latest Documentation)
-
-_Documentation links updated 2025-10-22_
-
----
-
-## Changelog
-
-- **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
-- **v1.0.0** (2025-03-29): Initial Skill release
+```
+/laravel/framework - Laravel web framework
+/symfony/symfony - Symfony components and framework
+/doctrine/orm - Doctrine ORM for PHP
+/phpunit/phpunit - PHP testing framework
+/pestphp/pest - Elegant PHP testing framework
+/laravel/sanctum - Laravel API authentication
+/laravel/horizon - Laravel queue dashboard
+```
 
 ---
 
 ## Works Well With
 
-- `moai-foundation-trust` (quality gates)
-- `moai-alfred-code-reviewer` (code review)
-- `moai-essentials-debug` (debugging support)
+- `moai-domain-backend` - REST API and microservices architecture
+- `moai-domain-database` - SQL patterns and ORM optimization
+- `moai-quality-testing` - TDD and testing strategies
+- `moai-platform-deploy` - Docker and deployment patterns
+- `moai-essentials-debug` - AI-powered debugging
+- `moai-foundation-trust` - TRUST 5 quality principles
 
 ---
 
-## Best Practices
+## Troubleshooting
+
+Common Issues:
+
+PHP Version Check:
+```bash
+php --version  # Should be 8.3+
+php -m | grep -E 'pdo|mbstring|openssl'  # Required extensions
+```
+
+Composer Autoload Issues:
+```bash
+composer dump-autoload -o  # Regenerate optimized autoload
+composer clear-cache  # Clear composer cache
+```
+
+Laravel Cache Issues:
+```bash
+php artisan config:clear
+php artisan cache:clear
+php artisan route:clear
+php artisan view:clear
+```
+
+Symfony Cache Issues:
+```bash
+php bin/console cache:clear
+php bin/console cache:warmup
+```
+
+Database Connection:
+```php
+// Laravel - Check database connection
+try {
+    DB::connection()->getPdo();
+    echo "Connected successfully";
+} catch (\Exception $e) {
+    echo "Connection failed: " . $e->getMessage();
+}
+```
+
+Migration Rollback:
+```bash
+# Laravel
+php artisan migrate:rollback --step=1
+php artisan migrate:fresh --seed  # Development only
+
+# Symfony
+php bin/console doctrine:migrations:migrate prev
+```
 
-✅ **DO**:
-- Follow language best practices
-- Use latest stable tool versions
-- Maintain test coverage ≥85%
-- Document all public APIs
+---
 
-❌ **DON'T**:
-- Skip quality gates
-- Use deprecated tools
-- Ignore security warnings
-- Mix testing frameworks
+Last Updated: 2025-12-07
+Status: Active (v1.0.0)