Remove backslashes from DateTime references

[franzholz]

The backslash is not part of the class name. It is only needed if you do not have a "use DateTime;" statement.

[jokumer]

Looks good

[linawolf]

We are always using Fully Quallified names here and the FQN of DateTime is \DateTime. This way it is uniquely differnicated form other implementations called DateTime

[franzholz]

This is wrong. What you mean is FQDN. And it has much more than a leading backslash.

https://www.checkdomain.de/hosting/lexikon/fqdn

The TYPO3 documentation uses class names almost everywhere without leading backslashes.
And TYPO3 uses no other implementation for DateTime than the one shipped with PHP. The backslash only means to use no namespace.

[garvinhicking]

The Interface comes from PHP which has the root namespace \ and no other. The term is "FQN" or "FQCN" - an "FQDN" refers to domain names is unrelated here.

And I agree, for distinction we should always use the full namespace if we notice it. Removing the absolutely identifying namespace is not good.

[franzholz]

Ok, I was wrong with the term FQDN.
But a FQN still does not contain the leading backslash. I have found this :

What is a fully qualified name in PHP?
Fully qualified names always resolve to the name without leading namespace separator. For instance \A\B resolves to A\B . Relative names always resolve to the name with namespace replaced by the current namespace. If the name occurs in the global namespace, the namespace\ prefix is stripped.

[DavidBruchmann]

Without sticking to any FQ... expressions, I personally think the slash doesn't hurt inside the class and it's directly clear, that it's a PHP class and not an individual one.
Every programmer is free to handle it like you, @franzholz , proposed, but I'm in favor of the current notation of the documentation.

Relating to the reasoning of @linawolf it might also avoid the need to use aliases for individual DateTime implementations.

[franzholz]

Here is the answer from Chatgpt:

"Is it recommended to have a leading backslash for a class name in a PHP documentation?"

In PHP documentation, especially when you're documenting classes or referring to fully qualified class names (FQCN), it is not common or recommended to add a leading backslash (\) in the class name when you are referring to it inside the documentation.

Documentation Tools and Conventions:

Most documentation tools or PHPDoc itself (like in IDEs or API documentation generators) will handle the namespace and backslash correctly, so you don't have to add extra backslashes manually. If you're writing about PHP classes in general documentation, the best practice is simply to use the class names and namespaces as they are, without the leading backslash unless it’s part of an explicit example where it shows the global namespace context.

[DavidBruchmann]

I don't think your talk with ChatGTP adds anything useful but rather adds confusion. The fact that the code is in the documentation isn't of interest, as documentation and real-case-code are usually expected to have no fundamental differences. Notation of placeholders for classes or variables might be special cases where notation in documentation might differ or at least individual values have to be added by replacements. like in YourClass.

Your solution would add the PHP class with the use-statement which maps \DateTime on DateTime but would make it indistinguishable from individual classes if the use-statements of a class are not known (or currently not visible while reading the class-code with 3000 lines).

Beside the arguments which are mentioned in this thread already, your adjustment would overhaul the TYPO3 specific convention and require to replace all cases of PHP classes in the whole documentation, so this adjustment had a huge impact, no matter about any practical value, and should rather be started with a basic discussion than a simple single commit.

[franzholz]

@david: I cannot follow your argumentations.
ChatGTP collects its information from several sources.
If you have a proprietary class outside of PHP with any class name, then the documentation must anyways specify the full namespace before it If you use DateTime for another class name than the PHP's then this must be explained somewhere.

Is there really such a TYPO3 convention about a backslash before a class name? Where is it?

[DavidBruchmann]

@franzholz your question was very general, so chatGTP answered generally too -- too general to cover any specific use-cases. And if with the answer any sources are mentioned, you should link these sources perhaps.

then the documentation must anyways specify the full namespace before it

If no specific namespace is written with the class-name the current namespace is used. So if you have a Controller with namespace Vendor\Controllers\MyController and just use DateTime without use-statement and without slash, then the class Vendor\Controllers\DateTime is searched for. Actually this is nothing new for you, else you wouldn't have added the use-statement.
It seems to me that you conflate general usage with the simple fact that the use-statement just adds an alias to use, even if the alias is the same as the class-name.

Concerning the conventions I didn't find the specific document or paragraph, I found two links possibly of interest which were broken. I'm sure, @linawolf could help.

[franzholz]

@david: Yes, the PHP code is clear about the usage of a classname like DateTime .
But this topic is not about the PHP code, but about the documentation! This is the difference. In a documentation it is easier to name a classname as it is done in the PHP code class DateTime {...}. And when I refer to it in the documentation, then I am used to just write DateTime . It does not matter if the PHP code needs to have a \DateTime or not. It is the PHP programmer's job to understand the PHP syntax and namespace rules. And PHP will force these rules on him. But when I write about this matter in a sentence, then I consider it as strange to use a backslash. The documentation does not need this at all. And for the understanding it is not needed either. Every programmer already knows that every TYPO3 extension could have one or many classnames DateTime. But how often does this happen? And if it happens, then this could be a bad coding style or it could be an enhancement to the PHP DateTime. And if it is so, then the original documentation still works. The reader must always know of which class we are talking about. I see no reason to mention the PHP specifics which the reader will know anyways. And if other big players like Symfony do not use the backslash in the documentation either, why do we use a different approach? Will this make the life of the readers easier?

[DavidBruchmann]

For not so experienced programmers or people who just start programming those small differences might have huge negative impact, as it's, especially in the beginning, hard to know which details are important, which can be ignored.
Think about the different notations of models, sometimes they are written in lower_snake_case (tables), sometimes in lowerCamelCase (variables) or in UpperCamelCase (class-names), adding confusion to those important differences is imho needless, without any value and makes it additional hard. Beside that it makes it harder to copy and paste code in general.

So if you want to change it, just find the right arguments to convince the community. Personally I don't think that it's worth it to think longer time about it, but if you've good arguments someone will perhaps agree with you.

Keep in mind that you never had to convince the documentation team only but also the core programmers, as if consequently used, also according comments throughout the source-code had to be adjusted perhaps.