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 and costs:

View all API calls with response times and costs
Filter by provider, operation type, date range
Track cache hit/miss rates
See cost breakdowns and savings 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 costs are tracked via synthetic audit log entries. When users select from map/autocomplete, the package logs both the reverse geocoding cost and a synthetic autocomplete entry ($0.00283 per request) for complete cost accounting. 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:

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:

php

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:

bash

# 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

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:

php

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)
Cost (in USD)
Timestamp
User ID (hidden by default)

Actions:

Analytics - Opens modal with:
- Total API cost (last 30 days)
- Savings from caching
- Cache hit rate
- Cost breakdown by provider
- Estimated monthly cost

Filters:

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

The audit log analytics modal shows:

Cost Overview

Total API Cost - Money spent on actual API calls
Saved by Caching - Money saved by serving cached results

Cache Effectiveness

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

Cost by Provider

Breakdown showing:

Provider name (colored badge)
Number of requests
Total cost per provider

Estimated Monthly

Projection of monthly costs based on current usage patterns.

Permissions

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

php

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

php

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

Customization

Extending Resources

Create your own resource that extends the package resource:

php

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:

php

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

Examples

Development Setup

Show all resources for development/debugging:

php

->resources(FilamentAddressServiceProvider::getResources())

Production Setup

Hide admin resources, use commands only:

php

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

Agency Setup

Show to admins only:

php

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

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

Admin Panel Resources ​

Available Resources ​

1. Address Cache Viewer (AddressCacheResource) ​

2. API Audit Log (AddressAuditLogResource) ​

Registration Options ​

Option 1: Register All Resources (Recommended) ​

Option 2: Register Specific Resources ​

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

Navigation ​

Features ​

Address Cache Resource ​

API Audit Log Resource ​

Analytics Modal ​

Cost Overview ​

Cache Effectiveness ​

Cost by Provider ​

Estimated Monthly ​

Permissions ​

Customization ​

Extending Resources ​

Hiding Resources ​

Examples ​

Development Setup ​

Production Setup ​

Agency Setup ​

Related Documentation ​