[Documentation] Types Cleanup #6341

ThomasLandauer · 2024-03-20T09:23:29Z

Page: https://www.doctrine-project.org/projects/doctrine-dbal/en/3.8/reference/types.html#reference

This PR is the "sibling" of doctrine/orm#11384

Once you've merged this, I will go over these types again and refine the wording a little.
Besides, the "Mapping Matrix" at https://www.doctrine-project.org/projects/doctrine-orm/en/2.19/reference/basic-mapping.html#doctrine-mapping-types is unusable right now. So I'm suggesting to split it and move the ~5 rows about each type to that type's section. Good idea?
What is the relation of https://www.doctrine-project.org/projects/doctrine-orm/en/2.19/cookbook/custom-mapping-types.html and https://www.doctrine-project.org/projects/doctrine-dbal/en/3.8/reference/types.html#custom-mapping-types ? Is this the same?

... in favor of https://www.doctrine-project.org/projects/doctrine-dbal/en/3.8/reference/types.html#reference Page: https://www.doctrine-project.org/projects/doctrine-orm/en/2.19/reference/basic-mapping.html#doctrine-mapping-types As announced in doctrine/dbal#6336 (comment) , the goal is to remove this duplicated type information from ORM and replace it with a link to DBAL. In doctrine/dbal#6341 , I'm adding any detail which I'm deleting here to the DBAL.

SenseException · 2024-03-20T22:40:27Z

Please squash the commits like you did in doctrine/orm#11384

ThomasLandauer · 2024-03-21T11:46:19Z

OK, done :-)

derrabus

Thank you for your attempt to improve the documentation. However, I don't believe any of those changes actually improve what we currently have. In most cases, you replace perfectly find statements with implementation details and technicalities.

docs/en/reference/types.rst

derrabus · 2024-03-21T14:00:13Z

docs/en/reference/types.rst

@@ -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()``.


Implementation details don't belong into a documentation.

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.

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.

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)

derrabus · 2024-03-21T14:00:32Z

docs/en/reference/types.rst

-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 ``,``).


Again: implementation details!

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".

the note about not supporting values containing a comma is good to keep though.

Co-authored-by: Alexander M. Turek <me@derrabus.de>

ThomasLandauer · 2024-03-21T14:25:29Z

All I did in this PR was adding some details that were present in the ORM docs, but were deleted in doctrine/orm#11384

docs/en/reference/types.rst

stof · 2024-06-10T14:59:22Z

docs/en/reference/types.rst

-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 ``,``).


the note about not supporting values containing a comma is good to keep though.

derrabus · 2024-06-11T07:43:07Z

docs/en/reference/types.rst

-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()``.


Implementation details, the current version is fine.

derrabus · 2024-06-11T07:43:13Z

docs/en/reference/types.rst

-Maps and converts object data based on PHP serialization.
+Maps and converts object data using PHP's ``serialize()`` and ``unserialize()``.


Implementation details, the current version is fine.

Let's take a look at the current version:

Maps and converts object data based on PHP serialization. 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. Values retrieved from the database are always converted to PHP's object type using deserialization or null if no data is present.

The same pseudo-information ("serialization") is repeated over and over; but which form of serialization is hidden from the user. Why?
So ultimately, I'd suggest to add a link to https://www.php.net/manual/function.serialize.php - then half of this paragraph can be deleted.

which form of serialization is hidden from the user.

🤔 it says "PHP serialization"… are there several forms of PHP serialization?

I don't know.
But if there's just one anyway, we can call it by its name; instead of leaving users uncertain.

I'm really not convinced.

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.

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 serialize()?!

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.

are there several forms of PHP serialization?

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...

The real problem on that page is the horrible Mapping Matrix,

But that's not what this PR changed, is it.

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 serialize()?!

Right, we should've closed this PR sooner.

ThomasLandauer mentioned this pull request Mar 20, 2024

[Documentation] Removing "Doctrine Mapping Types" ... doctrine/orm#11384

Merged

SenseException added the Documentation label Mar 20, 2024

[Documentation] Types Cleanup

ba67678

derrabus requested changes Mar 21, 2024

View reviewed changes

ThomasLandauer and others added 3 commits March 21, 2024 15:18

Update types.rst

4298622

Update types.rst

5b92b7d

Update docs/en/reference/types.rst

a701865

Co-authored-by: Alexander M. Turek <me@derrabus.de>

Update types.rst

abca6d0

stof reviewed Jun 10, 2024

View reviewed changes

derrabus requested changes Jun 11, 2024

View reviewed changes

Update types.rst

4a4aa49

greg0ire closed this Jun 21, 2024

ThomasLandauer deleted the patch-2 branch June 21, 2024 12:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Documentation] Types Cleanup #6341

[Documentation] Types Cleanup #6341

ThomasLandauer commented Mar 20, 2024 •

edited

Loading

SenseException commented Mar 20, 2024

ThomasLandauer commented Mar 21, 2024

derrabus left a comment

derrabus Mar 21, 2024

ThomasLandauer Mar 21, 2024

derrabus Mar 21, 2024

ThomasLandauer Mar 21, 2024 •

edited

Loading

derrabus Mar 21, 2024

ThomasLandauer Mar 21, 2024

stof Jun 10, 2024

ThomasLandauer commented Mar 21, 2024

stof Jun 10, 2024

derrabus Jun 11, 2024

derrabus Jun 11, 2024

ThomasLandauer Jun 11, 2024

greg0ire Jun 11, 2024

ThomasLandauer Jun 11, 2024

greg0ire Jun 20, 2024

SenseException Jun 20, 2024

ThomasLandauer Jun 21, 2024

derrabus Jun 21, 2024 •

edited

Loading

		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()``.

		Maps and converts object data based on PHP serialization.
		Maps and converts object data using PHP's ``serialize()`` and ``unserialize()``.

[Documentation] Types Cleanup #6341

[Documentation] Types Cleanup #6341

Conversation

ThomasLandauer commented Mar 20, 2024 • edited Loading

SenseException commented Mar 20, 2024

ThomasLandauer commented Mar 21, 2024

derrabus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ThomasLandauer Mar 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ThomasLandauer commented Mar 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

derrabus Jun 21, 2024 • edited Loading

Choose a reason for hiding this comment

ThomasLandauer commented Mar 20, 2024 •

edited

Loading

ThomasLandauer Mar 21, 2024 •

edited

Loading

derrabus Jun 21, 2024 •

edited

Loading