@famgia/omnify-laravel 0.0.88 → 0.0.89

package/ai-guides/laravel-guide.md

@@ -1,461 +0,0 @@
-# Omnify Laravel Generator Guide
-
-This guide covers Laravel-specific features and generated code patterns for Omnify.
-
-## Quick Start
-
-```bash
-# Create new Laravel project (recommended)
-npx @famgia/omnify create-laravel-project my-app
-cd my-app
-
-# Or initialize in existing project
-npx @famgia/omnify init
-
-# Generate Laravel migrations and models
-npx @famgia/omnify generate
-```
-
-## Generated Files
-
-When you run `npx @famgia/omnify generate`, the following Laravel files are generated:
-
-### Migrations
-- `database/migrations/omnify/*.php` - Laravel migrations for each schema
-
-### Models
-- `app/Models/OmnifyBase/{ModelName}BaseModel.php` - Generated base models (DO NOT EDIT)
-- `app/Models/{ModelName}.php` - Extendable model classes (safe to customize)
-
-### Traits
-- `app/Models/OmnifyBase/Traits/HasLocalizedDisplayName.php` - Localization trait
-
-### Locales
-- `app/Models/OmnifyBase/Locales/{ModelName}Locales.php` - i18n display names
-
-### Service Provider
-- `app/Providers/OmnifyServiceProvider.php` - Morph map registration (configurable path)
-
-## Model Structure
-
-```php
-// app/Models/User.php (YOUR customizations go here)
-<?php
-namespace App\Models;
-
-use App\Models\OmnifyBase\UserBaseModel;
-
-class User extends UserBaseModel
-{
-    // Add your custom methods, scopes, accessors, etc.
-}
-```
-
-```php
-// app/Models/OmnifyBase/UserBaseModel.php (DO NOT EDIT - auto-generated)
-<?php
-namespace App\Models\OmnifyBase;
-
-use App\Models\OmnifyBase\Traits\HasLocalizedDisplayName;
-use App\Models\OmnifyBase\Locales\UserLocales;
-
-class UserBaseModel extends Model
-{
-    use HasLocalizedDisplayName;
-
-    protected static array $localizedDisplayNames = UserLocales::DISPLAY_NAMES;
-    protected static array $localizedPropertyDisplayNames = UserLocales::PROPERTY_DISPLAY_NAMES;
-
-    protected $fillable = ['name', 'email', 'password'];
-    protected $casts = [...];
-
-    // Relations defined here
-}
-```
-
-## Schema Options
-
-### Hidden Schemas (System Tables)
-
-For system tables that only need migrations (no models), use `hidden: true`:
-
-```yaml
-# schemas/system/Cache.yaml
-name: AppCache
-options:
-  id: false
-  timestamps: false
-  hidden: true           # Skip model generation
-  tableName: cache       # Use Laravel's default cache table name
-properties:
-  key:
-    type: String
-    primary: true
-  value:
-    type: MediumText
-  expiration:
-    type: Int
-```
-
-Use cases for `hidden: true`:
-- Laravel cache tables (`cache`, `cache_locks`)
-- Job queues (`jobs`, `failed_jobs`)
-- Session tables
-- System tables that don't need application models
-
-### Custom Table Name
-
-Override the auto-generated table name:
-
-```yaml
-name: AppCache
-options:
-  tableName: cache       # Use 'cache' instead of 'app_caches'
-```
-
-### Soft Delete
-
-```yaml
-options:
-  softDelete: true  # Adds deleted_at column and SoftDeletes trait
-```
-
-### Timestamps
-
-```yaml
-options:
-  timestamps: true  # Adds created_at, updated_at columns (default: true)
-```
-
-### Custom ID Type
-
-```yaml
-options:
-  idType: Uuid     # BigInt (default), Int, Uuid, String
-```
-
-### No Auto ID
-
-```yaml
-options:
-  id: false        # For tables with custom primary key
-```
-
-## Property Types
-
-### String Types
-
-| Type | Description | MySQL Column |
-|------|-------------|--------------|
-| `String` | Short text (default 255) | `VARCHAR(length)` |
-| `Text` | Text (~65KB) | `TEXT` |
-| `MediumText` | Medium text (~16MB) | `MEDIUMTEXT` |
-| `LongText` | Long text (~4GB) | `LONGTEXT` |
-
-### Numeric Types
-
-| Type | Description | MySQL Column |
-|------|-------------|--------------|
-| `TinyInt` | 8-bit (-128~127) | `TINYINT` |
-| `Int` | 32-bit integer | `INT` |
-| `BigInt` | 64-bit integer | `BIGINT` |
-| `Float` | Floating point | `FLOAT` |
-| `Decimal` | Precise decimal | `DECIMAL(p,s)` |
-
-### Date/Time Types
-
-| Type | Description | MySQL Column |
-|------|-------------|--------------|
-| `Date` | Date only | `DATE` |
-| `DateTime` | Date and time | `DATETIME` |
-| `Timestamp` | Timestamp | `TIMESTAMP` |
-
-### Timestamp with useCurrent
-
-```yaml
-properties:
-  created_at:
-    type: Timestamp
-    useCurrent: true           # Default to CURRENT_TIMESTAMP
-  updated_at:
-    type: Timestamp
-    useCurrent: true
-    useCurrentOnUpdate: true   # Auto-update on row change
-```
-
-Generated migration:
-```php
-$table->timestamp('created_at')->useCurrent();
-$table->timestamp('updated_at')->useCurrent()->useCurrentOnUpdate();
-```
-
-## Localization (i18n)
-
-### Display Names
-```php
-// Get localized model name
-User::getLocalizedDisplayName(); // Returns based on app()->getLocale()
-
-// Get localized property name
-User::getLocalizedPropertyDisplayName('email');
-```
-
-### Schema Definition
-```yaml
-name: User
-displayName:
-  ja: ユーザー
-  en: User
-properties:
-  email:
-    type: String
-    displayName:
-      ja: メールアドレス
-      en: Email Address
-```
-
-## Relationships
-
-### ManyToOne (BelongsTo)
-```yaml
-# In Post schema
-author:
-  type: Association
-  relation: ManyToOne
-  target: User
-  onDelete: CASCADE
-```
-
-Generated:
-```php
-public function author(): BelongsTo
-{
-    return $this->belongsTo(User::class);
-}
-```
-
-### OneToMany (HasMany)
-```yaml
-# In User schema
-posts:
-  type: Association
-  relation: OneToMany
-  target: Post
-  mappedBy: author
-```
-
-Generated:
-```php
-public function posts(): HasMany
-{
-    return $this->hasMany(Post::class, 'author_id');
-}
-```
-
-### ManyToMany (BelongsToMany)
-```yaml
-tags:
-  type: Association
-  relation: ManyToMany
-  target: Tag
-  pivotTable: post_tags
-  pivotFields:
-    - name: order
-      type: Int
-      default: 0
-```
-
-Generated:
-```php
-public function tags(): BelongsToMany
-{
-    return $this->belongsToMany(Tag::class, 'post_tags')
-        ->withPivot(['order']);
-}
-```
-
-### MorphTo (Polymorphic)
-```yaml
-# Comment can belong to Post or Video
-commentable:
-  type: Association
-  relation: MorphTo
-  targets: [Post, Video]
-  nullable: true           # Default: true
-```
-
-Generated columns:
-- `commentable_type` (enum: 'Post', 'Video')
-- `commentable_id` (bigint, nullable)
-
-## Enum Support
-
-```yaml
-# schemas/PostStatus.yaml
-name: PostStatus
-kind: enum
-values:
-  draft: 下書き
-  published: 公開済み
-  archived: アーカイブ
-```
-
-Usage in schema:
-```yaml
-status:
-  type: EnumRef
-  enum: PostStatus
-  default: draft
-```
-
-Generated migration:
-```php
-$table->enum('status', ['draft', 'published', 'archived'])->default('draft');
-```
-
-## Configuration
-
-```typescript
-// omnify.config.ts
-import { defineConfig } from '@famgia/omnify';
-import laravel from '@famgia/omnify-laravel/plugin';
-
-export default defineConfig({
-  schemasDir: './schemas',
-  lockFilePath: './.omnify.lock',
-
-  database: {
-    driver: 'mysql',
-    devUrl: 'mysql://root:password@localhost:3306/dev_db',
-  },
-
-  plugins: [
-    laravel({
-      // Migration output path
-      migrationsPath: 'database/migrations/omnify',
-
-      // Model output paths
-      modelsPath: 'app/Models',
-      baseModelsPath: 'app/Models/OmnifyBase',
-
-      // Service provider path (for morph map)
-      providersPath: 'app/Providers',
-
-      // Locales path
-      localesPath: 'app/Models/OmnifyBase/Locales',
-    }),
-  ],
-});
-```
-
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `migrationsPath` | `string` | `database/migrations/omnify` | Laravel migrations output |
-| `modelsPath` | `string` | `app/Models` | Model classes output |
-| `baseModelsPath` | `string` | `app/Models/OmnifyBase` | Base model classes output |
-| `providersPath` | `string` | `app/Providers` | Service provider output |
-| `localesPath` | `string` | `app/Models/OmnifyBase/Locales` | Locale files output |
-
-## Commands
-
-```bash
-# Create new Laravel project
-npx @famgia/omnify create-laravel-project my-app
-
-# Generate Laravel migrations and models
-npx @famgia/omnify generate
-
-# Force regenerate all files
-npx @famgia/omnify generate --force
-
-# Only generate migrations
-npx @famgia/omnify generate --migrations-only
-
-# Validate schemas
-npx @famgia/omnify validate
-
-# Show pending changes
-npx @famgia/omnify diff
-
-# Reset all generated files
-npx @famgia/omnify reset
-```
-
-## Examples
-
-### System Table (Cache)
-
-```yaml
-# schemas/system/AppCache.yaml
-name: AppCache
-options:
-  id: false
-  timestamps: false
-  hidden: true
-  tableName: cache
-properties:
-  key:
-    type: String
-    length: 255
-    primary: true
-  value:
-    type: MediumText
-  expiration:
-    type: Int
-```
-
-### User with Authenticatable
-
-```yaml
-# schemas/User.yaml
-name: User
-displayName:
-  ja: ユーザー
-  en: User
-options:
-  softDelete: true
-  authenticatable: true
-properties:
-  name:
-    type: String
-    displayName:
-      ja: 氏名
-      en: Full Name
-  email:
-    type: Email
-    unique: true
-  password:
-    type: Password
-```
-
-### Post with Relations
-
-```yaml
-# schemas/Post.yaml
-name: Post
-displayName:
-  ja: 投稿
-  en: Post
-options:
-  softDelete: true
-properties:
-  title:
-    type: String
-  content:
-    type: LongText
-  status:
-    type: EnumRef
-    enum: PostStatus
-    default: draft
-  author:
-    type: Association
-    relation: ManyToOne
-    target: User
-    onDelete: CASCADE
-  tags:
-    type: Association
-    relation: ManyToMany
-    target: Tag
-```