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.

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

[QUESTION] Explain about deprecation .yml on entities on docs #776

Closed
shakaran opened this Issue Feb 7, 2018 · 6 comments

Comments

Projects
None yet
5 participants
@shakaran
Copy link

shakaran commented Feb 7, 2018

As far I could read in "latest" doc (which is related to Doctrine 2.x) it seems that still .yml entities are supported
http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/yaml-mapping.html

But from some github issues that I read (not sure if it is written in other place), it seems that from 2.6 or 2.7 an future 3.x from Doctrine, the entities with .yml format will be deprecated and not supported anymore.

I would like know some technical explanation (or maybe not technical) of why drop the support for YML in favour of annotations or XML only. I just try to understand why, I don't judge if keep it is better o not.

Specially for non very technical people, understand a yml file is more easy than anotations or XML and sometimes is more quick to write in yaml format (manually) than XML or annotations

@Ocramius

This comment has been minimized.

Copy link
Member

Ocramius commented Feb 7, 2018

@shakaran few things here:

  1. this is a dev tool, intended to be used by developers. Non-devs have no business in defining mappings
  2. YAML lacks a proper DTD/XSD/Schema system and/or integration with editors that enforces structure in it
  3. anyone can type following in any modern IDE of choice and get auto-completion without having to even read the docs about mappings (some of it is even optional):
    <?xml version="1.0" encoding="UTF-8"?>
    <doctrine-mapping
        xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="./vendor/doctrine/orm/doctrine-mapping.xsd"
    >
        <!-- now simply CTRL+SPACE through the day :-) -->
    </doctrine-mapping>
  4. you get visual alerting (by your editor) that something is wrong with your mappings even before you run anything within the context of the ORM
  5. there is no proper way to help users that paste in their mappings, since visual validation requires deep knowledge of the existing keys rather than just pasting the mappings in an editor and just checking whether something is wrong. From the perspective of somebody providing support, helping somebody that writes YAML mappings in a Github issue is a nightmare, as everything needs to be checked manually against the YamlDriver.
  6. XML parsers are old and extremely stable beasts that are also extremely efficient

From our point of view (doctrine project), YAML mappings are overhead and added work for little to no benefit to the community besides personal taste of some users.

Strict configuration formats like Doctrine ORM mappings MUST be provided within a strict validation framework, in this case provided by static analysis of annotations or XSD/DTD validation in XML.

@Ocramius Ocramius closed this Feb 7, 2018

@Ocramius Ocramius self-assigned this Feb 7, 2018

@Ocramius

This comment has been minimized.

Copy link
Member

Ocramius commented Feb 7, 2018

@shakaran

This comment has been minimized.

Copy link
Author

shakaran commented Feb 7, 2018

@Ocramius thanks for you time and explanations, very clear to me now ;)

@alirezakazemi

This comment has been minimized.

Copy link

alirezakazemi commented Mar 17, 2019

@shakaran few things here:

1. this is a dev tool, intended to be used by developers. Non-devs have no business in defining mappings

2. YAML lacks a proper DTD/XSD/Schema system and/or integration with editors that enforces structure in it

3. anyone can type following in any modern IDE of choice and get auto-completion without having to even read the docs about mappings (some of it is even optional):
   ```
   <?xml version="1.0" encoding="UTF-8"?>
   <doctrine-mapping
       xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="./vendor/doctrine/orm/doctrine-mapping.xsd"
   >
       <!-- now simply CTRL+SPACE through the day :-) -->
   </doctrine-mapping>
   ```

4. you get visual alerting (by your editor) that something is wrong with your mappings even before you run anything within the context of the ORM

5. there is no proper way to help users that paste in their mappings, since visual validation requires deep knowledge of the existing keys rather than just pasting the mappings in an editor and just checking whether something is wrong. From the perspective of somebody providing support, helping somebody that writes YAML mappings in a Github issue is a nightmare, as everything needs to be checked manually against the [`YamlDriver`](https://github.com/doctrine/doctrine2/blob/v2.6.0/lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php).

6. XML parsers are old and extremely stable beasts that are also extremely efficient

From our point of view (doctrine project), YAML mappings are overhead and added work for little to no benefit to the community besides personal taste of some users.

Strict configuration formats like Doctrine ORM mappings MUST be provided within a strict validation framework, in this case provided by static analysis of annotations or XSD/DTD validation in XML.

Its true that XML benefits XST/DTD/Schema. But nothing is perfect including XML. Eventhough XML is a text representation, it is more machine readable rather than human readable, It is too verbose. But YAML although currently lackes DTD/Schema facilities, but is just kind of the pure data. It Elegantly imposes structure on data without the need for messing symbols. A single look on yaml presents data to the developer at a second but It takes more than 10 seconds to read the same XML.

Human compatibility is not an irrelevant feature at all. It is the reason for the success of text based network application protocols like HTTP, SMTP, etc. So I think is too important.

So It was not so wise to remove support for the yaml presentation. If the tooling dev support was the reason someone could provide converters to XML or Annotations and the remaining processing would work on a single (e.g. XML) presentation.

Morover YAML theoretically could have something like DTD/Scheam although currently it may lack one.
As an example I refer you to the Symfony 1.x Schema notation and tooling which defined a schema for some data. Some tools the then generated PHP parsing codes from schema which could then parse the YAML fixtures (as data).
I know that the schema which was written in schema.yml was itself schema less. But this is just an approximate example to show that YAML may be improved to have a true schema some day. However I think even before having a strict DTD/Schema it is superior in some aspects. XML & YAML both are data presentation languages which can have exactly the same features but other than YAML currently lacks a developed or well-known schema and XML suffers from verbosity and readability.

As you mentioned about being used by Developers not ordinary users, I should mention even 16 year developers (like me) is also a human not a machine and it is better to make things ergonomic.

About availability of using IDE/Intellisense, ... its true, but just in the context of creating new code/data and not in the context of reading previous code/data. Even during developing new code one requires frequently reading previous code.

So I strongly suggest to get YAML back as it is the most simple, human readable, yet a very powerful and flexible data presentation language.

@bertoost

This comment has been minimized.

Copy link

bertoost commented Mar 28, 2019

OH NO! Yaml should not be removed!! please

So I strongly suggest to get YAML back as it is the most simple, human readable, yet a very powerful and flexible data presentation language.

So true!

@Majkl578

This comment has been minimized.

Copy link
Contributor

Majkl578 commented Apr 1, 2019

So I strongly suggest to get YAML back as it is the most simple, human readable, yet a very powerful and flexible data presentation language.

Few points:

  • YAML is definitely not the most simple, quite the opposite, with all the madness around labels, references, assisted copy-paste etc.
  • It's human readable as long as simple it contains simple data. When it contains more complex data, like multi-lines or abovementioned referenctes, it's no longer simple and readable.
  • It seems to be powerful, but with great power comes great responsibility. And YAML is sacrificing straightforwardness and simplicity for power.
  • YAML is not a data presentation language in our context, it's definition language as it is used for configuration.
  • It's prone to multiple ambiguities, offset-by-one indentation errors or arrays as few examples.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.