aigroup-workflow 2.1.2 → 2.2.0

package/skills/php/php-pro/references/laravel-patterns.md

@@ -0,0 +1,377 @@
+# Laravel Patterns
+
+## Service Layer Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+use App\DTOs\CreateUserData;
+use App\Models\User;
+use App\Repositories\UserRepositoryInterface;
+use Illuminate\Support\Facades\Hash;
+
+final readonly class UserService
+{
+    public function __construct(
+        private UserRepositoryInterface $userRepository,
+        private EmailService $emailService,
+    ) {}
+
+    public function createUser(CreateUserData $data): User
+    {
+        $user = $this->userRepository->create([
+            'name' => $data->name,
+            'email' => $data->email,
+            'password' => Hash::make($data->password),
+        ]);
+
+        $this->emailService->sendWelcomeEmail($user);
+
+        return $user;
+    }
+
+    public function suspendUser(int $userId, string $reason): void
+    {
+        $user = $this->userRepository->findOrFail($userId);
+
+        $this->userRepository->update($user->id, [
+            'status' => UserStatus::SUSPENDED,
+            'suspension_reason' => $reason,
+            'suspended_at' => now(),
+        ]);
+
+        $this->emailService->sendSuspensionNotice($user, $reason);
+    }
+}
+```
+
+## Repository Pattern
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Repositories;
+
+use App\Models\User;
+use Illuminate\Database\Eloquent\Collection;
+
+interface UserRepositoryInterface
+{
+    public function findOrFail(int $id): User;
+    public function findByEmail(string $email): ?User;
+    public function create(array $data): User;
+    public function update(int $id, array $data): User;
+    public function delete(int $id): void;
+    public function getActive(): Collection;
+}
+
+final class UserRepository implements UserRepositoryInterface
+{
+    public function findOrFail(int $id): User
+    {
+        return User::findOrFail($id);
+    }
+
+    public function findByEmail(string $email): ?User
+    {
+        return User::where('email', $email)->first();
+    }
+
+    public function create(array $data): User
+    {
+        return User::create($data);
+    }
+
+    public function update(int $id, array $data): User
+    {
+        $user = $this->findOrFail($id);
+        $user->update($data);
+        return $user->fresh();
+    }
+
+    public function delete(int $id): void
+    {
+        $this->findOrFail($id)->delete();
+    }
+
+    public function getActive(): Collection
+    {
+        return User::where('status', UserStatus::ACTIVE)
+            ->orderBy('created_at', 'desc')
+            ->get();
+    }
+}
+```
+
+## Form Requests with Enums
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests;
+
+use App\Enums\UserRole;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+use Illuminate\Validation\Rules\Enum;
+use Illuminate\Validation\Rules\Password;
+
+final class CreateUserRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()?->can('create', User::class) ?? false;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'max:255'],
+            'email' => ['required', 'email', 'unique:users,email'],
+            'password' => ['required', Password::min(8)->mixedCase()->numbers()],
+            'role' => ['required', new Enum(UserRole::class)],
+            'settings' => ['sometimes', 'array'],
+            'settings.theme' => ['string', Rule::in(['light', 'dark'])],
+        ];
+    }
+
+    public function toDto(): CreateUserData
+    {
+        return new CreateUserData(
+            name: $this->validated('name'),
+            email: $this->validated('email'),
+            password: $this->validated('password'),
+            role: UserRole::from($this->validated('role')),
+        );
+    }
+}
+```
+
+## API Resources
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/**
+ * @mixin \App\Models\User
+ */
+final class UserResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'name' => $this->name,
+            'email' => $this->email,
+            'status' => $this->status->value,
+            'role' => $this->role->value,
+            'created_at' => $this->created_at->toIso8601String(),
+
+            // Conditional relationships
+            'posts' => PostResource::collection($this->whenLoaded('posts')),
+            'profile' => new ProfileResource($this->whenLoaded('profile')),
+
+            // Conditional attributes
+            'is_admin' => $this->when($this->role === UserRole::ADMIN, true),
+
+            // Pivot data
+            'team_role' => $this->whenPivotLoaded('team_user', fn() =>
+                $this->pivot->role
+            ),
+        ];
+    }
+}
+
+final class UserCollection extends ResourceCollection
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'data' => $this->collection,
+            'meta' => [
+                'total' => $this->total(),
+                'per_page' => $this->perPage(),
+            ],
+        ];
+    }
+}
+```
+
+## Controllers with DTOs
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\CreateUserRequest;
+use App\Http\Resources\UserResource;
+use App\Services\UserService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+
+final class UserController extends Controller
+{
+    public function __construct(
+        private readonly UserService $userService,
+    ) {}
+
+    public function index(): AnonymousResourceCollection
+    {
+        $users = User::with('profile')
+            ->where('status', UserStatus::ACTIVE)
+            ->paginate(20);
+
+        return UserResource::collection($users);
+    }
+
+    public function store(CreateUserRequest $request): JsonResponse
+    {
+        $user = $this->userService->createUser($request->toDto());
+
+        return (new UserResource($user))
+            ->response()
+            ->setStatusCode(201);
+    }
+
+    public function show(User $user): UserResource
+    {
+        $user->load(['posts', 'profile']);
+        return new UserResource($user);
+    }
+
+    public function destroy(User $user): JsonResponse
+    {
+        $this->authorize('delete', $user);
+
+        $this->userService->deleteUser($user->id);
+
+        return response()->json(null, 204);
+    }
+}
+```
+
+## Jobs & Queues
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Jobs;
+
+use App\Models\User;
+use App\Services\EmailService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+final class SendWelcomeEmail implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    public int $tries = 3;
+    public int $timeout = 30;
+
+    public function __construct(
+        private readonly int $userId,
+    ) {}
+
+    public function handle(EmailService $emailService): void
+    {
+        $user = User::findOrFail($this->userId);
+        $emailService->sendWelcomeEmail($user);
+    }
+
+    public function failed(\Throwable $exception): void
+    {
+        \Log::error('Failed to send welcome email', [
+            'user_id' => $this->userId,
+            'error' => $exception->getMessage(),
+        ]);
+    }
+}
+
+// Dispatching jobs
+SendWelcomeEmail::dispatch($user->id);
+SendWelcomeEmail::dispatch($user->id)->delay(now()->addMinutes(5));
+SendWelcomeEmail::dispatch($user->id)->onQueue('emails');
+```
+
+## Event Listeners
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Events;
+
+use App\Models\User;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+final readonly class UserRegistered
+{
+    use Dispatchable, SerializesModels;
+
+    public function __construct(
+        public User $user,
+    ) {}
+}
+
+namespace App\Listeners;
+
+use App\Events\UserRegistered;
+use App\Jobs\SendWelcomeEmail;
+use Illuminate\Contracts\Queue\ShouldQueue;
+
+final class SendWelcomeNotification implements ShouldQueue
+{
+    public function handle(UserRegistered $event): void
+    {
+        SendWelcomeEmail::dispatch($event->user->id);
+    }
+}
+
+// In EventServiceProvider
+protected $listen = [
+    UserRegistered::class => [
+        SendWelcomeNotification::class,
+        UpdateUserStatistics::class,
+    ],
+];
+```
+
+## Quick Reference
+
+| Pattern | Purpose | File Location |
+|---------|---------|---------------|
+| Service | Business logic | `app/Services/` |
+| Repository | Data access | `app/Repositories/` |
+| Form Request | Validation | `app/Http/Requests/` |
+| Resource | API responses | `app/Http/Resources/` |
+| Job | Async tasks | `app/Jobs/` |
+| Event | Domain events | `app/Events/` |
+| DTO | Data transfer | `app/DTOs/` |
+| Policy | Authorization | `app/Policies/` |

package/skills/php/php-pro/references/modern-php-features.md

@@ -0,0 +1,323 @@
+# Modern PHP 8.3+ Features
+
+## Strict Types & Type Declarations
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Domain\User;
+
+final readonly class User
+{
+    public function __construct(
+        public int $id,
+        public string $email,
+        public UserStatus $status,
+        public \DateTimeImmutable $createdAt,
+    ) {}
+}
+
+function calculateTotal(int $price, float $taxRate): float
+{
+    return $price * (1 + $taxRate);
+}
+
+// Union types
+function processId(int|string $id): string
+{
+    return is_int($id) ? (string)$id : $id;
+}
+
+// Intersection types
+interface Timestamped {}
+interface Authenticatable {}
+
+function handleUser(Timestamped&Authenticatable $user): void {}
+```
+
+## Enums with Methods
+
+```php
+<?php
+
+declare(strict_types=1);
+
+enum UserStatus: string
+{
+    case ACTIVE = 'active';
+    case SUSPENDED = 'suspended';
+    case DELETED = 'deleted';
+
+    public function label(): string
+    {
+        return match($this) {
+            self::ACTIVE => 'Active User',
+            self::SUSPENDED => 'Suspended',
+            self::DELETED => 'Deleted User',
+        };
+    }
+
+    public function canLogin(): bool
+    {
+        return $this === self::ACTIVE;
+    }
+
+    public static function fromString(string $value): self
+    {
+        return self::from(strtolower($value));
+    }
+}
+
+enum HttpStatus: int
+{
+    case OK = 200;
+    case CREATED = 201;
+    case BAD_REQUEST = 400;
+    case UNAUTHORIZED = 401;
+    case NOT_FOUND = 404;
+    case SERVER_ERROR = 500;
+
+    public function isSuccess(): bool
+    {
+        return $this->value >= 200 && $this->value < 300;
+    }
+}
+```
+
+## Readonly Properties & Classes
+
+```php
+<?php
+
+declare(strict_types=1);
+
+// Readonly class (PHP 8.2+)
+final readonly class Money
+{
+    public function __construct(
+        public int $amount,
+        public string $currency,
+    ) {
+        if ($amount < 0) {
+            throw new \InvalidArgumentException('Amount cannot be negative');
+        }
+    }
+
+    public function add(Money $other): self
+    {
+        if ($this->currency !== $other->currency) {
+            throw new \InvalidArgumentException('Currency mismatch');
+        }
+        return new self($this->amount + $other->amount, $this->currency);
+    }
+}
+
+// Individual readonly properties
+class Configuration
+{
+    public function __construct(
+        public readonly string $apiKey,
+        public readonly string $apiSecret,
+        private string $cache = '',
+    ) {}
+}
+```
+
+## Attributes (Metadata)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+#[\Attribute(\Attribute::TARGET_CLASS)]
+final readonly class Route
+{
+    public function __construct(
+        public string $path,
+        public string $method = 'GET',
+        public array $middleware = [],
+    ) {}
+}
+
+#[\Attribute(\Attribute::TARGET_PROPERTY)]
+final readonly class Validate
+{
+    public function __construct(
+        public ?string $rule = null,
+        public ?int $min = null,
+        public ?int $max = null,
+    ) {}
+}
+
+// Using attributes
+#[Route('/api/users', method: 'POST', middleware: ['auth'])]
+final class CreateUserController
+{
+    public function __invoke(CreateUserRequest $request): JsonResponse
+    {
+        // ...
+    }
+}
+
+class UserDto
+{
+    #[Validate(rule: 'email')]
+    public string $email;
+
+    #[Validate(min: 8, max: 100)]
+    public string $password;
+}
+```
+
+## First-Class Callables
+
+```php
+<?php
+
+declare(strict_types=1);
+
+class UserService
+{
+    public function findById(int $id): ?User {}
+    public function create(array $data): User {}
+}
+
+$service = new UserService();
+
+// PHP 8.1+ first-class callable syntax
+$finder = $service->findById(...);
+$user = $finder(42);
+
+// Array operations
+$numbers = [1, 2, 3, 4, 5];
+$doubled = array_map(fn($n) => $n * 2, $numbers);
+
+// Named arguments with callable
+$result = array_filter(
+    array: $numbers,
+    callback: fn($n) => $n % 2 === 0,
+);
+```
+
+## Match Expressions
+
+```php
+<?php
+
+declare(strict_types=1);
+
+function getStatusColor(UserStatus $status): string
+{
+    return match ($status) {
+        UserStatus::ACTIVE => 'green',
+        UserStatus::SUSPENDED => 'yellow',
+        UserStatus::DELETED => 'red',
+    };
+}
+
+function calculateShipping(int $weight, string $zone): float
+{
+    return match (true) {
+        $weight < 1000 => 5.00,
+        $weight < 5000 && $zone === 'local' => 10.00,
+        $weight < 5000 => 15.00,
+        default => 25.00,
+    };
+}
+
+// Match with multiple conditions
+function getHttpMessage(int $code): string
+{
+    return match ($code) {
+        200, 201, 204 => 'Success',
+        400, 422 => 'Client Error',
+        401, 403 => 'Unauthorized',
+        500, 502, 503 => 'Server Error',
+        default => 'Unknown',
+    };
+}
+```
+
+## Fibers (PHP 8.1+)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+// Basic fiber example
+$fiber = new \Fiber(function (): void {
+    $value = \Fiber::suspend('fiber started');
+    echo "Received: {$value}\n";
+    \Fiber::suspend('second suspend');
+    echo "Fiber completed\n";
+});
+
+$result1 = $fiber->start();
+echo "First result: {$result1}\n";
+
+$result2 = $fiber->resume('data from main');
+echo "Second result: {$result2}\n";
+
+$fiber->resume('final data');
+
+// Async-style with fibers
+function async(callable $callback): \Fiber
+{
+    return new \Fiber($callback);
+}
+
+function await(\Fiber $fiber): mixed
+{
+    if (!$fiber->isStarted()) {
+        return $fiber->start();
+    }
+    return $fiber->resume();
+}
+```
+
+## Never Type
+
+```php
+<?php
+
+declare(strict_types=1);
+
+function redirect(string $url): never
+{
+    header("Location: {$url}");
+    exit;
+}
+
+function abort(int $code, string $message): never
+{
+    http_response_code($code);
+    echo json_encode(['error' => $message]);
+    exit;
+}
+
+class NotFoundException extends \Exception
+{
+    public static function throw(string $resource): never
+    {
+        throw new self("Resource not found: {$resource}");
+    }
+}
+```
+
+## Quick Reference
+
+| Feature | PHP Version | Usage |
+|---------|-------------|-------|
+| Readonly properties | 8.1+ | `public readonly string $name` |
+| Readonly classes | 8.2+ | `readonly class User {}` |
+| Enums | 8.1+ | `enum Status: string {}` |
+| First-class callables | 8.1+ | `$fn = $obj->method(...)` |
+| Never type | 8.1+ | `function exit(): never` |
+| Fibers | 8.1+ | `new \Fiber(fn() => ...)` |
+| Pure intersection types | 8.1+ | `A&B $param` |
+| DNF types | 8.2+ | `(A&B)\|C $param` |
+| Constants in traits | 8.2+ | `trait T { const X = 1; }` |