README

Polls and their ballots for Symfony applications: single, multiple or ranked, anonymous or not, counted on demand, with the single transferable vote for several seats and a voting interface to show them.

phil/poll-bundle puts the voting engine of phil/poll behind the services of a Symfony application. A poll has a question, two to a hundred labelled options, the rules of its ballots, the method its ballots are counted by, and, when the application wants it, an opening and a closing. People cast a ballot, change it, withdraw it while the poll is open; the people who manage it close it, reschedule it or delete it; the results are counted when they are asked for, and shown as the poll's visibility says — at any time, after voting, after closing, or to its managers only.

A poll that fills several seats — a board, a jury — is counted by the single transferable vote, by Meek's method, in exact numbers: every round is published, with its quota, the votes and keep factor of each option and the value exhausted, so that anyone holding the ballots replays the count to the last decimal.

A poll may be anonymous: its ballots are then kept apart from their voters. The bundle records that a voter took part, so that nobody votes twice, but nothing ties a ballot to them: the ballot has a random identifier, no time, and only the hash of the receipt its voter was given, with which they may change it while the poll is open.

It is for any Symfony application where people vote, and for the bundles that build on a vote: a poll of availabilities that finds a date, a questionnaire, a box of ideas voted by members, the general assembly of an association. A poll may belong to one of the application's resources — an idea, a meeting — named as a reference of phil/resource (idea:42), and so may its voters (user:7). The application says who may create a poll, vote and manage it; it may add counting methods of its own beside the four of the library. The bundles built on it show a poll with the same views and templates: the form of a ballot and the results, in the markup of the PHIL UX kit's recipes, working without JavaScript, and a DOM event when the results of a closed poll are revealed, on which the kit's celebration plays.

It is a Symfony bundle on phil/poll, phil/resource and Doctrine ORM: polls, ballots and participations live in three tables, or in memory for tests. The services keep no state between requests and are safe in a long-running worker; every action dispatches an event that names the poll and nothing else. A count can be kept in a cache pool until the next ballot, when the application names one.

Status

Documentation

Quick start

composer require phil/poll-bundle

use Phil\Poll\BallotKind;
use Phil\PollBundle\Application\PollDraft;
use Phil\PollBundle\Application\Polls;
use Phil\PollBundle\Domain\Status\ResultsVisibility;
use Phil\PollBundle\Domain\ValueObject\PollOption;
use Phil\Resource\ResourceReference;

final readonly class DrinksController
{
    public function __construct(
        private Polls $polls,
    ) {
    }

    public function create(ResourceReference $member): string
    {
        $poll = $this->polls->create(new PollDraft(
            'What do we drink at the next meeting?',
            [PollOption::of('tea', 'Tea'), PollOption::of('coffee', 'Coffee'), PollOption::of('cocoa', 'Cocoa')],
            BallotKind::Ranked,
            anonymous: true,
            results: ResultsVisibility::AfterClosing,
        ), $member);

        return $poll->id;
    }

    public function vote(string $poll, ResourceReference $member, array $choices): ?string
    {
        return $this->polls->cast($poll, $member, $choices)->receipt;   // shown once to the voter
    }
}

Requirements

PHP 8.5 or later with mbstring and sodium, Symfony 8.2, Doctrine ORM 3.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.