Merge pull request #7101 from coollabsio/next

v4.0.0-beta.440

Author: andrasbacsai

.cursor/rules/frontend-patterns.mdc

@@ -267,18 +267,365 @@ For complete documentation, see **[form-components.mdc](mdc:.cursor/rules/form-c
 
 ## Form Handling Patterns
 
+### Livewire Component Data Synchronization Pattern
+
+**IMPORTANT**: All Livewire components must use the **manual `syncData()` pattern** for synchronizing component properties with Eloquent models.
+
+#### Property Naming Convention
+- **Component properties**: Use camelCase (e.g., `$gitRepository`, `$isStatic`)
+- **Database columns**: Use snake_case (e.g., `git_repository`, `is_static`)
+- **View bindings**: Use camelCase matching component properties (e.g., `id="gitRepository"`)
+
+#### The syncData() Method Pattern
+
+```php
+use Livewire\Attributes\Validate;
+use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
+
+class MyComponent extends Component
+{
+    use AuthorizesRequests;
+
+    public Application $application;
+
+    // Properties with validation attributes
+    #[Validate(['required'])]
+    public string $name;
+
+    #[Validate(['string', 'nullable'])]
+    public ?string $description = null;
+
+    #[Validate(['boolean', 'required'])]
+    public bool $isStatic = false;
+
+    public function mount()
+    {
+        $this->authorize('view', $this->application);
+        $this->syncData(); // Load from model
+    }
+
+    public function syncData(bool $toModel = false): void
+    {
+        if ($toModel) {
+            $this->validate();
+
+            // Sync TO model (camelCase → snake_case)
+            $this->application->name = $this->name;
+            $this->application->description = $this->description;
+            $this->application->is_static = $this->isStatic;
+
+            $this->application->save();
+        } else {
+            // Sync FROM model (snake_case → camelCase)
+            $this->name = $this->application->name;
+            $this->description = $this->application->description;
+            $this->isStatic = $this->application->is_static;
+        }
+    }
+
+    public function submit()
+    {
+        $this->authorize('update', $this->application);
+        $this->syncData(toModel: true); // Save to model
+        $this->dispatch('success', 'Saved successfully.');
+    }
+}
+```
+
+#### Validation with #[Validate] Attributes
+
+All component properties should have `#[Validate]` attributes:
+
+```php
+// Boolean properties
+#[Validate(['boolean'])]
+public bool $isEnabled = false;
+
+// Required strings
+#[Validate(['string', 'required'])]
+public string $name;
+
+// Nullable strings
+#[Validate(['string', 'nullable'])]
+public ?string $description = null;
+
+// With constraints
+#[Validate(['integer', 'min:1'])]
+public int $timeout;
+```
+
+#### Benefits of syncData() Pattern
+
+- **Explicit Control**: Clear visibility of what's being synchronized
+- **Type Safety**: #[Validate] attributes provide compile-time validation info
+- **Easy Debugging**: Single method to check for data flow issues
+- **Maintainability**: All sync logic in one place
+- **Flexibility**: Can add custom logic (encoding, transformations, etc.)
+
+#### Creating New Form Components with syncData()
+
+#### Step-by-Step Component Creation Guide
+
+**Step 1: Define properties in camelCase with #[Validate] attributes**
+```php
+use Livewire\Attributes\Validate;
+use Illuminate\Foundation\Auth\Access\AuthorizesRequests;
+use Livewire\Component;
+
+class MyFormComponent extends Component
+{
+    use AuthorizesRequests;
+
+    // The model we're syncing with
+    public Application $application;
+
+    // Component properties in camelCase with validation
+    #[Validate(['string', 'required'])]
+    public string $name;
+
+    #[Validate(['string', 'nullable'])]
+    public ?string $gitRepository = null;
+
+    #[Validate(['string', 'nullable'])]
+    public ?string $installCommand = null;
+
+    #[Validate(['boolean'])]
+    public bool $isStatic = false;
+}
+```
+
+**Step 2: Implement syncData() method**
+```php
+public function syncData(bool $toModel = false): void
+{
+    if ($toModel) {
+        $this->validate();
+
+        // Sync TO model (component camelCase → database snake_case)
+        $this->application->name = $this->name;
+        $this->application->git_repository = $this->gitRepository;
+        $this->application->install_command = $this->installCommand;
+        $this->application->is_static = $this->isStatic;
+
+        $this->application->save();
+    } else {
+        // Sync FROM model (database snake_case → component camelCase)
+        $this->name = $this->application->name;
+        $this->gitRepository = $this->application->git_repository;
+        $this->installCommand = $this->application->install_command;
+        $this->isStatic = $this->application->is_static;
+    }
+}
+```
+
+**Step 3: Implement mount() to load initial data**
+```php
+public function mount()
+{
+    $this->authorize('view', $this->application);
+    $this->syncData(); // Load data from model to component properties
+}
+```
+
+**Step 4: Implement action methods with authorization**
+```php
+public function instantSave()
+{
+    try {
+        $this->authorize('update', $this->application);
+        $this->syncData(toModel: true); // Save component properties to model
+        $this->dispatch('success', 'Settings saved.');
+    } catch (\Throwable $e) {
+        return handleError($e, $this);
+    }
+}
+
+public function submit()
+{
+    try {
+        $this->authorize('update', $this->application);
+        $this->syncData(toModel: true); // Save component properties to model
+        $this->dispatch('success', 'Changes saved successfully.');
+    } catch (\Throwable $e) {
+        return handleError($e, $this);
+    }
+}
+```
+
+**Step 5: Create Blade view with camelCase bindings**
+```blade
+<div>
+    <form wire:submit="submit">
+        <x-forms.input
+            canGate="update"
+            :canResource="$application"
+            id="name"
+            label="Name"
+            required />
+
+        <x-forms.input
+            canGate="update"
+            :canResource="$application"
+            id="gitRepository"
+            label="Git Repository" />
+
+        <x-forms.input
+            canGate="update"
+            :canResource="$application"
+            id="installCommand"
+            label="Install Command" />
+
+        <x-forms.checkbox
+            instantSave
+            canGate="update"
+            :canResource="$application"
+            id="isStatic"
+            label="Static Site" />
+
+        <x-forms.button
+            canGate="update"
+            :canResource="$application"
+            type="submit">
+            Save Changes
+        </x-forms.button>
+    </form>
+</div>
+```
+
+**Key Points**:
+- Use `wire:model="camelCase"` and `id="camelCase"` in Blade views
+- Component properties are camelCase, database columns are snake_case
+- Always include authorization checks (`authorize()`, `canGate`, `canResource`)
+- Use `instantSave` for checkboxes that save immediately without form submission
+
+#### Special Patterns
+
+**Pattern 1: Related Models (e.g., Application → Settings)**
+```php
+public function syncData(bool $toModel = false): void
+{
+    if ($toModel) {
+        $this->validate();
+
+        // Sync main model
+        $this->application->name = $this->name;
+        $this->application->save();
+
+        // Sync related model
+        $this->application->settings->is_static = $this->isStatic;
+        $this->application->settings->save();
+    } else {
+        // From main model
+        $this->name = $this->application->name;
+
+        // From related model
+        $this->isStatic = $this->application->settings->is_static;
+    }
+}
+```
+
+**Pattern 2: Custom Encoding/Decoding**
+```php
+public function syncData(bool $toModel = false): void
+{
+    if ($toModel) {
+        $this->validate();
+
+        // Encode before saving
+        $this->application->custom_labels = base64_encode($this->customLabels);
+        $this->application->save();
+    } else {
+        // Decode when loading
+        $this->customLabels = $this->application->parseContainerLabels();
+    }
+}
+```
+
+**Pattern 3: Error Rollback**
+```php
+public function submit()
+{
+    $this->authorize('update', $this->resource);
+    $original = $this->model->getOriginal();
+
+    try {
+        $this->syncData(toModel: true);
+        $this->dispatch('success', 'Saved successfully.');
+    } catch (\Throwable $e) {
+        // Rollback on error
+        $this->model->setRawAttributes($original);
+        $this->model->save();
+        $this->syncData(); // Reload from model
+        return handleError($e, $this);
+    }
+}
+```
+
+#### Property Type Patterns
+
+**Required Strings**
+```php
+#[Validate(['string', 'required'])]
+public string $name;  // No ?, no default, always has value
+```
+
+**Nullable Strings**
+```php
+#[Validate(['string', 'nullable'])]
+public ?string $description = null;  // ?, = null, can be empty
+```
+
+**Booleans**
+```php
+#[Validate(['boolean'])]
+public bool $isEnabled = false;  // Always has default value
+```
+
+**Integers with Constraints**
+```php
+#[Validate(['integer', 'min:1'])]
+public int $timeout;  // Required
+
+#[Validate(['integer', 'min:1', 'nullable'])]
+public ?int $port = null;  // Nullable
+```
+
+#### Testing Checklist
+
+After creating a new component with syncData(), verify:
+
+- [ ] All checkboxes save correctly (especially `instantSave` ones)
+- [ ] All form inputs persist to database
+- [ ] Custom encoded fields (like labels) display correctly if applicable
+- [ ] Form validation works for all fields
+- [ ] No console errors in browser
+- [ ] Authorization checks work (`@can` directives and `authorize()` calls)
+- [ ] Error rollback works if exceptions occur
+- [ ] Related models save correctly if applicable (e.g., Application + ApplicationSetting)
+
+#### Common Pitfalls to Avoid
+
+1. **snake_case in component properties**: Always use camelCase for component properties (e.g., `$gitRepository` not `$git_repository`)
+2. **Missing #[Validate] attributes**: Every property should have validation attributes for type safety
+3. **Forgetting to call syncData()**: Must call `syncData()` in `mount()` to load initial data
+4. **Missing authorization**: Always use `authorize()` in methods and `canGate`/`canResource` in views
+5. **View binding mismatch**: Use camelCase in Blade (e.g., `id="gitRepository"` not `id="git_repository"`)
+6. **wire:model vs wire:model.live**: Use `.live` for `instantSave` checkboxes to avoid timing issues
+7. **Validation sync**: If using `rules()` method, keep it in sync with `#[Validate]` attributes
+8. **Related models**: Don't forget to save both main and related models in syncData() method
+
 ### Livewire Forms
 ```php
 class ServerCreateForm extends Component
 {
     public $name;
     public $ip;
-    
+
     protected $rules = [
         'name' => 'required|min:3',
         'ip' => 'required|ip',
     ];
-    
+
     public function save()
     {
         $this->validate();