Admin Panel Resources

Last updated: 2026-03-22

The package includes optional Filament resources for managing addresses and monitoring API usage. These resources can be registered in your Filament panel.

---

Available Resources

1. Address Cache Viewer (AddressCacheResource)

View and manage cached API responses:

• Browse cached geocoding/verification results
• See cache hit rates and expiration dates
• Clear expired entries or all cache
• View cache statistics

2. API Audit Log (AddressAuditLogResource)

Monitor API usage:

• View all API calls with response times
• Filter by provider, operation type, date range
• Track cache hit/miss rates
• See cache hit rate and usage analytics

Tracked Operations:

• geocode - Forward geocoding (address → coordinates)
• reverse_geocode - Reverse geocoding (coordinates → address)
• verify - Address verification (USPS, Google, etc.)
• autocomplete - Google Places Autocomplete (synthetic entries)

Note: Autocomplete sessions are tracked via synthetic audit log entries when users select from map/autocomplete. These synthetic entries are marked with "synthetic": true in their response data.

Privacy: The address_api_audit_logs table stores address PII (street addresses, coordinates, city/state) in input_data and response_data columns. Include this table in your data retention policy and GDPR/CCPA data subject access/deletion procedures.

---

Registration Options

Option 1: Register All Resources (Recommended)

In your app/Providers/Filament/AdminPanelProvider.php:

use Viewflex\FilamentAddress\FilamentAddressServiceProvider;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->resources([
            // Your existing resources...
        ])
        ->discoverResources(
            in: app_path('Filament/Resources'),
            for: 'App\\Filament\\Resources'
        )
        // Register all package resources
        ->resources(FilamentAddressServiceProvider::getResources());
}

This adds:

• Address Manager (/admin/addresses) - standalone global address table with search, filters, import/export
• Address Cache Viewer (/admin/address-api-cache)
• API Audit Log (/admin/address-api-audit-log)

---

Option 2: Register Specific Resources

If you only want certain resources:

use Viewflex\FilamentAddress\FilamentAddressServiceProvider;

public function panel(Panel $panel): Panel
{
    return $panel
        ->resources([
            // Just the cache viewer
            FilamentAddressServiceProvider::getCacheResource(),

            // Or just the audit log
            FilamentAddressServiceProvider::getAuditLogResource(),
        ]);
}

---

Option 3: Don't Register (Use Commands Only)

You don't have to register any resources! The cache and audit system works automatically. You can manage it via Artisan commands:

# View cache statistics
php artisan addresses:cache:stats

# Clean expired cache
php artisan addresses:cache:cleanup

# Clear all cache
php artisan addresses:cache:cleanup --all

---

Navigation

Resources appear in the "Address API" navigation group with these labels:

• API Cache (navigation sort: 2)
• API Audit Log (navigation sort: 3)

You can customize this by extending the resources:

namespace App\Filament\Resources;

use Viewflex\FilamentAddress\Filament\Resources\AddressCacheResource as BaseResource;

class AddressCacheResource extends BaseResource
{
    protected static ?string $navigationGroup = 'System';

    protected static ?int $navigationSort = 10;
}

---

Features

Address Cache Resource

Table Columns:

• Cache Key (copyable)
• Operation Type (badge: geocode/reverse_geocode/verify)
• Provider (badge: google/usps/smarty)
• Country Code
• Success Status
• Cached At / Expires At (color-coded)

Actions:

• Clear Expired - Remove expired cache entries
• Clear All - Remove all cache (with confirmation)
• Statistics - View cache size and age range modal

Filters:

• Operation Type
• Provider
• Success Status

---

API Audit Log Resource

Table Columns:

• Trace ID (copyable UUID)
• Operation Type (badge)
• Provider (badge)
• Country Code
• Cache Status (HIT/MISS badge)
• Request Status (Success/Failed)
• Response Time (color-coded: <100ms green, <500ms yellow, >500ms red)
• Timestamp
• User ID (hidden by default)

Actions:

• Analytics - Opens modal with:
  • Cache hit rate
  • Request breakdown by provider

Filters:

• Operation Type
• Provider
• Cache Status (Hit/Miss)
• Request Status (Success/Failed)
• Date Range (from/until)

---

Analytics Modal

The audit log analytics modal shows:

Cache Effectiveness

• Hit Rate Percentage - Overall cache effectiveness
• Total Requests - All API calls made
• Cache Hits - Requests served from cache

Requests by Provider

Breakdown showing:

• Provider name (colored badge)
• Number of requests

---

Permissions

Both resources are read-only by default (users cannot create entries directly). To restrict access further, use Filament's policy system:

// app/Policies/AddressCachePolicy.php
public function viewAny(User $user): bool
{
    return $user->hasRole('admin');
}

Register in AuthServiceProvider:

protected $policies = [
    \Viewflex\FilamentAddress\Filament\Resources\AddressCacheResource::class
        => \App\Policies\AddressCachePolicy::class,
];

---

Customization

Extending Resources

Create your own resource that extends the package resource:

namespace App\Filament\Resources;

use Viewflex\FilamentAddress\Filament\Resources\AddressCacheResource as BaseResource;

class CustomCacheResource extends BaseResource
{
    protected static ?string $navigationIcon = 'heroicon-o-server';

    protected static ?string $navigationLabel = 'API Cache Manager';

    // Override table() method to add custom columns, filters, actions
    public static function table(Table $table): Table
    {
        return parent::table($table)
            ->columns([
                // Add or modify columns
            ]);
    }
}

Hiding Resources

To hide a resource in certain environments:

class AddressCacheResource extends BaseResource
{
    public static function shouldRegisterNavigation(): bool
    {
        return app()->environment('local', 'staging');
    }
}

---

Examples

Development Setup

Show all resources for development/debugging:

->resources(FilamentAddressServiceProvider::getResources())

Production Setup

Hide admin resources, use commands only:

// Don't register any address API resources
// Use: php artisan addresses:cache:stats for monitoring

Agency Setup

Show to admins only:

->resources(
    auth()->user()?->hasRole('admin')
        ? FilamentAddressServiceProvider::getResources()
        : []
)

---

Related Documentation

• Panel Setup Guide - Complete walkthrough: add resources + widgets, dedicated panel, admin-only access
• Configuration
• User Guide
• API Reference
• Implementation Patterns - Multi-panel setups and common patterns