php-extended/php-vote-object

A library that implements the php-vote-object package

Installation

The installation of this library is made via composer. Download composer.phar from their website. Then add to your composer.json :

	"require": {
		...
		"php-extended/php-vote-object": "^2",
		...
	}

Then run php composer.phar update to install this library. The autoloading of all classes of this library is made through composer's autoloader.

Basic Usage :

To run this library, you need at least one other library, which is to provide a specific voting method implementing the PhpExtended\Vote\VotingMethodInterface interface.

Additionnally, an additional library that provides the biases to modify the votes before the election is runned may be used. The biases must implement the PhpExtended\Vote\BiasInterface interface.

Finally, the core of the voting system is to vote for something, so you must provide a library which creates citizens for the voting process, such citizens may vote and rank any candidate in the election. All the citizens must implement the PhpExtended\Vote\CitizenInterface interface. Those citizens are very important, they provide the candidates and their arguments. Their arguments is what will be examined by the different citizens when they will be choosing for a vote ordering, so the citizen methods must be coherent!

Once every piece comes together, the engine may be used the following way :

use PhpExtended\Vote\ElectionRunner;
use PhpExtended\Vote\InvalidCandidateException;
use PhpExtended\Vote\InvalidVoteException;
use PhpExtended\Vote\UnsolvableSituationException;

$runner = new ElectionRunner();
$biases = new ArrayIterator(array(
	$yourBiasedObjects,	// each implement BiasInterface
));
$citizens = new ArrayIterator(array(
	$yourCitizenObjects,	// each implement CitizenInterface
));
$method = $theChoosenMethod;	// implements VotingMethodInterface

try
{
	$result = $runner->runElection($method, $biases, $citizens);
}
catch(InvalidCandidateException $ice)
{
	// TODO handle the fact that one candidate is refused
}
catch(InvalidVoteException $ive)
{
	// TODO handle the fact that one vote is refused
}
catch(UnsolvableSituationException $use)
{
	// TODO handle the fact that an ordering between the 
	// candidates could not be decided by the current voting
	// method and the votes that were given.
}

foreach($result->getRankings() as $individualResult)
{
	// The rankings are given in order of importance, winner
	// first and loser last
	/* @var $individualResult \PhpExtended\Vote\ElectionResultInterface */
	$candidate = $individualResult->getCandidate();
	// here the candidate is one of the candidate object that
	// was given by one of your citizens, and you retrieve
	// its objects within the arguments of the citizen.
}

License

MIT (See license file).