From d509f3dbdee118f6a21df96eb30a9afdd29289c5 Mon Sep 17 00:00:00 2001 From: Joachim Rey Date: Mon, 9 Feb 2026 22:30:18 +0100 Subject: [PATCH 1/5] Update Number::toReadableSize() to new specifications --- docs/en/core-libraries/number.md | 55 ++++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/docs/en/core-libraries/number.md b/docs/en/core-libraries/number.md index 3c1a774628..fa028b39cf 100644 --- a/docs/en/core-libraries/number.md +++ b/docs/en/core-libraries/number.md @@ -166,28 +166,55 @@ echo Number::toPercentage(0.45691, 1, [ ### Number::toReadableSize() -`method` Cake\\I18n\\Number::**toReadableSize**(string $size): string +`method` Cake\\I18n\\Number::**toReadableSize**(mixed $size, ?bool $useIecUnits = null): string -This method formats data sizes in human readable forms. It provides -a shortcut way to convert bytes to KB, MB, GB, and TB. The size is -displayed with a two-digit precision level, according to the size -of data supplied (i.e. higher sizes are expressed in larger -terms): +This method formats data sizes in human-readable forms. By default, it +converts bytes to KB, MB, GB, and TB. The parameter `$useIecUnits` and +the global setter `setUseIecUnits()` can be used to switch to ISO/IEC 80000-13 +units, which are KiB, MiB, GiB, and TiB. The size is displayed with a two-digit +precision level, according to the amount of data supplied (i.e., higher sizes +are expressed in larger terms): ```php +// By default, decimal units are used // Called as NumberHelper -echo $this->Number->toReadableSize(0); // 0 Byte -echo $this->Number->toReadableSize(1024); // 1 KB -echo $this->Number->toReadableSize(1321205.76); // 1.26 MB -echo $this->Number->toReadableSize(5368709120); // 5 GB +echo $this->Number->toReadableSize(0); // 0 Bytes +echo $this->Number->toReadableSize(1024); // 1.02 KB +echo $this->Number->toReadableSize(1321205.76); // 1.32 MB +echo $this->Number->toReadableSize(5368709120); // 5.37 GB // Called as Number -echo Number::toReadableSize(0); // 0 Byte -echo Number::toReadableSize(1024); // 1 KB -echo Number::toReadableSize(1321205.76); // 1.26 MB -echo Number::toReadableSize(5368709120); // 5 GB +echo Number::toReadableSize(0); // 0 Bytes +echo Number::toReadableSize(1024); // 1.02 KB +echo Number::toReadableSize(1321205.76); // 1.32 MB +echo Number::toReadableSize(5368709120); // 5.37 GB + +// Change default units to IEC units +$this->Number->setUseIecUnits(true); + +// Bytes are now calculated with exponents of two using IEC units +echo $this->Number->toReadableSize(0); // 0 Bytes +echo $this->Number->toReadableSize(1024); // 1 KiB +echo $this->Number->toReadableSize(1321205.76); // 1.26 MiB +echo $this->Number->toReadableSize(5368709120); // 5 GiB ``` +It should be noted that IEC units are exponents of two and decimal units of ten. +This mean that: +- 1000 Bytes = 1 KB +- 1024 Bytes = 1 KiB + +## Setting the Default Byte Units + +### Number::setUseIecUnits() + +`static` Cake\\I18n\\Number::**setUseIecUnits**(bool $useIec): void + +This method acts as a setter for the default byte units. It eliminates the +need to pass the boolean parameter to `Cake\I18n\Number::toReadableSize()` when +switching between decimal units and IEC units. If `$useIec` is defined as true, +IEC units will be employed; otherwise, decimal units will be used. + ## Formatting Numbers ### Number::format() From 9609025faa88f27e5b35a5499972f01cffbec516 Mon Sep 17 00:00:00 2001 From: Joachim Rey Date: Mon, 9 Feb 2026 22:31:56 +0100 Subject: [PATCH 2/5] Add Number::toReadableSize() changes to migration guide --- docs/en/appendices/5-4-migration-guide.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/en/appendices/5-4-migration-guide.md b/docs/en/appendices/5-4-migration-guide.md index 562d3d79ff..eaae49673d 100644 --- a/docs/en/appendices/5-4-migration-guide.md +++ b/docs/en/appendices/5-4-migration-guide.md @@ -14,6 +14,15 @@ automating some of the migration work. Run rector before updating your bin/cake upgrade rector --rules cakephp54 ``` +## Breaking Changes + +- `Number::toReadableSize()` now calculates decimal units (KB, MB, GB and TB) +using an exponent of ten, meaning that 1 KB is 1000 Bytes. The units from the +previous calculation method, where 1024 Bytes equaled 1 KB, have been changed +to KiB, MiB, GiB, and TiB as defined in ISO/IEC 80000-13. It is possible to +switch between the two units using a new optional boolean parameter in +`Number::toReadableSize()`, as well as the new global setter `Number::setUseIecUnits()`. + ## Behavior Changes - WIP From 8db09bb0da2e2ee1b6209e13c73fa03742924187 Mon Sep 17 00:00:00 2001 From: Joachim Rey Date: Mon, 9 Feb 2026 22:48:43 +0100 Subject: [PATCH 3/5] markdownlint newline --- docs/en/core-libraries/number.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/core-libraries/number.md b/docs/en/core-libraries/number.md index fa028b39cf..c38105306b 100644 --- a/docs/en/core-libraries/number.md +++ b/docs/en/core-libraries/number.md @@ -201,6 +201,7 @@ echo $this->Number->toReadableSize(5368709120); // 5 GiB It should be noted that IEC units are exponents of two and decimal units of ten. This mean that: + - 1000 Bytes = 1 KB - 1024 Bytes = 1 KiB From 987de11f5dcbe6264ae0e03a90187fadb0bbb2c8 Mon Sep 17 00:00:00 2001 From: Joachim Date: Wed, 18 Feb 2026 16:53:24 +0100 Subject: [PATCH 4/5] Added note and changed category in migration guide --- docs/en/appendices/5-4-migration-guide.md | 18 +++++++++--------- docs/en/core-libraries/number.md | 5 +++++ 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/en/appendices/5-4-migration-guide.md b/docs/en/appendices/5-4-migration-guide.md index eaae49673d..f039961a1a 100644 --- a/docs/en/appendices/5-4-migration-guide.md +++ b/docs/en/appendices/5-4-migration-guide.md @@ -14,15 +14,6 @@ automating some of the migration work. Run rector before updating your bin/cake upgrade rector --rules cakephp54 ``` -## Breaking Changes - -- `Number::toReadableSize()` now calculates decimal units (KB, MB, GB and TB) -using an exponent of ten, meaning that 1 KB is 1000 Bytes. The units from the -previous calculation method, where 1024 Bytes equaled 1 KB, have been changed -to KiB, MiB, GiB, and TiB as defined in ISO/IEC 80000-13. It is possible to -switch between the two units using a new optional boolean parameter in -`Number::toReadableSize()`, as well as the new global setter `Number::setUseIecUnits()`. - ## Behavior Changes - WIP @@ -33,6 +24,15 @@ switch between the two units using a new optional boolean parameter in ## New Features +### I18n + +- `Number::toReadableSize()` now calculates decimal units (KB, MB, GB and TB) +using an exponent of ten, meaning that 1 KB is 1000 Bytes. The units from the +previous calculation method, where 1024 Bytes equaled 1 KB, have been changed +to KiB, MiB, GiB, and TiB as defined in ISO/IEC 80000-13. It is possible to +switch between the two units using a new optional boolean parameter in +`Number::toReadableSize()`, as well as the new global setter `Number::setUseIecUnits()`. + ### Utility - New `Cake\Utility\Fs\Finder` class provides a fluent, iterator-based API for diff --git a/docs/en/core-libraries/number.md b/docs/en/core-libraries/number.md index c38105306b..252ec9d53b 100644 --- a/docs/en/core-libraries/number.md +++ b/docs/en/core-libraries/number.md @@ -205,6 +205,11 @@ This mean that: - 1000 Bytes = 1 KB - 1024 Bytes = 1 KiB +::: info Added in version 5.4.0 +It is now possible to use the byte units defined by the ISO/IEC 80000-13 +standard alongside more natural decimal units. +::: + ## Setting the Default Byte Units ### Number::setUseIecUnits() From bc1345a8c2d68899e92d267cecf6db472c2c8702 Mon Sep 17 00:00:00 2001 From: Joachim Rey Date: Wed, 18 Feb 2026 22:15:50 +0100 Subject: [PATCH 5/5] add note for setUseIecUnits --- docs/en/core-libraries/number.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/en/core-libraries/number.md b/docs/en/core-libraries/number.md index 252ec9d53b..40ae942784 100644 --- a/docs/en/core-libraries/number.md +++ b/docs/en/core-libraries/number.md @@ -205,7 +205,7 @@ This mean that: - 1000 Bytes = 1 KB - 1024 Bytes = 1 KiB -::: info Added in version 5.4.0 +::: info Modified in version 5.4.0 It is now possible to use the byte units defined by the ISO/IEC 80000-13 standard alongside more natural decimal units. ::: @@ -221,6 +221,11 @@ need to pass the boolean parameter to `Cake\I18n\Number::toReadableSize()` when switching between decimal units and IEC units. If `$useIec` is defined as true, IEC units will be employed; otherwise, decimal units will be used. +::: info Added in version 5.4.0 +This method has been added to remove the need to pass the optionnal boolean argument +each time IEC units are needed. +::: + ## Formatting Numbers ### Number::format()