Skip to content

Commit 987313d

Browse files
webmozartwebmozart
committed
[Validator] Improved inline documentation of the violation builder
1 parent 79387a7 commit 987313d

File tree

6 files changed

+188
-35
lines changed

6 files changed

+188
-35
lines changed

‎src/Symfony/Component/Validator/ConstraintViolation.php

+37-22
Original file line numberDiff line numberDiff line change
@@ -31,12 +31,12 @@ class ConstraintViolation implements ConstraintViolationInterface
3131
/**
3232
* @var array
3333
*/
34-
private $messageParameters;
34+
private $parameters;
3535

3636
/**
3737
* @var integer|null
3838
*/
39-
private $messagePluralization;
39+
private $plural;
4040

4141
/**
4242
* @var mixed
@@ -61,27 +61,26 @@ class ConstraintViolation implements ConstraintViolationInterface
6161
/**
6262
* Creates a new constraint violation.
6363
*
64-
* @param string $message The violation message.
65-
* @param string $messageTemplate The raw violation message.
66-
* @param array $messageParameters The parameters to substitute
67-
* in the raw message.
68-
* @param mixed $root The value originally passed
69-
* to the validator.
70-
* @param string $propertyPath The property path from the
71-
* root value to the invalid
72-
* value.
73-
* @param mixed $invalidValue The invalid value causing the
74-
* violation.
75-
* @param integer|null $messagePluralization The pluralization parameter.
76-
* @param mixed $code The error code of the
77-
* violation, if any.
78-
*/
79-
public function __construct($message, $messageTemplate, array $messageParameters, $root, $propertyPath, $invalidValue, $messagePluralization = null, $code = null)
64+
* @param string $message The violation message
65+
* @param string $messageTemplate The raw violation message
66+
* @param array $parameters The parameters to substitute in the
67+
* raw violation message
68+
* @param mixed $root The value originally passed to the
69+
* validator
70+
* @param string $propertyPath The property path from the root
71+
* value to the invalid value
72+
* @param mixed $invalidValue The invalid value that caused this
73+
* violation
74+
* @param integer|null $plural The number for determining the plural
75+
* form when translation the message
76+
* @param mixed $code The error code of the violation
77+
*/
78+
public function __construct($message, $messageTemplate, array $parameters, $root, $propertyPath, $invalidValue, $plural = null, $code = null)
8079
{
8180
$this->message = $message;
8281
$this->messageTemplate = $messageTemplate;
83-
$this->messageParameters = $messageParameters;
84-
$this->messagePluralization = $messagePluralization;
82+
$this->parameters = $parameters;
83+
$this->plural = $plural;
8584
$this->root = $root;
8685
$this->propertyPath = $propertyPath;
8786
$this->invalidValue = $invalidValue;
@@ -130,15 +129,31 @@ public function getMessageTemplate()
130129
*/
131130
public function getMessageParameters()
132131
{
133-
return $this->messageParameters;
132+
return $this->parameters;
133+
}
134+
135+
/**
136+
* Alias of {@link getMessageParameters()}.
137+
*/
138+
public function getParameters()
139+
{
140+
return $this->parameters;
134141
}
135142

136143
/**
137144
* {@inheritDoc}
138145
*/
139146
public function getMessagePluralization()
140147
{
141-
return $this->messagePluralization;
148+
return $this->plural;
149+
}
150+
151+
/**
152+
* Alias of {@link getMessagePluralization()}.
153+
*/
154+
public function getPlural()
155+
{
156+
return $this->plural;
142157
}
143158

144159
/**

‎src/Symfony/Component/Validator/Context/ExecutionContext.php

+3
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@
3030
* @author Bernhard Schussek <bschussek@gmail.com>
3131
*
3232
* @see ExecutionContextInterface
33+
*
34+
* @internal You should not instantiate or use this class. Code against
35+
* {@link ExecutionContextInterface} instead.
3336
*/
3437
class ExecutionContext implements ExecutionContextInterface
3538
{

‎src/Symfony/Component/Validator/Context/ExecutionContextFactory.php

+3
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@
2020
*
2121
* @since 2.5
2222
* @author Bernhard Schussek <bschussek@gmail.com>
23+
*
24+
* @internal You should not instantiate or use this class. Code against
25+
* {@link ExecutionContextFactoryInterface} instead.
2326
*/
2427
class ExecutionContextFactory implements ExecutionContextFactoryInterface
2528
{

‎src/Symfony/Component/Validator/Tests/Validator/Abstract2Dot5ApiTest.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -538,7 +538,7 @@ public function testAddCustomizedViolation()
538538
$context->buildViolation('Message %param%')
539539
->setParameter('%param%', 'value')
540540
->setInvalidValue('Invalid value')
541-
->setPluralization(2)
541+
->setPlural(2)
542542
->setCode('Code')
543543
->addViolation();
544544
};

‎src/Symfony/Component/Validator/Violation/ConstraintViolationBuilder.php

+68-9
Original file line numberDiff line numberDiff line change
@@ -17,29 +17,64 @@
1717
use Symfony\Component\Validator\Util\PropertyPath;
1818

1919
/**
20-
* @since %%NextVersion%%
20+
* Default implementation of {@link ConstraintViolationBuilderInterface}.
21+
*
22+
* @since 2.5
2123
* @author Bernhard Schussek <bschussek@gmail.com>
24+
*
25+
* @internal You should not instantiate or use this class. Code against
26+
* {@link ConstraintViolationBuilderInterface} instead.
2227
*/
2328
class ConstraintViolationBuilder implements ConstraintViolationBuilderInterface
2429
{
30+
/**
31+
* @var ConstraintViolationList
32+
*/
2533
private $violations;
2634

35+
/**
36+
* @var string
37+
*/
2738
private $message;
2839

40+
/**
41+
* @var array
42+
*/
2943
private $parameters;
3044

45+
/**
46+
* @var mixed
47+
*/
3148
private $root;
3249

50+
/**
51+
* @var mixed
52+
*/
3353
private $invalidValue;
3454

55+
/**
56+
* @var string
57+
*/
3558
private $propertyPath;
3659

60+
/**
61+
* @var TranslatorInterface
62+
*/
3763
private $translator;
3864

65+
/**
66+
* @var string|null
67+
*/
3968
private $translationDomain;
4069

41-
private $pluralization;
70+
/**
71+
* @var integer|null
72+
*/
73+
private $plural;
4274

75+
/**
76+
* @var mixed
77+
*/
4378
private $code;
4479

4580
public function __construct(ConstraintViolationList $violations, $message, array $parameters, $root, $propertyPath, $invalidValue, TranslatorInterface $translator, $translationDomain = null)
@@ -54,58 +89,82 @@ public function __construct(ConstraintViolationList $violations, $message, array
5489
$this->translationDomain = $translationDomain;
5590
}
5691

57-
public function atPath($subPath)
92+
/**
93+
* {@inheritdoc}
94+
*/
95+
public function atPath($path)
5896
{
59-
$this->propertyPath = PropertyPath::append($this->propertyPath, $subPath);
97+
$this->propertyPath = PropertyPath::append($this->propertyPath, $path);
6098

6199
return $this;
62100
}
63101

102+
/**
103+
* {@inheritdoc}
104+
*/
64105
public function setParameter($key, $value)
65106
{
66107
$this->parameters[$key] = $value;
67108

68109
return $this;
69110
}
70111

112+
/**
113+
* {@inheritdoc}
114+
*/
71115
public function setParameters(array $parameters)
72116
{
73117
$this->parameters = $parameters;
74118

75119
return $this;
76120
}
77121

122+
/**
123+
* {@inheritdoc}
124+
*/
78125
public function setTranslationDomain($translationDomain)
79126
{
80127
$this->translationDomain = $translationDomain;
81128

82129
return $this;
83130
}
84131

132+
/**
133+
* {@inheritdoc}
134+
*/
85135
public function setInvalidValue($invalidValue)
86136
{
87137
$this->invalidValue = $invalidValue;
88138

89139
return $this;
90140
}
91141

92-
public function setPluralization($pluralization)
142+
/**
143+
* {@inheritdoc}
144+
*/
145+
public function setPlural($number)
93146
{
94-
$this->pluralization = $pluralization;
147+
$this->plural = $number;
95148

96149
return $this;
97150
}
98151

152+
/**
153+
* {@inheritdoc}
154+
*/
99155
public function setCode($code)
100156
{
101157
$this->code = $code;
102158

103159
return $this;
104160
}
105161

162+
/**
163+
* {@inheritdoc}
164+
*/
106165
public function addViolation()
107166
{
108-
if (null === $this->pluralization) {
167+
if (null === $this->plural) {
109168
$translatedMessage = $this->translator->trans(
110169
$this->message,
111170
$this->parameters,
@@ -115,7 +174,7 @@ public function addViolation()
115174
try {
116175
$translatedMessage = $this->translator->transChoice(
117176
$this->message,
118-
$this->pluralization,
177+
$this->plural,
119178
$this->parameters,
120179
$this->translationDomain#
121180
);
@@ -135,7 +194,7 @@ public function addViolation()
135194
$this->root,
136195
$this->propertyPath,
137196
$this->invalidValue,
138-
$this->pluralization,
197+
$this->plural,
139198
$this->code
140199
));
141200
}

‎src/Symfony/Component/Validator/Violation/ConstraintViolationBuilderInterface.php

+76-3
Original file line numberDiff line numberDiff line change
@@ -12,24 +12,97 @@
1212
namespace Symfony\Component\Validator\Violation;
1313

1414
/**
15-
* @since %%NextVersion%%
15+
* Builds {@link \Symfony\Component\Validator\ConstraintViolationInterface}
16+
* objects.
17+
*
18+
* Use the various methods on this interface to configure the built violation.
19+
* Finally, call {@link addViolation()} to add the violation to the current
20+
* execution context.
21+
*
22+
* @since 2.5
1623
* @author Bernhard Schussek <bschussek@gmail.com>
1724
*/
1825
interface ConstraintViolationBuilderInterface
1926
{
20-
public function atPath($subPath);
27+
/**
28+
* Stores the property path at which the violation should be generated.
29+
*
30+
* The passed path will be appended to the current property path of the
31+
* execution context.
32+
*
33+
* @param string $path The property path
34+
*
35+
* @return ConstraintViolationBuilderInterface This builder
36+
*/
37+
public function atPath($path);
2138

39+
/**
40+
* Sets a parameter to be inserted into the violation message.
41+
*
42+
* @param string $key The name of the parameter
43+
* @param string $value The value to be inserted in the parameter's place
44+
*
45+
* @return ConstraintViolationBuilderInterface This builder
46+
*/
2247
public function setParameter($key, $value);
2348

49+
/**
50+
* Sets all parameters to be inserted into the violation message.
51+
*
52+
* @param array $parameters An array with the parameter names as keys and
53+
* the values to be inserted in their place as
54+
* values
55+
*
56+
* @return ConstraintViolationBuilderInterface This builder
57+
*/
2458
public function setParameters(array $parameters);
2559

60+
/**
61+
* Sets the translation domain which should be used for translating the
62+
* violation message.
63+
*
64+
* @param string $translationDomain The translation domain
65+
*
66+
* @return ConstraintViolationBuilderInterface This builder
67+
*
68+
* @see \Symfony\Component\Translation\TranslatorInterface
69+
*/
2670
public function setTranslationDomain($translationDomain);
2771

72+
/**
73+
* Sets the invalid value that caused this violation.
74+
*
75+
* @param mixed $invalidValue The invalid value
76+
*
77+
* @return ConstraintViolationBuilderInterface This builder
78+
*/
2879
public function setInvalidValue($invalidValue);
2980

30-
public function setPluralization($pluralization);
81+
/**
82+
* Sets the number which determines how the plural form of the violation
83+
* message is chosen when it is translated.
84+
*
85+
* @param integer $number The number for determining the plural form
86+
*
87+
* @return ConstraintViolationBuilderInterface This builder
88+
*
89+
* @see \Symfony\Component\Translation\TranslatorInterface::transChoice()
90+
*/
91+
public function setPlural($number);
3192

93+
/**
94+
* Sets the violation code.
95+
*
96+
* @param mixed $code The violation code
97+
*
98+
* @return ConstraintViolationBuilderInterface This builder
99+
*
100+
* @internal This method is internal and should not be used by user code
101+
*/
32102
public function setCode($code);
33103

104+
/**
105+
* Adds the violation to the current execution context.
106+
*/
34107
public function addViolation();
35108
}

0 commit comments

Comments
 (0)