Radar Laravel Package

Getting Started

Start by confirming what the package actually ships before wiring it into an app:

1. Install with Composer:

   composer require joshdonnell/radar
   

2. Check the package service provider for publishable assets, config, migrations, and routes. In a typical Laravel package this is done with:

   php artisan vendor:publish --provider="JoshDonnell\Radar\RadarServiceProvider"
   

   If the package defines publish tags, prefer those over publishing everything.
3. Review config/radar.php (or the equivalent config file) for route prefix, middleware, dashboard layout, and any storage/driver settings.
4. Run migrations only if the package includes them:

   php artisan migrate
   

5. Open the dashboard route. The exact path is config-driven, but it is commonly something like /radar. Confirm the dashboard renders and that its layout is being resolved from the package or from your published override.

The first real use case is usually: install the package, publish the config, protect the dashboard with your app’s auth middleware, and load it in a local or staging environment to verify the dashboard layout and data sources work. Do this before customizing views so you know the baseline behavior.

Where to look first:

• The package service provider: register, boot, publishes, route loading, view namespaces.
• The package config/ file: route prefix, middleware, dashboard layout, enabled features.
• The package routes/ file: actual dashboard URL and middleware stack.
• The package resources/views/: dashboard layout and any published overrides.
• The package README/upgrade notes for version-specific behavior.

Implementation Patterns

Treat the dashboard as a configurable Laravel surface rather than a black box.

Config-first integration. Keep package behavior in config/radar.php and environment variables rather than editing vendor files. Typical day-to-day settings are the route prefix, middleware, and dashboard layout. If the package supports multiple environments, gate it so production is not exposed accidentally.

Protect the dashboard explicitly. Even if the package ships middleware, add your own auth/authorization middleware in config or in the route group:

// config/radar.php
'middleware' => [
    'web',
    'auth',
    'can:viewRadar',
],

Then define the viewRadar gate or policy in your app. This is safer than relying on the package’s default middleware.

Publish only what you need to override. If you need to change the dashboard layout, publish views and edit your copy. If you do not need to change views, leave them unpublished so package updates flow through. When you do publish, record which files are now app-owned so future package layout changes do not silently break you.

Use the package in local/staging first. Dashboards often expose operational data. Install it locally, verify data sources, then promote the same config to staging. Avoid enabling broad access in production until you have confirmed middleware and data exposure.

Version pin deliberately. Since this is a 0.x package, minor releases can include behavior changes. Prefer a constrained requirement such as ^0.3 and review release notes before jumping minor versions. If the dashboard is business-critical, pin the exact version in composer.json and upgrade intentionally.

Integrate with existing app conventions. Reuse your app’s layout components, auth guards, and route middleware where the package allows it. If the package has its own layout, keep custom app chrome in a published override rather than forking vendor code. This makes future upgrades much less painful.

Test the dashboard route. Add a feature test that asserts the dashboard route responds successfully for an authorized user and redirects or forbids unauthorized users:

public function test_radar_dashboard_requires_auth(): void
{
    $this->get(config('radar.path', '/radar'))
        ->assertRedirect('/login');
}

This catches route, middleware, and layout regressions after package upgrades.

Gotchas and Tips

v0.3.1 renamed the dashboard layout to avoid stale compiled views. This is the key upgrade note. After updating, clear compiled views and caches:

php artisan view:clear
php artisan config:clear
php artisan route:clear
php artisan optimize:clear

If you previously published the old layout, check whether your published view still references the old layout name. The package rename may fix the vendor default but not your local override. Search your app for the old layout name:

grep -R "old-layout-name" resources/views config

and update or republish the view if needed.

Compiled views can mask layout changes. Laravel compiles Blade views into storage/framework/views. If the dashboard still looks stale after upgrading, clear that directory via php artisan view:clear and confirm file permissions allow Laravel to write new compiled views. In containerized deployments, ensure the storage and bootstrap/cache directories are writable by the runtime user.

Config caching can hide new config keys. If you run php artisan config:cache in deployment, new package config keys may not appear until you rebuild the cache. Always run php artisan config:clear or php artisan optimize:clear after upgrading. Better yet, make cache clearing part of your deploy script.

Published views become your responsibility. Once you publish the dashboard layout, package updates to that layout will not reach your app. Periodically diff your published views against the package’s current views, especially after minor releases. If the package renames a layout or view, your override may continue to work but diverge from upstream fixes.

Route and middleware conflicts. If your app already uses the same route prefix or middleware alias, the package may conflict. Check the registered routes with:

php artisan route:list

and confirm the dashboard path, name, and middleware match your expectations. If the dashboard is behind auth, verify unauthenticated requests redirect rather than throwing a 500.

Authorization is not the same as authentication. Do not assume that adding auth middleware is enough. Add a gate or policy so only intended users can view operational data. This is especially important if the dashboard displays logs, jobs, or environment details.

Asset publishing can go stale. If the package publishes CSS/JS assets, re-publish or rebuild them after upgrading. Cached browser assets can make it look like the layout rename did not take effect. Check the browser network tab and the public asset path.

Extension points to prefer. Use config values, published views, and documented extension points rather than modifying vendor/. If the package dispatches events or exposes contracts, hook into those. Keep a short internal note of every published file and config override so upgrades remain predictable.

Debugging checklist for dashboard rendering issues:

1. php artisan route:list — confirm the route exists and has the expected middleware.
2. php artisan view:clear — eliminate stale compiled views.
3. php artisan config:clear — eliminate stale config.
4. Check storage/logs/laravel.log for Blade/view resolution errors.
5. Verify the configured layout view actually exists:

   php artisan tinker
   >>> view()->exists(config('radar.layout'))
   

6. Confirm the authenticated user passes the dashboard gate/policy.

Version note. This assessment is based on the v0.3.1 release note and general Laravel package conventions. Before relying on exact config keys, route names, or publish tags, verify them against the package’s README and service provider for the installed version.