[Validator] Document constraints as php 8 Attributes #14544

wkania · 2020-11-14T14:42:43Z

We already have examples of code for the PHP attributes.
We also have Constraints as php 8 Attributes and 2.
The rest will be implemented in the future.

wkania · 2020-11-16T17:20:52Z

@javiereguiluz Hi. Before I will add info about the attributes in constraints, could I receive some review about the message and position of the message?
In my opinion, it should be between the table and Basic Usage header.
The message:

The ability to use PHP attributes to configure constraints was introduced in
Symfony 5.2. Prior to this, Doctrine Annotations were the only way to
annotate field of a class with constraint configuration.

OskarStark · 2020-12-07T11:16:29Z

I would love to get your review here @derrabus 👍 Thanks

@wkania I am not sure if we need this information, the code examples are only available in the 5.2 docs 🤔

derrabus

Thank you very much for working on the documentation of my feature.

The added code blocks look pretty much correct. However, I'd like to suggest a couple of code-style changes:

Some constraints have worked with magic strings in the past (CardScheme, Isbn). While implementing the attributes I have introduced constants for those strings and my suggestion would be to use them.
We should use ::class instead of FQCN strings imho, but I don't know if there's a policy for the docs regarding that preference.
Symfony's code-style prefers single quotes over double quotes. I'd suggest to apply this preference to attributes as well. They're PHP code, after all.
I'd prefer to use trailing commas in multiline attributes. This would be consistent with Symfony's code style for multiline arrays and multiline Doctrine-style annotations.

derrabus · 2020-12-07T11:32:38Z

reference/constraints/Callback.rst

+        use Symfony\Component\Validator\Constraints as Assert;
+
+        #[Assert\Callback(["Acme\Validator", "validate"])]


Suggested change

use Symfony\Component\Validator\Constraints as Assert;

#[Assert\Callback(["Acme\Validator", "validate"])]

use Acme\Validator;

use Symfony\Component\Validator\Constraints as Assert;

#[Assert\Callback([Validator::class, 'validate'])]

We should prefer ::class over FQCN strings in PHP code.

We should use single quotes if we don't need the additional semantics of double quotes.

Ok, good to know. I have created attributes examples based on the annotation. I will fix it everywhere. In some other pull request, I will also update the annotations.

derrabus · 2020-12-07T11:35:48Z

reference/constraints/CardScheme.rst

+                schemes: ["VISA"],
+                message: "Your credit card number is invalid."


Suggested change

schemes: ["VISA"],

message: "Your credit card number is invalid."

schemes: [Assert\CardScheme::VISA],

message: 'Your credit card number is invalid.',

We have added constants for the available card schemes and I suggest we make use of them.

CS: prefer single quotes.

CS: use trailing comma in multiline constructor calls.

I added commas in all multiline constructor calls.

derrabus · 2020-12-07T11:37:56Z

reference/constraints/Choice.rst

+            /**
+             * You can also directly provide an array constant to the "choices" option in the annotation
+             */
+            #[Assert\Choice(choices: Conference::GENRES, message: "Choose a valid genre.")]


Suggested change

/**

* You can also directly provide an array constant to the "choices" option in the annotation

*/

#[Assert\Choice(choices: Conference::GENRES, message: "Choose a valid genre.")]

// You can also directly provide an array constant to the "choices" option in the annotation.

#[Assert\Choice(choices: Author::GENRES, message: 'Choose a valid genre.')]

The code comment explains the following attribute block. I find it confusing to use a phpdoc block for that.

Just copy, paste from annotation example. Fixed

derrabus · 2020-12-07T11:39:53Z

reference/constraints/Choice.rst

+
+        class Author
+        {
+            #[Assert\Choice(callback: "getGenres")]


Suggested change

#[Assert\Choice(callback: "getGenres")]

#[Assert\Choice(callback: 'getGenres')]

derrabus · 2020-12-07T11:40:30Z

reference/constraints/Choice.rst

+
+        class Author
+        {
+            #[Assert\Choice(callback: ["App\Entity\Genre", "getGenres"])]


Suggested change

#[Assert\Choice(callback: ["App\Entity\Genre", "getGenres"])]

#[Assert\Choice(callback: [Genre::class, 'getGenres'])]

derrabus · 2020-12-07T11:41:02Z

reference/constraints/Count.rst

+                minMessage: "You must specify at least one email",
+                maxMessage: "You cannot specify more than {{ limit }} emails"


Suggested change

minMessage: "You must specify at least one email",

maxMessage: "You cannot specify more than {{ limit }} emails"

minMessage: 'You must specify at least one email',

maxMessage: 'You cannot specify more than {{ limit }} emails',

derrabus · 2020-12-07T11:46:26Z

reference/constraints/Isbn.rst

+                type: "isbn10",
+                message : "This value is not valid."


Suggested change

type: "isbn10",

message : "This value is not valid."

type: Assert\Isbn::ISBN_10,

message : 'This value is not valid.',

wkania

@derrabus All fixed

I would love to get your review here @derrabus +1 Thanks

@wkania I am not sure if we need this information, the code examples are only available in the 5.2 docs thinking

I do not know what is the policy behind adding such information, but @derrabus added it.

derrabus · 2020-12-08T19:32:52Z

I don't think that we want to have this versionadded block on each constraint page. On some overview article that describes the various ways a developer might configure constraints, this block is certainly helpful, though.

wkania · 2021-01-20T18:04:16Z

Hi @OskarStark , @derrabus , @xabbuh , @maxhelias
From what I see, @HeahDude is a former member of docs team.
What about his review of this pull request?

OskarStark · 2021-01-21T18:48:25Z

It took time, but here we go, this is in now. Thank you very much @wkania.

This PR was submitted for the 5.x branch but it was merged into the 5.2 branch instead. Discussion ---------- [Validator] Use constant instead of magic string Related to the [comment](#14544 (review)). Commits ------- 9db655a [Validator] Use constant instead of magic string

wkania requested review from HeahDude and xabbuh as code owners November 14, 2020 14:42

carsonbot added Status: Needs Review Validator labels Nov 14, 2020

carsonbot added this to the 5.2 milestone Nov 14, 2020

wkania mentioned this pull request Nov 14, 2020

[Validator] Document constraints as php 8 Attributes #14538

Closed

derrabus suggested changes Dec 7, 2020

View reviewed changes

carsonbot added Status: Needs Work Status: Needs Review and removed Status: Needs Review Status: Needs Work labels Dec 7, 2020

derrabus approved these changes Dec 8, 2020

View reviewed changes

carsonbot added Status: Reviewed and removed Status: Needs Review labels Dec 8, 2020

wkania commented Dec 8, 2020

View reviewed changes

maxhelias approved these changes Dec 13, 2020

View reviewed changes

xabbuh approved these changes Jan 2, 2021

View reviewed changes

derrabus approved these changes Jan 2, 2021

View reviewed changes

OskarStark approved these changes Jan 20, 2021

View reviewed changes

[Validator] Document constraints as php 8 Attributes

748bd54

OskarStark force-pushed the ticket_14305 branch from bd52960 to 748bd54 Compare January 21, 2021 18:48

OskarStark merged commit 7b23335 into symfony:5.2 Jan 21, 2021

wkania mentioned this pull request Jan 23, 2021

[Validator] Use constant instead of magic string #14871

Merged

javiereguiluz mentioned this pull request Apr 22, 2021

[Validator] Constraints as php 8 Attributes #14305

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Validator] Document constraints as php 8 Attributes #14544

[Validator] Document constraints as php 8 Attributes #14544

wkania commented Nov 14, 2020

wkania commented Nov 16, 2020

OskarStark commented Dec 7, 2020 •

edited

Loading

derrabus left a comment

derrabus Dec 7, 2020

wkania Dec 8, 2020

derrabus Dec 7, 2020

wkania Dec 8, 2020

derrabus Dec 7, 2020

wkania Dec 8, 2020

derrabus Dec 7, 2020

wkania Dec 8, 2020

derrabus Dec 7, 2020

wkania Dec 8, 2020

derrabus Dec 7, 2020

wkania Dec 8, 2020

derrabus Dec 7, 2020

wkania Dec 8, 2020

wkania left a comment

derrabus commented Dec 8, 2020

wkania commented Jan 20, 2021

OskarStark commented Jan 21, 2021

		use Symfony\Component\Validator\Constraints as Assert;

		#[Assert\Callback(["Acme\Validator", "validate"])]

		schemes: ["VISA"],
		message: "Your credit card number is invalid."

	#[Assert\Choice(callback: "getGenres")]
	#[Assert\Choice(callback: 'getGenres')]

	#[Assert\Choice(callback: ["App\Entity\Genre", "getGenres"])]
	#[Assert\Choice(callback: [Genre::class, 'getGenres'])]

		minMessage: "You must specify at least one email",
		maxMessage: "You cannot specify more than {{ limit }} emails"

[Validator] Document constraints as php 8 Attributes #14544

[Validator] Document constraints as php 8 Attributes #14544

Conversation

wkania commented Nov 14, 2020

wkania commented Nov 16, 2020

OskarStark commented Dec 7, 2020 • edited Loading

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wkania left a comment

Choose a reason for hiding this comment

derrabus commented Dec 8, 2020

wkania commented Jan 20, 2021

OskarStark commented Jan 21, 2021

OskarStark commented Dec 7, 2020 •

edited

Loading