From 260168e1bf125654f0a5c6f0fd439bff9c096ab1 Mon Sep 17 00:00:00 2001 From: Koray Zorluoglu Date: Thu, 4 Jan 2024 22:43:59 +0100 Subject: [PATCH 1/2] added detailed PHPDoc comments to GroupSequence class in Validator component --- .../Validator/Constraints/GroupSequence.php | 56 ++++++------------- 1 file changed, 17 insertions(+), 39 deletions(-) diff --git a/src/Symfony/Component/Validator/Constraints/GroupSequence.php b/src/Symfony/Component/Validator/Constraints/GroupSequence.php index 3c2cc48ba815b..afebc52ea7dad 100644 --- a/src/Symfony/Component/Validator/Constraints/GroupSequence.php +++ b/src/Symfony/Component/Validator/Constraints/GroupSequence.php @@ -12,37 +12,18 @@ namespace Symfony\Component\Validator\Constraints; /** - * A sequence of validation groups. + * The GroupSequence class represents a sequence of validation groups. + * It is used to enforce a specific order in which validation groups should be processed. * - * When validating a group sequence, each group will only be validated if all - * of the previous groups in the sequence succeeded. For example: + * When validating a group sequence, each group is validated sequentially. A group is only validated if all + * previous groups in the sequence succeeded. This approach is beneficial for scenarios where certain validation + * groups are more resource-intensive or rely on the success of prior validations. * - * $validator->validate($address, null, new GroupSequence(['Basic', 'Strict'])); + * Group sequences can also be used to override the "Default" validation group for a class. When a class has an + * associated group sequence and is validated in the "Default" group, the group sequence is applied instead. * - * In the first step, all constraints that belong to the group "Basic" will be - * validated. If none of the constraints fail, the validator will then validate - * the constraints in group "Strict". This is useful, for example, if "Strict" - * contains expensive checks that require a lot of CPU or slow, external - * services. You usually don't want to run expensive checks if any of the cheap - * checks fail. - * - * When adding metadata to a class, you can override the "Default" group of - * that class with a group sequence: - * #[GroupSequence(['Address', 'Strict'])] - * class Address - * { - * // ... - * } - * - * Whenever you validate that object in the "Default" group, the group sequence - * will be validated: - * - * $validator->validate($address); - * - * If you want to execute the constraints of the "Default" group for a class - * with an overridden default group, pass the class name as group name instead: - * - * $validator->validate($address, null, "Address") + * This feature allows for fine-grained control over the validation process, ensuring efficient and effective + * validation flows. * * @author Bernhard Schussek */ @@ -50,28 +31,25 @@ class GroupSequence { /** - * The groups in the sequence. + * An array of groups that make up the sequence. The validation process will adhere to this order. + * Each element can be a string representing a single group, an array of groups, or another GroupSequence. * * @var array */ public array $groups; /** - * The group in which cascaded objects are validated when validating - * this sequence. - * - * By default, cascaded objects are validated in each of the groups of - * the sequence. + * Specifies the group that will be used for cascaded validation. + * By default, all groups in the sequence are used for cascading. + * If a group sequence is attached to a class, replacing the "Default" group, + * this property allows specifying an alternate group for cascading validations. * - * If a class has a group sequence attached, that sequence replaces the - * "Default" group. When validating that class in the "Default" group, the - * group sequence is used instead, but still the "Default" group should be - * cascaded to other objects. + * @var string|GroupSequence */ public string|GroupSequence $cascadedGroup; /** - * Creates a new group sequence. + * Constructs a new GroupSequence with the specified sequence of groups. * * @param array $groups The groups in the sequence */ From 3a19f10b32899123af9f524264fbf0f952d3682e Mon Sep 17 00:00:00 2001 From: Koray Zorluoglu Date: Fri, 5 Jan 2024 09:49:29 +0100 Subject: [PATCH 2/2] GroupSequence class description with example extend --- .../Validator/Constraints/GroupSequence.php | 26 +++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/src/Symfony/Component/Validator/Constraints/GroupSequence.php b/src/Symfony/Component/Validator/Constraints/GroupSequence.php index afebc52ea7dad..1c67221d2654e 100644 --- a/src/Symfony/Component/Validator/Constraints/GroupSequence.php +++ b/src/Symfony/Component/Validator/Constraints/GroupSequence.php @@ -19,8 +19,30 @@ * previous groups in the sequence succeeded. This approach is beneficial for scenarios where certain validation * groups are more resource-intensive or rely on the success of prior validations. * - * Group sequences can also be used to override the "Default" validation group for a class. When a class has an - * associated group sequence and is validated in the "Default" group, the group sequence is applied instead. + * For example, when validating an address: + * + * $validator->validate($address, null, new GroupSequence(['Basic', 'Strict'])); + * + * In this case, all constraints in the "Basic" group are validated first. If none of the "Basic" constraints fail, + * the "Strict" group constraints are then validated. This is useful if, for instance, the "Strict" group contains + * more resource-intensive checks. + * + * Group sequences can also be used to override the "Default" validation group for a class: + * + * #[GroupSequence(['Address', 'Strict'])] + * class Address + * { + * // ... + * } + * + * When you validate the `Address` object in the "Default" group, the specified group sequence is applied: + * + * $validator->validate($address); + * + * To validate the constraints of the "Default" group for a class with an overridden default group, + * pass the class name as the group name: + * + * $validator->validate($address, null, "Address") * * This feature allows for fine-grained control over the validation process, ensuring efficient and effective * validation flows.