From d509f3dbdee118f6a21df96eb30a9afdd29289c5 Mon Sep 17 00:00:00 2001
From: Joachim Rey <joachim.rey@etu.univ-lyon1.fr>
Date: Mon, 9 Feb 2026 22:30:18 +0100
Subject: [PATCH 1/3] 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 <joachim.rey@etu.univ-lyon1.fr>
Date: Mon, 9 Feb 2026 22:31:56 +0100
Subject: [PATCH 2/3] 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 <path/to/app/src>
 ```
 
+## 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 <joachim.rey@etu.univ-lyon1.fr>
Date: Mon, 9 Feb 2026 22:48:43 +0100
Subject: [PATCH 3/3] 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