From 5fbed361c28034618bb34859f63417fc56fe0c13 Mon Sep 17 00:00:00 2001 From: Tobias Schultze Date: Thu, 30 Aug 2012 16:35:30 +0200 Subject: [PATCH] extended phpdoc of ConfigurableRequirementsInterface --- .../ConfigurableRequirementsInterface.php | 20 +++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/src/Symfony/Component/Routing/Generator/ConfigurableRequirementsInterface.php b/src/Symfony/Component/Routing/Generator/ConfigurableRequirementsInterface.php index 89c86588ee..5925838c3f 100644 --- a/src/Symfony/Component/Routing/Generator/ConfigurableRequirementsInterface.php +++ b/src/Symfony/Component/Routing/Generator/ConfigurableRequirementsInterface.php @@ -15,10 +15,22 @@ namespace Symfony\Component\Routing\Generator; * ConfigurableRequirementsInterface must be implemented by URL generators that * can be configured whether an exception should be generated when the parameters * do not match the requirements. It is also possible to disable the requirements - * check for URL generation completely to improve performance when you know that - * the parameters meet the requirements anyway (because they are from a trusted - * source or you validated them beforehand which should be the case in production - * environment as it would otherwise break your site). + * check for URL generation completely. + * + * The possible configurations and use-cases: + * - setStrictRequirements(true): Throw an exception for mismatching requirements. This + * is mostly useful in development environment. + * - setStrictRequirements(false): Don't throw an exception but return null as URL for + * mismatching requirements and log the problem. Useful when you cannot control all + * params because they come from third party libs but don't want to have a 404 in + * production environment. It should log the mismatch so one can review it. + * - setStrictRequirements(null): Return the URL with the given parameters without + * checking the requirements at all. When generating an URL you should either trust + * your params or you validated them beforehand because otherwise it would break your + * link anyway. So in production environment you should know that params always pass + * the requirements. Thus this option allows to disable the check on URL generation for + * performance reasons (saving a preg_match for each requirement every time a URL is + * generated). * * @author Fabien Potencier * @author Tobias Schultze