diogo
/
symfony
Archived
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Validator] Improved inline documentation of the validators

This commit is contained in:
Bernhard Schussek 2014-02-21 16:27:31 +01:00
parent 9986f03ce2
commit 524a9538bc
5 changed files with 164 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
src/Symfony/Component/Validator/Validator/ContextualValidator.php
View File

@ -24,7 +24,9 @@ use Symfony\Component\Validator\NodeTraverser\NodeTraverserInterface;
use Symfony\Component\Validator\Util\PropertyPath;
/**
* @since %%NextVersion%%
* Default implementation of {@link ContextualValidatorInterface}.
*
* @since 2.5
* @author Bernhard Schussek <bschussek@gmail.com>
*/
class ContextualValidator implements ContextualValidatorInterface
@ -44,6 +46,15 @@ class ContextualValidator implements ContextualValidatorInterface
*/
private $metadataFactory;
/**
* Creates a validator for the given context.
*
* @param ExecutionContextInterface $context The execution context
* @param NodeTraverserInterface $nodeTraverser The node traverser
* @param MetadataFactoryInterface $metadataFactory The factory for fetching
* the metadata of validated
* objects
*/
public function __construct(ExecutionContextInterface $context, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory)
{
$this->context = $context;
@ -53,13 +64,19 @@ class ContextualValidator implements ContextualValidatorInterface
$this->metadataFactory = $metadataFactory;
}
public function atPath($subPath)
/**
* {@inheritdoc}
*/
public function atPath($path)
{
$this->defaultPropertyPath = $this->context->getPropertyPath($subPath);
$this->defaultPropertyPath = $this->context->getPropertyPath($path);
return $this;
}
/**
* {@inheritdoc}
*/
public function validate($value, $constraints = null, $groups = null)
{
if (null === $constraints) {
@ -84,6 +101,9 @@ class ContextualValidator implements ContextualValidatorInterface
return $this;
}
/**
* {@inheritdoc}
*/
public function validateProperty($object, $propertyName, $groups = null)
{
$classMetadata = $this->metadataFactory->getMetadataFor($object);
@ -118,6 +138,9 @@ class ContextualValidator implements ContextualValidatorInterface
return $this;
}
/**
* {@inheritdoc}
*/
public function validatePropertyValue($object, $propertyName, $value, $groups = null)
{
$classMetadata = $this->metadataFactory->getMetadataFor($object);
@ -151,6 +174,21 @@ class ContextualValidator implements ContextualValidatorInterface
return $this;
}
/**
* {@inheritdoc}
*/
public function getViolations()
{
return $this->context->getViolations();
}
/**
* Normalizes the given group or list of groups to an array.
*
* @param mixed $groups The groups to normalize
*
* @return array A group array
*/
protected function normalizeGroups($groups)
{
if (is_array($groups)) {
@ -159,9 +197,4 @@ class ContextualValidator implements ContextualValidatorInterface
return array($groups);
}
public function getViolations()
{
return $this->context->getViolations();
}
}

57
src/Symfony/Component/Validator/Validator/ContextualValidatorInterface.php
View File

@ -15,17 +15,24 @@ use Symfony\Component\Validator\Constraint;
use Symfony\Component\Validator\ConstraintViolationListInterface;
/**
* @since %%NextVersion%%
* A validator in a specific execution context.
*
* @since 2.5
* @author Bernhard Schussek <bschussek@gmail.com>
*/
interface ContextualValidatorInterface
{
/**
* @param string $subPath
* Appends the given path to the property path of the context.
*
* If called multiple times, the path will always be reset to the context's
* original path with the given path appended to it.
*
* @param string $path The path to append
*
* @return ContextualValidatorInterface This validator
*/
public function atPath($subPath);
public function atPath($path);
/**
* Validates a value against a constraint or a list of constraints.
@ -33,46 +40,50 @@ interface ContextualValidatorInterface
* If no constraint is passed, the constraint
* {@link \Symfony\Component\Validator\Constraints\Valid} is assumed.
*
* @param mixed $value The value to validate.
* @param Constraint|Constraint[] $constraints The constraint(s) to validate against.
* @param array|null $groups The validation groups to validate.
* @param mixed $value The value to validate
* @param Constraint|Constraint[] $constraints The constraint(s) to validate
* against
* @param array|null $groups The validation groups to
* validate. If none is given,
* "Default" is assumed
*
* @return ContextualValidatorInterface This validator
*/
public function validate($value, $constraints = null, $groups = null);
/**
* Validates a property of a value against its current value.
* Validates a property of an object against the constraints specified
* for this property.
*
* The accepted values depend on the {@link MetadataFactoryInterface}
* implementation.
*
* @param mixed $object The value containing the property.
* @param string $propertyName The name of the property to validate.
* @param array|null $groups The validation groups to validate.
* @param object $object The object
* @param string $propertyName The name of the validated property
* @param array|null $groups The validation groups to validate. If
* none is given, "Default" is assumed
*
* @return ContextualValidatorInterface This validator
*/
public function validateProperty($object, $propertyName, $groups = null);
/**
* Validate a property of a value against a potential value.
* Validates a value against the constraints specified for an object's
* property.
*
* The accepted values depend on the {@link MetadataFactoryInterface}
* implementation.
*
* @param string $object The value containing the property.
* @param string $propertyName The name of the property to validate
* @param string $value The value to validate against the
* constraints of the property.
* @param array|null $groups The validation groups to validate.
* @param object $object The object
* @param string $propertyName The name of the property
* @param mixed $value The value to validate against the
* property's constraints
* @param array|null $groups The validation groups to validate. If
* none is given, "Default" is assumed
*
* @return ContextualValidatorInterface This validator
*/
public function validatePropertyValue($object, $propertyName, $value, $groups = null);
/**
* @return ConstraintViolationListInterface
* Returns the violations that have been generated so far in the context
* of the validator.
*
* @return ConstraintViolationListInterface The constraint violations
*/
public function getViolations();
}

5
src/Symfony/Component/Validator/Validator/LegacyValidator.php
View File

@ -17,9 +17,14 @@ use Symfony\Component\Validator\Constraints\Valid;
use Symfony\Component\Validator\ValidatorInterface as LegacyValidatorInterface;
/**
* A validator that supports both the API of Symfony < 2.5 and Symfony 2.5+.
*
* @since 2.5
* @author Bernhard Schussek <bschussek@gmail.com>
*
* @see \Symfony\Component\Validator\ValidatorInterface
* @see \Symfony\Component\Validator\Validator\ValidatorInterface
*
* @deprecated Implemented for backwards compatibility with Symfony < 2.5.
* To be removed in Symfony 3.0.
*/

23
src/Symfony/Component/Validator/Validator/Validator.php
View File

@ -17,7 +17,9 @@ use Symfony\Component\Validator\NodeTraverser\NodeTraverserInterface;
use Symfony\Component\Validator\MetadataFactoryInterface;
/**
* @since %%NextVersion%%
* Default implementation of {@link ValidatorInterface}.
*
* @since 2.5
* @author Bernhard Schussek <bschussek@gmail.com>
*/
class Validator implements ValidatorInterface
@ -37,6 +39,16 @@ class Validator implements ValidatorInterface
*/
protected $metadataFactory;
/**
* Creates a new validator.
*
* @param ExecutionContextFactoryInterface $contextFactory The factory for
* creating new contexts
* @param NodeTraverserInterface $nodeTraverser The node traverser
* @param MetadataFactoryInterface $metadataFactory The factory for
* fetching the metadata
* of validated objects
*/
public function __construct(ExecutionContextFactoryInterface $contextFactory, NodeTraverserInterface $nodeTraverser, MetadataFactoryInterface $metadataFactory)
{
$this->contextFactory = $contextFactory;
@ -84,6 +96,9 @@ class Validator implements ValidatorInterface
return $this->metadataFactory->hasMetadataFor($object);
}
/**
* {@inheritdoc}
*/
public function validate($value, $constraints = null, $groups = null)
{
return $this->startContext($value)
@ -91,6 +106,9 @@ class Validator implements ValidatorInterface
->getViolations();
}
/**
* {@inheritdoc}
*/
public function validateProperty($object, $propertyName, $groups = null)
{
return $this->startContext($object)
@ -98,6 +116,9 @@ class Validator implements ValidatorInterface
->getViolations();
}
/**
* {@inheritdoc}
*/
public function validatePropertyValue($object, $propertyName, $value, $groups = null)
{
return $this->startContext($object)

91
src/Symfony/Component/Validator/Validator/ValidatorInterface.php
View File

@ -16,7 +16,9 @@ use Symfony\Component\Validator\ConstraintViolationListInterface;
use Symfony\Component\Validator\Context\ExecutionContextInterface;
/**
* @since %%NextVersion%%
* Validates PHP values against constraints.
*
* @since 2.5
* @author Bernhard Schussek <bschussek@gmail.com>
*/
interface ValidatorInterface
@ -27,60 +29,91 @@ interface ValidatorInterface
* If no constraint is passed, the constraint
* {@link \Symfony\Component\Validator\Constraints\Valid} is assumed.
*
* @param mixed $value The value to validate.
* @param Constraint|Constraint[] $constraints The constraint(s) to validate against.
* @param array|null $groups The validation groups to validate.
* @param mixed $value The value to validate
* @param Constraint|Constraint[] $constraints The constraint(s) to validate
* against
* @param array|null $groups The validation groups to
* validate. If none is given,
* "Default" is assumed
*
* @return ConstraintViolationListInterface A list of constraint violations. If the
* list is empty, validation succeeded.
* @return ConstraintViolationListInterface A list of constraint violations.
* If the list is empty, validation
* succeeded
*/
public function validate($value, $constraints = null, $groups = null);
/**
* Validates a property of a value against its current value.
* Validates a property of an object against the constraints specified
* for this property.
*
* The accepted values depend on the {@link MetadataFactoryInterface}
* implementation.
* @param object $object The object
* @param string $propertyName The name of the validated property
* @param array|null $groups The validation groups to validate. If
* none is given, "Default" is assumed
*
* @param mixed $object The value containing the property.
* @param string $propertyName The name of the property to validate.
* @param array|null $groups The validation groups to validate.
*
* @return ConstraintViolationListInterface A list of constraint violations. If the
* list is empty, validation succeeded.
* @return ConstraintViolationListInterface A list of constraint violations.
* If the list is empty, validation
* succeeded
*/
public function validateProperty($object, $propertyName, $groups = null);
/**
* Validate a property of a value against a potential value.
* Validates a value against the constraints specified for an object's
* property.
*
* The accepted values depend on the {@link MetadataFactoryInterface}
* implementation.
* @param object $object The object
* @param string $propertyName The name of the property
* @param mixed $value The value to validate against the
* property's constraints
* @param array|null $groups The validation groups to validate. If
* none is given, "Default" is assumed
*
* @param string $object The value containing the property.
* @param string $propertyName The name of the property to validate
* @param string $value The value to validate against the
* constraints of the property.
* @param array|null $groups The validation groups to validate.
*
* @return ConstraintViolationListInterface A list of constraint violations. If the
* list is empty, validation succeeded.
* @return ConstraintViolationListInterface A list of constraint violations.
* If the list is empty, validation
* succeeded
*/
public function validatePropertyValue($object, $propertyName, $value, $groups = null);
/**
* @return ContextualValidatorInterface
* Starts a new validation context and returns a validator for that context.
*
* The returned validator collects all violations generated within its
* context. You can access these violations with the
* {@link ContextualValidatorInterface::getViolations()} method.
*
* @return ContextualValidatorInterface The validator for the new context
*/
public function startContext();
/**
* @param ExecutionContextInterface $context
* Returns a validator in the given execution context.
*
* @return ContextualValidatorInterface
* The returned validator adds all generated violations to the given
* context.
*
* @param ExecutionContextInterface $context The execution context
*
* @return ContextualValidatorInterface The validator for that context
*/
public function inContext(ExecutionContextInterface $context);
/**
* Returns the metadata for an object.
*
* @param object $object The object
*
* @return \Symfony\Component\Validator\Mapping\MetadataInterface The metadata
*
* @throws \Symfony\Component\Validator\Exception\NoSuchMetadataException If no metadata exists
*/
public function getMetadataFor($object);
/**
* Returns whether the validator has metadata for an object.
*
* @param object $object The object
*
* @return Boolean Whether metadata exists for that object
*/
public function hasMetadataFor($object);
}