New Exceptions System

.gitignore

@@ -15,3 +15,6 @@ lib/Algo/Methods/KemenyYoung-Data/10.data
 build/
 *.phar
 Dev/large.votes
+
+# phpstorm
+.idea

Dev/CondorcetDocumentationGenerator/CondorcetDocAttributes/Throws.php

@@ -0,0 +1,24 @@
+<?php
+/*
+    Condorcet PHP - Election manager and results calculator.
+    Designed for the Condorcet method. Integrating a large number of algorithms extending Condorcet. Expandable for all types of voting systems.
+
+    By Julien Boudry and contributors - MIT LICENSE (Please read LICENSE.txt)
+    https://github.com/julien-boudry/Condorcet
+*/
+declare(strict_types=1);
+
+namespace CondorcetPHP\Condorcet\Dev\CondorcetDocumentationGenerator\CondorcetDocAttributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Throws
+{
+    public array $exceptionList;
+
+    public function __construct(string ...$exceptionList)
+    {
+        $this->exceptionList = $exceptionList;
+    }
+}

Dockerfile

@@ -1,4 +1,4 @@
-FROM php:8.0-cli-bullseye
+FROM php:8.1-rc-cli-bullseye
 
 COPY . /usr/src/condorcetapp
 WORKDIR /usr/src/condorcetapp

Documentation/Election Class/public Election--addConstraint.md

@@ -15,7 +15,7 @@ A valid class path. Class must extend VoteConstraint class.
 
 ### Return value:   
 
-*(bool)* True on success. Throw Throwable\CondorcetException code 27/28/29 on error.
+*(bool)* True on success.
 
 
 ---------------------------------------

README.md

@@ -494,7 +494,6 @@ _Benchmark on a modern machine (linux - x64 - php 8.0 - cli)._
 
 ## Roadmap for further releases 
 
-  - Rebuild Exception System
   - **Research reference librarians !!**  
 
 

Tests/lib/Algo/Methods/CondorcetBasicTest.php

@@ -4,6 +4,8 @@
 namespace CondorcetPHP\Condorcet\Tests\Algo\Methods;
 
 use CondorcetPHP\Condorcet\{Candidate, Condorcet, CondorcetUtil, Election, Result, Vote, VoteConstraint};
+use CondorcetPHP\Condorcet\Algo\Methods\CondorcetBasic;
+use CondorcetPHP\Condorcet\Throwable\AlgorithmWithoutRankingFeatureException;
 use PHPUnit\Framework\TestCase;
 
 class CondorcetBasicTest extends TestCase
@@ -126,8 +128,8 @@ public function testResult_6 (): void
 
     public function testNoResultObject (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(102);
+        $this->expectException(AlgorithmWithoutRankingFeatureException::class);
+        $this->expectExceptionMessage("This algortihm can't provide a full ranking (but only Winner and Loser): ".CondorcetBasic::METHOD_NAME[0]);
 
         $this->election->addCandidate('A');
         $this->election->addCandidate('B');
@@ -140,7 +142,7 @@ public function testNoResultObject (): never
             A > C > L
         ');
 
-        $this->election->getResult(\CondorcetPHP\Condorcet\Algo\Methods\CondorcetBasic::class);
+        $this->election->getResult(CondorcetBasic::class);
     }
 
 }

Tests/lib/Algo/Methods/KemenyYoung/KemenyYoungTest.php

@@ -5,6 +5,7 @@
 
 use CondorcetPHP\Condorcet\{Candidate, Condorcet, CondorcetUtil, Election, Result, Vote, VoteConstraint};
 use CondorcetPHP\Condorcet\Algo\Methods\KemenyYoung\KemenyYoung;
+use CondorcetPHP\Condorcet\Throwable\CandidatesMaxNumberReachedException;
 use PHPUnit\Framework\TestCase;
 
 class KemenyYoungTest extends TestCase
@@ -77,9 +78,8 @@ public function testResult2 (): void
 
     public function testMaxCandidates (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(101);
-        $this->expectExceptionMessage('Kemeny–Young is configured to accept only 8 candidates');
+        $this->expectException(CandidatesMaxNumberReachedException::class);
+        $this->expectExceptionMessage("Maximum number of candidates reached: The method 'Kemeny–Young' is configured to accept only 8 candidates");
 
         for ($i=0; $i < 10; $i++) :
             $this->election->addCandidate();

Tests/lib/Algo/Methods/RankedPairs/RankedPairsTest.php

@@ -4,6 +4,7 @@
 namespace CondorcetPHP\Condorcet\Tests\Algo\Methods\RankedPairs;
 
 use CondorcetPHP\Condorcet\{Candidate, Condorcet, CondorcetUtil, Election, Result, Vote, VoteConstraint};
+use CondorcetPHP\Condorcet\Throwable\CandidatesMaxNumberReachedException;
 use PHPUnit\Framework\TestCase;
 
 class RankedPairsTest extends TestCase
@@ -388,9 +389,8 @@ public function testResult_11 (): void
 
     public function testMaxCandidates (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(101);
-        $this->expectExceptionMessage('Ranked Pairs Winning is configured to accept only 40 candidates');
+        $this->expectException(CandidatesMaxNumberReachedException::class);
+        $this->expectExceptionMessage("Maximum number of candidates reached: The method 'Ranked Pairs Winning' is configured to accept only 40 candidates");
 
         for ($i=0; $i < 41; $i++) :
             $this->election->addCandidate();

Tests/lib/Algo/Methods/STV/SingleTransferableVoteTest.php

@@ -3,10 +3,10 @@
 
 namespace CondorcetPHP\Condorcet\Tests\Algo\STV;
 
-use CondorcetPHP\Condorcet\{Candidate, Condorcet, CondorcetUtil, Election, Result, Vote, VoteConstraint};
+use CondorcetPHP\Condorcet\Election;
+use CondorcetPHP\Condorcet\Throwable\StvQuotaNotImplementedException;
 use CondorcetPHP\Condorcet\Algo\Methods\STV\SingleTransferableVote;
 use CondorcetPHP\Condorcet\Algo\Tools\StvQuotas;
-use CondorcetPHP\Condorcet\Throwable\CondorcetException;
 use PHPUnit\Framework\TestCase;
 
 class SingleTransferableVoteTest extends TestCase
@@ -29,9 +29,8 @@ public function testQuotaOption (): never
             $this->election->setMethodOption('STV', 'Quota', StvQuotas::make('Hagenbach-Bischoff'))
         );
 
-        $this->expectException(CondorcetException::class);
-        $this->expectExceptionCode(103);
-        $this->expectExceptionMessage('This quota is not implemented.');
+        $this->expectException(StvQuotaNotImplementedException::class);
+        $this->expectExceptionMessage('This STV quota is not implemented: "another quota"');
 
         $this->election->setMethodOption('STV', 'Quota', StvQuotas::make('another quota'));
         $this->election->addCandidate('A');

Tests/lib/CandidateTest.php

@@ -4,6 +4,7 @@
 namespace CondorcetPHP\Condorcet\Tests;
 
 use CondorcetPHP\Condorcet\{Candidate, Condorcet, CondorcetUtil, Election, Result, Vote, VoteConstraint};
+use CondorcetPHP\Condorcet\Throwable\{CandidateInvalidNameException, CandidateExistsException};
 use PHPUnit\Framework\TestCase;
 
 class CandidateTest extends TestCase
@@ -36,20 +37,20 @@ public function testTrimName (): void
         self::assertSame('candidateName',(string) $candidate);
     }
 
-    public function testToLongName (): never
+    public function testTooLongName (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(1);
+        $name = bin2hex(random_bytes(Election::MAX_LENGTH_CANDIDATE_ID + 42));
 
-        new Candidate (
-            bin2hex(random_bytes(Election::MAX_LENGTH_CANDIDATE_ID + 42))
-        );
+        $this->expectException(CandidateInvalidNameException::class);
+        $this->expectExceptionMessage("This name is not valid: $name");
+
+        new Candidate($name);
     }
 
     public function testBadName (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(1);
+        $this->expectException(CandidateInvalidNameException::class);
+        $this->expectExceptionMessage("This name is not valid");
 
         new Candidate ('<$"');
     }
@@ -63,8 +64,8 @@ public function testCandidateBadClass (): never
 
     public function testAddSameCandidate1 (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(3);
+        $this->expectException(CandidateExistsException::class);
+        $this->expectExceptionMessage("This candidate already exists: Schizophrenic");
 
         $election1 = new Election ();
 
@@ -76,8 +77,8 @@ public function testAddSameCandidate1 (): never
 
     public function testAddSameCandidate2 (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(3);
+        $this->expectException(CandidateExistsException::class);
+        $this->expectExceptionMessage("This candidate already exists: candidate1");
 
         $election1 = new Election ();
 
@@ -86,8 +87,8 @@ public function testAddSameCandidate2 (): never
 
     public function testAddSameCandidate3 (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(3);
+        $this->expectException(CandidateExistsException::class);
+        $this->expectExceptionMessage("This candidate already exists: candidate1");
 
         $election1 = new Election ();
 
@@ -110,8 +111,8 @@ public function testAddSameCandidate4 (): void
 
     function testSameCandidateToMultipleElection ()
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(19);
+        $this->expectException(CandidateExistsException::class);
+        $this->expectExceptionMessage("This candidate already exists: the name 'Debussy' is taken by another candidate");
 
         $election1 = new Election ();
         $election2 = new Election ();
@@ -138,7 +139,7 @@ function testSameCandidateToMultipleElection ()
         self::assertNotSame($this->candidate1, $election1->addCandidate('candidate1.n1'));
 
         $election2->addCandidate('Debussy');
-        $this->candidate1->setName('Debussy'); // Throw an Exception. Code 19.
+        $this->candidate1->setName('Debussy');
     }
 
     public function testCloneCandidate(): void

Tests/lib/CondorcetTest.php

@@ -5,6 +5,7 @@
 
 use CondorcetPHP\Condorcet\{Candidate, Condorcet, CondorcetUtil, Election, Result, Vote, VoteConstraint};
 use CondorcetPHP\Condorcet\Algo\{Method, MethodInterface};
+use CondorcetPHP\Condorcet\Throwable\AlgorithmException;
 
 use PHPUnit\Framework\TestCase;
 
@@ -27,8 +28,8 @@ public function testAddExistingMethod (): void
 
     public function testBadClassMethod (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(9);
+        $this->expectException(AlgorithmException::class);
+        $this->expectExceptionMessage("The voting algorithm is not available: no class found for 'sjskkdlkkzksh'");
 
         Condorcet::addMethod('sjskkdlkkzksh');
     }
@@ -47,8 +48,8 @@ public function testAuthMethod (): void
       */
     public function testAddMethod (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(25);
+        $this->expectException(AlgorithmException::class);
+        $this->expectExceptionMessage("The voting algorithm is not available: the given class is using an existing alias");
 
         $algoClassPath = CondorcetTest_ValidAlgorithmName::class;
 
@@ -64,8 +65,8 @@ public function testAddMethod (): never
 
     public function testAddUnvalidMethod (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(10);
+        $this->expectException(AlgorithmException::class);
+        $this->expectExceptionMessage("The voting algorithm is not available: the given class is not correct");
 
         $algoClassPath = CondorcetTest_UnvalidAlgorithmName::class;
 
@@ -84,8 +85,8 @@ public function testUnvalidDefaultMethod (): void
 
     public function testEmptyMethod (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(8);
+        $this->expectException(AlgorithmException::class);
+        $this->expectExceptionMessage("The voting algorithm is not available: no method name given");
 
         Condorcet::isAuthMethod('');
     }

Tests/lib/Console/Commands/ElectionCommandTest.php

@@ -3,6 +3,7 @@
 
 namespace CondorcetPHP\Condorcet\Tests\Console\Commands;
 
+use CondorcetPHP\Condorcet\Throwable\ResultRequestedWithoutVotesException;
 use PHPUnit\Framework\TestCase;
 use CondorcetPHP\Condorcet\Console\CondorcetApplication;
 use Symfony\Bundle\FrameworkBundle\Console\Application;
@@ -189,8 +190,8 @@ public function testInteractiveCommand (): void
 
     public function testNonInteractionMode (): never
     {
-        $this->expectException(\CondorcetPHP\Condorcet\Throwable\CondorcetException::class);
-        $this->expectExceptionCode(6);
+        $this->expectException(ResultRequestedWithoutVotesException::class);
+        $this->expectExceptionMessage("The result cannot be requested without votes");
 
         $this->electionCommand->execute([],['interactive' => false]);