• Table of Contents
• Features
• Requirements
• Quick Start
• Installation
  • Step 1: Install Package
  • Step 2: Publish and Run Migrations
  • Step 3: Optional Publishing
• Configuration
  • Basic Setup
  • Configuration Options
    • Navigation
    • Poll Defaults
    • Limits & Performance
    • Authentication
  • Complete Example
  • Custom Table Names
• Usage
  • 1. Create Polls
  • 2. Display Polls on Frontend
    • Using Blade Component (Recommended)
    • Using Livewire Component
  • 3. Passing Polls to Views
• Events
  • Available Events
  • Listening to Events
  • Example Use Cases
• Security Considerations
  • Overview
  • Vote Tracking Methods
  • Security Notes
  • Performance
• Testing
  • Run Tests
  • Using Factories
  • Available Factory States
• Accessibility
• License

A FilamentPHP v4 plugin for creating and managing interactive polls with Livewire-powered components.

#Table of Contents

• Features
• Requirements
• Quick Start
• Installation
• Configuration
• Usage
• Events
• Testing
• Security
• Accessibility
• License

#Features

• Easy Management - Create and manage polls through Filament admin panel
• Flexible Voting - Single or multiple choice polls
• Guest Support - Optional guest voting with session tracking
• Real-time Updates - Live vote counting with configurable polling intervals
• Rich Display - Results with percentages and progress bars
• Scheduled Closing - Set poll closing dates
• Interactive UI - Livewire-powered voting experience
• Simple Integration - Blade component for easy frontend use
• Event System - Listen to poll lifecycle events
• Accessible - WCAG 2.1 AA compliant

#Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• FilamentPHP 4.x

#Quick Start

composer require caresome/filament-poll
php artisan vendor:publish --tag="filament-poll-migrations"
php artisan migrate

Register the plugin in your panel provider:

use Caresome\FilamentPoll\PollPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            PollPlugin::make(),
        ]);
}

Display a poll on your frontend:

<x-caresome::filament-poll :poll-id="1" />

#Installation

#Step 1: Install Package

composer require caresome/filament-poll

#Step 2: Publish and Run Migrations

php artisan vendor:publish --tag="filament-poll-migrations"
php artisan migrate

#Step 3: Optional Publishing

Publish config file (for customizing table names):

php artisan vendor:publish --tag="filament-poll-config"

Publish views (for customization):

php artisan vendor:publish --tag="filament-poll-views"

#Configuration

#Basic Setup

Add the plugin to your Filament panel provider:

use Caresome\FilamentPoll\PollPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            PollPlugin::make(),
        ]);
}

#Configuration Options

The plugin provides chainable methods to customize behavior:

#Navigation

PollPlugin::make()
    ->navigationIcon('heroicon-o-chart-bar')
    ->navigationSort(10)

#Poll Defaults

PollPlugin::make()
    ->isActiveByDefault(true)
    ->allowGuestVotingByDefault(false)
    ->multipleChoiceByDefault(false)
    ->showResultsBeforeVotingByDefault(false)
    ->showVoteCountByDefault(true)

#Limits & Performance

PollPlugin::make()
    ->maxPollOptions(20)
    ->maxOptionTextLength(255)
    ->pollingInterval('5s')

#Authentication

PollPlugin::make()
    ->authGuard('admin')

How it works:

• Auto-detects the Filament panel's guard
• Falls back to Laravel's default guard
• Supports multi-guard applications

Example:

PollPlugin::make()
    ->authGuard('admin')

#Complete Example

use Caresome\FilamentPoll\PollPlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            PollPlugin::make()
                ->navigationIcon('heroicon-o-chart-bar')
                ->navigationSort(10)
                ->isActiveByDefault(true)
                ->allowGuestVotingByDefault(false)
                ->multipleChoiceByDefault(false)
                ->showResultsBeforeVotingByDefault(false)
                ->showVoteCountByDefault(true)
                ->maxPollOptions(20)
                ->maxOptionTextLength(255)
                ->pollingInterval('5s')
                ->authGuard('admin'),
        ]);
}

#Custom Table Names

Publish the config file and modify table names:

php artisan vendor:publish --tag="filament-poll-config"

return [
    'table_names' => [
        'polls' => 'custom_polls',
        'poll_options' => 'custom_poll_options',
        'poll_votes' => 'custom_poll_votes',
    ],
];

#Usage

#1. Create Polls

Navigate to the Polls resource in your Filament admin panel:

1. Click "New Poll"
2. Enter poll question and options
3. Configure settings (guest voting, multiple choice, etc.)
4. Set closing date (optional)
5. Save and publish

#2. Display Polls on Frontend

#Using Blade Component (Recommended)

By Poll ID:

<x-caresome::filament-poll :poll-id="1" />

By Poll Model:

<x-caresome::filament-poll :poll="$poll" />

#Using Livewire Component

@livewire('caresome::filament-poll', ['poll' => $poll])

#3. Passing Polls to Views

In your controller:

use Caresome\FilamentPoll\Models\Poll;
 
public function index()
{
    $poll = Poll::where('is_active', true)->first();
 
    return view('welcome', compact('poll'));
}

In your view:

@if($poll)
    <x-caresome::filament-poll :poll="$poll" />
@endif

#Events

The package dispatches lifecycle events for custom integrations.

#Available Events

#Listening to Events

In EventServiceProvider:

use Caresome\FilamentPoll\Events\{PollCreated, PollVoted, PollClosed};
 
protected $listen = [
    PollCreated::class => [
        SendPollNotification::class,
    ],
    PollVoted::class => [
        TrackAnalytics::class,
    ],
    PollClosed::class => [
        SendResultsSummary::class,
    ],
];

Using Event::listen():

use Illuminate\Support\Facades\Event;
use Caresome\FilamentPoll\Events\PollVoted;
 
Event::listen(PollVoted::class, function (PollVoted $event) {
    $poll = $event->poll;
    $vote = $event->vote;
 
});

#Example Use Cases

• Send notifications when polls are created
• Track voting analytics
• Trigger webhooks on vote events
• Archive closed polls
• Send result summaries to stakeholders

#Security Considerations

#Overview

The package implements multiple security layers for vote tracking and prevention of abuse.

#Vote Tracking Methods

#Security Notes

Authenticated Users:

• ✅ One vote per user per poll
• ✅ Database-level enforcement
• ✅ High security

Guest Voting:

• ⚠️ Session + IP tracking (reasonable protection)
• ⚠️ Can vote again if cookies cleared
• ⚠️ VPN users share IPs (but unique sessions prevent conflicts)
• 🔒 Disable for high-security polls: allowGuestVotingByDefault(false)

#Performance

The package includes built-in optimizations:

• ✅ Eager loading prevents N+1 queries
• ✅ Database indexes on frequently queried fields
• ✅ Cached vote counting
• ✅ Efficient query constraints

#Testing

#Run Tests

composer test
composer test-coverage

#Using Factories

The package provides factories for testing:

use Caresome\FilamentPoll\Models\{Poll, PollOption, PollVote};
 
$poll = Poll::factory()->active()->multipleChoice()->create();
 
$option = PollOption::factory()->forPoll($poll)->create();
 
$vote = PollVote::factory()->forOption($option)->authenticated(1)->create();
$vote = PollVote::factory()->forOption($option)->guest()->create();

#Available Factory States

#Accessibility

WCAG 2.1 AA compliant with full accessibility support:

#License

The MIT License (MIT). See LICENSE.md for details.