Skip to content
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

Jump to bottom

[Documentation] Types Cleanup #6341

Open
wants to merge 5 commits into
base: 3.8.x
Choose a base branch
from
Open

[Documentation] Types Cleanup #6341

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ba67678
[Documentation] Types Cleanup
ThomasLandauer Mar 20, 2024
4298622
Update types.rst
ThomasLandauer Mar 21, 2024
5b92b7d
Update types.rst
ThomasLandauer Mar 21, 2024
a701865
Update docs/en/reference/types.rst
ThomasLandauer Mar 21, 2024
abca6d0
Update types.rst
ThomasLandauer Mar 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 9 additions & 7 deletions docs/en/reference/types.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ float
+++++

Maps and converts numeric data with floating-point precision.
Works only with locale settings that use decimal points as comma separator.
If you only need an approximate precision for numbers with fractions, you should
consider using this type.
Values retrieved from the database are always converted to PHP's
Expand All @@ -146,13 +147,13 @@ string
Maps and converts string data with a maximum length.
If you know that the data to be stored always fits into the specified length,
you should consider using this type.
Values retrieved from the database are always converted to PHP's string type
Values retrieved from the database are always converted to PHP's ``string`` type
ThomasLandauer marked this conversation as resolved.
Show resolved Hide resolved
or ``null`` if no data is present.

.. note::

Database vendors have different limits for the maximum length of a
varying string. Doctrine internally maps the ``string`` type to the
SQL VARCHAR. Doctrine internally maps the ``string`` type to the
ThomasLandauer marked this conversation as resolved.
Show resolved Hide resolved
vendor's ``text`` type if the maximum allowed length is exceeded.
This can lead to type inconsistencies when reverse engineering the
type from the database.
Expand All @@ -176,7 +177,7 @@ or ``null`` if no data is present.
guid
++++

Maps and converts a "Globally Unique Identifier".
Maps and converts a "Globally Unique Identifier" (GUID/UUID).
ThomasLandauer marked this conversation as resolved.
Show resolved Hide resolved
If you want to store a GUID, you should consider using this type, as some
database vendors have a native data type for this kind of data which offers
the most efficient way to store it. For vendors that do not support this
Expand Down Expand Up @@ -369,7 +370,7 @@ real arrays or JSON format arrays.
array
^^^^^

Maps and converts array data based on PHP serialization.
Maps and converts array data using PHP's ``serialize()`` and ``unserialize()``.
Copy link
Member

Choose a reason for hiding this comment

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

Implementation details don't belong into a documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

In this case it's an added benefit, cause if somebody has questions about some details, they can just find out what serialize() and unserialize() are doing exactly.

Copy link
Member

Choose a reason for hiding this comment

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

Don't overload the reader with technicalities in the first sentence then. Maybe just add a like to PHP docs at the end of this section for futher reading.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Well, in this case the only thing that's really important is the deprecation ;-) So I moved it upwards now.

BTW: This link is not working: :ref:\json``, see https://www.doctrine-project.org/projects/doctrine-dbal/en/3.8/reference/types.html#array - do you know how to fix it? (There are more occurrences on the page)

If you need to store an exact representation of your array data,
you should consider using this type as it uses serialization
to represent an exact copy of your array as string in the database.
Expand All @@ -393,7 +394,8 @@ using deserialization or ``null`` if no data is present.
simple_array
^^^^^^^^^^^^

Maps and converts array data based on PHP comma delimited imploding and exploding.
Maps and converts array data using PHP's ``implode()`` and ``explode()``, with a comma as delimiter
(so only use this type if you are sure that your values cannot contain a ``,``).
Comment on lines -396 to +398
Copy link
Member

Choose a reason for hiding this comment

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

Again: implementation details!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Here, the rather non-saying term "imploding and exploding" is repeated twice in the paragraph ;-)
Please leave the `implode()andexplode()`` in for now, so I don't forget it.
I will go over this page again (e.g. remove the phrase "Maps and converts" which is repeated all over), but I need to see it live - can't do this here on GitHub.
Besides, the main problem on this page IMO is the out-of-bounds "Mapping Matrix".

If you know that the data to be stored always is a scalar value based one-dimensional
array, you should consider using this type as it uses simple PHP imploding and
exploding techniques to serialize and deserialize your data.
Expand Down Expand Up @@ -423,7 +425,7 @@ using comma delimited ``explode()`` or ``null`` if no data is present.
json
^^^^

Maps and converts array data based on PHP's JSON encoding functions.
Maps and converts array data using PHP's ``json_encode()`` and ``json_decode()``.
If you know that the data to be stored always is in a valid UTF-8
encoded JSON format string, you should consider using this type.
Values retrieved from the database are always converted to PHP's
Expand Down Expand Up @@ -463,7 +465,7 @@ Types that map to objects such as POPOs.
object
^^^^^^

Maps and converts object data based on PHP serialization.
Maps and converts object data using PHP's ``serialize()`` and ``unserialize()``.
If you need to store an exact representation of your object data,
you should consider using this type as it uses serialization
to represent an exact copy of your object as string in the database.
Expand Down