Organization Chart Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require yacoubalhaidari/organization-chart
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="YacoubAlhardari\OrganizationChart\OrganizationChartServiceProvider"
   

2. Basic Widget Registration Add the widget to a Filament panel or resource:

   use YacoubAlhardari\OrganizationChart\Widgets\OrganizationChart;
   
   OrganizationChart::make()
       ->heading('Company Hierarchy')
       ->data($this->getChartData()) // Your data source
       ->mount();
   

3. First Use Case Fetch hierarchical data from your database (e.g., users with manager_id relationship):

   public function getChartData()
   {
       return User::with('manager', 'subordinates')
           ->whereNull('manager_id')
           ->get()
           ->map(function ($user) {
               return [
                   'id' => $user->id,
                   'name' => $user->name,
                   'title' => $user->title,
                   'image' => $user->profile_photo_url,
                   'children' => $user->subordinates->map(fn($sub) => [
                       'id' => $sub->id,
                       'name' => $sub->name,
                       // ... nested structure
                   ]),
               ];
           });
   }
   

Implementation Patterns

Data Structure

• Hierarchical Array: The package expects a nested array with id, name, and optional children keys.

  [
      'id' => '1',
      'name' => 'CEO',
      'children' => [
          ['id' => '2', 'name' => 'CTO', ...],
          ['id' => '3', 'name' => 'CFO', ...],
      ],
  ]
  

• Dynamic Data: Use Eloquent relationships or recursive queries to build the structure:

  $data = User::whereNull('manager_id')->with('subordinates')->get()->toHierarchy();
  

Customization

• Styling: Chain methods for visual tweaks:

  OrganizationChart::make()
      ->heading('Team Structure')
      ->height('600px')
      ->orientation('vertical') // or 'horizontal'
      ->nodeWidth(150)
      ->nodeHeight(100)
      ->colors(['#4CAF50', '#2196F3', '#FFC107'])
      ->showImages(true)
      ->showTitles(true);
  

• Interactivity:

  ->onNodeClick(fn($node) => redirect()->route('users.show', $node['id']))
  ->onNodeHover(fn($node) => toast()->success("Hovering on {$node['name']}"));
  

Integration with Filament

• Panel Widget:

  // app/Filament/Resources/UserResource.php
  public static function getWidgets(): array
  {
      return [
          OrganizationChart::make()
              ->query(fn() => User::whereNull('manager_id')->with('subordinates'))
              ->heading('Organization'),
      ];
  }
  

• Live Updates: Use Filament’s livewire or polling to refresh data:

  OrganizationChart::make()
      ->pollingInterval('60') // Refresh every 60 seconds
      ->data(fn() => $this->getLiveData());
  

Gotchas and Tips

Debugging

• Data Validation: Ensure your data matches the expected structure. Use dd($this->getChartData()) to verify.
• Highcharts Errors: Check browser console for Highcharts-specific errors (e.g., missing id or name keys).
• Caching: Clear Filament cache if styles don’t update:

  php artisan filament:cache:clear
  

Performance

• Large Hierarchies: For >500 nodes, optimize with lazy-loading or pagination:

  ->data(fn() => $this->getPaginatedData(100)) // Load 100 nodes at a time
  

• Database Queries: Use with() sparingly to avoid N+1 queries. Pre-load relationships:

  User::with(['subordinates' => fn($q) => $q->with('subordinates')])->get();
  

Extension Points

• Custom Node Templates: Override the default node rendering via a view:

  ->view('filament.organization-chart::custom-node', ['node' => $node])
  

• API Integration: Fetch data from an external API:

  ->data(fn() => Http::get('https://api.example.com/hierarchy')->json())
  

• Localization: Extend translations:

  // lang/en/filament-organization-chart.php
  return [
      'no_data' => 'No employees found in this department.',
  ];
  

Quirks

• Image Paths: Ensure profile images are accessible via absolute URLs or Filament’s storage disk:

  'image' => Storage::disk('public')->url($user->profile_photo_path),
  

• Orientation: Horizontal charts may require wider containers. Use CSS to enforce:

  .filament-widgets-organization-chart { min-width: 1000px; }
  

• Filament Version: Test compatibility with your Filament version (e.g., ^3.0). Check the package’s composer.json for constraints.