-
-
Notifications
You must be signed in to change notification settings - Fork 1.3k
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.
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
[Documentation] Types Cleanup #6341
base: 3.8.x
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
|
@@ -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). | ||
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 | ||
|
@@ -369,7 +370,11 @@ real arrays or JSON format arrays. | |
array | ||
^^^^^ | ||
|
||
Maps and converts array data based on PHP serialization. | ||
.. warning:: | ||
|
||
This type is deprecated since 3.4.0, use :ref:`json` instead. | ||
|
||
Maps and converts array data using PHP's ``serialize()`` and ``unserialize()``. | ||
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. | ||
|
@@ -386,14 +391,11 @@ using deserialization or ``null`` if no data is present. | |
properly on vendors not supporting column comments and will fall back to | ||
``text`` type instead. | ||
|
||
.. warning:: | ||
|
||
This type is deprecated since 3.4.0, use :ref:`json` instead. | ||
|
||
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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Again: implementation details! There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 ;-) |
||
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. | ||
|
@@ -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 | ||
|
@@ -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. | ||
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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()
andunserialize()
are doing exactly.There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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)