Additional steering for PHPstan

Here we specify at the generic function and override with more specific
fields if the function is overridden after inheritance.

One improvement can be had with the awards where we should return always
a list of awards instead of either an award or a list of awards.

phpstan-baseline.neon

@@ -180,51 +180,6 @@ parameters:
 			count: 1
 			path: webapp/src/Controller/API/SubmissionController.php
 
-		-
-			message: "#^Method App\\\\Controller\\\\Jury\\\\ClarificationController\\:\\:getClarificationFormData\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Controller/Jury/ClarificationController.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\ExternalRelationshipEntityInterface\\:\\:getExternalRelationships\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/ExternalRelationshipEntityInterface.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\ExternalSourceWarning\\:\\:getContent\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/ExternalSourceWarning.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\ExternalSourceWarning\\:\\:setContent\\(\\) has parameter \\$content with no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/ExternalSourceWarning.php
-
-		-
-			message: "#^Property App\\\\Entity\\\\ExternalSourceWarning\\:\\:\\$content type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/ExternalSourceWarning.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\Judging\\:\\:getExternalRelationships\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/Judging.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\Submission\\:\\:getExternalRelationships\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/Submission.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\Team\\:\\:getExternalRelationships\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/Team.php
-
-		-
-			message: "#^Method App\\\\Entity\\\\User\\:\\:getExternalRelationships\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Entity/User.php
-
 		-
 			message: "#^Method App\\\\FosRestBundle\\\\FlattenExceptionHandler\\:\\:serializeToJson\\(\\) has parameter \\$type with no value type specified in iterable type array\\.$#"
 			count: 1
@@ -250,21 +205,6 @@ parameters:
 			count: 1
 			path: webapp/src/Helpers/OrdinalArray.php
 
-		-
-			message: "#^Method App\\\\Service\\\\AwardService\\:\\:getAwards\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Service/AwardService.php
-
-		-
-			message: "#^Property App\\\\Service\\\\AwardService\\:\\:\\$awardCache type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Service/AwardService.php
-
-		-
-			message: "#^Method App\\\\Service\\\\BalloonService\\:\\:collectBalloonTable\\(\\) return type has no value type specified in iterable type array\\.$#"
-			count: 1
-			path: webapp/src/Service/BalloonService.php
-
 		-
 			message: "#^Method App\\\\Service\\\\ExternalContestSourceService\\:\\:addOrUpdateWarning\\(\\) has parameter \\$content with no value type specified in iterable type array\\.$#"
 			count: 1

webapp/src/Controller/Jury/ClarificationController.php

@@ -211,6 +211,9 @@ public function viewAction(int $id): Response
         );
     }
 
+    /**
+     * @return array{teams: array<string|int, string>, subjects: array<string, array<string, string>>}
+     */
     protected function getClarificationFormData(?Team $team = null): array
     {
         $teamlist = [];

webapp/src/Entity/ExternalRelationshipEntityInterface.php

@@ -13,6 +13,8 @@ interface ExternalRelationshipEntityInterface
      *
      * This method should return an array with as keys the JSON field names and as values the actual entity
      * objects that the SetExternalIdVisitor should check for applicable external IDs.
+     *
+     * @return array<string, Object|Object[]|null>
      */
     public function getExternalRelationships(): array;
 }

webapp/src/Entity/ExternalSourceWarning.php

@@ -54,6 +54,7 @@ class ExternalSourceWarning
     #[ORM\Column(options: ['comment' => 'Hash of this warning. Unique within the source.'])]
     private string $hash;
 
+    /** @var array<string, mixed> $content */
     #[ORM\Column(
         type: 'json',
         options: ['comment' => 'JSON encoded content of the warning. Type-specific.']
@@ -135,11 +136,17 @@ public function setHash(string $hash): ExternalSourceWarning
         return $this;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function getContent(): array
     {
         return $this->content;
     }
 
+    /**
+     * @param array<string, mixed> $content
+     */
     public function setContent(array $content): ExternalSourceWarning
     {
         $this->content = $content;

webapp/src/Entity/Judging.php

@@ -444,6 +444,8 @@ public function getInternalError(): ?InternalError
      *
      * This method should return an array with as keys the JSON field names and as values the actual entity
      * objects that the SetExternalIdVisitor should check for applicable external ID's.
+     *
+     * @return array{submission_id: Submission}
      */
     public function getExternalRelationships(): array
     {

webapp/src/Entity/Submission.php

@@ -444,6 +444,8 @@ public function getRejudging(): ?Rejudging
      *
      * This method should return an array with as keys the JSON field names and as values the actual entity
      * objects that the SetExternalIdVisitor should check for applicable external ID's.
+     *
+     * @return array{language_id: Language, problem_id: Problem, team_id: Team|null}
      */
     public function getExternalRelationships(): array
     {

webapp/src/Entity/Team.php

@@ -591,7 +591,7 @@ public function canViewClarification(Clarification $clarification): bool
     }
 
     /**
-     * @inheritdoc
+     * @return array{organization_id: TeamAffiliation|null, group_ids: TeamCategory[]}
      */
     public function getExternalRelationships(): array
     {

webapp/src/Entity/User.php

@@ -500,6 +500,9 @@ public function getUserIdentifier(): string
         return $this->getUsername();
     }
 
+    /**
+     * @return array{team_id: Team|null}
+     */
     public function getExternalRelationships(): array
     {
         return [

webapp/src/Service/AwardService.php

@@ -8,6 +8,7 @@
 
 class AwardService
 {
+    /** @var array<array{id: string, citation: string, team_ids: string[]}> $awardCache */
     protected array $awardCache = [];
 
     public function __construct(protected readonly EventLogService $eventLogService)
@@ -114,6 +115,9 @@ protected function loadAwards(Contest $contest, Scoreboard $scoreboard): void
         $this->awardCache[$contest->getCid()] = $results;
     }
 
+    /**
+     * @return array<array{id: string, citation: string, team_ids: string[]}>|array{id: string, citation: string, team_ids: string[]}|null
+     */
     public function getAwards(Contest $contest, Scoreboard $scoreboard, string $requestedType = null): ?array
     {
         if (!isset($this->awardCache[$contest->getCid()])) {

webapp/src/Service/BalloonService.php

@@ -4,9 +4,12 @@
 
 use App\Entity\Balloon;
 use App\Entity\Contest;
+use App\Entity\ContestProblem;
 use App\Entity\Judging;
 use App\Entity\ScoreCache;
 use App\Entity\Submission;
+use App\Entity\Team;
+use App\Entity\TeamAffiliation;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\NonUniqueResultException;
 use Doctrine\ORM\NoResultException;
@@ -75,6 +78,12 @@ public function updateBalloons(
         }
     }
 
+    /**
+     * @return array<array{data: array{balloonid: int, time: string, problem: string, contestproblem: ContestProblem,
+     *                                 team: Team, teamid: int, location: string|null, affiliation: TeamAffiliation|null,
+     *                                 affiliationid: int, category: string, categoryid: int, total: array<string, ContestProblem>,
+     *                                 awards: string, done: bool}}>
+    */
     public function collectBalloonTable(Contest $contest, bool $todo = false): array
     {
         $em = $this->em;