Filament Screenshot Review Laravel Package

Getting Started

Minimal Setup

1. Install the package in a Filament v5 project:

   composer require --dev visualbuilder/filament-screenshot-review
   php artisan migrate
   

2. Mount the plugin in your Filament panel provider (e.g., DesignSystemPanelProvider):

   ->plugins([
       \Visualbuilder\FilamentScreenshotReview\Filament\FilamentScreenshotReviewPlugin::make(),
   ])
   

3. Register pages (one-time sync):

   php artisan screenshot-review:sync-pages --panel=design-system
   

4. Trigger captures (e.g., via CI/CD or manually):

   php artisan screenshot:dispatch --panel=design-system --tag=latest
   

5. Sync captures to the review dashboard:

   php artisan screenshot-review:sync-captures --panel=design-system --tag=latest
   

First Use Case

• Review a single capture: Navigate to the Captures tab in Filament, locate a card, and click Approve or Request Changes. If the latter, a ticket is filed via your TicketSink.

Implementation Patterns

Core Workflow

1. Page Management:

   • Use sync-pages to populate the sitemap from filament-panel-screenshot-catalogue.
   • Toggle page inclusion via the Pages tab in Filament (e.g., exclude staging URLs).

2. Capture Dispatch:

   • Integrate screenshot:dispatch into your deployment pipeline (e.g., post-build).
   • Tag captures (e.g., latest, v1.0) for traceability.

3. Review Loop:

   • Status Tab: Monitor panel health (e.g., % approved, pending changes).
   • Captures Tab: Grid view with inline actions (approve/request changes).
   • Pages Tab: Manage sitemap inclusion/exclusion.

Integration Tips

• Ticket Sinks: Implement TicketSink for your issue tracker (e.g., Jira, GitHub Issues). Example:

  class JiraTicketSink implements TicketSink {
      public function file(string $title, string $description, array $metadata): string {
          // API call to Jira...
          return $ticketUrl;
      }
  }
  

• Automation: Chain commands in a script (e.g., sync-pages → dispatch → sync-captures). Example (Bash):

  php artisan screenshot-review:sync-pages --panel=design-system
  php artisan screenshot:dispatch --panel=design-system --tag=latest
  php artisan screenshot-review:sync-captures --panel=design-system --tag=latest
  

• Custom Metadata: Extend capture cards by publishing views or modifying the plugin’s CaptureCard component.

Gotchas and Tips

Pitfalls

1. Tag Mismatch:

   • Ensure --tag in dispatch and sync-captures match. Mismatches cause orphaned captures.

2. Permission Issues:

   • Verify the Filament user has access to the plugin’s resources (e.g., screenshot_review.*).

3. Empty Captures:

   • If sync-captures yields no results, check:
     • The tag exists in the catalogue’s storage.
     • The panel name matches the catalogue’s configuration.

4. TicketSink Failures:

   • Default NullSink logs errors but doesn’t block. Override to handle failures gracefully (e.g., retry logic).

Debugging

• Artisan Commands: Use --verbose for detailed output:

  php artisan screenshot-review:sync-captures --panel=design-system --tag=latest -v
  

• Database: Inspect screenshot_review_captures and screenshot_review_pages tables for sync issues.

Extension Points

1. Custom Status Indicators: Override the StatusCard widget to add custom metrics (e.g., "Critical Bugs").

2. Capture Filters: Extend the Captures grid with custom filters (e.g., by created_at or status).

3. Notification Triggers: Listen to CaptureApproved/CaptureRequested events to send Slack/email alerts:

   Event::listen(\Visualbuilder\FilamentScreenshotReview\Events\CaptureRequested::class, function ($event) {
       // Send notification...
   });
   

4. Storage Backend: Modify the CaptureRepository to support alternative storage (e.g., S3) for images.

Configuration Quirks

• Panel Defaults: The plugin assumes a design-system panel by convention. Explicitly specify --panel in commands to avoid ambiguity.

• Concurrent Runs: Avoid running dispatch or sync-captures concurrently for the same panel/tag to prevent race conditions.