@famgia/omnify-laravel 0.0.87 → 0.0.89

package/stubs/ai-guides/laravel/datetime.md.stub

@@ -0,0 +1,334 @@
+# DateTime Handling Guide
+
+> **Related:** [README](./README.md) | [Resource Guide](./resource-guide.md)
+
+## Golden Rule: "Store UTC, Respond UTC, Accept UTC"
+
+```
+Database (UTC) ← Carbon (UTC) → API Response (ISO 8601 UTC)
+                     ↑
+              API Request (UTC)
+```
+
+---
+
+## Configuration
+
+### 1. Set Application Timezone to UTC
+
+**`config/app.php`:**
+
+```php
+'timezone' => 'UTC',
+```
+
+> ⚠️ NEVER change this to local timezone. Always use UTC.
+
+### 2. Database Timezone
+
+**MySQL** - Ensure UTC:
+
+```sql
+SET GLOBAL time_zone = '+00:00';
+SET time_zone = '+00:00';
+```
+
+Or in `my.cnf`:
+```ini
+[mysqld]
+default-time-zone = '+00:00'
+```
+
+---
+
+## Carbon Usage Rules
+
+### Always Use Carbon (Never raw DateTime)
+
+```php
+use Illuminate\Support\Carbon;
+
+// ✅ Correct
+$now = Carbon::now();           // Current UTC time
+$date = Carbon::parse($input);  // Parse with UTC
+
+// ❌ Wrong
+$now = new \DateTime();         // Don't use raw DateTime
+$now = date('Y-m-d H:i:s');     // Don't use date()
+```
+
+### API Response Format
+
+**Always return ISO 8601 with Z suffix:**
+
+```php
+// In Model - cast dates properly
+protected $casts = [
+    'email_verified_at' => 'datetime',
+    'scheduled_at' => 'datetime',
+    'created_at' => 'datetime',
+    'updated_at' => 'datetime',
+];
+
+// In Resource - format as ISO 8601 UTC
+public function toArray($request): array
+{
+    return [
+        'id' => $this->id,
+        'title' => $this->title,
+        'scheduled_at' => $this->scheduled_at?->toISOString(),  // "2024-01-15T10:30:00.000000Z"
+        'created_at' => $this->created_at?->toISOString(),
+        'updated_at' => $this->updated_at?->toISOString(),
+    ];
+}
+```
+
+### Accepting Date Input
+
+```php
+// In FormRequest
+public function rules(): array
+{
+    return [
+        'scheduled_at' => ['required', 'date'],  // Accepts ISO 8601
+    ];
+}
+
+// In Controller - Carbon auto-parses UTC
+public function store(StoreEventRequest $request): JsonResponse
+{
+    $event = Event::create([
+        'title' => $request->title,
+        'scheduled_at' => Carbon::parse($request->scheduled_at),  // Already UTC
+    ]);
+
+    return new EventResource($event);
+}
+```
+
+---
+
+## Common Patterns
+
+### Compare Dates
+
+```php
+use Illuminate\Support\Carbon;
+
+// Current UTC time
+$now = Carbon::now();
+
+// Check if past
+if ($event->scheduled_at->isPast()) {
+    // Event has passed
+}
+
+// Check if within range
+$start = Carbon::parse($request->start_date);
+$end = Carbon::parse($request->end_date);
+
+Event::whereBetween('scheduled_at', [$start, $end])->get();
+```
+
+### Query by Date Range
+
+```php
+// Frontend sends UTC strings
+// "2024-01-01T00:00:00Z" to "2024-01-31T23:59:59Z"
+
+public function index(Request $request)
+{
+    $query = Event::query();
+
+    if ($request->filled('start_date')) {
+        $query->where('scheduled_at', '>=', Carbon::parse($request->start_date));
+    }
+
+    if ($request->filled('end_date')) {
+        $query->where('scheduled_at', '<=', Carbon::parse($request->end_date));
+    }
+
+    return EventResource::collection($query->paginate());
+}
+```
+
+### Display for Specific Timezone (if needed)
+
+```php
+// Only when generating reports for specific timezone
+$userTimezone = 'Asia/Tokyo';
+
+$localTime = $event->scheduled_at->setTimezone($userTimezone);
+// Keep original as UTC, create copy for display
+```
+
+---
+
+## Model Setup
+
+### Recommended Model Structure
+
+```php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Carbon;
+
+class Event extends Model
+{
+    protected $fillable = [
+        'title',
+        'scheduled_at',
+    ];
+
+    protected $casts = [
+        'scheduled_at' => 'datetime',
+    ];
+
+    // Accessor for formatted date (if needed internally)
+    public function getScheduledAtFormattedAttribute(): string
+    {
+        return $this->scheduled_at?->toISOString() ?? '';
+    }
+
+    // Scope for upcoming events
+    public function scopeUpcoming($query)
+    {
+        return $query->where('scheduled_at', '>', Carbon::now());
+    }
+
+    // Scope for past events
+    public function scopePast($query)
+    {
+        return $query->where('scheduled_at', '<', Carbon::now());
+    }
+}
+```
+
+### Resource Format
+
+```php
+<?php
+
+namespace App\Http\Resources;
+
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class EventResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'id' => $this->id,
+            'title' => $this->title,
+            'scheduled_at' => $this->scheduled_at?->toISOString(),
+            'is_past' => $this->scheduled_at?->isPast() ?? false,
+            'created_at' => $this->created_at?->toISOString(),
+            'updated_at' => $this->updated_at?->toISOString(),
+        ];
+    }
+}
+```
+
+---
+
+## Migration Example
+
+```php
+Schema::create('events', function (Blueprint $table) {
+    $table->id();
+    $table->string('title');
+    $table->timestamp('scheduled_at');  // Use timestamp, not datetime
+    $table->timestamps();               // created_at, updated_at
+});
+```
+
+> **Note:** `timestamp` columns in MySQL are stored as UTC internally.
+
+---
+
+## Anti-Patterns ❌
+
+```php
+// ❌ DON'T: Set local timezone in config
+'timezone' => 'Asia/Tokyo',  // Wrong!
+
+// ❌ DON'T: Use raw PHP date functions
+$date = date('Y-m-d H:i:s');
+$date = new \DateTime();
+
+// ❌ DON'T: Return formatted local time in API
+return ['created_at' => $this->created_at->format('Y/m/d H:i')];
+
+// ❌ DON'T: Store timezone offset in database
+$event->scheduled_at = '2024-01-15 19:30:00+09:00';
+
+// ❌ DON'T: Convert to local timezone before storing
+$event->scheduled_at = Carbon::parse($input)->setTimezone('Asia/Tokyo');
+```
+
+## Correct Patterns ✅
+
+```php
+// ✅ DO: Keep UTC timezone
+'timezone' => 'UTC',
+
+// ✅ DO: Use Carbon everywhere
+$now = Carbon::now();
+$date = Carbon::parse($input);
+
+// ✅ DO: Return ISO 8601 UTC in API
+return ['created_at' => $this->created_at?->toISOString()];
+
+// ✅ DO: Store as UTC
+$event->scheduled_at = Carbon::parse($input);  // Input should be UTC from frontend
+```
+
+---
+
+## API Contract with Frontend
+
+| Direction      | Format        | Example                         |
+| -------------- | ------------- | ------------------------------- |
+| API → Frontend | ISO 8601 UTC  | `"2024-01-15T10:30:00.000000Z"` |
+| Frontend → API | ISO 8601 UTC  | `"2024-01-15T10:30:00.000Z"`    |
+| Database       | UTC Timestamp | `2024-01-15 10:30:00`           |
+
+---
+
+## Testing with Dates
+
+```php
+use Illuminate\Support\Carbon;
+
+public function test_creates_event_with_correct_date(): void
+{
+    Carbon::setTestNow('2024-01-15 10:00:00');  // Freeze time in UTC
+
+    $response = $this->postJson('/api/events', [
+        'title' => 'Test Event',
+        'scheduled_at' => '2024-01-20T15:00:00.000Z',
+    ]);
+
+    $response->assertCreated();
+    
+    $this->assertDatabaseHas('events', [
+        'title' => 'Test Event',
+        'scheduled_at' => '2024-01-20 15:00:00',  // Stored as UTC
+    ]);
+}
+```
+
+---
+
+## Checklist
+
+- [ ] `config/app.php` timezone is `UTC`
+- [ ] MySQL timezone is UTC
+- [ ] All models use `datetime` cast for date fields
+- [ ] All Resources return `->toISOString()` for dates
+- [ ] Never use raw `date()` or `DateTime` - always Carbon
+- [ ] Never convert to local timezone before storing
+- [ ] API documentation specifies UTC format

package/stubs/ai-guides/laravel/openapi.md.stub

@@ -0,0 +1,369 @@
+# OpenAPI Documentation Guide
+
+> **Related:** [README](./README.md) | [Controller Guide](./controller-guide.md) | [Checklist](./checklist.md)
+
+## Overview
+
+This project uses [L5-Swagger](https://github.com/DarkaOnLine/L5-Swagger) with PHP 8 Attributes.
+
+**Key files:**
+- `app/OpenApi/Schemas.php` - Reusable components (parameters, responses)
+- `app/Http/Controllers/*Controller.php` - Endpoint documentation
+
+## Commands
+
+```bash
+./artisan l5-swagger:generate    # Generate OpenAPI JSON
+# View at: https://api.{folder}.app/api/documentation
+```
+
+---
+
+## Architecture
+
+```
+app/OpenApi/
+└── Schemas.php              ← Define reusable components HERE
+
+app/Http/Controllers/
+└── UserController.php       ← Use $ref to reference components
+```
+
+---
+
+## Step 1: Define Reusable Components
+
+**File:** `app/OpenApi/Schemas.php`
+
+```php
+<?php
+
+namespace App\OpenApi;
+
+use OpenApi\Attributes as OA;
+
+#[OA\Info(
+    version: '1.0.0',
+    title: 'My API',
+    description: 'API documentation'
+)]
+#[OA\Server(url: '/api', description: 'API Server')]
+
+// ============================================================================
+// COMMON PARAMETERS
+// ============================================================================
+
+#[OA\Parameter(
+    parameter: 'QuerySearch',
+    name: 'search',
+    in: 'query',
+    description: 'Search term',
+    schema: new OA\Schema(type: 'string')
+)]
+#[OA\Parameter(
+    parameter: 'QueryPage',
+    name: 'page',
+    in: 'query',
+    description: 'Page number',
+    schema: new OA\Schema(type: 'integer', default: 1, minimum: 1)
+)]
+#[OA\Parameter(
+    parameter: 'QueryPerPage',
+    name: 'per_page',
+    in: 'query',
+    description: 'Items per page',
+    schema: new OA\Schema(type: 'integer', default: 10, minimum: 1, maximum: 100)
+)]
+#[OA\Parameter(
+    parameter: 'QuerySortBy',
+    name: 'sort_by',
+    in: 'query',
+    description: 'Sort field',
+    schema: new OA\Schema(type: 'string', default: 'id')
+)]
+#[OA\Parameter(
+    parameter: 'QuerySortOrder',
+    name: 'sort_order',
+    in: 'query',
+    description: 'Sort direction',
+    schema: new OA\Schema(type: 'string', enum: ['asc', 'desc'], default: 'desc')
+)]
+#[OA\Parameter(
+    parameter: 'PathId',
+    name: 'id',
+    in: 'path',
+    required: true,
+    description: 'Resource ID',
+    schema: new OA\Schema(type: 'integer', minimum: 1)
+)]
+
+// ============================================================================
+// COMMON RESPONSES
+// ============================================================================
+
+#[OA\Response(response: 'Success', description: 'Successful operation')]
+#[OA\Response(response: 'Created', description: 'Resource created successfully')]
+#[OA\Response(response: 'NoContent', description: 'Successfully deleted')]
+#[OA\Response(response: 'NotFound', description: 'Resource not found')]
+#[OA\Response(response: 'Unauthorized', description: 'Unauthenticated')]
+#[OA\Response(response: 'Forbidden', description: 'Forbidden')]
+#[OA\Response(
+    response: 'ValidationError',
+    description: 'Validation failed',
+    content: new OA\JsonContent(
+        properties: [
+            new OA\Property(property: 'message', type: 'string', example: 'The given data was invalid.'),
+            new OA\Property(property: 'errors', type: 'object', example: ['email' => ['The email has already been taken.']]),
+        ]
+    )
+)]
+class Schemas
+{
+    // This class exists only to hold OpenAPI attributes
+}
+```
+
+---
+
+## Step 2: Use $ref in Controllers
+
+### Index (GET list)
+
+```php
+#[OA\Get(
+    path: '/api/users',
+    summary: 'List users',
+    description: 'Paginated list with search and sorting',
+    tags: ['Users'],
+    parameters: [
+        new OA\Parameter(ref: '#/components/parameters/QuerySearch'),
+        new OA\Parameter(ref: '#/components/parameters/QueryPage'),
+        new OA\Parameter(ref: '#/components/parameters/QueryPerPage'),
+        new OA\Parameter(ref: '#/components/parameters/QuerySortBy'),
+        new OA\Parameter(ref: '#/components/parameters/QuerySortOrder'),
+    ],
+    responses: [
+        new OA\Response(ref: '#/components/responses/Success', response: 200),
+    ]
+)]
+public function index(Request $request): AnonymousResourceCollection
+```
+
+### Store (POST)
+
+```php
+#[OA\Post(
+    path: '/api/users',
+    summary: 'Create user',
+    description: 'Create a new user account',
+    tags: ['Users'],
+    requestBody: new OA\RequestBody(
+        required: true,
+        content: new OA\JsonContent(
+            required: ['name_lastname', 'name_firstname', 'email', 'password'],
+            properties: [
+                new OA\Property(property: 'name_lastname', type: 'string', maxLength: 50, example: '田中'),
+                new OA\Property(property: 'name_firstname', type: 'string', maxLength: 50, example: '太郎'),
+                new OA\Property(property: 'email', type: 'string', format: 'email', example: 'tanaka@example.com'),
+                new OA\Property(property: 'password', type: 'string', format: 'password', minLength: 8),
+            ]
+        )
+    ),
+    responses: [
+        new OA\Response(ref: '#/components/responses/Created', response: 201),
+        new OA\Response(ref: '#/components/responses/ValidationError', response: 422),
+    ]
+)]
+public function store(UserStoreRequest $request): UserResource
+```
+
+### Show (GET single)
+
+```php
+#[OA\Get(
+    path: '/api/users/{id}',
+    summary: 'Get user',
+    description: 'Get user by ID',
+    tags: ['Users'],
+    parameters: [
+        new OA\Parameter(ref: '#/components/parameters/PathId'),
+    ],
+    responses: [
+        new OA\Response(ref: '#/components/responses/Success', response: 200),
+        new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+    ]
+)]
+public function show(User $user): UserResource
+```
+
+### Update (PUT)
+
+```php
+#[OA\Put(
+    path: '/api/users/{id}',
+    summary: 'Update user',
+    description: 'Update user (partial update supported)',
+    tags: ['Users'],
+    parameters: [
+        new OA\Parameter(ref: '#/components/parameters/PathId'),
+    ],
+    requestBody: new OA\RequestBody(
+        content: new OA\JsonContent(
+            properties: [
+                new OA\Property(property: 'name_lastname', type: 'string', maxLength: 50),
+                new OA\Property(property: 'name_firstname', type: 'string', maxLength: 50),
+                new OA\Property(property: 'email', type: 'string', format: 'email'),
+                new OA\Property(property: 'password', type: 'string', format: 'password', minLength: 8),
+            ]
+        )
+    ),
+    responses: [
+        new OA\Response(ref: '#/components/responses/Success', response: 200),
+        new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+        new OA\Response(ref: '#/components/responses/ValidationError', response: 422),
+    ]
+)]
+public function update(UserUpdateRequest $request, User $user): UserResource
+```
+
+### Destroy (DELETE)
+
+```php
+#[OA\Delete(
+    path: '/api/users/{id}',
+    summary: 'Delete user',
+    description: 'Permanently delete user',
+    tags: ['Users'],
+    parameters: [
+        new OA\Parameter(ref: '#/components/parameters/PathId'),
+    ],
+    responses: [
+        new OA\Response(ref: '#/components/responses/NoContent', response: 204),
+        new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+    ]
+)]
+public function destroy(User $user): JsonResponse
+```
+
+---
+
+## Available Components
+
+### Parameters (use with `ref: '#/components/parameters/...'`)
+
+| Name             | Description                            |
+| ---------------- | -------------------------------------- |
+| `QuerySearch`    | Search term                            |
+| `QueryPage`      | Page number (default: 1)               |
+| `QueryPerPage`   | Items per page (default: 10, max: 100) |
+| `QuerySortBy`    | Sort field (default: id)               |
+| `QuerySortOrder` | Sort direction (asc/desc)              |
+| `PathId`         | Resource ID in path                    |
+
+### Responses (use with `ref: '#/components/responses/...'`)
+
+| Name              | HTTP Code | Description          |
+| ----------------- | --------- | -------------------- |
+| `Success`         | 200       | Successful operation |
+| `Created`         | 201       | Resource created     |
+| `NoContent`       | 204       | Successfully deleted |
+| `NotFound`        | 404       | Resource not found   |
+| `ValidationError` | 422       | Validation failed    |
+| `Unauthorized`    | 401       | Unauthenticated      |
+| `Forbidden`       | 403       | Forbidden            |
+
+---
+
+## ⚠️ Important: Verify Fields Before Writing
+
+**DO NOT make up fields!** Check these files first:
+
+| What to Document    | Check This File                                                     |
+| ------------------- | ------------------------------------------------------------------- |
+| Request body fields | `app/Http/Requests/OmnifyBase/*RequestBase.php` → `schemaRules()`   |
+| Response fields     | `app/Http/Resources/OmnifyBase/*ResourceBase.php` → `schemaArray()` |
+
+---
+
+## Adding New Components
+
+### New Parameter
+
+```php
+// In app/OpenApi/Schemas.php
+#[OA\Parameter(
+    parameter: 'QueryStatus',      // Unique name
+    name: 'status',                // Query param name
+    in: 'query',
+    description: 'Filter by status',
+    schema: new OA\Schema(type: 'string', enum: ['active', 'inactive'])
+)]
+```
+
+### New Response
+
+```php
+// In app/OpenApi/Schemas.php
+#[OA\Response(
+    response: 'PaymentRequired',
+    description: 'Payment required'
+)]
+```
+
+---
+
+## Checklist
+
+### Before Writing
+
+- [ ] Check `OmnifyBase/*RequestBase.php` for request fields
+- [ ] Check `OmnifyBase/*ResourceBase.php` for response fields
+- [ ] DON'T make up fields that don't exist!
+
+### Writing OpenAPI
+
+- [ ] Add `#[OA\Tag]` to controller class
+- [ ] Use `$ref` for common parameters (QuerySearch, QueryPage, etc.)
+- [ ] Use `$ref` for common responses (Success, NotFound, etc.)
+- [ ] Only write `requestBody` properties manually (match FormRequest)
+- [ ] Use Japanese examples for JapaneseName fields
+
+### After Writing
+
+- [ ] Run `./artisan l5-swagger:generate`
+- [ ] Verify at `/api/documentation`
+
+---
+
+## Anti-Patterns
+
+```php
+// ❌ BAD: Repeating common parameters
+parameters: [
+    new OA\Parameter(name: 'page', in: 'query', schema: new OA\Schema(type: 'integer')),
+    new OA\Parameter(name: 'per_page', in: 'query', schema: new OA\Schema(type: 'integer')),
+]
+
+// ✅ GOOD: Use $ref
+parameters: [
+    new OA\Parameter(ref: '#/components/parameters/QueryPage'),
+    new OA\Parameter(ref: '#/components/parameters/QueryPerPage'),
+]
+
+// ❌ BAD: Repeating response definitions
+responses: [
+    new OA\Response(response: 404, description: 'Resource not found'),
+]
+
+// ✅ GOOD: Use $ref
+responses: [
+    new OA\Response(ref: '#/components/responses/NotFound', response: 404),
+]
+
+// ❌ BAD: Making up fields
+new OA\Property(property: 'username', ...)  // Does this exist?
+
+// ✅ GOOD: Check OmnifyBase first, then write
+// Checked: OmnifyBase/UserStoreRequestBase.php has name_lastname, name_firstname...
+new OA\Property(property: 'name_lastname', type: 'string', example: '田中'),
+```