[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <fabien@symfony.com>
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  namespace Symfony\Component\Routing\Generator;
  13  
  14  /**
  15   * ConfigurableRequirementsInterface must be implemented by URL generators that
  16   * can be configured whether an exception should be generated when the parameters
  17   * do not match the requirements. It is also possible to disable the requirements
  18   * check for URL generation completely.
  19   *
  20   * The possible configurations and use-cases:
  21   * - setStrictRequirements(true): Throw an exception for mismatching requirements. This
  22   *   is mostly useful in development environment.
  23   * - setStrictRequirements(false): Don't throw an exception but return null as URL for
  24   *   mismatching requirements and log the problem. Useful when you cannot control all
  25   *   params because they come from third party libs but don't want to have a 404 in
  26   *   production environment. It should log the mismatch so one can review it.
  27   * - setStrictRequirements(null): Return the URL with the given parameters without
  28   *   checking the requirements at all. When generating a URL you should either trust
  29   *   your params or you validated them beforehand because otherwise it would break your
  30   *   link anyway. So in production environment you should know that params always pass
  31   *   the requirements. Thus this option allows to disable the check on URL generation for
  32   *   performance reasons (saving a preg_match for each requirement every time a URL is
  33   *   generated).
  34   *
  35   * @author Fabien Potencier <fabien@symfony.com>
  36   * @author Tobias Schultze <http://tobion.de>
  37   */
  38  interface ConfigurableRequirementsInterface
  39  {
  40      /**
  41       * Enables or disables the exception on incorrect parameters.
  42       * Passing null will deactivate the requirements check completely.
  43       *
  44       * @param bool|null $enabled
  45       */
  46      public function setStrictRequirements($enabled);
  47  
  48      /**
  49       * Returns whether to throw an exception on incorrect parameters.
  50       * Null means the requirements check is deactivated completely.
  51       *
  52       * @return bool|null
  53       */
  54      public function isStrictRequirements();
  55  }