Parametry pre action – pouzivanie a validacia

Tak nakoniec sa mi podarilo najst pre mna dolezite miesta v kode a vysledok je podla mna hodne silna validacia vstupnych parametrov.

Co sa validuje

• persistentne parametry
• parametry akcie/render metody

V oboch pripade sa validuje ci uz uvedena hodnota v URL alebo defaultne uvedena hodnota v zdrojaku. V pripade, ze sa validacia nepodari vyhodi sa Exception, takze v ErrorPresenter si ju mozete
odchytit a podla nej nastavit napr nejaky pekny View s chybovou hlaskou.

Zapis

Validacne pravidla sa zapisuju anotaciami nasledovnym stylom: @validate($var, callback [, $arg, $arg ..])

Ich umiestnenie je mozne bud pred metodou actionXY alebo renderXY. Ak vsak existuju obe musia byt anotacie uvedene pred metodou actionXY.

Priklad:

	/**
* @param int $id
* 		@validate($id, %i)
* 		@validate($id, >=, 6)
* @param string $color
* 		@validate($color, {}, red, green, blue)
* @param bool $render
*
* @nullable($render)
*/
	public function actionXY() { .. }

Vyssie uvedene znamene presne to by ste si mysleli:

• $id musi byt cislo vecsie rovne ako 6
• $color moze byt jedna z hodnot ‚red‘, ‚green‘, ‚blue‘
• $render moze byt prazdny (nadobudat prazdnu hodnotu – na jej detekovanie sa nepouziva empty ale sofistikovanejsi sposob)

Specialitka

Neviem nakolko kto vyuziva persistentne parametre, ja som sa vsak obcas dostal do situacie, ked som mal v presentere jeden persistentny parameter $id, ktory vsak sluzil roznym actions a vzdy na
tak trochu iny ucel (mohol nadobudat rozne typy hodnot).

Validacia pamata aj na tuto situaciu a je mozne nieco nasledovne:

final SamplePresenter extends BasePresenter
{
	/** @persistent int */
	$id;

	/**
	 * @validate($id, {}, 2, 4, 6)
	 * Tu moze byt $id len jedno z cisiel 2, 4 alebo 6
	 */
	public actionX() { .. }

	/**
	 * @validate($id, %i)
	 * Tu musi byt $id obecny integer
	 */
	public actionY() { .. }

	/**
	 * @param bool $id
	 * Tu sme spravili pretypovanie z int uvedeneho na zaciatku na bool
	 */
	public actionY() { .. }

}

Kesovanie

Aby sa urychlila validacia, resp spracovavanie anotacii, su tieto spracovane iba raz a potom su kesovane. Kes je nastavena tak, aby sa invalidovala pri kazdej zmene .php subory, ktory obsahuje definiciu presenteru.

Implementacia

	final private function validateParameters()
	{
	    // common regular expressions
	    static $phpIdentifier = '[_a-zA-Z\x7F-\xFF][_a-zA-Z0-9\x7F-\xFF]*';
	    static $phpTypes = 'int|integer|bool|boolean|float|double|real|string|array|object|mixed';

	    // ---------------------------------------------------------------------------------------------------------------------------
	    // 1. try cache
	    // ---------------------------------------------------------------------------------------------------------------------------
	    $cache    = NEnvironment::getCache('application/parameters.validation');
	    $cacheKey = $this->getAction(TRUE);

	    if (isset($cache[$cacheKey])) {
	        $params = $cache[$cacheKey]['params'];
	        $dValues = $cache[$cacheKey]['dValues'];
	        $nullable = $cache[$cacheKey]['nullable'];
	    }
	    else {

	    $r = $this->getReflection();

	    $actionMethod = $this->formatActionMethod($this->getAction());
	    $renderMethod = $this->formatRenderMethod($this->getAction());

	    $method = ($r->hasMethod($actionMethod)) ? $actionMethod : (($r->hasMethod($renderMethod)) ? $renderMethod : NULL);

	    $annotations = $r->getMethod($method)->getAnnotations();

	    if (!isset($annotations['validate'])) { return; }

	    // ---------------------------------------------------------------------------------------------------------------------------
	    // 2. build params & default values
	    // ---------------------------------------------------------------------------------------------------------------------------
	    $params   = array();
	    $dValues  = array();
	    $nullable = (isset($annotations['nullable'][0])) ? (array) $annotations['nullable'][0] : array();

	    // a) persistent params
	    foreach ($this->getReflection()->getPersistentParams() as $name => $param) {
	        if (isset($param['def'])) {
	            $dValues[$name] = $param['def'];
	        }
	        $ann = $this->getReflection()->getProperty($name)->getAnnotation('persistent');
	        preg_match('/(' . $phpIdentifier . '){0,1}/', $ann, $matches);
	        if (empty($matches)) { continue; }
	        $params['$' . $name] = array(
	            'type'	=> $matches[1],
	        );
	    }

	    // b) method params
	    $mParams = $r->getMethod($method)->getParameters();
	    foreach ($mParams as $param) {
	        if ($param->isDefaultValueAvailable()) {
	            $dValues[$param->getName()] = $param->getDefaultValue();
	        }
	    }

	    // c) annotated params
	    foreach ((isset($annotations['param'])) ? $annotations['param'] : array() as $param) {
	        preg_match('/(' . $phpIdentifier . '){0,1}\s*(\$' . $phpIdentifier . ')/', $param, $matches);
	        if (empty($matches)) { continue; }
	        $params[$matches[2]] = array(
	            'type'	=> $matches[1],
	        );
	    }

	    // ---------------------------------------------------------------------------------------------------------------------------
	    // 3. attach validation rules
	    // @validate($var, $callback [, $arg, $arg, ..])
	    // ---------------------------------------------------------------------------------------------------------------------------
	    foreach ($annotations['validate'] as $rule) {
	        $identifier = $rule[0];
	        $validator  = $rule[1];
	        $args = array_slice((array) $rule, 2);

	        if (!isset($params[$identifier])) { continue; }

	        switch (TRUE) {
	            // compare type fallback
	            case PValidate::isCompareType($validator) && (count($args) == 1) :
	                $args[] = $validator;
	                if (in_array($params[$identifier]['type'], array('int', 'integer', 'float', 'double', 'real',))) {
	                    $validator = PValidate::NUMERIC_CMP;
	                }
	                elseif ($params[$identifier]['type'] == 'string') {
	                    $validator = PValidate::STRING_CMP;
	                }
	                else {
	                    $validator = PValidate::COMPARE;
	                }
	                break;
	            // range type fallback
	            case PValidate::isRangeType($validator) :
	                $args[] = $validator;
	                $validator = ($params[$identifier]['type'] == 'string') ? PValidate::STRING_RANGE : PValidate::RANGE;
	                break;
	            // default callback processing
	            case is_callable($validator): break;
	            // Validate fallback
	            default:
	                $validator = PValidate::of($validator);
	                break;
	        }

	        $params[$identifier]['validators'][] = array(
	            CALLBACK => $validator,
	            ARGUMENTS=> $args,
	        );

	    }

	    // ---------------------------------------------------------------------------------------------------------------------------
	    // 4. save to cache
	    // Depends on Presenter .php file
	    // ---------------------------------------------------------------------------------------------------------------------------
	    $application = NEnvironment::getApplication();
	    $requests = $application->getRequests(); $request = end($requests);

	    $cache->save(
	        $this->getAction(TRUE),
	        array(
	        'params'	=> $params,
	        'dValues'	=> $dValues,
	            'nullable'	=> $nullable,
	        ),
	        array(
	            'files' => array(
	                $application->getPresenterLoader()->formatPresenterFile($request->getPresenterName()),
	            ),
	        )
	    );

	    }

	    // ---------------------------------------------------------------------------------------------------------------------------
	    // 5. perform validation
	    // ---------------------------------------------------------------------------------------------------------------------------
	    foreach ($params as $param => $meta) {
	        if (!isset($meta['validators'])) { continue; }
	        $identifier = substr($param, 1); // get rid of $
	        $defVal= (isset($dValues[$identifier])) ? $dValues[$identifier] : NULL;
	        $value = $this->getParam($identifier, $defVal);
	        if (((string) $value == '') && in_array($param, $nullable)) { continue; } // do not validate nullable null parameters
	        if (!PValidate::conditions($value, $meta['validators'])) {
	            throw new PBadParamRequestException('Param ' . $param . ' is not valid');
	        }
	    }

	}

Pouzitie

Danu funkciu si mozete dat napr do BasePresenteru a volat ju pri startup metode takto:

abstract class BasePresenter extends NPresenter
{
	public function startup()
	{
	    parent::startup();

	    // parameters validation
	    $this->validateParameters();

	}
}

Known issues

Pri implementovani ma zarazilo par veci, ktore Nette robi a jedna z nich sa mi nepodarila obist (bol by nutny zasah do FW). Ide o to, ze ak persistentnemu parametru nastavite nejaku default hodnotu napr:

/** @persistent */
$id = 10;

Nette si zapameta, ze dany parameter bol typu integer a automaticky potom nastavuje tento typ akejkolvek hodnote parametru cim znemoznuje pouzitie roznorodych validacii pre persistentny parameter ako je to uvedene v sekcii „Specialitka“

Zaverom

V uvedenej implementacii je pouzitych vela mojich internych classes, nemal som vsak tendenciu to z ukazkoveho kodu mazat – sluzi to aspon k tomu aby ludia popustili uzdu fantazie a videli co vsetko je mozne docielit.
Taky zapis <=, 30 je podla mna ovela citatelnejsi ako someNumberComparingFunction, <=, 30.

Cely priklad ma preto posluzit najme ako zakladna kostra implementacie a miesto jej vyuzitia v Nette, kazdy si ju moze upravit a zmenit ako uzna za vhodne.

Dalej uz nejaku dobu premyslam, ze zverejnim niektore svoje validacne a helper classy a tym padom by mohla komunita pouzivat aj vyssie uvedene zapisy – toto vsak moze a nemusi nastat, zavysi ci budem mat cas na prepisanie danych tried do navonok konzsistentne pouzitelneho packagu.