Core: Remove Api prefix from Annotations

[backbone87]

All other annotations from symfony and doctrine dont prefix their annotations and its common practice to import the whole annotation namespace into a short prefix:

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Validator\Constraints as Assert;
use ApiPlatform\Core\Annotation as API; // results in @API\ApiResource or @API\ApiProperty

This is just pure cosmetic and low prio.

[sstok]

Personally I think @ApiResource looks cleaner then @API\ApiResource.

webmozart (Bernhard Schussek) creator of the Symfony Validation component actually recommends to not use as Assert https://speakerdeck.com/webmozart/symfony2-forms-dos-and-donts (page 83) but instead always import all annotations explicitly, as it's more uniform with how we use PHP classes.

In the end it's more a personal preference of course 😉

[dunglas]

I also find @ApiResource better (Resource or Property are terms too generic). Anyway, we cannot change the name now because it would be a BC break.

[backbone87]

Personally I think @ApiResource looks cleaner then @API\ApiResource.

Thats exactly what this ticket is meant to address. @API\Resource

webmozart's recommendation is actually orthogonal to this ticket:

/**
 * current situation:
 * @ApiResource
 * @API\ApiResource <- ugly
 * proposed situation:
 * @Resource
 * @API\Resource <- much better
 */

And yes: just renaming the annotation would be a BC break, but i am sure there are possibilities for soft transitions. Anyway, I would be very OK, if i have to wait until v3. After all its just cosmetic

edit: i personally prefer the namespace import, because you immediately see what component is the provider and probably the main consumer of the annotation. ofc you could hover the annotation or look at the imports, but that involves more disruption while reading the code

[dunglas]

webmozart and a lot of other people recommend to not alias the namespace (@API\Resource is discouraged). @Resource is not clearer (resource doesn't mean anything). @ApiResource is explicit.

[teohhanhui]

resource is a reserved word since PHP 7. There's no possibility of us
changing this back.

On Sat, 15 Apr 2017, 17:13 Kévin Dunglas, [e-mail] wrote:

webmozart (and a lot of other people) recommend to not alias the namespace
(@APIResource is discouraged). @Resource is not clearer (resource
doesn't mean anything). @ApiResource is explicit.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/api-platform/core/issues/1061#issuecomment-294281796,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAhf6zOKTskii6bC7noB8Ti_QfI7l6lMks5rwIo8gaJpZM4M-N3t
.

[backbone87]

just out of curiosity: whats the reasoning behind the "per class import" rec? (none given in the linked slides)

[sroze]

It'd say your dependencies are directly visible in the header of your file
On Sat, 15 Apr 2017 at 10:42, Oliver Hoff [e-mail] wrote:

just out of curiosity: whats the reasoning behind the "per class import"
rec? (none given in the linked slides)

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/api-platform/core/issues/1061#issuecomment-294283061,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAxHER2qtkhLKMOFp9XR3rc-B0mcuux2ks5rwJEDgaJpZM4M-N3t
.

[backbone87]

It'd say your dependencies are directly visible in the header of your file

Which is only half true, because namespaces are just string expansions. Some\Identifier can be a class AND a namespace (a folder): new Identifier and new Identifier\Anything can be both valid.

So if a user looks at the imports, he cant be sure what the dependencies are, because each import can be potentially be a namespace import.

If a machine wants to know the dependency, it has to at least get the AST anyway and can search for all class references easily then.

I agree that this is a pure question of preference and that both arguments:

dependencies are directly visible in the header of your file

and

you see what component is the provider and probably the main consumer of the annotation

are somewhat similar in weight (especially if you take the shortcomings of both arguments into account)

however

resource is a reserved word since PHP 7

pretty much kills this ticket anyway