MVC in punFramework
How to use punFramework?
punFramework is a very simple MVC (Model-View-Controller) framework incorporated in fluxBB forum. It is designed as a tool allowing to add additional components to the forum like news, articles or other php script. punFramework can't modify punBB itself, it add extra pages with your code. The MVC design pattern allows you to create modules in a clean, unified and easy way.
All your code (modules) is accessed using mvc.php. You can rename the file to any name you want.
- Controllers are located in punFramework/controllers/
- Each controller is a PHP class that inherits punController class.
- Filename must be the same as the class name, Class news would be saved as news.php
- A class skeleton would look like this:
- Each module should have its own controller
- Each controller class method is responsible for a certain page like "show news" "add news", "delete news". each of those examples should be methods of the controller class.
- Class should return content to display rather than echo it.
URL RouterpunFramework uses simple url router:
- CONTROLLER_NAME is the name of the controller (for example "news" will call news controller form punFramework/controllers/news.php).
- METHOD_NAME is a name of a method from the controller.
- controller and method names may only contain alphabet character! small and BIG letters may be used
- If you don't specify a METHOD_NAME framework will try to call "index" method by default.
Available punBB variablesThe controllers have access to:
- $this->pun_user - $pun_user array with user data
- $this->db - the $db object for database operations
- $this->pun_config - $pun_config array with config data
- $this->pun_url - $pun_url array with urls to common places
- $this->lang_common - $lang_common array with common translation string.
- you can use print_r(The array); to see array content
ViewsViews should contain all the look and feel of your modules - they are templates. Each view must be saved as a NAME.php file, and it can contain PHP code.
- To load a view in a controller you use:
- VIEW_NAME is the view filename without .php.
- views are saved in punFramework/views/
- view is returned, not displayed
- Second argument is optional - an associative array with key => value which will be passed to the view.
- Passed array is available in views under $data variable ($data['key'] will show your data assigned for that key)
- You should use punBB styles as much as possible
ModelsModels are classes similar to Controllers (inherit punRoot) but they should contain only methods that use the database (like add, edit, delete entries). Use of models (or views) is optional but in the end will make your modules easy to modify and to extend.
- Skeleton of a model would look like this:
- You save models in punFramework/models as CLASSNAME.php
- Each database operation should have its own method.
- You can use $this->db - the standard punBB object for database operations
- You can use also a wrapper (available in controllers and models) CLASSNAME::query inherited from punRoot/punController
- ::query("SQL QUERY") wrapper will return an associative array for all SELECT queries and for non-Select it will execute the query and return true.
- The wrapper will raise an exception on any error (see error handling)
- To load model in a controller use:
- CLASSNAME is the name of the controller class
- MODELNAME is the name of the model class
- $object - under this variable you will have the model class object ready to use
- In controllers you can use:
CLASSNAME::render_template('title', 'content');Which will return a generic punBB XHTML/CSS "box".
- You can also quickcheck users state:
CLASSNAME::is_admin() # returns True if current user is Admin (group ID 1), else - False CLASSNAME::is_user() # returns True if current user is a normal user (group ID 3), else - False CLASSNAME::check_login() # returns True if current user is logged in
Error handlingWhen a framework encounters an error it will raise an Exception - a nice error handling "thing" which will be caught by the framework
- error page will be displayed and the Exception message will be saved to debug.php (open it in a editor to get the full error log)
- In your controllers you should use Exceptions for error handling, for example:
- The code will stop executing in the place of the exception generation. punFramework will catch it and show the error message etc. See http://www.php.net/exceptions for info about exceptions
- Exceptions are saved to debug.php