simply put: Forms - Discusses error handling, sessions, preventing attacks, etc.

Forms

Displaying and processing forms may be more complex than you think. PIE provides a complete solution that takes care of routing, onSuccess, onError, preventing CSRF attacks, and and displaying errors next to their respective fields, and supporting AJAX.

To output HTML forms, you would do something like this:

<?php echo Pie_Html::form($action, 'post') ?>
	<?php echo Pie_Html::formInfo($on_success) ?>
	<!-- form contents go here -->
</form>

The Pie_Html::formInfo() function inserts hidden fields into the form, which are transmitted when the form is submitted throught the browser. They include:

• $on_success — the URI or URL to redirect to after a successful form submission. Often, you would simply want to return to the current url, i.e. Pie_Request::url().
• $on_error — if provided, this is the internal URI that PIE's dispatcher forwards to, in case there are errors. For example, if Pie_Response::addError($exception) is called, or an uncaught exception is thrown from an event like "pie/validate" or "pie/post", then PIE starts dispatching this URI.
• $session_nonce_field — if provided, this is the name of the index in the $_SESSION superglobal array, which would hold a nonce for the session, and is used to prevent CSRF attacks.

Handling Forms

When this form is submitted through the browser, (i.e. not intercepted with Javascript), these hidden form fields are sent along with the request. When handling the form, you will have access to all these fields through the $_REQUEST['_'] array.

The default "pie/response" handler already knows what to do with the $_REQUEST['_']['on_success'] and $_REQUEST['_']['on_error'] fields, if they are provided. However, to check the nonce that has been sent, you will have to call Pie_Valid::nonce(true); yourself. This is usually done during the "pie/validate" event.

Sessions

Note, by the way, that PIE lets you use superglobal variables, such as $_SESSION, $_REQUEST, etc. as you would normally. However, it provides cool facilities for enhancing them, such as the Pie_Session class. You should use this class for all your session management needs:

• Pie_Session::start() - Call this to start a session
• Pie_Session::id($new_id = null) - Returns a non-empty string if a session is already running. Also can be used to set the session id.
• Pie_Session::name($new_name = null) - Returns the session's name. Also can be used to set the session name.

If you set the pie/session/appendSuffix config field to true, PIE will append &session_name=session_id to the querystring of every URL generated (in links, form actions, and so forth). This can be useful when cookies are being blocked by the browser, such as in a third-party website running in an iframe. You probably shouldn't use it unless your pages are in an iframe, because you can unwittingly enable "session fixation" or "session hijacking" attacks, when users start sharing links with session ids in them.