Laravel Dashboard Laravel Package

Getting Started

1. Install via Composer: composer require iutrace/laravel-dashboard.
2. Publish config and assets: php artisan vendor:publish --provider="Iutrace\Dashboard\DashboardServiceProvider" (check the README for exact tags; typically --tag=dashboard-config and --tag=dashboard-assets).
3. Run migrations if the package stores tile data: php artisan migrate.
4. Create your first dashboard class: php artisan make:dashboard MainDashboard (or manually extend the package’s base Dashboard class).
5. Define tiles in the tiles() method – start with one or two built-in tiles (e.g., a stat tile or chart tile) to confirm the wiring.
6. Register the dashboard route (usually automatic via config, but verify config/dashboard.php for the route prefix and middleware).
7. Visit /dashboard (or your configured path) to see the tiles.

Where to look first: config/dashboard.php (route, middleware, cache settings), the generated app/Dashboard/MainDashboard.php, and the package’s src/Tiles directory for available tile types. The 1.1.2 release updates Dashboard.php – review the diff on GitHub if you’ve extended or overridden that class.

First use case: Build a simple “team stats” dashboard with a stat tile showing user count and a line-chart tile showing signups over the last 30 days. Use a scheduled command to populate the tile data (see Implementation Patterns).

Implementation Patterns

• Tile composition: Each dashboard’s tiles() method returns an array of tile instances. Compose tiles by position and width (most dashboard packages use a grid system). Example:

  public function tiles(): array
  {
      return [
          UserCountTile::make()->width('1/3'),
          SignupsChartTile::make()->width('2/3'),
      ];
  }
  

• Data fetching: Tiles typically read from cache or a database table. Create an artisan command per data source (e.g., FetchUserStats) and schedule it in app/Console/Kernel.php:

  $schedule->command('dashboard:fetch-user-stats')->everyFiveMinutes();
  

  The tile then reads cache('dashboard.user-count') or queries a dedicated table.
• Custom tiles: Extend the package’s base tile class, implement the required data method, and provide a Blade view. Register the tile in any dashboard by instantiating your class.
• Multiple dashboards: Create separate dashboard classes and register additional routes (or use the package’s route registration if it supports multiple). Apply different middleware/gates per dashboard for access control.
• Live updates: If tiles support polling (Livewire or AJAX), configure the refresh interval per tile. For heavy data, prefer scheduled background fetches and let the tile poll the cache.
• Integration with existing apps: Embed a dashboard inside an existing admin panel by using the package’s route macro or by rendering the dashboard component directly in a Blade view. Ensure the dashboard’s middleware includes your auth guard.

Gotchas and Tips

• Stale data: The most common pitfall is forgetting to schedule the data-fetch commands. Tiles will show empty or outdated values. Add a health check or log entry when a fetch command runs.
• Caching intervals: Tiles may cache their output. If you update a fetch command, clear the tile cache (php artisan cache:clear or a targeted tag) to see changes immediately.
• Asset publishing: After upgrading the package, re-publish assets (php artisan vendor:publish --tag=dashboard-assets --force) if the UI looks broken. Check the release notes – 1.1.2 only touches Dashboard.php, so asset changes are unlikely, but always verify.
• Extending Dashboard.php: If your app subclasses or overrides methods in Dashboard.php, review the 1.1.2 diff (PR #3) before upgrading. A patch release can still change internal behaviour (e.g., method visibility or default property values) that affects subclasses.
• Route conflicts: The default route prefix (/dashboard) may clash with existing routes. Change it in config/dashboard.php early.
• Authorization: The package does not enforce authorization by default. Add middleware (e.g., auth, can:view-dashboard) to the dashboard routes in config or in your route registration.
• Debugging tiles: Use Laravel Telescope or log the data returned by your fetch commands. If a tile is blank, check that the tile’s data key matches what the fetch command stores.
• Extension points: Most packages allow overriding tile views via view()->prependNamespace() or by publishing views. Check the package’s views directory for customizable Blade files. For custom behaviour, prefer extending base classes over editing vendor files.
• Version pinning: Since this is a patch release (1.1.2), it’s safe to upgrade from 1.1.1 for most users. Pin to ^1.1 in composer.json to receive bug fixes without accidental breaking changes.