@famgia/omnify-laravel 0.0.125 → 0.0.127

package/dist/plugin.js

@@ -1,6 +1,6 @@
 import {
   laravelPlugin
-} from "./chunk-C3AGVZB4.js";
+} from "./chunk-IIA2I36W.js";
 export {
   laravelPlugin as default,
   laravelPlugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@famgia/omnify-laravel",
-  "version": "0.0.125",
+  "version": "0.0.127",
   "description": "Laravel migration and TypeScript type generator for omnify-schema",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,9 @@
     "README.md"
   ],
   "dependencies": {
-    "@famgia/omnify-types": "0.0.114",
-    "@famgia/omnify-core": "0.0.116",
-    "@famgia/omnify-atlas": "0.0.110"
+    "@famgia/omnify-types": "0.0.116",
+    "@famgia/omnify-atlas": "0.0.112",
+    "@famgia/omnify-core": "0.0.118"
   },
   "scripts": {
     "build": "tsup",

package/stubs/ai-guides/README.md.stub

@@ -41,6 +41,7 @@
 ├── rules/               # Must-follow rules (WHAT)
 │   ├── security.md      # Security rules
 │   ├── performance.md   # Performance & quality rules
+│   ├── php-standards.md # PHP 8+ standards & best practices
 │   └── naming.md        # Naming conventions
 │
 ├── guides/              # Implementation guides (REFERENCE)

package/stubs/ai-guides/claude-omnify/schema-guide.md.stub

@@ -67,6 +67,35 @@ propertyName:
   fillable: false      # Exclude from mass assignment
 ```
 
+## ⚠️ Default Value Rules
+
+**DB functions NOT allowed in default:**
+
+```yaml
+# ❌ WRONG
+failed_at:
+  type: Timestamp
+  default: CURRENT_TIMESTAMP  # ERROR!
+
+# ✅ CORRECT
+failed_at:
+  type: Timestamp
+  useCurrent: true            # = CURRENT_TIMESTAMP
+
+updated_at:
+  type: Timestamp
+  useCurrent: true
+  useCurrentOnUpdate: true    # ON UPDATE CURRENT_TIMESTAMP
+```
+
+| Type | Valid Default | Invalid |
+|------|---------------|---------|
+| Int | 0, 100, -1 | AUTO_INCREMENT, RAND() |
+| Date | 2024-01-01 | CURRENT_DATE |
+| Time | 14:30:00 | CURRENT_TIME |
+| Timestamp | use `useCurrent` | CURRENT_TIMESTAMP |
+| Uuid | static UUID | UUID() |
+
 ## Associations
 
 ```yaml

package/stubs/ai-guides/claude-rules/php-standards.md.stub

@@ -0,0 +1,305 @@
+---
+paths:
+  - "{{LARAVEL_ROOT}}app/**/*.php"
+---
+
+# PHP Standards & Best Practices
+
+> **PHP 8+ features** and coding standards for Laravel projects.
+
+## 🔵 Strict Types
+
+**Always declare strict types at the top of PHP files.**
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+
+// ... class definition
+```
+
+| Rule | Description |
+| ---- | ----------- |
+| `declare(strict_types=1)` | Required in all PHP files |
+| Place at very top | Before namespace declaration |
+
+---
+
+## 🔵 Constructor Property Promotion (PHP 8.0+)
+
+**Use constructor promotion for dependency injection.**
+
+```php
+// ❌ OLD STYLE: Verbose
+class UserService
+{
+    private UserRepository $repository;
+    private CacheManager $cache;
+    
+    public function __construct(UserRepository $repository, CacheManager $cache)
+    {
+        $this->repository = $repository;
+        $this->cache = $cache;
+    }
+}
+
+// ✅ PHP 8.0+: Constructor promotion
+class UserService
+{
+    public function __construct(
+        private readonly UserRepository $repository,
+        private readonly CacheManager $cache
+    ) {}
+}
+```
+
+| Modifier | Usage |
+| -------- | ----- |
+| `private readonly` | Immutable dependencies (preferred) |
+| `private` | Mutable internal state |
+| `protected readonly` | For extension by subclasses |
+
+---
+
+## 🔵 PHP 8+ Features
+
+### Named Arguments
+
+```php
+// ✅ Clear intent
+$this->checkEmailLockout(
+    email: $request->email,
+    checkOnly: true
+);
+
+// Use when function has many optional parameters
+```
+
+### Nullsafe Operator
+
+```php
+// ❌ OLD STYLE
+$country = $user->address ? ($user->address->country ? $user->address->country->name : null) : null;
+
+// ✅ PHP 8.0+: Nullsafe operator
+$country = $user->address?->country?->name;
+```
+
+### Union Types
+
+```php
+public function process(int|string $id): Response|RedirectResponse
+{
+    // ...
+}
+```
+
+### Match Expression
+
+```php
+// ❌ OLD: switch statement
+switch ($status) {
+    case 'active': return 'Active';
+    case 'inactive': return 'Inactive';
+    default: return 'Unknown';
+}
+
+// ✅ PHP 8.0+: match expression
+return match($status) {
+    'active' => 'Active',
+    'inactive' => 'Inactive',
+    default => 'Unknown',
+};
+```
+
+---
+
+## 🔵 Constants Organization
+
+**Use dedicated Constants classes instead of magic values.**
+
+```php
+// ❌ BAD: Magic strings scattered in code
+if ($user->role === 'admin') { ... }
+Cache::get('user:' . $id);
+session()->get('2fa:user_id');
+
+// ✅ GOOD: Constants in dedicated class
+namespace App\Constants;
+
+class TwoFactorConstants
+{
+    public const ENABLED = true;
+    public const CODE_LENGTH = 6;
+    public const EXPIRY_MINUTES = 5;
+    
+    // Session keys
+    public const SESSION_USER_ID = '2fa:user_id';
+    public const SESSION_EMAIL = '2fa:email';
+}
+
+// Usage
+use App\Constants\TwoFactorConstants;
+
+if (TwoFactorConstants::ENABLED) {
+    $code = Str::random(TwoFactorConstants::CODE_LENGTH);
+    session()->put(TwoFactorConstants::SESSION_USER_ID, $user->id);
+}
+```
+
+| Location | Purpose |
+| -------- | ------- |
+| `app/Constants/` | Application-wide constants |
+| Class constants | Domain-specific constants |
+| `config/*.php` | Environment-dependent values |
+
+---
+
+## 🔵 PHPDoc Standards
+
+### Method Documentation
+
+```php
+/**
+ * Get user's authorization for a service.
+ *
+ * @param User $user The user to check
+ * @param Service $service The service being accessed
+ *
+ * @return array{
+ *     organization_id: int,
+ *     organization_slug: string,
+ *     role: string,
+ *     level: int
+ * }|null Returns null if user has no access
+ *
+ * @throws AuthorizationException When service is inactive
+ */
+public function getUserAuthorization(User $user, Service $service): ?array
+{
+    // ...
+}
+```
+
+### Array Shape Documentation
+
+```php
+/**
+ * @return array{
+ *     id: int,
+ *     name: string,
+ *     email: string,
+ *     roles: string[]
+ * }
+ */
+public function toArray(): array
+```
+
+### When to Document
+
+| Document | Don't Document |
+| -------- | -------------- |
+| Complex return types | Obvious getters/setters |
+| Array shapes | Simple CRUD methods |
+| Exception conditions | Self-explanatory code |
+| Business logic | Framework conventions |
+
+---
+
+## 🔵 Code Complexity Limits
+
+### Method Guidelines
+
+| Metric | Limit | Action if exceeded |
+| ------ | ----- | ------------------ |
+| Lines per method | Max 50 | Extract to helper/service |
+| Parameters | Max 4 | Use DTO or config object |
+| Cyclomatic complexity | Max 10 | Split into smaller methods |
+| Nesting depth | Max 3 | Early return pattern |
+
+### Class Guidelines
+
+| Metric | Limit | Action if exceeded |
+| ------ | ----- | ------------------ |
+| Public methods | Max 10 | Split class (SRP violation) |
+| Dependencies | Max 5 | Facade or aggregate service |
+| Lines per class | Max 500 | Extract sub-classes |
+
+### Early Return Pattern
+
+```php
+// ❌ BAD: Deep nesting
+public function process($user)
+{
+    if ($user) {
+        if ($user->isActive()) {
+            if ($user->hasPermission('edit')) {
+                // do something
+            }
+        }
+    }
+}
+
+// ✅ GOOD: Early returns
+public function process($user)
+{
+    if (!$user) {
+        return;
+    }
+    
+    if (!$user->isActive()) {
+        return;
+    }
+    
+    if (!$user->hasPermission('edit')) {
+        return;
+    }
+    
+    // do something
+}
+```
+
+---
+
+## 🔵 Interface & Trait Naming
+
+```php
+// Interfaces: suffix with Interface
+interface PaymentGatewayInterface
+{
+    public function charge(int $amount): PaymentResult;
+}
+
+// Traits: suffix with Trait (optional but recommended)
+trait HasApiTokens
+{
+    // ...
+}
+
+// Or descriptive name without suffix
+trait Searchable
+{
+    public function scopeSearch(Builder $query, string $term): Builder
+    {
+        // ...
+    }
+}
+```
+
+---
+
+## Quick Reference
+
+| Category | Rule |
+| -------- | ---- |
+| **Strict** | `declare(strict_types=1)` at top |
+| **Constructor** | Use property promotion with `readonly` |
+| **Nullsafe** | `$obj?->prop?->value` instead of null checks |
+| **Match** | Prefer `match` over `switch` |
+| **Constants** | Use `App\Constants\*` classes |
+| **Complexity** | Max 50 lines/method, 4 params, 10 complexity |
+| **Nesting** | Max 3 levels, use early returns |
+| **PHPDoc** | Document complex types and exceptions |

package/stubs/ai-guides/claude-rules/schema-yaml.md.stub

@@ -46,6 +46,20 @@ default: "'cloud'"
 default: cloud
 ```
 
+## ⚠️ CRITICAL: DB Functions NOT Allowed
+
+```yaml
+# ❌ WRONG - DB functions
+failed_at:
+  type: Timestamp
+  default: CURRENT_TIMESTAMP  # ERROR!
+
+# ✅ CORRECT - use useCurrent
+failed_at:
+  type: Timestamp
+  useCurrent: true            # = CURRENT_TIMESTAMP
+```
+
 ## Property Types
 
 | Type | SQL | TypeScript |

package/stubs/ai-guides/cursor/omnify-schema.mdc.stub

@@ -235,6 +235,25 @@ category:
   relation: belongsTo  # belongsTo, hasMany, hasOne, belongsToMany
 ```
 
+### ⚠️ CRITICAL: DB Functions NOT Allowed in Default
+
+```yaml
+# ❌ WRONG - DB functions are NOT allowed
+failed_at:
+  type: Timestamp
+  default: CURRENT_TIMESTAMP  # ERROR!
+
+# ✅ CORRECT - Use useCurrent option
+failed_at:
+  type: Timestamp
+  useCurrent: true            # Equivalent to CURRENT_TIMESTAMP
+
+updated_at:
+  type: Timestamp
+  useCurrent: true
+  useCurrentOnUpdate: true    # ON UPDATE CURRENT_TIMESTAMP
+```
+
 ---
 
 ## Step 5: Run Migration 🗄️

package/stubs/ai-guides/cursor/schema-create.mdc.stub

@@ -235,6 +235,35 @@ category:
   relation: belongsTo  # belongsTo, hasMany, hasOne, belongsToMany
 ```
 
+### ⚠️ CRITICAL: DB Functions NOT Allowed in Default
+
+```yaml
+# ❌ WRONG - DB functions are NOT allowed
+failed_at:
+  type: Timestamp
+  default: CURRENT_TIMESTAMP  # ERROR!
+
+# ✅ CORRECT - Use useCurrent option
+failed_at:
+  type: Timestamp
+  useCurrent: true            # Equivalent to CURRENT_TIMESTAMP
+
+updated_at:
+  type: Timestamp
+  useCurrent: true
+  useCurrentOnUpdate: true    # ON UPDATE CURRENT_TIMESTAMP
+
+# ❌ WRONG - UUID() function
+external_id:
+  type: Uuid
+  default: UUID()             # ERROR!
+
+# ✅ CORRECT - Static value or nullable
+external_id:
+  type: Uuid
+  nullable: true              # Let application generate
+```
+
 ---
 
 ## Step 5: Run Migration 🗄️
@@ -342,3 +371,76 @@ status:
 status:
   type: PostStatus  # Reference enum schema
 ```
+
+---
+
+## 🔌 Partial Schema (External Package Connection)
+
+When referencing schemas from external packages that aren't loaded:
+
+```yaml
+# schemas/stubs/User.yaml
+# Create stub to connect to external User schema
+name: User
+kind: partial
+target: User           # Same name = standalone schema
+
+properties:
+  email:
+    type: Email
+    displayName:
+      ja: メール
+      en: Email
+```
+
+Now you can use `User` in relationships:
+
+```yaml
+# schemas/blog/Post.yaml
+author:
+  type: User           # ✅ Works! User exists as partial
+  relation: belongsTo
+```
+
+### Extend Package Schema
+
+```yaml
+# schemas/extensions/User.yaml
+name: User
+kind: partial
+target: User           # Extend the User schema
+
+properties:
+  # Add custom properties
+  avatar_url:
+    type: String
+    nullable: true
+```
+
+---
+
+## 📦 Register Schemas from Laravel Package
+
+In your package's ServiceProvider:
+
+```php
+use App\Support\Omnify;
+
+public function boot(): void
+{
+    if (class_exists(Omnify::class)) {
+        Omnify::registerSchemaPath(
+            path: __DIR__ . '/../../schemas',
+            namespace: 'your-package'
+        );
+    }
+}
+```
+
+Export paths before generate:
+
+```bash
+php artisan omnify:sync
+# Then
+npx omnify generate
+```