Filament Cloudflare Laravel Package

Getting Started

• Install with Composer and register the Filament plugin in your panel provider:

  composer require notwonderful/filament-cloudflare
  

  use NotWonderful\FilamentCloudflare\FilamentCloudflarePlugin;
  
  public function panel(Panel $panel): Panel
  {
      return $panel
          ->plugin(FilamentCloudflarePlugin::make());
  }
  

• Publish and review the package config first. Look for the Cloudflare API token, zone ID(s), navigation settings, and Filament page/resource registration. Check the package README for the exact publish tag.

• Create a scoped Cloudflare API token rather than using a global API key. At minimum, expect to need zone read, DNS edit, and cache purge permissions for the workflows you enable.

• Add credentials to .env and keep separate tokens for local/staging/production. After changing env values, run php artisan config:clear if config is cached.

• First use case: open the Cloudflare section in your Filament admin panel, select a zone, and manage DNS records. Release 0.1.3 adds DNS records management, so the first practical workflow is listing, creating, editing, and deleting DNS records without leaving the admin panel.

• Where to look first: config/filament-cloudflare.php, the plugin class, and the Filament pages/resources under the package’s src/Filament namespace. Confirm the navigation group and route prefix before exposing it to users.

Implementation Patterns

• Use the plugin as an internal operations console: enable it only in admin/staff panels, place it behind Filament authentication, and restrict access with policies or panel-level authorization.
• For single-zone applications, configure the zone ID in .env and let the panel focus on DNS records and cache purge. For multi-zone accounts, rely on the zone selector/list and make sure users understand which zone they are editing.
• Treat DNS record management as a CRUD workflow: create common records such as A, AAAA, CNAME, TXT, and MX; validate name, content, TTL, priority, and proxied status before saving. Use the package’s Filament forms/actions where possible instead of duplicating Cloudflare API calls.
• Integrate cache purge into deployment or content-publish workflows. Wrap purge calls in queued jobs or listeners so web requests and Filament saves are not blocked by Cloudflare API latency.
• Use Cloudflare as the source of truth for quick operational changes, but keep infrastructure-as-code for repeatable DNS. A common pattern is Terraform/OpenTofu for baseline records and the Filament panel for urgent fixes, verification, and cache purges.
• Scope multi-tenant usage carefully. If different teams manage different zones, add authorization around zone selection and DNS record actions; do not rely on navigation visibility alone.
• Cache zone lists and other slow Cloudflare reads where appropriate, but invalidate after DNS changes or zone updates.
• In tests, fake Cloudflare HTTP responses or bind a fake client. Assert Filament form behavior and authorization without hitting the real Cloudflare API.
• Use separate Cloudflare tokens per environment and per panel. A staging panel should not be able to mutate production DNS records.

Gotchas and Tips

• This is a 0.x package. Expect API, config, and Filament class names to change between minor releases. Pin the version in composer.json and review changelogs before upgrading.
• Cloudflare API token scopes are the most common failure point. A token that can read zones may still fail on DNS edits or cache purge. Check for 403/Authentication error responses and verify zone-level permissions.
• Prefer zone IDs over zone names in configuration. Zone names can change, and names are not unique across accounts.
• DNS changes are not instant everywhere. TTL, proxied records, and downstream resolvers affect propagation. Do not use the panel as a substitute for a change-management process on critical records.
• Proxied records have restrictions: not every record type can be proxied, and CNAME flattening behavior can surprise you. Validate record combinations before saving.
• Bulk DNS edits can hit Cloudflare rate limits. Queue bulk changes, add retries/backoff, and avoid loops that call the API per row without throttling.
• Filament pages are not automatically restricted to super-admins. Add policies, gates, or panel access controls before deploying to an admin panel with multiple users.
• Package validation may be intentionally lightweight. Add custom validation for protected records, domain ownership, and reserved names if non-technical users can edit DNS.
• Debugging through Filament notifications can hide the underlying Cloudflare error. Check storage/logs/laravel.log, enable HTTP client logging temporarily, and inspect the Cloudflare response body.
• After changing .env or package config, clear cached config. In production, deploy config changes deliberately rather than editing cached config files.
• Before enabling DNS deletion or bulk actions, consider soft safeguards: protected record names, confirmation modals, audit logging, and exports/backups of current DNS state.
• Extension points to review: published config, package views, Filament page/resource classes, navigation registration, policies, and any service/client bindings. Prefer extending the package’s Filament resources or adding custom actions over forking the package for small UI changes.