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

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