controller.md

Controller

In the KumbiaPHP Framework, the controller layer contains the code that connects business logic with presentation logic. It's divided into various components used for different purposes:

• Actions verify the integrity of requests and prepare the data required by the presentation layer.
• The Input and Session classes provide access to request parameters and the user's persistent data. These are frequently used in the controller layer.
• Filters are pieces of code executed for each request, before and/or after a controller, and even before and/or after an action. For instance, security and validation filters are commonly used in web applications.

This chapter describes all these components. For a basic page, you'll likely only need to write a few lines of code in the action class, and that's it. The other controller components are only used in specific situations.

Actions

Actions are fundamental in the application because they define the flow in which the application will respond to specific requests. Actions utilize the model and define variables for the view. When a web request is made in a KumbiaPHP application, the URL defines an action and the request parameters. Refer to the KumbiaPHP and its URLs section.

Actions are methods of a controller class, called ClassController, which inherits from the AppController class. They can be grouped into modules or not.

Actions and Views

Each time an action is executed, KumbiaPHP searches for a view with the same name as the action. This behavior is set by default. Usually, requests need to respond to the client who made the request. Therefore, if we have an action called greeting(), there should be an associated view called greeting.phtml. A more comprehensive chapter will explain views in KumbiaPHP.

Getting Values from an Action

KumbiaPHP URLs consist of several parts, each serving a specific function. To access the values from a controller that are sent in the URL, you can use some properties defined in the controller.

Consider the following URL:

http://www.example.com/news/show/12/

• Controller: News
• Action: show
• Parameters: 12

<?php
/** 
 * News Controller
 */ 
class NewsController extends AppController {
    /** 
     * Method to show the news item
     * @param int $id
     */ 
    public function show($id) {
        echo $this->controller_name; // news   
        echo $this->action_name; // show   
        // An array with all parameters sent to the action   
        var_dump($this->parameters);   
    }
}

It's essential to note the relationship between the parameters sent via URL and the action. In this sense, KumbiaPHP has a feature that makes executing actions secure: parameter transmission is limited to what is defined in the method (action). This means that all parameters sent via URL are arguments received by the action. See the KumbiaPHP and its URLs section.

In the previous example, the action show($id) defined only one parameter. If this parameter isn't sent, or if additional parameters are attempted, KumbiaPHP will throw an exception (in production, it shows a 404 error). This is the framework's default behavior, but it can be adjusted for different scenarios depending on the application's purpose.

In the "Hello World" example, you can practice the above by sending additional parameters to the hello($name) method, which only accepts one parameter (the name). If you visit http://localhost/kumbiaphp/greeting/hello/CaChi/additional, you'll see the exception generated by KumbiaPHP, as shown in Figure 3.1.

Figure 3.1: Exception due to incorrect number of parameters.

Following the same example, suppose we want the execution of the hello() action to ignore the number of parameters sent via URL. In that case, we need to tell KumbiaPHP to disregard the number of parameters passed in the URL by setting the $limit_params attribute to FALSE.

<?php
/** 
 * Greeting Controller
 */ 
class GreetingController extends AppController {
    /** 
     * Limits the correct number of action parameters 
     */ 
    public $limit_params = FALSE;
   ... methods ...
}

When this attribute is set to FALSE, it ignores the number of parameters passed to the action. Visit the following URL [http://localhost/kumbiaphp/greeting/hello/CaChi/param2/param3/] and you'll see that the exception in Figure 3.1 no longer appears, and you can see the action view as shown in Figure 3.2.

Figure 3.2: Ignoring the number of action parameters.

Conventions and Creating a Controller

Conventions

Controllers in KumbiaPHP must adhere to the following conventions and characteristics:

• The file should only be created in the app/controllers/ directory.
• The file should have the same name as the controller and end with _controller.php. For instance, greeting_controller.php.
• The file should contain the controller class with the same name as the file using CamelCase notation. Continuing
• with the above example, the controller class name would be GreetingController.

Creating a Controller

Let's put this into practice and create a controller called Greeting.

<?php
/** 
 * Greeting Controller
 */ 
class GreetingController extends AppController {
}

AppController Class

It's important to remember that KumbiaPHP is an MVC and OOP framework. In this sense, there is the AppController, which is the superclass for controllers. All controllers must inherit (extend) this class to have the attributes and methods that facilitate interaction between the model and presentation layers.

The AppController class is defined in app/libs/app_controller.php. It's a very easy-to-use class and a key component within the MVC architecture.

Default Actions and Controllers

Filters

Controllers in KumbiaPHP have useful methods that allow checks to be performed before and after executing a controller and an action. Filters can be understood as a security mechanism in which the request processing can be altered as needed (e.g., checking if a user is authenticated).

KumbiaPHP runs filters in a logical order to handle checks at the application level or specifically for a controller.

Controller Filters

Controller filters run before and after a controller and are useful for application-level checks, such as verifying the module being accessed or user sessions. They can also protect the controller from inappropriate data.

Filters are methods we override (OOP feature) to give them the desired behavior.

initialize()

KumbiaPHP calls the initialize() method before executing the controller, and it is defined for use in the AppController class. See the AppController section.

finalize()

KumbiaPHP calls the finalize() method after executing the controller, and it is defined for use in the AppController class. See the AppController section.

Action Filters

Action filters run before and after an action and are useful for controller-level checks, such as verifying that a request is asynchronous or changing response types. They can also protect actions from inappropriate information.

before_filter()

KumbiaPHP calls the before_filter() method before executing the controller's action. It is useful for checking if a request is asynchronous, among other things.

after_filter()

KumbiaPHP calls the after_filter() method after executing the controller's action. It's useful for modifying session values, among other tasks.