Ploi Dashboard Laravel Package

Getting Started

• composer require lartisan/ploi-dashboard (v2.1.1 is the first release with Filament 5 support — confirm your filament/filament constraint before upgrading, and stay on the 2.1.0 line if you're still on Filament 3/4).
• Publish the config (php artisan vendor:publish and pick the ploi-dashboard config tag) and set your API token in .env. Tokens are generated in your Ploi account settings and inherit that account's permissions, so use an account whose access matches what you want the panel to be able to do.
• Register the plugin on your panel in app/Providers/Filament/*PanelProvider.php:

  ->plugin(PloiDashboardPlugin::make())
  

• Look first at the plugin's config file (token key, navigation registration) and at the Filament page/resource classes it registers — that's where navigation labels, slugs, and authorization hooks are wired.
• First use case: open the Ploi page in your admin panel, confirm your servers list loads, drill into a site, and trigger a deploy from the site actions. If servers don't load, the token or config:cache is the culprit 9 times out of 10.

Implementation Patterns

• Admin-panel only. Register the plugin on your internal/ops panel, not on customer-facing panels. If you must expose it more broadly, wrap access in a Gate/policy and enforce it via panel access control rather than relying on the plugin defaults.
• Separate deploy automation from the UI. Use the dashboard for manual operations (deploys, restarts, env var edits) and keep CI/CD on the Ploi API or Ploi's deploy webhooks. Don't build a pipeline that clicks through Filament pages.
• Cache the read paths. Server/site listings hit the Ploi API on every page load by default. Wrap list queries in Cache::remember() with a short TTL (30–60s) and bust the cache after mutating actions (deploy, restart, env update).
• Multi-tenant / multi-account. The token is global config. If different teams need different Ploi accounts, the clean pattern is one panel per account (each with its own config or a service provider that overrides the token at boot), not a single panel with runtime token swapping.
• Testing. Use Http::fake(['ploi.io/*' => Http::response($fixture)]) around Livewire/Filament page tests so the suite never touches the real API. Assert on the actions (deploy triggered, restart called) rather than on rendered markup.
• Local development. Without a token the plugin has nothing to render — install it only in environments where you set the token, or gate registration with ->plugin(...)->when(fn () => app()->environment('production', 'staging')) style conditionals on the panel.

Gotchas and Tips

• Filament version matrix. v2.1.1's headline change is Filament 5 compatibility (plus Dependabot bumps to the Pint action and fetch-metadata — CI-only, no runtime impact). Nothing here is breaking for existing Filament 3/4 users, but pin the plugin version deliberately in composer.json if you can't move Filament yet.
• Config caching. After changing the token or config, run php artisan config:clear (and re-cache in deploy). A stale cached token produces confusing 401s that look like permission problems.
• Deploys are asynchronous. Triggering a deploy from the dashboard only queues the work on Ploi's side. Don't treat the action's success as "deployed" — poll the deployment status if you need real confirmation.
• Rate limits and latency. Ploi's API is not local; unpaginated server/site loops will be slow and can trip limits. Paginate, cache, and avoid calling the API from boot() methods or view composers.
• Destructive actions. Site deletion, server reboots, and service restarts are one click away in the UI. Restrict the plugin to trusted roles and consider hiding destructive actions in production-critical panels.
• Debugging. Failed API calls surface as generic Filament notifications. Log the underlying response (Http::fake in tests, Log::debug() around the client in dev) to see Ploi's actual error body — it's usually far more specific than what the UI shows.
• Extension points. Publish the views/config to override labels and layout, and extend the plugin's page/resource classes rather than forking the package; that keeps you on the upgrade path for the next Filament major.