From 0c945cddd923a2905329ed0bfbc91b664b9193aa Mon Sep 17 00:00:00 2001 From: shimomo Date: Fri, 29 Aug 2025 21:38:47 +0900 Subject: [PATCH 1/2] docs: update PHPDoc comments --- src/ProgramScraper.php | 62 +++++++-------------------- src/ProgramStorage.php | 46 +++----------------- src/ScraperAdapter.php | 50 ++++------------------ src/ScraperInterface.php | 83 +++++++++++++++++++----------------- tests/ProgramScraperTest.php | 50 ++++------------------ tests/ProgramStorageTest.php | 10 ++++- 6 files changed, 92 insertions(+), 209 deletions(-) diff --git a/src/ProgramScraper.php b/src/ProgramScraper.php index 3eb9d051..e74000c9 100644 --- a/src/ProgramScraper.php +++ b/src/ProgramScraper.php @@ -8,12 +8,16 @@ use Carbon\CarbonInterface; /** + * @psalm-import-type ScrapedStadiumRaces from ScraperInterface + * * @author shimomo */ final class ProgramScraper { /** - * @param \BOA\Programs\ScraperInterface $scraper + * @psalm-param \BOA\Programs\ScraperInterface $scraper + * + * @param \BOA\Programs\ScraperInterface $scraper */ public function __construct(private readonly ScraperInterface $scraper) { @@ -21,60 +25,26 @@ public function __construct(private readonly ScraperInterface $scraper) } /** - * @phpstan-type ScrapedRace array|string|int> - * @phpstan-type ScrapedRaces array - * @phpstan-type NormalizedBoat array{ - * racer_boat_number: int, - * racer_name: string, - * racer_number: int, - * racer_class_number: int, - * racer_branch_number: int, - * racer_birthplace_number: int, - * racer_age: int, - * racer_weight: float|int, - * racer_flying_count: int, - * racer_late_count: int, - * racer_average_start_timing: float|int, - * racer_national_top_1_percent: float|int, - * racer_national_top_2_percent: float|int, - * racer_national_top_3_percent: float|int, - * racer_local_top_1_percent: float|int, - * racer_local_top_2_percent: float|int, - * racer_local_top_3_percent: float|int, - * racer_assigned_motor_number: int, - * racer_assigned_motor_top_2_percent: float|int, - * racer_assigned_motor_top_3_percent: float|int, - * racer_assigned_boat_number: int, - * racer_assigned_boat_top_2_percent: float|int, - * racer_assigned_boat_top_3_percent: float|int - * } - * @phpstan-type NormalizedRace array{ - * race_date: string, - * race_stadium_number: int, - * race_number: int, - * race_closed_at: string, - * race_grade_number: int, - * race_title: string, - * race_subtitle: string, - * race_distance: int, - * boats: array - * } - * @phpstan-type NormalizedRaces array + * @psalm-param \Carbon\CarbonInterface|string $date + * @psalm-return ScrapedStadiumRaces * - * @param \Carbon\CarbonInterface|string $date - * @return array + * @param \Carbon\CarbonInterface|string $date + * @return array */ public function scrape(CarbonInterface|string $date = 'today'): array { $date = Carbon::parse($date, 'Asia/Tokyo'); - /** @var array $programs */ + /** @psalm-var ScrapedStadiumRaces $programs */ $programs = $this->scraper->scrapePrograms($date); return $this->normalize($programs); } /** - * @param array $programs - * @return array + * @psalm-param ScrapedStadiumRaces $programs + * @psalm-return ScrapedStadiumRaces + * + * @param array $programs + * @return array */ private function normalize(array $programs): array { @@ -89,7 +59,7 @@ private function normalize(array $programs): array } } - /** @var array */ + /** @psalm-var ScrapedStadiumRaces */ return $newPrograms; } } diff --git a/src/ProgramStorage.php b/src/ProgramStorage.php index 6d3e8c43..f55a9b79 100644 --- a/src/ProgramStorage.php +++ b/src/ProgramStorage.php @@ -5,51 +5,19 @@ namespace BOA\Programs; /** + * @psalm-import-type ScrapedStadiumRaces from ScraperInterface + * * @author shimomo */ final class ProgramStorage { /** - * @phpstan-type NormalizedBoat array{ - * racer_boat_number: int, - * racer_name: string, - * racer_number: int, - * racer_class_number: int, - * racer_branch_number: int, - * racer_birthplace_number: int, - * racer_age: int, - * racer_weight: float|int, - * racer_flying_count: int, - * racer_late_count: int, - * racer_average_start_timing: float|int, - * racer_national_top_1_percent: float|int, - * racer_national_top_2_percent: float|int, - * racer_national_top_3_percent: float|int, - * racer_local_top_1_percent: float|int, - * racer_local_top_2_percent: float|int, - * racer_local_top_3_percent: float|int, - * racer_assigned_motor_number: int, - * racer_assigned_motor_top_2_percent: float|int, - * racer_assigned_motor_top_3_percent: float|int, - * racer_assigned_boat_number: int, - * racer_assigned_boat_top_2_percent: float|int, - * racer_assigned_boat_top_3_percent: float|int - * } - * @phpstan-type NormalizedRace array{ - * race_date: string, - * race_stadium_number: int, - * race_number: int, - * race_closed_at: string, - * race_grade_number: int, - * race_title: string, - * race_subtitle: string, - * race_distance: int, - * boats: array - * } - * @phpstan-type NormalizedRaces array + * @psalm-param ScrapedStadiumRaces $programs + * @psalm-param non-empty-string $path + * @psalm-return void * - * @param array $programs - * @param non-empty-string $path + * @param array $programs + * @param string $path * @return void * @throws \RuntimeException */ diff --git a/src/ScraperAdapter.php b/src/ScraperAdapter.php index 84453169..8432d91c 100644 --- a/src/ScraperAdapter.php +++ b/src/ScraperAdapter.php @@ -8,12 +8,16 @@ use Carbon\CarbonInterface; /** + * @psalm-import-type ScrapedStadiumRaces from ScraperInterface + * * @author shimomo */ final class ScraperAdapter implements ScraperInterface { /** - * @param \BVP\Scraper\Scraper $scraper + * @psalm-param \BVP\Scraper\Scraper $scraper + * + * @param \BVP\Scraper\Scraper $scraper */ public function __construct(private readonly Scraper $scraper) { @@ -21,47 +25,11 @@ public function __construct(private readonly Scraper $scraper) } /** - * @psalm-type ScrapedBoat = array{ - * racer_boat_number: int, - * racer_name: string, - * racer_number: int, - * racer_class_number: int, - * racer_branch_number: int, - * racer_birthplace_number: int, - * racer_age: int, - * racer_weight: float, - * racer_flying_count: int, - * racer_late_count: int, - * racer_average_start_timing: float, - * racer_national_top_1_percent: float, - * racer_national_top_2_percent: float, - * racer_national_top_3_percent: float, - * racer_local_top_1_percent: float, - * racer_local_top_2_percent: float, - * racer_local_top_3_percent: float, - * racer_assigned_motor_number: int, - * racer_assigned_motor_top_2_percent: float, - * racer_assigned_motor_top_3_percent: float, - * racer_assigned_boat_number: int, - * racer_assigned_boat_top_2_percent: float, - * racer_assigned_boat_top_3_percent: float - * } - * @psalm-type ScrapedRace = array{ - * race_date: string, - * race_stadium_number: int, - * race_number: int, - * race_closed_at: string, - * race_grade_number: int, - * race_title: string, - * race_subtitle: string, - * race_distance: int, - * boats: array - * } - * @psalm-type ScrapedRaces = array - * @psalm-type ScrapedStadiumRaces = array + * @psalm-param \Carbon\CarbonInterface $date + * @psalm-return ScrapedStadiumRaces * - * @param \Carbon\CarbonInterface $date - * @return ScrapedStadiumRaces + * @param \Carbon\CarbonInterface $date + * @return array */ #[\Override] public function scrapePrograms(CarbonInterface $date): array diff --git a/src/ScraperInterface.php b/src/ScraperInterface.php index e58982b2..48703732 100644 --- a/src/ScraperInterface.php +++ b/src/ScraperInterface.php @@ -7,52 +7,55 @@ use Carbon\CarbonInterface; /** + * @psalm-type ScrapedBoat = array{ + * racer_boat_number: int, + * racer_name: string, + * racer_number: int, + * racer_class_number: int, + * racer_branch_number: int, + * racer_birthplace_number: int, + * racer_age: int, + * racer_weight: float, + * racer_flying_count: int, + * racer_late_count: int, + * racer_average_start_timing: float, + * racer_national_top_1_percent: float, + * racer_national_top_2_percent: float, + * racer_national_top_3_percent: float, + * racer_local_top_1_percent: float, + * racer_local_top_2_percent: float, + * racer_local_top_3_percent: float, + * racer_assigned_motor_number: int, + * racer_assigned_motor_top_2_percent: float, + * racer_assigned_motor_top_3_percent: float, + * racer_assigned_boat_number: int, + * racer_assigned_boat_top_2_percent: float, + * racer_assigned_boat_top_3_percent: float + * } + * @psalm-type ScrapedRace = array{ + * race_date: string, + * race_stadium_number: int, + * race_number: int, + * race_closed_at: string, + * race_grade_number: int, + * race_title: string, + * race_subtitle: string, + * race_distance: int, + * boats: array + * } + * @psalm-type ScrapedRaces = array + * @psalm-type ScrapedStadiumRaces = array + * * @author shimomo */ interface ScraperInterface { /** - * @psalm-type ScrapedBoat = array{ - * racer_boat_number: int, - * racer_name: string, - * racer_number: int, - * racer_class_number: int, - * racer_branch_number: int, - * racer_birthplace_number: int, - * racer_age: int, - * racer_weight: float, - * racer_flying_count: int, - * racer_late_count: int, - * racer_average_start_timing: float, - * racer_national_top_1_percent: float, - * racer_national_top_2_percent: float, - * racer_national_top_3_percent: float, - * racer_local_top_1_percent: float, - * racer_local_top_2_percent: float, - * racer_local_top_3_percent: float, - * racer_assigned_motor_number: int, - * racer_assigned_motor_top_2_percent: float, - * racer_assigned_motor_top_3_percent: float, - * racer_assigned_boat_number: int, - * racer_assigned_boat_top_2_percent: float, - * racer_assigned_boat_top_3_percent: float - * } - * @psalm-type ScrapedRace = array{ - * race_date: string, - * race_stadium_number: int, - * race_number: int, - * race_closed_at: string, - * race_grade_number: int, - * race_title: string, - * race_subtitle: string, - * race_distance: int, - * boats: array - * } - * @psalm-type ScrapedRaces = array - * @psalm-type ScrapedStadiumRaces = array + * @psalm-param \Carbon\CarbonInterface $date + * @psalm-return ScrapedStadiumRaces * - * @param \Carbon\CarbonInterface $date - * @return ScrapedStadiumRaces + * @param \Carbon\CarbonInterface $date + * @return array */ public function scrapePrograms(CarbonInterface $date): array; } diff --git a/tests/ProgramScraperTest.php b/tests/ProgramScraperTest.php index aa5e10b2..62f1f8fb 100644 --- a/tests/ProgramScraperTest.php +++ b/tests/ProgramScraperTest.php @@ -10,12 +10,15 @@ use PHPUnit\Framework\TestCase; /** + * @psalm-import-type ScrapedStadiumRaces from ScraperInterface + * * @author shimomo */ final class ProgramScraperTest extends Testcase { /** - * @param \Carbon\CarbonInterface|string $date + * @psalm-return void + * * @return void */ public function testScrape(): void @@ -32,48 +35,11 @@ public function testScrape(): void } /** - * @psalm-type NormalizedBoat array{ - * racer_boat_number: int, - * racer_name: string, - * racer_number: int, - * racer_class_number: int, - * racer_branch_number: int, - * racer_birthplace_number: int, - * racer_age: int, - * racer_weight: int|float, - * racer_flying_count: int, - * racer_late_count: int, - * racer_average_start_timing: float, - * racer_national_top_1_percent: float, - * racer_national_top_2_percent: float, - * racer_national_top_3_percent: float, - * racer_local_top_1_percent: float, - * racer_local_top_2_percent: float, - * racer_local_top_3_percent: float, - * racer_assigned_motor_number: int, - * racer_assigned_motor_top_2_percent: float, - * racer_assigned_motor_top_3_percent: float, - * racer_assigned_boat_number: int, - * racer_assigned_boat_top_2_percent: float, - * racer_assigned_boat_top_3_percent: float - * } - * - * @psalm-type NormalizedRace array{ - * race_date: string, - * race_stadium_number: int, - * race_number: int, - * race_closed_at: string, - * race_grade_number: int, - * race_title: string, - * race_subtitle: string, - * race_distance: int, - * boats: array - * } - * - * @psalm-type NormalizedRaces array + * @psalm-param int $keyIndex + * @psalm-return ScrapedStadiumRaces * - * @param int $keyIndex - * @return NormalizedRaces + * @param int $keyIndex + * @return array */ private function testScrapeData(int $keyIndex): array { diff --git a/tests/ProgramStorageTest.php b/tests/ProgramStorageTest.php index d4d321a1..1744a159 100644 --- a/tests/ProgramStorageTest.php +++ b/tests/ProgramStorageTest.php @@ -13,11 +13,15 @@ final class ProgramStorageTest extends TestCase { /** - * @var non-empty-string + * @psalm-var non-empty-string + * + * @var string */ private string $tempDir; /** + * @psalm-return void + * * @return void */ protected function setUp(): void @@ -28,6 +32,8 @@ protected function setUp(): void } /** + * @psalm-return void + * * @return void */ protected function tearDown(): void @@ -47,6 +53,8 @@ protected function tearDown(): void } /** + * @psalm-return void + * * @return void */ public function testSave(): void From 9d20c9131f2f06f4f0f927373af4172d9ff7f27d Mon Sep 17 00:00:00 2001 From: shimomo Date: Fri, 29 Aug 2025 21:41:23 +0900 Subject: [PATCH 2/2] refactor: remove unnecessary array casts --- src/ProgramScraper.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ProgramScraper.php b/src/ProgramScraper.php index e74000c9..b0b63f16 100644 --- a/src/ProgramScraper.php +++ b/src/ProgramScraper.php @@ -53,7 +53,7 @@ private function normalize(array $programs): array foreach (array_values($programs) as $data) { foreach (array_values($data) as $program) { $program['boats'] = isset($program['boats']) - ? array_values((array) $program['boats']) + ? array_values($program['boats']) : []; $newPrograms[] = $program; }