tyler.durden
/
icingaweb2
mirror of https://github.com/Icinga/icingaweb2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Framework: Fix Form's docstrings 

refs #4440
This commit is contained in:
Eric Lippmann 2013-08-12 11:23:01 +02:00
parent e95c604084
commit 5cb9c67443
2 changed files with 82 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
application/forms/Authentication/LoginForm.php
View File

@ -32,6 +32,12 @@ use Icinga\Web\Form;
*/ */
class LoginForm extends Form class LoginForm extends Form
{ {
/**
* Disable CSRF protection
* @var bool
*/
protected $tokenDisabled = true;
/** /**
* Interface how the form should be created * Interface how the form should be created
*/ */
@ -63,7 +69,5 @@ class LoginForm extends Form
'class' => 'pull-right' 'class' => 'pull-right'
) )
); );
$this->setTokenDisabled(true);
} }
} }

138
library/Icinga/Web/Form.php
View File

@ -25,18 +25,16 @@
namespace Icinga\Web; namespace Icinga\Web;
use Icinga\Exception\ProgrammingError;
use Icinga\Web\Form\InvalidCSRFTokenException;
use \Zend_Controller_Request_Abstract; use \Zend_Controller_Request_Abstract;
use \Zend_Form_Element_Submit; use \Zend_Form_Element_Submit;
use \Zend_Form_Element_Reset; use \Zend_Form_Element_Reset;
use \Zend_View_Interface; use \Zend_View_Interface;
use \Zend_Form; use \Zend_Form;
use Icinga\Exception\ProgrammingError;
use Icinga\Web\Form\InvalidCSRFTokenException;
/** /**
* Class Form * Base class for forms providing CSRF protection, confirmation logic and auto submission
*
* How forms are used in Icinga 2 Web
*/ */
abstract class Form extends Zend_Form abstract class Form extends Zend_Form
{ {
@ -47,12 +45,12 @@ abstract class Form extends Zend_Form
private $request; private $request;
/** /**
* Whether this form should NOT add random generated "challenge" tokens that are associated * Whether this form should NOT add random generated "challenge" tokens that are associated with the user's current
* with the user's current session in order to prevent Cross-Site Request Forgery (CSRF). * session in order to prevent Cross-Site Request Forgery (CSRF). It is the form's responsibility to verify the
* It is the form's responsibility to verify the existence and correctness of this token * existence and correctness of this token
* @var bool * @var bool
*/ */
private $tokenDisabled = false; protected $tokenDisabled = false;
/** /**
* Name of the CSRF token element (used to create non-colliding hashes) * Name of the CSRF token element (used to create non-colliding hashes)
@ -60,12 +58,6 @@ abstract class Form extends Zend_Form
*/ */
private $tokenElementName = 'CSRFToken'; private $tokenElementName = 'CSRFToken';
/**
* Time to live for the CRSF token
* @var int
*/
private $tokenTimeout = 300;
/** /**
* Flag to indicate that form is already build * Flag to indicate that form is already build
* @var bool * @var bool
@ -73,15 +65,15 @@ abstract class Form extends Zend_Form
private $created = false; private $created = false;
/** /**
* Session id required for CSRF token generation * Session id used for CSRF token generation
* @var numeric|bool * @var string
*/ */
private $sessionId = false; private $sessionId;
/** /**
* Label for submit button * Label for submit button
* *
* If omitted, no button will be shown. * If omitted, no button will be shown
* *
* @var string * @var string
*/ */
@ -90,15 +82,20 @@ abstract class Form extends Zend_Form
/** /**
* Label for cancel button * Label for cancel button
* *
* If omitted, no button will be shown. * If omitted, no button will be shown
* *
* @var string * @var string
*/ */
private $cancelLabel; private $cancelLabel;
/** /**
* Returns the session ID stored in this form instance * Getter for the session ID
* @return mixed *
* If the ID has never been set, the ID from session_id() is returned
*
* @return string
* @see session_id()
* @see setSessionId()
*/ */
public function getSessionId() public function getSessionId()
{ {
@ -109,10 +106,11 @@ abstract class Form extends Zend_Form
} }
/** /**
* Overwrites the currently set session id to a user * Setter for the session ID
* provided one, helpful when testing
* *
* @param $sessionId The session id to use for CSRF generation * This method should be used for testing purposes only
*
* @param string $sessionId
*/ */
public function setSessionId($sessionId) public function setSessionId($sessionId)
{ {
@ -120,10 +118,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Returns the html-element name of the CSRF token * Return the HTML element name of the CSRF token field
* field
* *
* @return string * @return string
*/ */
public function getTokenElementName() public function getTokenElementName()
{ {
@ -131,9 +128,10 @@ abstract class Form extends Zend_Form
} }
/** /**
* Render the form to html * Render the form to HTML
* @param Zend_View_Interface $view *
* @return string * @param Zend_View_Interface $view
* @return string
*/ */
public function render(Zend_View_Interface $view = null) public function render(Zend_View_Interface $view = null)
{ {
@ -155,8 +153,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Setter for request * Setter for the request
* @param Zend_Controller_Request_Abstract $request The request object of a session *
* @param Zend_Controller_Request_Abstract $request
*/ */
public function setRequest(Zend_Controller_Request_Abstract $request) public function setRequest(Zend_Controller_Request_Abstract $request)
{ {
@ -164,8 +163,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Getter for request * Getter for the request
* @return Zend_Controller_Request_Abstract *
* @return Zend_Controller_Request_Abstract
*/ */
public function getRequest() public function getRequest()
{ {
@ -173,7 +173,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Triggers form creation * Create the form if not done already
*
* Adds all elements to the form
*/ */
public function buildForm() public function buildForm()
{ {
@ -199,8 +201,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Setter for cancel label * Setter for the cancel label
* @param string $cancelLabel *
* @param string $cancelLabel
*/ */
public function setCancelLabel($cancelLabel) public function setCancelLabel($cancelLabel)
{ {
@ -223,8 +226,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Setter for submit label * Setter for the submit label
* @param string $submitLabel *
* @param string $submitLabel
*/ */
public function setSubmitLabel($submitLabel) public function setSubmitLabel($submitLabel)
{ {
@ -238,7 +242,7 @@ abstract class Form extends Zend_Form
{ {
$submitButton = new Zend_Form_Element_Submit( $submitButton = new Zend_Form_Element_Submit(
array( array(
'name' => 'btn_submit', 'name' => 'btn_submit',
'label' => $this->submitLabel, 'label' => $this->submitLabel,
'class' => 'btn btn-primary pull-right' 'class' => 'btn btn-primary pull-right'
) )
@ -247,12 +251,12 @@ abstract class Form extends Zend_Form
} }
/** /**
* Enable automatic submission * Enable automatic form submission on the given elements
* *
* Enables automatic submission of this form once the user edits specific elements. * Enables automatic submission of this form once the user edits specific elements
* *
* @param array $triggerElements The element names which should auto-submit the form * @param array $triggerElements The element names which should auto-submit the form
* @throws ProgrammingError When an element is found which does not yet exist * @throws ProgrammingError When an element is found which does not yet exist
*/ */
final public function enableAutoSubmit($triggerElements) final public function enableAutoSubmit($triggerElements)
{ {
@ -272,11 +276,10 @@ abstract class Form extends Zend_Form
/** /**
* Check whether the form was submitted with a valid request * Check whether the form was submitted with a valid request
* *
* Ensures that the current request method is POST, that the * Ensures that the current request method is POST, that the form was manually submitted and that the data provided
* form was manually submitted and that the data provided in * in the request is valid and gets repopulated in case its invalid.
* the request is valid and gets repopulated in case its invalid.
* *
* @return bool * @return bool
*/ */
public function isSubmittedAndValid() public function isSubmittedAndValid()
{ {
@ -306,12 +309,16 @@ abstract class Form extends Zend_Form
/** /**
* Disable CSRF counter measure and remove its field if already added * Disable CSRF counter measure and remove its field if already added
* @param boolean $value Flag *
* This method should be used for testing purposes only
*
* @param bool $disabled
* @see tokenDisabled
*/ */
final public function setTokenDisabled($value = true) final public function setTokenDisabled($disabled = true)
{ {
$this->tokenDisabled = (boolean)$value; $this->tokenDisabled = (boolean) $disabled;
if ($value == true) { if ($disabled === true) {
$this->removeElement($this->tokenElementName); $this->removeElement($this->tokenElementName);
} }
} }
@ -324,22 +331,21 @@ abstract class Form extends Zend_Form
if ($this->tokenDisabled || $this->getElement($this->tokenElementName)) { if ($this->tokenDisabled || $this->getElement($this->tokenElementName)) {
return; return;
} }
$this->addElement( $this->addElement(
'hidden', 'hidden',
$this->tokenElementName, $this->tokenElementName,
array( array(
'value' => $this->generateCsrfTokenAsString(), 'value' => $this->generateCsrfTokenAsString(),
'decorators' => array('ViewHelper') 'decorators' => array('ViewHelper')
) )
); );
} }
/** /**
* Tests the submitted data for a correct CSRF token, if needed * Test the submitted data for a correct CSRF token
* *
* @param Array $checkData The POST data send by the user * @param array $checkData The POST data send by the user
* @throws InvalidCSRFTokenException When CSRF Validation fails * @throws InvalidCSRFTokenException When CSRF Validation fails
*/ */
final public function assertValidCsrfToken(array $checkData) final public function assertValidCsrfToken(array $checkData)
{ {
@ -357,12 +363,11 @@ abstract class Form extends Zend_Form
/** /**
* Check whether the form's CSRF token-field has a valid value * Check whether the form's CSRF token-field has a valid value
* *
* @param string $elementValue Value from the form element * @param string $elementValue Value from the form element
* @return bool * @return bool
*/ */
final private function hasValidCsrfToken($elementValue) private function hasValidCsrfToken($elementValue)
{ {
if ($this->getElement($this->tokenElementName) === null) { if ($this->getElement($this->tokenElementName) === null) {
return false; return false;
} }
@ -381,7 +386,8 @@ abstract class Form extends Zend_Form
/** /**
* Generate a new (seed, token) pair * Generate a new (seed, token) pair
* @return array *
* @return array
*/ */
final public function generateCsrfToken() final public function generateCsrfToken()
{ {
@ -392,9 +398,9 @@ abstract class Form extends Zend_Form
} }
/** /**
* Returns the string representation of the CSRF seed/token pair * Return the string representation of the CSRF seed/token pair
* *
* @return string * @return string
*/ */
final public function generateCsrfTokenAsString() final public function generateCsrfTokenAsString()
{ {