Skip to content

[Validator] Support "maxSize" given in KiB #3895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Aug 16, 2014
Merged

[Validator] Support "maxSize" given in KiB #3895

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e3acdc5
Support MaxSize in KiB and MiB
May 31, 2014
deac0c3
Add option binaryFormat in constraint file
jderusse Jun 1, 2014
3f3f4e0
Provide information about SI and Binary prefixes
jderusse Jun 1, 2014
71fdd60
Fix line wrap
jderusse Jun 1, 2014
7dcd7c3
Move secion "binaryFormat" to the right place
jderusse Jun 1, 2014
b414f5c
Use comma as thousands separator
Jun 19, 2014
77a0687
Add versionAdded on binary suffix
Jun 24, 2014
1e8fa48
Replace bullet list by a table
Jun 24, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 35 additions & 7 deletions reference/constraints/File.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ form type.
| Applies to | :ref:`property or method <validation-property-target>` |
+----------------+---------------------------------------------------------------------+
| Options | - `maxSize`_ |
| | - `binaryFormat`_ |
| | - `mimeTypes`_ |
| | - `maxSizeMessage`_ |
| | - `mimeTypesMessage`_ |
Expand Down Expand Up @@ -78,7 +79,6 @@ below a certain file size and a valid PDF, add the following:
maxSize: 1024k
mimeTypes: [application/pdf, application/x-pdf]
mimeTypesMessage: Please upload a valid PDF


.. code-block:: php-annotations

Expand Down Expand Up @@ -154,19 +154,46 @@ Options
maxSize
~~~~~~~

.. versionadded:: 2.6
The suffixes ``Ki`` and ``Mi`` were introduced in Symfony 2.6.

**type**: ``mixed``

If set, the size of the underlying file must be below this file size in order
to be valid. The size of the file can be given in one of the following formats:

* **bytes**: To specify the ``maxSize`` in bytes, pass a value that is entirely
numeric (e.g. ``4096``);
+--------+-----------+-----------------+------+
| Suffix | Unit Name | value | e.g. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder why you are speaking about "suffix". It's a prefix for the unit.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depend on the context:

  • regarding the unit (MiB, km, kg...), they are prefixes
  • regarding the value expected of the property maxSize (100M, 1024Ki) they are suffixes

BTW: at line https://github.com/symfony/symfony-docs/pull/3895/files#diff-aa9fd68c6e685f7e2773332c00fbcb68R179 it should be "binary and SI prefixes". But I choose to use the word suffixes to avoid user confusion...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also like suffix, since the user will use this as the suffix for their value. But the distinction actually hadn't occurred to me :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jeremy-derusse I opened a pull request addressing this (see #4136). If you like to, I'll be happy to see your comments there.

+========+===========+=================+======+
| | byte | 1 byte | 4096 |
+--------+-----------+-----------------+------+
| k | kilobyte | 1,000 bytes | 200k |
+--------+-----------+-----------------+------+
| M | megabyte | 1,000,000 bytes | 2M |
+--------+-----------+-----------------+------+
| Ki | kibibyte | 1,024 bytes | 32Ki |
+--------+-----------+-----------------+------+
| Mi | mebibyte | 1,048,576 bytes | 8Mi |
+--------+-----------+-----------------+------+

For more information about the difference between binary and SI suffixes,
see `Wikipedia: Binary prefix`_.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the kibibytes and mebibytes support in maxSize also new in 2.6? If so, we need a versionadded:: 2.6 for them as well.

What do you all think about replacing the bullet points with a table of examples? Something like:

maxSize Notes Unit Name
4096 4096 bytes bytes
200k 1k = 1,000 bytes kilobye
4M 1M = 1,000,000 bytes megabyte

etc


binaryFormat
~~~~~~~~~~~~

.. versionadded:: 2.6
The ``binaryFormat`` option was introduced in Symfony 2.6.

**type**: ``boolean`` **default**: ``null``

* **kilobytes**: To specify the ``maxSize`` in kilobytes, pass a number and
suffix it with a lowercase "k" (e.g. ``200k``);
When ``true``, the sizes will be displayed in messages with binary suffixes
(KiB, MiB). When ``false``, the sizes will be displayed with SI suffixes (kB,
MB). When ``null``, then the binaryFormat will be guessed from the suffix
defined in the ``maxSize`` option.

* **megabytes**: To specify the ``maxSize`` in megabytes, pass a number and
suffix it with a capital "M" (e.g. ``4M``).
For more information about the difference between binary and SI suffixes,
see `Wikipedia: Binary prefix`_.

mimeTypes
~~~~~~~~~
Expand Down Expand Up @@ -238,3 +265,4 @@ to disk.


.. _`IANA website`: http://www.iana.org/assignments/media-types/index.html
.. _`Wikipedia: Binary prefix`: http://en.wikipedia.org/wiki/Binary_prefix