-
-
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
Changes from all commits
ba67678
4298622
5b92b7d
a701865
abca6d0
4a4aa49
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 |
---|---|---|
|
@@ -176,7 +176,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 +369,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 +390,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
+397
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 ;-) 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. the note about not supporting values containing a comma is good to keep though. |
||
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 +424,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()``. | ||
Comment on lines
-426
to
+427
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. Implementation details, the current version is fine. |
||
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 +464,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()``. | ||
Comment on lines
-466
to
+467
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. Implementation details, the current version is fine. 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. Let's take a look at the current version:
The same pseudo-information ("serialization") is repeated over and over; but which form of serialization is hidden from the user. Why? 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.
🤔 it says "PHP serialization"… are there several forms of PHP serialization? 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. I don't know. 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. I'm really not convinced. 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. It's like explaining how the motor of a car works while the user just wants to drive a car. If there are other places where the serialization got mentioned, then it's because we didn't know better about mentioning 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. Guys, I don't know what to say here. The real problem on that page is the horrible Mapping Matrix, but instead of discussing how it can be improved (i.e. removed), we keep arguing for three months if "PHP serialization" is a better term than As I said, all I did was to copy it over from https://github.com/doctrine/orm/blame/3.0.x/docs/en/reference/basic-mapping.rst#L257, where it has been sitting for some 14 years - and nobody of you cared.
Searching for "serialize" on https://www.php.net/ gives me 28 hits. So if everybody agrees with @derrabus that the current version is "perfectly fine", you can just close here... 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.
But that's not what this PR changed, is it.
Right, we should've closed this PR sooner. |
||
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)