Basic Enterprise Application Realm

Basic Enterprise Application Realm Documentation
  • 1 PHP Reference
    • 1.1 Introduction
    • 1.2 shared_lib.php
    • 1.3 ac_tables.php
    • 1.4 ac_email.php
  • 2 Javascript Reference
    • 2.1 Introduction
    • 2.2 ac_ajax
    • 2.3 ac_event
    • 2.4 ac_filter
    • 2.5 ac_menu
    • 2.6 ac_panel
    • 2.7 ac_select
    • 2.8 ac_toc
  • 3 Forms
    • 3.1 Introduction
    • 3.2 How It Works
    • 3.3 AJAX
    • 3.4 form_processor_v2
    • 3.5 form_processor

3.4 form_processor_v2

January 22nd, 2026

Contents

3.4.1 Differences to form_processor

The functionality of v2 has been split into two dedicated classes. One for the UI processors which is still called form_processor, and another for the backend to provide meaningful form responses called form_response. Previously, a single class provided everything and required whatever code processes and validates form requests to be very UI aware. This naturally leads to duplication of effort. Multiple filters (HTML, API, mobile etc.) require their own interface processors. However, they basically needed to all redo form validation and processing. Generic application code files only handle non form specific functions.

Conversely, v2 provides a dedicated class to help generic application code perform validation without UI awareness and return the results as a form_response object which the front end filters can then meaningfully use. This provides:

  • Greatly improves code reuse.
  • Simplifies the interface filters (since much code is moved to generic application code files)
  • Makes new interface development very rapid.

form_processor_v2 is not a complete rewrite but more of a reorganisation of methods and properties for independent use by UI filter code and generic application code respectively. For this reason, migrating to v2 is easy. In some cases, no code changes are required at all.

3.4.2 Prerequisites

Before you code up a form processing class file, there are several preparation steps that must be completed in order otherwise your PHP will die with a fatal error.

  1. Decide on the form name common to your class file
    This will be used to determine the correct strings to load (among other things).
  1. Create INI files containing the locale specific text strings
    When an object based on form_processor class is instantiated, BEAR will look at the USER::$lang and $this->formname properties to determine the correct strings file to load from shared memory. The fallback is always files in English under the locale code "en" but more may be provided. For example, in the package "my_app", if a class uses the form name "new_user" then at a minimum, the resources directory must contain the file /my_app/preload/en/new_user.ini.

String files are INI files that contain a set structure. There are a few expected elements which must exist in even your first draft of this file. The text example below can be used as a template.

; Generic strings go at the start my_string="Hello World" another_string="Hello Moon" ; ; The "message strings" go in a named array. error, errors, success, and warning [message] error="Sorry. There is a problem with your request. Please see the hint below and try again." errors="Sorry. There were #A# problems with your request. Please see the hints below and try again." success="The operation has been carried out successfully." warning="Your request was valid but there was an unspecified problem." ; ; The short hints to display according to each possible user error on each input field [hints] required="required"

  1. Reload the shared memory
    To put the string file into memory, BEAR must be either reloaded or restarted.

Obviously, you do not need to decide on all the text strings for your form right away. You can keep adding to the strings INI file as you go. Just remember to reload BEAR after each change to the file.

3.4.3 Linking the form_processor_v2 interface - UI filter only

When creating a new class that will provide any form processing, it must include and extend the form_processor interface. For example, to create a new class file to handle user registration for a package called "my_app", you might create the following file in the CGI directory called my_app/html_filters/register.php.

Creating a register class and linking to the interface would make the PHP in the class file would require the following code:

<?php include_once('shared_lib/form_processor_v2.php'); class register extends form_processor{ // CLASS CODE GOES HERE } ?>

However, the form_processor interface contains two abstract methods which must be defined in your class otherwise PHP will die with a fatal error. These methods are:

  • construct()
  • set_formname()

A full template of your new class which does not cause PHP to die will look like this.

<?php include_once('shared_lib/form_processor_v2.php'); class register extends form_processor{ /* -- METHOD (void) set_formname() -- Sets the formname as required by the interface ------------------------------------------------------ */ protected function set_formname(){ } /* -- METHOD (void) construct(request(str), sub request(str)) -- Main logic switch for running the log filters ------------------------------------------------------ */ protected function construct($request,$subrequest){ } } ?>

The rest of the class code is up to you. However, the tab labelled How-To will provide samples and best practices for the most common structures and tasks.

It is not necessary to include the shared_lib.php class file in your class since this included by the form_processor.php class file automatically.

3.4.4 Abstract Methods - UI filter only (mandatory)

Ver. Arguments Returns Purpose
set_formname 1,2 (void) (void) Sets the private property formname. This is generally a string hard-coded into your class though you may want to conditionally set this to different a different string. The formname is critical for saving persistent form data to the session without overwriting other form caches.
construct 1,2 processing request (string), sub request (string) (void) Not to be confused with the PHP class constructor __construct() (which already exists in the base form_processor class). This method is always called when the object is instantiated and must support 2 arguments. These represent a form request string and a subrequest string. Whether subrequests are used or not depends on if you specify such a string in the HTML form action. In many cases, forms will just send a single request.

All abstract methods should be defined as protected or private scope.

3.4.5 Public Properties

UI filter

The following properties belong to the form_processor class.

Ver. Static Type Default Purpose
message 1,2 N string A string of text to display to the user indicating the result of the form processing operation. This is commonly a message referring to success, failure, or some type of warning.
hints 1,2 N array An associative array with keys that correspond to points of possible user input failure and values that can have text inserted to indicate what mistake the user made. Generally, this is not manually manipulated after setting it up, but using the built-in add_error() method.
status 1,2 N integer 0 An integer that provides the overall processing result. Often used in conjunction with the message property since this can be used to determine the visual style of the message (such showing a page error in red or success message in green). Valid values are: 0 = success; 1 = completed with warnings; 2 = error; 3 = do nothing (often used with AJAX file uploads)
ns 1,2 N string This is the namespace string of the form elements. This is not an XML namespace but corresponds to a named prefix in the HTML element IDs so that changes are unambiguous. For example, two forms on the same page may have empty <div> tags for displaying a processing message. They cannot both be called "message". The ns property provides a way to indicate the ID prefix. Commonly, the construct method's request argument is assigned to ns but any string can be used as long as it corresponds to the IDs in the HTML.
next_url 1,2 N string This string contains an URL which can be used to forward the user's browser only if the value of the status property is zero (success).
anchor 1,2 N string Similar to the next_url property, however, this string changes the current page anchor point in the browser on form completion regardless of the status property.
presets 1,2 N array Some pages will need to initialise the class before the form is submitted to setup default values. For example, on a user profile update page, this can be used to pre-input the username etc. This is a simple associative array containing strings to use for your values. The values must be HTML safe.
redraw 1,2 N array This multidimensional array is the backbone of AJAX for the ac_ajax Javascript object. Each element (numerical keys) contains another array with the full HTML ID tag in index 0 and the HTML to insert at index 1. Unlike the hints array, the IDs must be complete. This means that they should include any namespace prefix from the ns property. The reason for this is that this array can be used to redraw the contents of any named HTML tag including those belonging to other forms with different namespaces.
values 2 N array An associative array that allows values in form fields to be replaced when used with ac_ajax. Each key represents the HTML ID of the field (sans namespace prefix), and each value is the string to insert as the new value. In this respect is it similar to the redraw property (and in fact redraw can be used for this) but provides a simpler interface to user input rewriting. Because the namespace is always automatically prefixed to the HTML ID care needs to be taken to ensure that the IDs in HTML contain proper <NAMESPACE>_<KEY> strings. This also means that one form can also get value updates from the submission of another form by labeling the IDs with the namespace prefix of the form that performs the update.
call 2 N string A container for arbitrary Javascript which, if present, is passed back to an AJAX form an called as the last thing any AJAX processor does. This allows for complex AJAX updates like new forms to be sent and registered.
Backend

The following properties belong to the form_response class.

Ver. Static Type Default Purpose
metadata 2 N mix This is a free format variable that can be used to pass arbitrary data back to the UI filter. The UI filter extending form_processor must still know how to use this data. In most cases, this will be left as null.
cache 2 N mix This is a free format variable that can be used to store values for caching. This is useful for multi page forms where data from one page needs to be cached and re-usable again on subsequent calls.

3.4.6 Private Properties

UI filter

The following properties belong to the form_processor class.

Ver. Static Type Default Purpose
input 1,2 N array all user input An associative array containing all the raw user input data from the form.
strings 1,2 N array locale specific strings An associative array that is auto-loaded when the object is created to include strings specific to the formname in the current user's locale.
errors 1,2 N integer 0 An incremental counter that tots up the number of user input errors so far. This can be used to determine after validation whether to proceed to take the user's desired action or to halt processing and display an error.
formname 1,2 N string This is the internal reference string of the form. This is used for determining the correct string file to load and for saving persistent form values to the session without overwriting other forms.
cache 1,2 N mixed If the session contains values linked to the formname then those are loaded into this property and can be used to give the form persistence (such as a wizard that allows users to go forward and back and review their input before the final submission).
is_submitted 1,2 N boolean FALSE A simple flag used for determining whether forms have been submitted in a secure way. If the form's unique submit value matches the one in the session, then this flag changes to TRUE and your code can use this to determine form submission.
message_ids 2 N array And array that contains a list of all form namespaces that appear on a page (or a subset thereof). This is used by other methods for resetting the form messages to empty strings.
Backend

The following properties belong to the form_response class.

Ver. Static Type Default Purpose
message 2 N string A string of text to display to the user indicating the result of the form processing operation. This is commonly a message referring to success, failure, or some type of warning.
hints 2 N array An associative array with keys that correspond to points of possible user input failure and values that can have text inserted to indicate what mistake the user made. Generally, this is not manually manipulated after setting it up, but using the built-in add_error() method.
status 2 N integer 0 An integer that provides the overall processing result. Often used in conjunction with the message property since this can be used to determine the visual style of the message (such showing a page error in red or success message in green). Valid values are: 0 = success; 1 = completed with warnings; 2 = error; 3 = do nothing (often used with AJAX file uploads)
errors 2 N integer 0 An incremental counter that tots up the number of user input errors so far. This can be used to determine after validation whether to proceed to take the user's desired action or to halt processing and display an error.

3.4.7 Methods

UI filter

The following methods belong to the form_processor class.

Ver. Static Arguments Returns Purpose
__construct 1,2 N processing request (string)[, sub request (string), input source (string)] (void) As the constructor this, is implicitly called when the object is instantiated with the new keyword. The first argument tells the class exactly what request should be processed. This allows a single class file to contain code for handling multiple different forms. The remaining parameters are optional. The sub request is useful where a single form may have different way of processing it. Finally, the input source indicates where the user input comes from to populate the input property. By default, the "POST" method is assumed. This class also makes the following method calls: set_formname(). and construct. In addition, it sets up the is_submitted, strings and cache properties.
get_resourcepath 1,2 Y (void) string indicating the absolute resource path for the current package File (non HTML interface related) resources are stored in each package's resource directory under the main BEAR resource directory. This static function returns the path for the current package. This should be used instead of hard coding the full path.
save_cache 1,2 N data (mixed-ref) (void) Saves the supplied data to the session in a formname designation location.
clear_cache 1,2 N [all data (boolean)] (void) Can be used to free the cache. If the optional all data argument is set to TRUE, then all form caches are dumped. Otherwise, only the cache defined by the formname is dumped.
clean_real 1,2 Y user input (mixed-ref) (void) Acts directly on the supplied argument to strip leading and trailing whitespace from the user input. If the user input is an array, it acts on all elements in the array recursively. This should never be used directly on the input property or one of its keys unless you have at least validated the number of elements. Malicious users could spoof the form with gigantic arrays of data.
clean_input 1,2 N [key list (array)] (void) Provides a shorthand for calling clean_real() by passing only the input elements specified in the key list. Each matching key in input is passed to clean_real(). If omitted, it passes the entire input array (not recommended).
clean_dynamic_fields 2 N field list (array), error limit (integer) TRUE if no errors, otherwise FALSE Performs a clean_input() on all user input elements from a dynamic list where the number of items is not known or the exact indexes used. This assumes that the namespace ns is already set at it looks for the following: input[<namespace>_total] = total number of elements. FALSE is returned if this is greater than the error limit;; input[<namespace>_max] = the maximum ID used. It will look for all field names in the format <field_name>_<ID> up until the input[<namespace>_max] or it has already found fields totalling input[<namespace>_total] (whichever comes first).
exists 1,2 Y date (mixed-ref) TRUE if exists, otherwise FALSE Shorthand for testing that the supplied variable is both set, not null, or a string of zero bytes. These are the basic criteria for validating whether user input contains a value. To avoid a false positive in case where a user input field contains only whitespace characters, clean_input() or clean_real() should be called first.
ingest_response 2 N response (form_response) (void) Takes a form_response object and populates the current object's message, errors, cache, status, and hints properties. This method provides the critical link between generic application code and the UI filter.
update_field 2 N HTML ID (string), string (string) (void) Populates the current object's values array by inserting the supplied string as an HTML entity encoded string. The supplied HTML ID must not contain the form ns prefix as this is automatically prepended by responder.php.
reset_messages 2 N (void) (void) Undraws any message text that may already exist on the screen from previous other form submissions. It uses the contents of the current object's message_ids array to work off of and resets all tags in the HTML to empty strings that are labelled <message_ID>_message. It will not reset the message if the ID matches the current object's namespace ns value.
register_messages 2 N message prefixes (mixed) (void) The message prefixes may be either a single string or an array of strings that will be used to reset all such message elements. But this needs to be used with caution. It makes any backend form processor reliant on the front end GUI having those form prefixes. Therefore, using it makes a multi-form page behave more elegantly. Whereas not using it gives the GUI designer freedom to break up forms onto different pages with no back end code impact.
Backend

The folowing methods belong to the form_response class. All methods are public.

Ver. Static Arguments Returns Purpose
__construct 2 N (void) (void) Instantiates the class.
get_response 2 N (void) array containing the object's message, errors, cache, status, and hints property values. This the partner method for the form_response class' ingest_response() method. The contents may be useful in other ways for the UI filter but that is highly application dependent.
register_hints 2 N hint keys (array) (void) Creates all the hint indexes with null values.
set_message 2 N message code (string) (void) Sets the message code describing the processing state of the form. This code must correspond to a key in the strings INI file loaded by the form_processor object.
add_error 2 N hint key (string), string key (string) (void) Simultaneously sets a string in the hints property to the string referenced by the string key from the strings['hints'] property, and then increments the errors counter by 1.
validated_ok 2 N (void) TRUE if no errors, otherwise FALSE Returns TRUE if there have been no errors logged in the object so far. This allows application code to test whether the form is validated successfully at one or more stages.
set_status 2 N status (integer) (void) Sets the status of the object irrespective of any detected errors or not. Enumerated values are: 0 = success; 1 = completed with warnings; 2 = error; 3 = do nothing (often used with AJAX file uploads)
increment_errors 2 N (void) (void) Increments the error counter. Useful when there are errors that have not been registered with the add_error() method.
previous: AJAX next: form_processor