Packages » Package freeform

Package freeform

Description:
This is the core package for the Freeform Framework. It contains declarations for the base classes and interfaces you will use while developing your own web applications.

See also:

Authors:
  • Dennis Popel

Interfaces:
  • AccessController
    This is the interface to access controllers that control access to each action. An action returns an AccessController instance appropriate for it. The front controller then invokes its isAccessible() method to see if this action is accessible to user. It is up to the application to define access policies according to the business logic.
  • ActionWrapper
    This interface declares a single method that is called by ActionController::processHTTP() for all executed actions. The implementations of this interface can redefine the executed action's Document object (via its Action::getResponse() call) to set the common master template for all actions and packages on your site
  • Document
    This is an interface to documents in Freeform Framework. Each action generates an instance of Document and passes it to the Responce object it is assotiated with.
  • LocationRewriter
    This interface is used to rewrite the URLs generated by the Location::toURL() method calls. More specifically, the Location::toURL will look up the config option locationRewriter of the freeform package and will call its LocationRewriter::rewrite() passing itself as the parameter. If this config option is unspecified, then Location objects will return standard URL. This feature is useful when used in combination with your web server URL rewrite engine (like Apache's mod_rewrite). You can create rules that will map rewritten URLs to real ones and write your own LocationRewriter to force Locations to create rewritten URLs. Please note that while the LocationRewriter::rewrite() method must return the absolute URL (including the protocol, host, port and absolute path), the LocationRewriter::decode() method acts on the query string only, which is passed as a single parameter.
  • SessionHandler
    SessionHandler interface allows to create different session implementations in a standard way. Each session implementation must be able to carry session variables between requests and to maintain a logged user. The Session API does not define how to handle users, but it guarantees that each session implementation will be able to carry user between requests. It is up to the application which user model to choose. All accesses to session impelmentation, or session handler, is done via static methods of a special Session class. Each session implementation must provide a static method load() that returns the instance of session implementation class and will take necessary actions to create that instance if the session has not yet been created. The loader will call the appropriate handler class' static method load() and it will return the instance of the session implementation class. That instance will be passed to the Session class and further all session access will be passed to it. The session implementation must define the isExpired() method to track session expiration. In case of expired session the load() method must return a new, valid session but it must return true from a call to isExpired() method. If the session has expired, a new handler should be created but return true in a call to its isExpired() method.
  • User
    This is a general User interface in Freeform framework. Sessions will accept and return instances of this interface in calls to getUser() and setUser(). Freeform framework allows developers create their own or incorporate existing user management systems - this is the main reason why this interface and the UserManager class exist. It declares the general contract of quering particular user details, such as the user name, role and possible other properties (via the call to User::getProperty() method). The framework does not impose any limitations nor gives any guidelines to creating user management systems. The only requirement being the user entity must be represented by a class that implements this interface. Instances of this class can be passed to the Session::getUser() and Session::setUser() methods. The instrances must be serializable by the standard session handlers, however a particular session handler may be used in combination with the user management system to treat User instances in a more particular way (for example, the PersistentSession session handler is used in conjunction with the PersistentUser class to correctly serialize its instances into the session).

    The user ID is the only property that cannot be modified after the user object has been created. This property (accessed via the User::getID() method) is used as the unique user ID. This interface also declares a method User::isRole, which should return true if the user matches a role. Users can have multiple roles. It is up to the implementation how these roles are managed. The Security API reserves one role, root, to mark the root user for its control programs. Packages may use the fact that a user has the root role to guard access to critical actions. Implementations may return false if they do not support user roles.

Classes:
  • Action
    Action is the base class for all MVC controller classes of every web application. Actions get execuped (processed) with every user gesture like clicking on a link or submitting a form. Action are responsible for processing parameters supplied with each user request and to update model and to prepare appropriate view (result page, an implementation of the Document) suitable for the requesting client or its user agent. The Request and Response objects are created by the ActionController and supplied to every Action through the call to the constructor of the Action. You can execute other actions from your action using ActionController::process().
  • ActionController
    ActionController is the front controller for the Freeform framework. It is responsible for instantiating the proper action, getting its AccessController and processing it. The steps taken are:
    1. a call to Request::parseHTTP is made to create initial Request from RequestAdaptor that handles incoming HTTP data based on their content type
    2. the request parameter action is analyzed and corresponding Action is instantiated. If the action cannot be instantiated (e.g., invalid action class name was supplied), the action.error configuration option is queried to construct the error-handling Action. If that fails, a ConfigurationException will be thrown, resulting in the fatal error of the application.
    3. the requested action is passed to the ActionController::process(), the result is returned to client. If the Action's AccessController forbids access to it, the Action::onAccessDenied() method is called; otherwise the Action::process() is invoked.
    Starting with 1.2.0.Beta you can use this class to call another action from you action by calling its static ActionController::process() method, passing it the Action object to be processed.
  • CaptchaInputField
    This class represents captcha input field. It uses session to store the current captcha text and automatically performs its validity check, so if you include it into a form, it will automatically be invalid if incorrect capctha submitted.
  • CaptchaInputFieldImage
    This is a helper class for CaptchaInputField
  • CaptchaInputFieldRendererHTML
  • CheckBoxInputField
    This class represents a single check box input field of an input form.
  • CheckBoxInputFieldRendererHTML
  • DefaultErrorAction
  • Form
    The Form objects offer a simple and convenient way to hold form fields, their values and detect form submission and validating user's input
  • InputField
    This is the base class for all form input fields. A form field has a value and can have a validator. The form renderer tag (e.g., HTMLShowForm for HTMLDocuments) will automatically render the field's representation with the help of field renderer returned in the call to InputField::getRenderer().
  • Location
    This class is used to embed links to other actions into responce documents. It saves the document template designers from various quirks of creating complex hyperlinks within, for expample, the <a> tag. The document implementation tag serving as a link placeholder will simply call Location::toURL method and will get correct URL of the link. Freeform reserves the following parameter names so that you cannot use them for custom parameter names: action, hash, id and page.
  • PHPSessionHandler
    A generic session handler using php builtin session mechanism. You will have to properly configure PHP sessions to use this class.
  • Package
    This class defines methods for runtime resolution of package paths and provides access to package configuration and resources. In Freeform a package is a programmed replacement for namespaces, support for which has been dropped for not so clear reasons.
  • RadioButtonInputField
    This class represents a single set of radio buttons in the input form. Since the radio buttons all share the same field name in the form, this class needs an array of values to be constructed. These values are then placed in the form as you display the fields of the set.
  • RadioButtonInputFieldRendererHTML
  • Request
    Instances of this class are passed to actions and the latter query request parameters and other user-related details. Using requests it is easy to emulate user gestures and to create action chains when one action might want to call several other actions without redirecting to them. Since the HTTP protocol is text-based, the empty form fields or empty get parameters will be returned from this object as empty strings as opposed to nulls that are returned if parameters were not passed with the request. Moreover, it would be impossible for the remote client to pass the special value of null. Note that empty file upload fields will be also returned as empty strings, not nulls. Null will be returned, for example, if the form that expects a file upload was not submitted.
  • RequestAdaptor
    Request adaptors serve to properly decode data exchanged over HTTP for use by actions. Actions do not directly query RequestAdaptors, they call methods of a Request associated with them. The front controller will analyze content-type of incoming data and populate initial Request object with passed parameters (headers, variables, and cookies). Actions may simulate requests by manually creating Request instances and passing them to other actions. NOTE: most nonstandard (i.e., FDF) adaptors may require that always_populate_raw_post_data is on (either in php.ini or .htaccess).
  • Responce
    An alias for Response
  • Response
    Response of current action. Instances of Response class are passed to each action. They get created by front controller or other actions and passed to action instances to collect response information in form of response document, additional headers or relocations. Besides that, Response is responsible for returning service status codes that indicate success or failure of requested action execution. As opposed to HTTP status codes that indicate status of the whole HTTP request, service status codes indicate how given action performed. Normally this status code will be analyzed by network applications rather than by regular browsers. In case of regular browsers, Response can be used to send redirects to other actions (pages), especially after submission of POST forms. In such case, the document will be sent along with corresponding Location: header (by default) so that client application will still be able to process response document (if any). Most web applications that are designed for browsers only, may ignore all these extra options. The developers should be familiar with how to return document body or to relocate to other actions. This is preferred practice when a POST form responds with a relocation rather with a document since if the user hits the 'Reload' button in browser, he will be asked whether the data should be resubmitted. Since 1.2.0.Alpha responses support caching via simple API. By default, every response document sent to the client will be accompanied by a set of cache-controlling headers that will prevent any caching. You can fine-tune the client-side cache behaviour by setting lifetime and last modification time of every response so that clients will use cached versions of a particular response. Correct use of the last-modification time can also save server's CPU time as in some cases the invoked action will inform the response that the data in the document have not changed, and the response won't call the Document::getBody() method. Normally, the actions that process POST forms will not use caching at all as they will use redirection.
  • SelectInputField
    A select form input field. Allows to display drop-down or single/multiple selection boxes, with grouped options and/or with separators, providing control over selection mode (no selection allowed/selection must be made) and featuring prompt labels (like "please select...")
  • SelectInputFieldRendererHTML
  • Session
    This is a static class to interface session implementation used in given application. See SessionHandler interface for description of methods. All methods are shortcuts to corresponding methods of a concrete SessionHandler implementation.
  • TextInputField
    A text input field (either a text, textarea or password)
  • TextInputFieldRendererHTML
  • UploadFileInputField
    This form field allows to create upload fields and validate uploaded files (check size, mime and whether the file was uploaded).
  • UploadFileInputFieldRendererHTML
  • UploadedFile
    This class is a convenient way to handle uploaded files. The Request::getParameter will return instances of this class if the parameter name designates an uploaded file.
  • UserManager
    This abstract class declares general contract of accessing user management systems. Its few methods will allow third-party software to easily communicate with whatever user system installed. It is quite easy to subclass UserManager on top of popular forum/blog software and use their user management systems from Freeform applications.
  • UserManagerException
    This exception is thrown from methods of the UserManager instance
  • WWWFormRequestAdaptor
    This RequestAdaptor handles normal HTML/WML forms of types application/x-www-form-urlencoded or multipart/form-data. It accepts file uploads and returns them with request variables in form of UploadedFileInfo objects.

    Since 1.1.1.Stable moved from the html package to the freeform package. This adapter expects that all incoming data are UTF-8 encoded (as Freeform is purely UTF-8 based framework). All document implementations must instruct the clients to submit data in the UTF-8 encoding (as HTTP does not leave a way to detect it, browsers will send data back in the encoding that matches the page's encoding). If you design your own document implementation for non-HTML apps, you can also design your own RequestAdaptor that may change the encoding of submitted data to UTF-8. The framework stipulates that all data retrieved from the calls to the Request::getXXX() methods are UTF-8.
  • WelcomeToFreeform
    This is an example action that will get executed if there is no default action configured on the server. It displays a welcome screen.