From 857da2a56ac6f66b2682fc5a1db8b3e166da324f Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 12 Nov 2024 13:44:40 +0100 Subject: [PATCH 01/18] refactor: differentiate between kilo/kibibytes and mega/mebibytes --- system/Files/File.php | 43 +++++++++++++-- system/Files/FileSizeUnit.php | 23 ++++++++ tests/system/Files/FileTest.php | 54 +++++++++++++++++++ user_guide_src/source/changelogs/v4.6.0.rst | 3 ++ user_guide_src/source/libraries/files.rst | 28 +++++++++- user_guide_src/source/libraries/files/017.php | 5 ++ user_guide_src/source/libraries/files/018.php | 5 ++ 7 files changed, 157 insertions(+), 4 deletions(-) create mode 100644 system/Files/FileSizeUnit.php create mode 100644 user_guide_src/source/libraries/files/017.php create mode 100644 user_guide_src/source/libraries/files/018.php diff --git a/system/Files/File.php b/system/Files/File.php index 15b53262e9c2..e36f24ac7529 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -70,17 +70,39 @@ public function getSize() return $this->size ?? ($this->size = parent::getSize()); } + /** + * Retrieve the file size by unit, calculated in IEC standards with 1024 as base value. + * + * @return false|int|string + */ + public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) + { + return $this->getSizeByUnitInternal(1024, $unit, $precision); + } + + /** + * Retrieve the file size by unit, calculated in metric standards with 1000 as base value. + * + * @return false|int|string + */ + public function getSizeByUnitMetric(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) + { + return $this->getSizeByUnitInternal(1000, $unit, $precision); + } + /** * Retrieve the file size by unit. * + * @deprecated Use getSizeByUnitBinary or getSizeByUnitMetric instead + * * @return false|int|string */ public function getSizeByUnit(string $unit = 'b') { return match (strtolower($unit)) { - 'kb' => number_format($this->getSize() / 1024, 3), - 'mb' => number_format(($this->getSize() / 1024) / 1024, 3), - default => $this->getSize(), + 'kb' => $this->getSizeByUnitBinary(FileSizeUnit::KB), + 'mb' => $this->getSizeByUnitBinary(FileSizeUnit::MB), + default => $this->getSizeByUnitBinary(FileSizeUnit::B) }; } @@ -189,4 +211,19 @@ public function getDestination(string $destination, string $delimiter = '_', int return $destination; } + + protected function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, int $precision) + { + $exponent = $unit->value; + $divider = pow($fileSizeBase, $exponent); + + $size = $this->getSize() / $divider; + + if($unit !== FileSizeUnit::B) + { + $size = number_format($size, $precision); + } + + return $size; + } } diff --git a/system/Files/FileSizeUnit.php b/system/Files/FileSizeUnit.php new file mode 100644 index 000000000000..8f30eeb00d8f --- /dev/null +++ b/system/Files/FileSizeUnit.php @@ -0,0 +1,23 @@ + + * + * For the full copyright and license information, please view + * the LICENSE file that was distributed with this source code. + */ + +namespace CodeIgniter\Files; + +enum FileSizeUnit : int +{ + case B = 0; + case KB = 1; + case MB = 2; + case GB = 3; + case TB = 4; +} \ No newline at end of file diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index 800a1ac278f1..9b608647a583 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -113,6 +113,42 @@ public function testGetSizeReturnsBytes(): void $this->assertSame($size, $file->getSizeByUnit('b')); } + /** + * @dataProvider provideGetSizeData + */ + public function testGetSizeBinary(FileSizeUnit $unit): void + { + $divider = pow(1024, $unit->value); + $file = new File(SYSTEMPATH . 'Common.php'); + $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); + $this->assertSame($size, $file->getSizeByUnitBinary($unit)); + } + + public function testGetSizeBinaryBytes(): void + { + $file = new File(SYSTEMPATH . 'Common.php'); + $size = filesize(SYSTEMPATH . 'Common.php'); + $this->assertSame($size, $file->getSizeByUnitBinary(FileSizeUnit::B)); + } + + /** + * @dataProvider provideGetSizeData + */ + public function testGetSizeMetric(FileSizeUnit $unit): void + { + $divider = pow(1000, $unit->value); + $file = new File(SYSTEMPATH . 'Common.php'); + $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); + $this->assertSame($size, $file->getSizeByUnitMetric($unit)); + } + + public function testGetSizeMetricBytes(): void + { + $file = new File(SYSTEMPATH . 'Common.php'); + $size = filesize(SYSTEMPATH . 'Common.php'); + $this->assertSame($size, $file->getSizeByUnitMetric(FileSizeUnit::B)); + } + public function testThrowsExceptionIfNotAFile(): void { $this->expectException(FileNotFoundException::class); @@ -135,4 +171,22 @@ public function testGetDestination(): void unlink(SYSTEMPATH . 'Common_Copy.php'); unlink(SYSTEMPATH . 'Common_Copy_5.php'); } + + public static function provideGetSizeData() + { + return [ + 'returns KB binary' => [ + FileSizeUnit::KB + ], + 'returns MB binary' => [ + FileSizeUnit::KB + ], + 'returns GB binary' => [ + FileSizeUnit::KB + ], + 'returns TB binary' => [ + FileSizeUnit::KB + ], + ]; + } } diff --git a/user_guide_src/source/changelogs/v4.6.0.rst b/user_guide_src/source/changelogs/v4.6.0.rst index d3dc4529d512..c1d2d59b36a2 100644 --- a/user_guide_src/source/changelogs/v4.6.0.rst +++ b/user_guide_src/source/changelogs/v4.6.0.rst @@ -277,6 +277,9 @@ Deprecations - The properties ``$arguments`` and ``$argumentsClass`` of ``Filters`` have been deprecated. No longer used. - The ``Filters::getArguments()`` method has been deprecated. No longer used. +- **File:** + - The function ``getSizeByUnit`` of ``File`` has been deprecated. + Use either ``getSizeByUnitBinary`` or ``getSizeByUnitMetric`` instead. ********** Bugs Fixed diff --git a/user_guide_src/source/libraries/files.rst b/user_guide_src/source/libraries/files.rst index 1622c3345c51..c171b5b047a1 100644 --- a/user_guide_src/source/libraries/files.rst +++ b/user_guide_src/source/libraries/files.rst @@ -56,14 +56,40 @@ A ``RuntimeException`` will be thrown if the file does not exist or an error occ getSizeByUnit() =============== +.. deprecated:: 4.6.0 + Returns the size of the file default in bytes. You can pass in either ``'kb'`` or ``'mb'`` as the first parameter to get -the results in kilobytes or megabytes, respectively: +the results in kibibytes or mebibytes, respectively: .. literalinclude:: files/005.php :lines: 2- A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. +getSizeByUnitBinary() +=============== + +Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get +the results in kibibytes, mebibytes etc. respectively. You can pass in a precision value as the second parameter to define +the amount of decimal places. + +.. literalinclude:: files/017.php + :lines: 2- + +A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. + +getSizeByUnitMetric() +=============== + +Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get +the results in kilobytes, megabytes etc. respectively. You can pass in a precision value as the second parameter to define +the amount of decimal places. + +.. literalinclude:: files/018.php + :lines: 2- + +A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. + getMimeType() ============= diff --git a/user_guide_src/source/libraries/files/017.php b/user_guide_src/source/libraries/files/017.php new file mode 100644 index 000000000000..f3cd9450af9c --- /dev/null +++ b/user_guide_src/source/libraries/files/017.php @@ -0,0 +1,5 @@ +getSizeByUnitBinary(); // 256901 +$kibibytes = $file->getSizeByUnitBinary(FileSizeUnit::KB); // 250.880 +$mebibytes = $file->getSizeByUnitBinary(FileSizeUnit::MB); // 0.245 diff --git a/user_guide_src/source/libraries/files/018.php b/user_guide_src/source/libraries/files/018.php new file mode 100644 index 000000000000..89138f8dbc04 --- /dev/null +++ b/user_guide_src/source/libraries/files/018.php @@ -0,0 +1,5 @@ +getSizeByUnitMetric(); // 256901 +$kilobytes = $file->getSizeByUnitMetric(FileSizeUnit::KB); // 256.901 +$megabytes = $file->getSizeByUnitMetric(FileSizeUnit::MB); // 0.256 From 34b3cfd86cee51c939f73a0082018044fc211e3b Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 10:50:39 +0100 Subject: [PATCH 02/18] add missing param declarations --- system/Files/File.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/system/Files/File.php b/system/Files/File.php index e36f24ac7529..e3b41767a989 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -73,6 +73,8 @@ public function getSize() /** * Retrieve the file size by unit, calculated in IEC standards with 1024 as base value. * + * @param FileSizeUnit $unit + * @phpstan-param positive-int $precision * @return false|int|string */ public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) @@ -83,6 +85,8 @@ public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $p /** * Retrieve the file size by unit, calculated in metric standards with 1000 as base value. * + * @param FileSizeUnit $unit + * @phpstan-param positive-int $precision * @return false|int|string */ public function getSizeByUnitMetric(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) From 0f32963f6f9b649921a84a9cf00e80dd129ca243 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 10:58:40 +0100 Subject: [PATCH 03/18] add missing return type declarations --- system/Files/File.php | 3 +++ tests/system/Files/FileTest.php | 3 +++ 2 files changed, 6 insertions(+) diff --git a/system/Files/File.php b/system/Files/File.php index e3b41767a989..598901a02ad2 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -216,6 +216,9 @@ public function getDestination(string $destination, string $delimiter = '_', int return $destination; } + /** + * @return false|int|string + */ protected function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, int $precision) { $exponent = $unit->value; diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index 9b608647a583..a359d4996ed9 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -172,6 +172,9 @@ public function testGetDestination(): void unlink(SYSTEMPATH . 'Common_Copy_5.php'); } + /** + * @return Array> + */ public static function provideGetSizeData() { return [ From 8296dc3796d4f558c10a4e920f77c12221f0fe61 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 11:02:25 +0100 Subject: [PATCH 04/18] add missing use statements --- user_guide_src/source/libraries/files.rst | 4 ++-- user_guide_src/source/libraries/files/017.php | 1 + user_guide_src/source/libraries/files/018.php | 1 + 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/libraries/files.rst b/user_guide_src/source/libraries/files.rst index c171b5b047a1..8c88ba01c647 100644 --- a/user_guide_src/source/libraries/files.rst +++ b/user_guide_src/source/libraries/files.rst @@ -74,7 +74,7 @@ the results in kibibytes, mebibytes etc. respectively. You can pass in a precisi the amount of decimal places. .. literalinclude:: files/017.php - :lines: 2- + :lines: 3- A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. @@ -86,7 +86,7 @@ the results in kilobytes, megabytes etc. respectively. You can pass in a precisi the amount of decimal places. .. literalinclude:: files/018.php - :lines: 2- + :lines: 3- A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. diff --git a/user_guide_src/source/libraries/files/017.php b/user_guide_src/source/libraries/files/017.php index f3cd9450af9c..ab917a1eb133 100644 --- a/user_guide_src/source/libraries/files/017.php +++ b/user_guide_src/source/libraries/files/017.php @@ -1,4 +1,5 @@ getSizeByUnitBinary(); // 256901 $kibibytes = $file->getSizeByUnitBinary(FileSizeUnit::KB); // 250.880 diff --git a/user_guide_src/source/libraries/files/018.php b/user_guide_src/source/libraries/files/018.php index 89138f8dbc04..d4926e1d52ac 100644 --- a/user_guide_src/source/libraries/files/018.php +++ b/user_guide_src/source/libraries/files/018.php @@ -1,4 +1,5 @@ getSizeByUnitMetric(); // 256901 $kilobytes = $file->getSizeByUnitMetric(FileSizeUnit::KB); // 256.901 From 5282aa33da838e2e186d1e646daef7cc3b9b409c Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 11:05:26 +0100 Subject: [PATCH 05/18] replace pow with expression --- system/Files/File.php | 2 +- tests/system/Files/FileTest.php | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/system/Files/File.php b/system/Files/File.php index 598901a02ad2..93710e72ffc5 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -222,7 +222,7 @@ public function getDestination(string $destination, string $delimiter = '_', int protected function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, int $precision) { $exponent = $unit->value; - $divider = pow($fileSizeBase, $exponent); + $divider = $fileSizeBase ** $exponent; $size = $this->getSize() / $divider; diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index a359d4996ed9..464b625189c7 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -118,7 +118,7 @@ public function testGetSizeReturnsBytes(): void */ public function testGetSizeBinary(FileSizeUnit $unit): void { - $divider = pow(1024, $unit->value); + $divider = 1024 ** $unit->value; $file = new File(SYSTEMPATH . 'Common.php'); $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); $this->assertSame($size, $file->getSizeByUnitBinary($unit)); @@ -136,7 +136,7 @@ public function testGetSizeBinaryBytes(): void */ public function testGetSizeMetric(FileSizeUnit $unit): void { - $divider = pow(1000, $unit->value); + $divider = 1000 ** $unit->value; $file = new File(SYSTEMPATH . 'Common.php'); $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); $this->assertSame($size, $file->getSizeByUnitMetric($unit)); From 40a867fb2f36f3c1fca250da5ccb4d2637069cdb Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 11:08:12 +0100 Subject: [PATCH 06/18] add missing underline chars --- user_guide_src/source/libraries/files.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/libraries/files.rst b/user_guide_src/source/libraries/files.rst index 8c88ba01c647..f6c0f4a20a95 100644 --- a/user_guide_src/source/libraries/files.rst +++ b/user_guide_src/source/libraries/files.rst @@ -67,7 +67,7 @@ the results in kibibytes or mebibytes, respectively: A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. getSizeByUnitBinary() -=============== +===================== Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get the results in kibibytes, mebibytes etc. respectively. You can pass in a precision value as the second parameter to define @@ -79,7 +79,7 @@ the amount of decimal places. A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. getSizeByUnitMetric() -=============== +===================== Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get the results in kilobytes, megabytes etc. respectively. You can pass in a precision value as the second parameter to define From 0e4f24035e61733ca7f9a127ff8100d404f399c8 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 11:09:41 +0100 Subject: [PATCH 07/18] add missing blank line --- user_guide_src/source/libraries/files.rst | 4 ++-- user_guide_src/source/libraries/files/017.php | 1 + user_guide_src/source/libraries/files/018.php | 1 + 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/libraries/files.rst b/user_guide_src/source/libraries/files.rst index f6c0f4a20a95..95cd97b33d37 100644 --- a/user_guide_src/source/libraries/files.rst +++ b/user_guide_src/source/libraries/files.rst @@ -74,7 +74,7 @@ the results in kibibytes, mebibytes etc. respectively. You can pass in a precisi the amount of decimal places. .. literalinclude:: files/017.php - :lines: 3- + :lines: 4- A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. @@ -86,7 +86,7 @@ the results in kilobytes, megabytes etc. respectively. You can pass in a precisi the amount of decimal places. .. literalinclude:: files/018.php - :lines: 3- + :lines: 4- A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. diff --git a/user_guide_src/source/libraries/files/017.php b/user_guide_src/source/libraries/files/017.php index ab917a1eb133..f99a1de87fba 100644 --- a/user_guide_src/source/libraries/files/017.php +++ b/user_guide_src/source/libraries/files/017.php @@ -1,4 +1,5 @@ getSizeByUnitBinary(); // 256901 diff --git a/user_guide_src/source/libraries/files/018.php b/user_guide_src/source/libraries/files/018.php index d4926e1d52ac..dbc13a397e8f 100644 --- a/user_guide_src/source/libraries/files/018.php +++ b/user_guide_src/source/libraries/files/018.php @@ -1,4 +1,5 @@ getSizeByUnitMetric(); // 256901 From 3ad691a035b7790daf49a242ffa78cb6022e99a4 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 11:18:45 +0100 Subject: [PATCH 08/18] fix github actions --- tests/system/Files/FileTest.php | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index 464b625189c7..80a7ebfc6455 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -113,9 +113,7 @@ public function testGetSizeReturnsBytes(): void $this->assertSame($size, $file->getSizeByUnit('b')); } - /** - * @dataProvider provideGetSizeData - */ + #[\PHPUnit\Framework\Attributes\DataProvider('provideGetSizeData')] public function testGetSizeBinary(FileSizeUnit $unit): void { $divider = 1024 ** $unit->value; @@ -131,9 +129,7 @@ public function testGetSizeBinaryBytes(): void $this->assertSame($size, $file->getSizeByUnitBinary(FileSizeUnit::B)); } - /** - * @dataProvider provideGetSizeData - */ + #[\PHPUnit\Framework\Attributes\DataProvider('provideGetSizeData')] public function testGetSizeMetric(FileSizeUnit $unit): void { $divider = 1000 ** $unit->value; @@ -173,22 +169,22 @@ public function testGetDestination(): void } /** - * @return Array> + * @return @return array> */ - public static function provideGetSizeData() + public static function provideGetSizeData(): iterable { return [ 'returns KB binary' => [ - FileSizeUnit::KB + FileSizeUnit::KB, ], 'returns MB binary' => [ - FileSizeUnit::KB + FileSizeUnit::MB, ], 'returns GB binary' => [ - FileSizeUnit::KB + FileSizeUnit::GB, ], 'returns TB binary' => [ - FileSizeUnit::KB + FileSizeUnit::TB, ], ]; } From a9862ec80f44625e4708ae5763aef7ba2c579427 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 12:02:47 +0100 Subject: [PATCH 09/18] fix failing jobs --- tests/system/Files/FileTest.php | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index 80a7ebfc6455..15ac0d52f4f5 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -15,6 +15,7 @@ use CodeIgniter\Files\Exceptions\FileNotFoundException; use CodeIgniter\Test\CIUnitTestCase; +use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\Attributes\Group; use ZipArchive; @@ -113,12 +114,12 @@ public function testGetSizeReturnsBytes(): void $this->assertSame($size, $file->getSizeByUnit('b')); } - #[\PHPUnit\Framework\Attributes\DataProvider('provideGetSizeData')] + #[DataProvider('provideGetSizeData')] public function testGetSizeBinary(FileSizeUnit $unit): void { $divider = 1024 ** $unit->value; - $file = new File(SYSTEMPATH . 'Common.php'); - $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); + $file = new File(SYSTEMPATH . 'Common.php'); + $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); $this->assertSame($size, $file->getSizeByUnitBinary($unit)); } @@ -129,12 +130,12 @@ public function testGetSizeBinaryBytes(): void $this->assertSame($size, $file->getSizeByUnitBinary(FileSizeUnit::B)); } - #[\PHPUnit\Framework\Attributes\DataProvider('provideGetSizeData')] + #[DataProvider('provideGetSizeData')] public function testGetSizeMetric(FileSizeUnit $unit): void { $divider = 1000 ** $unit->value; - $file = new File(SYSTEMPATH . 'Common.php'); - $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); + $file = new File(SYSTEMPATH . 'Common.php'); + $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); $this->assertSame($size, $file->getSizeByUnitMetric($unit)); } @@ -169,9 +170,9 @@ public function testGetDestination(): void } /** - * @return @return array> + * @return array> */ - public static function provideGetSizeData(): iterable + public static function provideGetSizeData() { return [ 'returns KB binary' => [ From a186c0fced8f8053094e5b3f140c6cc373e8db5d Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 12:30:58 +0100 Subject: [PATCH 10/18] fix failing jobs --- system/Files/File.php | 10 +++------- system/Files/FileSizeUnit.php | 4 ++-- tests/system/Files/FileTest.php | 2 +- 3 files changed, 6 insertions(+), 10 deletions(-) diff --git a/system/Files/File.php b/system/Files/File.php index 93710e72ffc5..4c1757a6b538 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -73,7 +73,6 @@ public function getSize() /** * Retrieve the file size by unit, calculated in IEC standards with 1024 as base value. * - * @param FileSizeUnit $unit * @phpstan-param positive-int $precision * @return false|int|string */ @@ -85,7 +84,6 @@ public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $p /** * Retrieve the file size by unit, calculated in metric standards with 1000 as base value. * - * @param FileSizeUnit $unit * @phpstan-param positive-int $precision * @return false|int|string */ @@ -222,12 +220,10 @@ public function getDestination(string $destination, string $delimiter = '_', int protected function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, int $precision) { $exponent = $unit->value; - $divider = $fileSizeBase ** $exponent; + $divider = $fileSizeBase ** $exponent; + $size = $this->getSize() / $divider; - $size = $this->getSize() / $divider; - - if($unit !== FileSizeUnit::B) - { + if($unit !== FileSizeUnit::B) { $size = number_format($size, $precision); } diff --git a/system/Files/FileSizeUnit.php b/system/Files/FileSizeUnit.php index 8f30eeb00d8f..4098e3a3e2bb 100644 --- a/system/Files/FileSizeUnit.php +++ b/system/Files/FileSizeUnit.php @@ -13,11 +13,11 @@ namespace CodeIgniter\Files; -enum FileSizeUnit : int +enum FileSizeUnit: int { case B = 0; case KB = 1; case MB = 2; case GB = 3; case TB = 4; -} \ No newline at end of file +} diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index 15ac0d52f4f5..c8a15fce29af 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -170,7 +170,7 @@ public function testGetDestination(): void } /** - * @return array> + * @return array> */ public static function provideGetSizeData() { From c7f21b1838344447a1a20b48565114ba673ece92 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Mon, 18 Nov 2024 12:52:21 +0100 Subject: [PATCH 11/18] fix failing jobs --- system/Files/File.php | 4 +++- tests/system/Files/FileTest.php | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/system/Files/File.php b/system/Files/File.php index 4c1757a6b538..6a2529cac149 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -74,6 +74,7 @@ public function getSize() * Retrieve the file size by unit, calculated in IEC standards with 1024 as base value. * * @phpstan-param positive-int $precision + * * @return false|int|string */ public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) @@ -85,6 +86,7 @@ public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $p * Retrieve the file size by unit, calculated in metric standards with 1000 as base value. * * @phpstan-param positive-int $precision + * * @return false|int|string */ public function getSizeByUnitMetric(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) @@ -223,7 +225,7 @@ protected function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, $divider = $fileSizeBase ** $exponent; $size = $this->getSize() / $divider; - if($unit !== FileSizeUnit::B) { + if ($unit !== FileSizeUnit::B) { $size = number_format($size, $precision); } diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index c8a15fce29af..e0105fb011a1 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -170,7 +170,7 @@ public function testGetDestination(): void } /** - * @return array> + * @return array> */ public static function provideGetSizeData() { From bf9a9a8b67902a71facb150724725cd1272962d0 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 19 Nov 2024 10:15:41 +0100 Subject: [PATCH 12/18] Update user_guide_src/source/changelogs/v4.6.0.rst Co-authored-by: kenjis --- user_guide_src/source/changelogs/v4.6.0.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/changelogs/v4.6.0.rst b/user_guide_src/source/changelogs/v4.6.0.rst index c1d2d59b36a2..d22346da6799 100644 --- a/user_guide_src/source/changelogs/v4.6.0.rst +++ b/user_guide_src/source/changelogs/v4.6.0.rst @@ -278,8 +278,8 @@ Deprecations been deprecated. No longer used. - The ``Filters::getArguments()`` method has been deprecated. No longer used. - **File:** - - The function ``getSizeByUnit`` of ``File`` has been deprecated. - Use either ``getSizeByUnitBinary`` or ``getSizeByUnitMetric`` instead. + - The function ``getSizeByUnit()`` of ``File`` has been deprecated. + Use either ``getSizeByUnitBinary()`` or ``getSizeByUnitMetric()`` instead. ********** Bugs Fixed From 8829ea8befea71c8da10242d55b72872751c82e4 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 19 Nov 2024 15:50:54 +0100 Subject: [PATCH 13/18] allow FileSizeUnit selection from String Co-authored-by: Michal Sniatala --- system/Files/FileSizeUnit.php | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/system/Files/FileSizeUnit.php b/system/Files/FileSizeUnit.php index 4098e3a3e2bb..49dac2cebf25 100644 --- a/system/Files/FileSizeUnit.php +++ b/system/Files/FileSizeUnit.php @@ -20,4 +20,16 @@ enum FileSizeUnit: int case MB = 2; case GB = 3; case TB = 4; + + public static function fromString(string $unit): self + { + return match (strtolower($unit)) { + 'b' => self::B, + 'kb' => self::KB, + 'mb' => self::MB, + 'gb' => self::GB, + 'tb' => self::TB, + default => throw new InvalidArgumentException("Invalid unit: $unit"), + }; + } } From 3767b29862a1721832b266e9b8560d0c74b62651 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 19 Nov 2024 15:52:06 +0100 Subject: [PATCH 14/18] revert refactoring of fallback call Co-authored-by: Michal Sniatala --- system/Files/File.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system/Files/File.php b/system/Files/File.php index 6a2529cac149..7c0b536e557c 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -106,7 +106,7 @@ public function getSizeByUnit(string $unit = 'b') return match (strtolower($unit)) { 'kb' => $this->getSizeByUnitBinary(FileSizeUnit::KB), 'mb' => $this->getSizeByUnitBinary(FileSizeUnit::MB), - default => $this->getSizeByUnitBinary(FileSizeUnit::B) + default => $this->getSize() }; } From f1464e31f0478e60ed37fd73a5c27afc82d888fe Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 19 Nov 2024 15:52:57 +0100 Subject: [PATCH 15/18] substantiate deprecation message Co-authored-by: Michal Sniatala --- system/Files/File.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system/Files/File.php b/system/Files/File.php index 7c0b536e557c..2f3e0fb2c393 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -97,7 +97,7 @@ public function getSizeByUnitMetric(FileSizeUnit $unit = FileSizeUnit::B, int $p /** * Retrieve the file size by unit. * - * @deprecated Use getSizeByUnitBinary or getSizeByUnitMetric instead + * @deprecated 4.6.0 Use getSizeByUnitBinary() or getSizeByUnitMetric() instead * * @return false|int|string */ From 066c03d1175569a58afdbf1853529226233c2094 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 19 Nov 2024 16:13:49 +0100 Subject: [PATCH 16/18] refactor FileSizeUnit enum * reorder cases and function * add DocBlock for return and throws --- system/Files/FileSizeUnit.php | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/system/Files/FileSizeUnit.php b/system/Files/FileSizeUnit.php index 49dac2cebf25..581582689f05 100644 --- a/system/Files/FileSizeUnit.php +++ b/system/Files/FileSizeUnit.php @@ -13,23 +13,30 @@ namespace CodeIgniter\Files; +use InvalidArgumentException; + enum FileSizeUnit: int { - case B = 0; - case KB = 1; - case MB = 2; - case GB = 3; - case TB = 4; - + /** + * Allows the creation of a FileSizeUnit from Strings like "kb" or "mb" + * + * @throws InvalidArgumentException + */ public static function fromString(string $unit): self { return match (strtolower($unit)) { - 'b' => self::B, - 'kb' => self::KB, - 'mb' => self::MB, - 'gb' => self::GB, - 'tb' => self::TB, - default => throw new InvalidArgumentException("Invalid unit: $unit"), + 'b' => self::B, + 'kb' => self::KB, + 'mb' => self::MB, + 'gb' => self::GB, + 'tb' => self::TB, + default => throw new InvalidArgumentException("Invalid unit: {$unit}"), }; } + + case B = 0; + case KB = 1; + case MB = 2; + case GB = 3; + case TB = 4; } From 5bb217028c46b9b1f819b58c5243ad02ec99dbb3 Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Wed, 20 Nov 2024 00:21:42 +0100 Subject: [PATCH 17/18] method names, visibility, return types --- system/Files/File.php | 19 ++++++------------- tests/system/Files/FileTest.php | 8 ++++---- user_guide_src/source/changelogs/v4.6.0.rst | 2 +- user_guide_src/source/libraries/files.rst | 4 ++-- user_guide_src/source/libraries/files/017.php | 6 +++--- user_guide_src/source/libraries/files/018.php | 6 +++--- 6 files changed, 19 insertions(+), 26 deletions(-) diff --git a/system/Files/File.php b/system/Files/File.php index 2f3e0fb2c393..1b9aefbb6694 100644 --- a/system/Files/File.php +++ b/system/Files/File.php @@ -74,10 +74,8 @@ public function getSize() * Retrieve the file size by unit, calculated in IEC standards with 1024 as base value. * * @phpstan-param positive-int $precision - * - * @return false|int|string */ - public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) + public function getSizeByBinaryUnit(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3): int|string { return $this->getSizeByUnitInternal(1024, $unit, $precision); } @@ -86,10 +84,8 @@ public function getSizeByUnitBinary(FileSizeUnit $unit = FileSizeUnit::B, int $p * Retrieve the file size by unit, calculated in metric standards with 1000 as base value. * * @phpstan-param positive-int $precision - * - * @return false|int|string */ - public function getSizeByUnitMetric(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3) + public function getSizeByMetricUnit(FileSizeUnit $unit = FileSizeUnit::B, int $precision = 3): int|string { return $this->getSizeByUnitInternal(1000, $unit, $precision); } @@ -97,15 +93,15 @@ public function getSizeByUnitMetric(FileSizeUnit $unit = FileSizeUnit::B, int $p /** * Retrieve the file size by unit. * - * @deprecated 4.6.0 Use getSizeByUnitBinary() or getSizeByUnitMetric() instead + * @deprecated 4.6.0 Use getSizeByBinaryUnit() or getSizeByMetricUnit() instead * * @return false|int|string */ public function getSizeByUnit(string $unit = 'b') { return match (strtolower($unit)) { - 'kb' => $this->getSizeByUnitBinary(FileSizeUnit::KB), - 'mb' => $this->getSizeByUnitBinary(FileSizeUnit::MB), + 'kb' => $this->getSizeByBinaryUnit(FileSizeUnit::KB), + 'mb' => $this->getSizeByBinaryUnit(FileSizeUnit::MB), default => $this->getSize() }; } @@ -216,10 +212,7 @@ public function getDestination(string $destination, string $delimiter = '_', int return $destination; } - /** - * @return false|int|string - */ - protected function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, int $precision) + private function getSizeByUnitInternal(int $fileSizeBase, FileSizeUnit $unit, int $precision): int|string { $exponent = $unit->value; $divider = $fileSizeBase ** $exponent; diff --git a/tests/system/Files/FileTest.php b/tests/system/Files/FileTest.php index e0105fb011a1..b8e82edd02fd 100644 --- a/tests/system/Files/FileTest.php +++ b/tests/system/Files/FileTest.php @@ -120,14 +120,14 @@ public function testGetSizeBinary(FileSizeUnit $unit): void $divider = 1024 ** $unit->value; $file = new File(SYSTEMPATH . 'Common.php'); $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); - $this->assertSame($size, $file->getSizeByUnitBinary($unit)); + $this->assertSame($size, $file->getSizeByBinaryUnit($unit)); } public function testGetSizeBinaryBytes(): void { $file = new File(SYSTEMPATH . 'Common.php'); $size = filesize(SYSTEMPATH . 'Common.php'); - $this->assertSame($size, $file->getSizeByUnitBinary(FileSizeUnit::B)); + $this->assertSame($size, $file->getSizeByBinaryUnit(FileSizeUnit::B)); } #[DataProvider('provideGetSizeData')] @@ -136,14 +136,14 @@ public function testGetSizeMetric(FileSizeUnit $unit): void $divider = 1000 ** $unit->value; $file = new File(SYSTEMPATH . 'Common.php'); $size = number_format(filesize(SYSTEMPATH . 'Common.php') / $divider, 3); - $this->assertSame($size, $file->getSizeByUnitMetric($unit)); + $this->assertSame($size, $file->getSizeByMetricUnit($unit)); } public function testGetSizeMetricBytes(): void { $file = new File(SYSTEMPATH . 'Common.php'); $size = filesize(SYSTEMPATH . 'Common.php'); - $this->assertSame($size, $file->getSizeByUnitMetric(FileSizeUnit::B)); + $this->assertSame($size, $file->getSizeByMetricUnit(FileSizeUnit::B)); } public function testThrowsExceptionIfNotAFile(): void diff --git a/user_guide_src/source/changelogs/v4.6.0.rst b/user_guide_src/source/changelogs/v4.6.0.rst index d22346da6799..1dfee3dcd107 100644 --- a/user_guide_src/source/changelogs/v4.6.0.rst +++ b/user_guide_src/source/changelogs/v4.6.0.rst @@ -279,7 +279,7 @@ Deprecations - The ``Filters::getArguments()`` method has been deprecated. No longer used. - **File:** - The function ``getSizeByUnit()`` of ``File`` has been deprecated. - Use either ``getSizeByUnitBinary()`` or ``getSizeByUnitMetric()`` instead. + Use either ``getSizeByBinaryUnit()`` or ``getSizeByMetricUnit()`` instead. ********** Bugs Fixed diff --git a/user_guide_src/source/libraries/files.rst b/user_guide_src/source/libraries/files.rst index 95cd97b33d37..3c1dd6ae2376 100644 --- a/user_guide_src/source/libraries/files.rst +++ b/user_guide_src/source/libraries/files.rst @@ -66,7 +66,7 @@ the results in kibibytes or mebibytes, respectively: A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. -getSizeByUnitBinary() +getSizeByBinaryUnit() ===================== Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get @@ -78,7 +78,7 @@ the amount of decimal places. A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. -getSizeByUnitMetric() +getSizeByMetricUnit() ===================== Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get diff --git a/user_guide_src/source/libraries/files/017.php b/user_guide_src/source/libraries/files/017.php index f99a1de87fba..ad4d89476180 100644 --- a/user_guide_src/source/libraries/files/017.php +++ b/user_guide_src/source/libraries/files/017.php @@ -2,6 +2,6 @@ use CodeIgniter\Files\FileSizeUnit; -$bytes = $file->getSizeByUnitBinary(); // 256901 -$kibibytes = $file->getSizeByUnitBinary(FileSizeUnit::KB); // 250.880 -$mebibytes = $file->getSizeByUnitBinary(FileSizeUnit::MB); // 0.245 +$bytes = $file->getSizeByBinaryUnit(); // 256901 +$kibibytes = $file->getSizeByBinaryUnit(FileSizeUnit::KB); // 250.880 +$mebibytes = $file->getSizeByBinaryUnit(FileSizeUnit::MB); // 0.245 diff --git a/user_guide_src/source/libraries/files/018.php b/user_guide_src/source/libraries/files/018.php index dbc13a397e8f..07521b4bbe1c 100644 --- a/user_guide_src/source/libraries/files/018.php +++ b/user_guide_src/source/libraries/files/018.php @@ -2,6 +2,6 @@ use CodeIgniter\Files\FileSizeUnit; -$bytes = $file->getSizeByUnitMetric(); // 256901 -$kilobytes = $file->getSizeByUnitMetric(FileSizeUnit::KB); // 256.901 -$megabytes = $file->getSizeByUnitMetric(FileSizeUnit::MB); // 0.256 +$bytes = $file->getSizeByMetricUnit(); // 256901 +$kilobytes = $file->getSizeByMetricUnit(FileSizeUnit::KB); // 256.901 +$megabytes = $file->getSizeByMetricUnit(FileSizeUnit::MB); // 0.256 From 9a3aacb906480f5db3dd9847789e234948950dac Mon Sep 17 00:00:00 2001 From: Thomas Meschke Date: Tue, 26 Nov 2024 10:04:10 +0100 Subject: [PATCH 18/18] reorder enum fields, add user guide information --- system/Files/FileSizeUnit.php | 14 +++++++------- user_guide_src/source/changelogs/v4.6.0.rst | 2 ++ user_guide_src/source/libraries/files.rst | 10 ++++++++++ 3 files changed, 19 insertions(+), 7 deletions(-) diff --git a/system/Files/FileSizeUnit.php b/system/Files/FileSizeUnit.php index 581582689f05..84c2ba44ca13 100644 --- a/system/Files/FileSizeUnit.php +++ b/system/Files/FileSizeUnit.php @@ -13,10 +13,16 @@ namespace CodeIgniter\Files; -use InvalidArgumentException; +use CodeIgniter\Exceptions\InvalidArgumentException; enum FileSizeUnit: int { + case B = 0; + case KB = 1; + case MB = 2; + case GB = 3; + case TB = 4; + /** * Allows the creation of a FileSizeUnit from Strings like "kb" or "mb" * @@ -33,10 +39,4 @@ public static function fromString(string $unit): self default => throw new InvalidArgumentException("Invalid unit: {$unit}"), }; } - - case B = 0; - case KB = 1; - case MB = 2; - case GB = 3; - case TB = 4; } diff --git a/user_guide_src/source/changelogs/v4.6.0.rst b/user_guide_src/source/changelogs/v4.6.0.rst index 1dfee3dcd107..e68f60a0d4c4 100644 --- a/user_guide_src/source/changelogs/v4.6.0.rst +++ b/user_guide_src/source/changelogs/v4.6.0.rst @@ -215,6 +215,8 @@ Model Libraries ========= +- **File:** Added ``getSizeByBinaryUnit()`` and ``getSizeByMetricUnit()`` to ``File`` class. + See :ref:`File::getSizeByBinaryUnit() ` and :ref:`File::getSizeByMetricUnit() `. - **FileCollection:** Added ``retainMultiplePatterns()`` to ``FileCollection`` class. See :ref:`FileCollection::retainMultiplePatterns() `. - **Validation:** Added ``min_dims`` validation rule to ``FileRules`` class. See diff --git a/user_guide_src/source/libraries/files.rst b/user_guide_src/source/libraries/files.rst index 3c1dd6ae2376..df9f2f4b89dc 100644 --- a/user_guide_src/source/libraries/files.rst +++ b/user_guide_src/source/libraries/files.rst @@ -66,9 +66,14 @@ the results in kibibytes or mebibytes, respectively: A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. + +.. _file-get-size-by-binary-unit: + getSizeByBinaryUnit() ===================== +.. versionadded:: 4.6.0 + Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get the results in kibibytes, mebibytes etc. respectively. You can pass in a precision value as the second parameter to define the amount of decimal places. @@ -78,9 +83,14 @@ the amount of decimal places. A ``RuntimeException`` will be thrown if the file does not exist or an error occurs. + +.. _file-get-size-by-metric-unit: + getSizeByMetricUnit() ===================== +.. versionadded:: 4.6.0 + Returns the size of the file default in bytes. You can pass in different FileSizeUnit values as the first parameter to get the results in kilobytes, megabytes etc. respectively. You can pass in a precision value as the second parameter to define the amount of decimal places.