Wireflow Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require getartisanflow/wireflow
   php artisan wireflow:install
   

   • Publishes config (if needed) and sets up basic Livewire integration.

2. First Component: Create a Livewire component with WithWireFlow concern:

   use ArtisanFlow\WireFlow\Concerns\WithWireFlow;
   
   class FlowEditor extends Component
   {
       use WithWireFlow;
   
       public array $nodes = [
           ['id' => '1', 'position' => ['x' => 100, 'y' => 100], 'data' => ['label' => 'Start']],
       ];
   
       public array $edges = [];
   }
   

3. Blade Integration:

   <x-flow wire:model="nodes" wire:model:edges="edges">
       <x-slot:node>
           <div x-flow-handle:target.top></div>
           <span x-text="node.data.label"></span>
       </x-slot:node>
   </x-flow>
   

First Use Case: Basic Flow Diagram

• Goal: Display a simple 2-node flow with a connection.
• Steps:
  1. Define $nodes and $edges in your Livewire component.
  2. Use <x-flow> with wire:model bindings.
  3. Customize node appearance via the :node slot.
  4. Add handles (x-flow-handle) for edge connections.

Implementation Patterns

Data Binding Workflows

• Livewire Model Binding: Use wire:model for reactive updates:

  <x-flow wire:model="nodes" wire:model:edges="edges">
  

  • Automatically syncs changes to $nodes and $edges arrays.

• Custom Node Data: Extend node data structure for rich content:

  $nodes = [
      [
          'id' => '1',
          'position' => ['x' => 100, 'y'  => 100],
          'data' => [
              'label' => 'Process',
              'type'  => 'process',
              'color' => '#4CAF50',
          ],
      ],
  ];
  

  Access via node.data in Blade slots.

Component Composition

• Panels and Toolbars:

  <x-flow-panel>
      <x-slot name="title">Node Properties</x-slot>
      <input wire:model="selectedNode.data.label">
  </x-flow-panel>
  
  <x-flow-toolbar>
      <button wire:click="addNode">Add Node</button>
  </x-flow-toolbar>
  

• Drag-and-Drop Handles:

  <x-flow-handle:target.top class="bg-blue-500"></x-flow-handle>
  <x-flow-handle:source.bottom class="bg-green-500"></x-flow-handle>
  

Server-Side Logic

• Event Handling: Use Livewire hooks for flow events:

  protected $listeners = ['nodeCreated' => 'handleNodeCreated'];
  
  public function handleNodeCreated($node) {
      // Save to DB or trigger side effects
  }
  

• Validation: Validate node/edge data before saving:

  protected function rules() {
      return [
          'nodes.*.data.label' => 'required|string',
          'edges.*.source'     => 'required|exists:nodes,id',
          'edges.*.target'     => 'required|exists:nodes,id',
      ];
  }
  

Gotchas and Tips

Debugging

• Edge Connection Issues:

  • Ensure source and target IDs in $edges match node IDs.
  • Verify x-flow-handle directives are placed inside <x-slot:node>.
  • Check for JavaScript errors in browser console (though WireFlow is JS-free, AlpineFlow may log warnings).

• Livewire Sync Delays:

  • Complex flows may cause lag. Use wire:ignore on non-critical elements:

    <div wire:ignore>...</div>
    

Configuration Quirks

• Default Styling: Override AlpineFlow defaults via published config:

  php artisan vendor:publish --provider="ArtisanFlow\WireFlow\WireFlowServiceProvider"
  

  Customize in config/wireflow.php (e.g., handle_size, node_padding).

• Slot Scope:

  • node and edge are available in slots, but flow scope is not exposed by default. Use AlpineFlow’s x-flow directives for global flow data.

Extension Points

• Custom Node Types: Extend functionality via AlpineFlow’s x-flow-node directive:

  <x-flow>
      <x-slot:node>
          @if($node->data->type === 'decision')
              <div x-flow-node:decision>
                  <!-- Custom decision node template -->
              </div>
          @else
              <div x-flow-node:default>
                  <span x-text="node.data.label"></span>
              </div>
          @endif
      </x-slot:node>
  </x-flow>
  

• Server-Side Validation: Use Livewire’s updatedNodes/updatedEdges to validate changes before persistence:

  public function updatedNodes($value) {
      $this->validate([
          'nodes.*.data.label' => 'required|unique:nodes,name,' . $value[0]['id'] ?? null,
      ]);
  }
  

• Performance:

  • For large flows, implement pagination or lazy-loading:

    public function getNodesProperty() {
        return Node::query()
            ->whereIn('id', $this->visibleNodeIds)
            ->get();
    }