Controllers

The Controller is the part of a module that handles a request. Controllers are responsible for receiving a request, and returning a response. In Alloy, this literally translates to each web-accessible controller method receiving a Request object as the first parameter, and using a return statement to respond with a string, view, or other response type.

Alloy does not automatically load or attach anything onto your controller, like views or models. The dispatch cycle in Alloy is extremely lightweight, and does little more than instantiate your controller class and call the requested method. This allows Alloy to dispatch HMVC nested sub-requests just like normal code libraries, and at near-zero cost.

Alloy requires you to be a little more explicit about what you want to do within a controller action than most other php frameworks. The rendered content is explicitly set by you issuing a return statement rather than the dispatch loop automatically (implicitly) loading a view template of the same name as the action called, assuming it's going to be there. This is intentional, and allows you greater flexibility over what content is rendered, when, and how.

Method Conventions - RESTful by Default

Web-Accessible controller methods are appended with either "Action" or "Method", depending on the request context. If the action "view" is determined from a matched URL route with a HTTP GET request, the method "viewAction" will be called. Conversely, if the same route is matched with a HTTP DELETE request, the method "deleteMethod" will be called instead. This design prevents incidental deletions and conforms to REST principles because a user will never be able to delete a resource with a simple GET request if you follow this convention. 

Example URLs and controllers based on default URL routes distributed with Alloy. Routes are easy to change and customize if you do not want or desire this behavior.

GET /events/1743
Controller: app/Module/Events/Controller.php
Method: viewAction

GET /users/new
Controller: app/Module/Users/Controller.php
Method: newAction

POST /users/new
Controller: app/Module/Users/Controller.php
Method: postMethod

DELETE /users/new
Controller: app/Module/Users/Controller.php
Method: deleteMethod

Alloy was designed with REST in mind from the beginning. The "{name}Method" controller methods are special because they can only be accessed by using the corresponding HTTP method. This semantic difference enables true RESTful behavior, because it separates processing actions from requesting ones, while still allowing you to use the same URL.

All web-accessible controller methods accept exactly one parameter: an \Alloy\Request object. Any named parameters captured or set by the matched route will be set on the request object in the dispatch cycle so they can be easily accessed anywhere in your application.

The "Hello World" Example

Also known as the simplest example possible to make the phrase "Hello World" appear on the screen within the framework's rules and boundaries.


            

              namespace Module\Home; use Alloy; class Controller extends Alloy\Module\ControllerAbstract { public function indexAction(Alloy\Request $request) { return "Hello World!"; } }
            

            

          

          

            

              Note the namespace declaration at the top - this follows the PSR-0 namespace autoload spec and will mirror the module's folder path. So with \Module\Home, this file would be expected to be at: app/Module/Home/Controller.php
            

          

        

      

      
      

    

  

  

Related Links