3.2 How It Works

January 22nd, 2026

The usage of the form_processor class is fairly straightforward but there are things that can easily overlooked. This example shows it being used in a UI filter with processing offloaded to the generic application code. This uses the new v2 functionality to separate the two code sets but link them logically.

In this example, the UI filter class provides an interface for a simple end-user feature that registers users.

• Logical flow
• Creating the UI filter class
• Creating generic application code

3.2.1 Logical Flow

The flow for handling forms is clearly more complex than a basic two file HTML/PHP configuration or a simple self processing PHP page. However, it is not hugely complicated and allows for excellent scalability and reusability. In this example, the client-side UI has been greatly simplified. More complex AJAX scenarios are the expected usage but the backup use of form processing remains completely unchanged.

Fig 1. Process and file relationships for form processing

In this example, the following happens:

1. The browser requests the page http://<domain>/my_app/some_form.acx`.
2. On form submission, my_app/html_filters/some_form.php is loaded from the CGI directory, which in turn loads form_processor_v2.php and extends the form_processor class contained in it.
3. Strings that are needed to give feedback to the end user in their native language are loaded from the resources path under my_app/preload/<LANGUAGE>/dome_form.ini. form_processor takes care of this automatically when instantiated.
4. As and when required, the filter object includes some generic application code from my_app.php, also in the CGI directory and makes direct calls to functions loaded in that file (usually public static methods).
5. Any form processing functions or methods called in my_app.php internally create new form_response objects and update this object state as they process the form data. None of the code in this file should be interface aware (it should care whether the form was submitted via HTML, mobile app, or API). This form_response object is always returned by the called function or method.
6. The filter object of form_processor type, ingests the returned form_response object and uses this to update its own state.
7. Finally, the filter object can provide a response back to the browser that is formatted in a way suitable for the end user's interface (a browser here) and language.

3.2.2 Creating The UI Filter Class

As shown above, the developer needs to provide at least a class file (or add methods to an existing class file) for processing the form.

Your form will normally to be a file located within a directory called html_filters under your package's CGI directory. In the "my_app" example, all form handling class files would be located under /bear/web_applications/cgi/my_app/html_filters/.

There is no recommendation on how many form processing class files to create. You could create one file per form; one file per logical group of forms or even one monolithic file containing methods for processing every form in your web application. All of these approaches have trade-offs in terms of performance and manageability. You are free to use whichever approach works best for you.

Using the user registration scenario, we allow users to register with just a username and password and minimal validation. The sample below shows our class file. Some AJAX required properties and libraries are inherited from the base class form_processor but are still shown here commented out so that you can see how everything works.

<?php /* CLASS FILE FILENAME: my_app/html_filters/some_form.php CLASS: register_user AUTHOR: Joey Dobias COPYRIGHT: Copyright (c) 2015 Joey Dobias LAST MODIFIED: 2015-02-03 DESCRIPTION: Provides user regsitration functionality. */ include_once('shared_lib/form_processor_v2.php'); // include('shared_lib.php'); class some_form extends form_processor{ // public $message; // (str) Display text at head after processing. // public $hints; // (ary) Correct user input hints to display. // public $status=0; // (int) Exit code. 0=SUCESS, 1=WARN, 2=ERROR, 3=NULL // public $ns; // (str) Form namespace used by AJAX responses. // protected $input; // (ary) All user input from the HTML form. /* -- METHOD (void) construct(request(str), sub request(str)) -- MANDATORY ------------------------------------------------------ Main logic switch for processing forms ------------------------------------------------------ */ protected function construct($request,$subrequest){ $this->ns=&$request; switch($this->ns){ case 'register': $this->run_register(); break; case 'img_upload': // Place holder for image upload form break; default: die("Unknown request '$request' passed to developer->construct()."); break; } } /* -- METHOD (bool) run_register() -- Processes the user regsitration form ------------------------------------------------------ */ protected function run_register(){ include_once('my_app.php'); $response=my_app::register($this->input); $this->ingest_response($response); } } ?>

In the sample code above, the class some_form simply calls its own run_register() method which itself does nothing more than pass off form processing to the generic application code.

1. some_form.acx would instantiate a some_form object and pass the request instruction (register) to it (in this example, we ignore the subrequest). This request string is used to determine which form to process.
2. Since the request is "register", the constructor calls the run_register() method.
3. run_register() makes a call to include the generic application code in my_app.php.
4. Finally, if no additional processing is required, a simple single line call can be made to ingest_response() by passing a call to the generic application code that processes the form, my_app::register(). The only thing we need to pass to the generic application code is the form input parameters contained in input.
5. The message and the hints (if any) result in changes to the HTML directly or via AJAX.

3.2.3 Creating the Generic Application Code

As mentioned, the application code should be completely divorced from the interface and be reusable, without modification or conditional branches, regardless of whether the input originally came from an HTML page, mobile or API call. The filter doing form handling in the previous section is responsible for all that stuff. To extend the example we started, a public static method register() is needed in my_app.php.

<?php /* CLASS FILE FILENAME: my_app.php CLASS: my_app AUTHOR: Joey Dobias COPYRIGHT: Copyright (c) 2015 Joey Dobias LAST MODIFIED: 2015-02-03 DESCRIPTION: Generic code for MyApp application */ class my_app { /* -- METHOD (form_response) register(user input(array)) -- ------------------------------------------------------ Processes the user regsitration form ------------------------------------------------------ */ public static function register(&$input){ $response=new form_response(); $response->register_hints('username','password'); // Validate username (must exist and be longer than 8 characters) if(!form_processor::exists($input['username'])){ $response->add_error('username','required'); }elseif(strlen($input['username'])<8){ $response->add_error('username','too_short'); } // Validate password (must exist, be minimum of 8 characters long) if(!form_processor::exists($input['password'])){ $response->add_error('password','required'); }elseif(strlen($input['password'])<8){ $response->add_error('password','too_short'); } // Register the user if things are okay if($response->validated_ok(){ / SOME CODE TO REGISTER USER / $response->set_message('success'); }else{ $response->set_message('error'); $response->set_status=2; } return $response; } } ?>

In the sample above, the file my_app.php contains the generic application code to validate a user registration form without knowing anything about the interface. Notice that we use methods from form_processor_v2.php but never include this file. It is never needed since any methods that process forms are always going to be called by filters like my_app/html_filters/some_form.php.

1. The generic application code method needs at least the user input array so we label that argument $input.
2. my_app::register() first instantiates the form_response object.
3. The form_response object calls register_hints() for the purpose of setting up per field feedback.
4. Input is validated in a generic way. Access to public static methods in form_processor and all the private methods in form_response are available. So incrementing errors with error codes that match strings in the form's INI file is built in as soon as form_response gets instantiated.
5. The form is evaluated in whole by calling the form_response object's validated_ok() method. If there are no errors, then some code is run to register the user and the status message code is set. Otherwise we can set an alternative message code and set the form_resposne object's status to 2 (error).
6. And finally the form_response object is returned.