8000 [Validator] Improved inline documentation of the metadata classes · symfony/symfony@79387a7 · GitHub
[go: up one dir, main page]
Skip to content
Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 79387a7

Browse files
webmozartwebmozart
committed
[Validator] Improved inline documentation of the metadata classes
1 parent 01ceeda commit 79387a7

13 files changed

+331
-89
lines changed

‎src/Symfony/Component/Validator/Mapping/BlackholeMetadataFactory.php

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,25 +11,30 @@
1111

1212
namespace Symfony\Component\Validator\Mapping;
1313

14+
use Symfony\Component\Validator\Exception\NoSuchMetadataException;
1415
use Symfony\Component\Validator\MetadataFactoryInterface;
1516

1617
/**
17-
* Simple implementation of MetadataFactoryInterface that can be used when using ValidatorInterface::validateValue().
18+
* Metadata factory that does not store metadata.
19+
*
20+
* This implementation is useful if you want to validate values against
21+
* constraints only and you don't need to add constraints to classes and
22+
* properties.
1823
*
1924
* @author Fabien Potencier <fabien@symfony.com>
2025
*/
2126
class BlackholeMetadataFactory implements MetadataFactoryInterface
2227
{
2328
/**
24-
* @inheritdoc
29+
* {@inheritdoc}
2530
*/
2631
public function getMetadataFor($value)
2732
{
28-
throw new \LogicException('BlackholeClassMetadataFactory only works with ValidatorInterface::validateValue().');
33+
throw new NoSuchMetadataException('This class does not support metadata.');
2934
}
3035

3136
/**
32-
* @inheritdoc
37+
* {@inheritdoc}
3338
*/
3439
public function hasMetadataFor($value)
3540
{

‎src/Symfony/Component/Validator/Mapping/ClassMetadata.php

Lines changed: 46 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,9 @@
2222
use Symfony\Component\Validator\Exception\GroupDefinitionException;
2323

2424
/**
25-
* Represents all the configured constraints on a given class.
25+
* Default implementation of {@link ClassMetadataInterface}.
26+
*
27+
* This class supports serialization and cloning.
2628
*
2729
* @author Bernhard Schussek <bschussek@gmail.com>
2830
* @author Fabien Potencier <fabien@symfony.com>
@@ -31,36 +33,64 @@ class ClassMetadata extends ElementMetadata implements LegacyMetadataInterface,
3133
{
3234
/**
3335
* @var string
36+
*
37+
* @internal This property is public in order to reduce the size of the
38+
* class' serialized representation. Do not access it. Use
39+
* {@link getClassName()} instead.
3440
*/
3541
public $name;
3642

3743
/**
3844
* @var string
45+
*
46+
* @internal This property is public in order to reduce the size of the
47+
* class' serialized representation. Do not access it. Use
48+
* {@link getDefaultGroup()} instead.
3949
*/
4050
public $defaultGroup;
4151

4252
/**
4353
* @var MemberMetadata[]
54+
*
55+
* @internal This property is public in order to reduce the size of the
56+
* class' serialized representation. Do not access it. Use
57+
* {@link getPropertyMetadata()} instead.
4458
*/
4559
public $members = array();
4660

4761
/**
4862
* @var PropertyMetadata[]
63+
*
64+
* @internal This property is public in order to reduce the size of the
65+
* class' serialized representation. Do not access it. Use
66+
* {@link getPropertyMetadata()} instead.
4967
*/
5068
public $properties = array();
5169

5270
/**
5371
* @var GetterMetadata[]
72+
*
73+
* @internal This property is public in order to reduce the size of the
74+
* class' serialized representation. Do not access it. Use
75+
* {@link getPropertyMetadata()} instead.
5476
*/
5577
public $getters = array();
5678

5779
/**
5880
* @var array
81+
*
82+
* @internal This property is public in order to reduce the size of the
83+
* class' serialized representation. Do not access it. Use
84+
* {@link getGroupSequence()} instead.
5985
*/
6086
public $groupSequence = array();
6187

6288
/**
6389
* @var Boolean
90+
*
91+
* @internal This property is public in order to reduce the size of the
92+
* class' serialized representation. Do not access it. Use
93+
* {@link isGroupSequenceProvider()} instead.
6494
*/
6595
public $groupSequenceProvider = false;
6696

@@ -70,6 +100,10 @@ class ClassMetadata extends ElementMetadata implements LegacyMetadataInterface,
70100
* By default, only instances of {@link \Traversable} are traversed.
71101
*
72102
* @var integer
103+
*
104+
* @internal This property is public in order to reduce the size of the
105+
* class' serialized representation. Do not access it. Use
106+
* {@link getTraversalStrategy()} instead.
73107
*/
74108
public $traversalStrategy = TraversalStrategy::IMPLICIT;
75109

@@ -94,6 +128,11 @@ public function __construct($class)
94128
}
95129
}
96130

131+
/**
132+
* {@inheritdoc}
133+
*
134+
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
135+
*/
97136
public function accept(ValidationVisitorInterface $visitor, $value, $group, $propertyPath, $propagatedGroup = null)
98137
{
99138
if (null === $propagatedGroup && Constraint::DEFAULT_GROUP === $group
@@ -129,9 +168,7 @@ public function accept(ValidationVisitorInterface $visitor, $value, $group, $pro
129168
}
130169

131170
/**
132-
* Returns the properties to be serialized
133-
*
134-
* @return array
171+
* {@inheritdoc}
135172
*/
136173
public function __sleep()
137174
{
@@ -152,9 +189,7 @@ public function __sleep()
152189
}
153190

154191
/**
155-
* Returns the fully qualified name of the class
156-
*
157-
* @return string The fully qualified class name
192+
* {@inheritdoc}
158193
*/
159194
public function getClassName()
160195
{
@@ -356,9 +391,7 @@ public function getPropertyMetadata($property)
356391
}
357392

358393
/**
359-
* Returns all properties for which constraints are defined.
360-
*
361-
* @return array An array of property names
394+
* {@inheritdoc}
362395
*/
363396
public function getConstrainedProperties()
364397
{
@@ -398,19 +431,15 @@ public function setGroupSequence($groupSequence)
398431
}
399432

400433
/**
401-
* Returns whether this class has an overridden default group sequence.
402-
*
403-
* @return Boolean
434+
* {@inheritdoc}
404435
*/
405436
public function hasGroupSequence()
406437
{
407438
return count($this->groupSequence) > 0;
408439
}
409440

410441
/**
411-
* Returns the default group sequence for this class.
412-
*
413-
* @return GroupSequence The group sequence or null
442+
* {@inheritdoc}
414443
*/
415444
public function getGroupSequence()
416445
{
@@ -452,9 +481,7 @@ public function setGroupSequenceProvider($active)
452481
}
453482

454483
/**
455-
* Returns whether the class is a group sequence provider.
456-
*
457-
* @return Boolean
484+
* {@inheritdoc}
458485
*/
459486
public function isGroupSequenceProvider()
460487
{

‎src/Symfony/Component/Validator/Mapping/ClassMetadataFactory.php

Lines changed: 55 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,34 +17,81 @@
1717
use Symfony\Component\Validator\Mapping\Cache\CacheInterface;
1818

1919
/**
20-
* A factory for creating metadata for PHP classes.
20+
* Creates new {@link ClassMetadataInterface} instances.
21+
*
22+
* Whenever {@link getMetadataFor()} is called for the first time with a given
23+
* class name or object of that class, a new metadata instance is created and
24+
* returned. On subsequent requests for the same class, the same metadata
25+
* instance will be returned.
26+
*
27+
* You can optionally pass a {@link LoaderInterface} instance to the constructor.
28+
* Whenever a new metadata instance, it will be passed to the loader, which can
29+
* configure the metadata based on configuration loaded from the filesystem or
30+
* a database. If you want to use multiple loaders, wrap them in a
31+
* {@link Loader\LoaderChain}.
32+
*
33+
* You can also optionally pass a {@link CacheInterface} instance to the
34+
* constructor. This cache will be used for persisting the generated metadata
35+
* between multiple PHP requests.
2136
*
2237
* @author Bernhard Schussek <bschussek@gmail.com>
2338
*/
2439
class ClassMetadataFactory implements MetadataFactoryInterface
2540
{
2641
/**
2742
* The loader for loading the class metadata
43+
*
2844
* @var LoaderInterface
2945
*/
3046
protected $loader;
3147

3248
/**
3349
* The cache for caching class metadata
50+
*
3451
* @var CacheInterface
3552
*/
3653
protected $cache;
3754

55+
/**
56+
* The loaded metadata, indexed by class name
57+
*
58+
* @var ClassMetadata[]
59+
*/
3860
protected $loadedClasses = array();
3961

62+
/**
63+
* Creates a new metadata factory.
64+
*
65+
* @param LoaderInterface|null $loader The loader for configuring new metadata
66+
* @param CacheInterface|null $cache The cache for persisting metadata
67+
* between multiple PHP requests
68+
*/
4069
public function __construct(LoaderInterface $loader = null, CacheInterface $cache = null)
4170
{
4271
$this->loader = $loader;
4372
$this->cache = $cache;
4473
}
4574

4675
/**
47-
* {@inheritdoc}
76+
* Returns the metadata for the given class name or object.
77+
*
78+
* If the method was called with the same class name (or an object of that
79+
* class) before, the same metadata instance is returned.
80+
*
81+
* If the factory was configured with a cache, this method will first look
82+
* for an existing metadata instance in the cache. If an existing instance
83+
* is found, it will be returned without further ado.
84+
*
85+
* Otherwise, a new metadata instance is created. If the factory was
86+
* configured with a loader, the metadata is passed to the
87+
* {@link LoaderInterface::loadClassMetadata()} method for further
88+
* configuration. At last, the new object is returned.
89+
*
90+
* @param string|object $value A class name or an object
91+
*
92+
* @return MetadataInterface The metadata for the value
93+
*
94+
* @throws NoSuchMetadataException If no metadata exists for the given value
4895
*/
4996
public function getMetadataFor($value)
5097
{
@@ -93,7 +140,12 @@ public function getMetadataFor($value)
93140
}
94141

95142
/**
96-
* {@inheritdoc}
143+
* Returns whether the factory is able to return metadata for the given
144+
* class name or object.
145+
*
146+
* @param string|object $value A class name or an object
147+
*
148+
* @return Boolean Whether metadata can be returned for that class
97149
*/
98150
public function hasMetadataFor($value)
99151
{

‎src/Symfony/Component/Validator/Mapping/ClassMetadataInterface.php

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,66 @@
1515
use Symfony\Component\Validator\PropertyMetadataContainerInterface as LegacyPropertyMetadataContainerInterface;;
1616

1717
/**
18-
* @since %%NextVersion%%
18+
* Stores all metadata needed for validating objects of specific class.
19+
*
20+
* Most importantly, the metadata stores the constraints against which an object
21+
* and its properties should be validated.
22+
*
23+
* Additionally, the metadata stores whether the "Default" group is overridden
24+
* by a group sequence for that class and whether instances of that class
25+
* should be traversed or not.
26+
*
27+
* @since 2.5
1928
* @author Bernhard Schussek <bschussek@gmail.com>
29+
*
30+
* @see MetadataInterface
31+
* @see \Symfony\Component\Validator\Constraints\GroupSequence
32+
* @see \Symfony\Component\Validator\GroupSequenceProviderInterface
33+
* @see TraversalStrategy
2034
*/
2135
interface ClassMetadataInterface extends MetadataInterface, LegacyPropertyMetadataContainerInterface, ClassBasedInterface
2236
{
37+
/**
38+
* Returns the names of all constrained properties.
39+
*
40+
* @return string[] A list of property names
41+
*/
2342
public function getConstrainedProperties();
2443

44+
/**
45+
* Returns whether the "Default" group is overridden by a group sequence.
46+
*
47+
* If it is, you can access the group sequence with {@link getGroupSequence()}.
48+
*
49+
* @return Boolean Returns true if the "Default" group is overridden
50+
*
51+
* @see \Symfony\Component\Validator\Constraints\GroupSequence
52+
*/
2553
public function hasGroupSequence();
2654

55+
/**
56+
* Returns the group sequence that overrides the "Default" group for this
57+
* class.
58+
*
59+
* @return \Symfony\Component\Validator\Constraints\GroupSequence|null The group sequence or null
60+
*
61+
* @see \Symfony\Component\Validator\Constraints\GroupSequence
62+
*/
2763
public function getGroupSequence();
2864

65+
/**
66+
* Returns whether the "Default" group is overridden by a dynamic group
67+
* sequence obtained by the validated objects.
68+
*
69+
* If this method returns true, the class must implement
70+
* {@link \Symfony\Component\Validator\GroupSequenceProviderInterface}.
71+
* This interface will be used to obtain the group sequence when an object
72+
* of this class is validated.
73+
*
74+
* @return Boolean Returns true if the "Default" group is overridden by
75+
* a dynamic group sequence
76+
*
77+
* @see \Symfony\Component\Validator\GroupSequenceProviderInterface
78+
*/
2979
public function isGroupSequenceProvider();
3080
}

‎src/Symfony/Component/Validator/Mapping/ElementMetadata.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,14 @@
1111

1212
namespace Symfony\Component\Validator\Mapping;
1313

14+
/**
15+
* Contains the metadata of a structural element.
16+
*
17+
* @author Bernhard Schussek <bschussek@gmail.com>
18+
*
19+
* @deprecated Deprecated since version 2.5, to be removed in Symfony 3.0.
20+
* Extend {@link GenericMetadata} instead.
21+
*/
1422
abstract class ElementMetadata extends GenericMetadata
1523
{
1624
}

0 commit comments

Comments
 (0)
0