FuelPHP Framework Guide — HMVC Modular Architecture

FuelPHP is a flexible, community-driven PHP framework featuring HMVC (Hierarchical Model-View-Controller) architecture — allowing controllers to call other controllers for true modular code organization.

What You’ll Learn

By the end of this guide, you’ll understand FuelPHP’s HMVC architecture, use the ORM with relations, work with the Auth framework, and organize code into reusable modules.

Why FuelPHP Matters

FuelPHP’s HMVC architecture makes it ideal for complex applications where components need to communicate internally — like dashboard widgets calling data controllers, or modular API services. At DodaTech, this pattern is valuable for Durga Antivirus Pro’s modular dashboard where threat detection, reporting, and system health each operate as independent modules.

FuelPHP Architecture

    flowchart TD
  A[Request] --> B[Controller]
  B --> C{Need data?}
  C -->|Yes| D[Model]
  C -->|Yes| E[Another Controller - HMVC]
  D --> F[View]
  E --> F
  F --> G[Response]
  

Key Features

HMVC Architecture

class Controller_Products extends Controller
{
    public function action_index()
    {
        // Request another controller internally
        $sidebar = Request::forge('sidebar/stats')->execute();
        $data['products'] = Model_Product::find_all();
        $data['sidebar'] = $sidebar;
        return View::forge('products/index', $data);
    }
}

ORM with Relations

class Model_Product extends \Orm\Model
{
    protected static $_belongs_to = ['category'];
    protected static $_has_many = ['reviews'];
    protected static $_many_many = ['tags'];

    protected static $_observers = [
        'Orm\\Observer_CreatedAt' => ['events' => ['before_insert']],
        'Orm\\Observer_UpdatedAt' => ['events' => ['before_save']],
    ];
}

FuelPHP’s Oil CLI handles code generation, database migrations, and running tasks:

php oil generate scaffold product name:string price:decimal
php oil refine migrate

How FuelPHP Processes Requests

FuelPHP processes each request through a well-defined lifecycle. Understanding this flow helps you write better code and debug issues faster:

1. Entry point — public/index.php loads the framework core, sets up error handling, and bootstraps the application environment.
2. Routing — The Router matches the requested URL against defined routes. FuelPHP supports literal routes, regex routes, and module-based routing.
3. Controller dispatch — The matched controller is instantiated and the action method is called with extracted route parameters.
4. Before hooks — Any before() method on the controller runs. This is ideal for authentication checks or loading shared data before the action executes.
5. Action execution — The action method runs. It may call models, make HMVC sub-requests to other controllers, or query the ORM for data.
6. After hooks — The after() method runs, typically used to modify the response or add common HTTP headers.
7. View rendering — The View object receives data from the controller, renders the template, and sends output to the client.
8. Shutdown — FuelPHP triggers shutdown events, allowing observers and modules to perform cleanup tasks.

Building RESTful APIs with Controller_Rest

FuelPHP provides a dedicated Controller_Rest base class for building REST APIs. It handles content negotiation, HTTP method detection, and automatic response serialization:

class Controller_Api_Products extends Controller_Rest
{
    public function get_list()
    {
        $products = Model_Product::find_all();
        return $this->response($products);
    }

    public function post_create()
    {
        $product = Model_Product::forge(Input::json());
        if ($product and $product->save()) {
            return $this->response([
                'id' => $product->id,
                'message' => 'Product created'
            ], 201);
        }
        return $this->response(['error' => 'Validation failed'], 400);
    }

    public function put_update($id = null)
    {
        $product = Model_Product::find($id);
        if (!$product) {
            return $this->response(['error' => 'Not found'], 404);
        }
        $product->from_array(Input::json());
        $product->save();
        return $this->response($product);
    }

    public function delete_delete($id = null)
    {
        if ($product = Model_Product::find($id)) {
            $product->delete();
            return $this->response(['message' => 'Deleted'], 200);
        }
        return $this->response(['error' => 'Not found'], 404);
    }
}

Expected output: GET /api/products/list returns all products as a JSON array. POST /api/products/create with {"name": "Widget", "price": 9.99} returns {"id": 1, "message": "Product created"} with HTTP 201. The put_update action updates a product by ID, and delete_delete removes one. FuelPHP’s Controller_Rest automatically maps HTTP verbs to action prefixes (get_, post_, put_, delete_) and serializes responses as JSON, XML, or other formats based on the Accept header.

Modular Application Architecture

FuelPHP’s module system packages controllers, models, views, configs, and tasks into self-contained directories:

fuel/app/modules/dashboard/
├── classes/
│   ├── controller/
│   │   └── admin.php
│   └── model/
│       └── stat.php
├── config/
│   └── routes.php
├── views/
│   └── admin/
│       └── index.php
└── tasks/
    └── cleanup.php

Modules register their own namespace and can be enabled or disabled through the application config. They communicate via HMVC requests, event hooks, or shared database models. This structure is perfect for the Durga Antivirus Pro dashboard — Threat Detection, Reporting, and System Health each live in their own module but share the centralized Auth and ORM layers.

Performance Optimization

• ORM query caching — Pass ['caching' => true, 'cache_prefix' => 'products'] to find_all() to reduce database round-trips.
• Output caching — Use Cache::call('dashboard_stats', function() { ... }, 3600) to cache rendered HTML fragments for an hour.
• Config caching — Run php oil refine config:cache in production to merge all config files into a single cached array.
• Profile before optimizing — FuelPHP’s built-in profiler shows query counts, execution times, and memory usage per request so you can identify real bottlenecks.

Common Mistakes

1. Misunderstanding HMVC overhead — Each internal request creates overhead. Use HMVC for modular widgets, not for every database query.

2. Not using Orm observers — Observers automate timestamps, validation, and slug generation. Forgetting them leads to manual code.

3. Ignoring the Auth framework — FuelPHP has built-in authentication with ACL and groups. Don’t reinvent login logic.

Practice Questions

1. How does HMVC differ from regular MVC?

HMVC allows controllers to call other controllers internally. Regular MVC restricts controllers to calling models and views only. This allows modular widget composition.

2. What’s the Oil CLI used for?

Code generation (scaffolds, models, controllers, migrations), running database migrations, and executing custom tasks.

3. What are ORM observers?

Event-driven hooks on model operations — automatically set timestamps, validate data, create slugs, or cascade operations.

4. How do you define a belongs_to relationship in FuelPHP’s ORM?

Add protected static $_belongs_to = ['category']; to your model class. FuelPHP assumes the foreign key is category_id and the related model is Model_Category. Customize with array syntax: $_belongs_to = ['category' => ['key_from' => 'category_id', 'model_to' => 'Model_Category']];.

5. What is the purpose of the before() method in a controller?

The before() method runs before the action method. It is typically used for authentication checks, loading common data, or setting up the view environment. If before() returns false or throws an exception, the action never executes.

Challenge: Build a modular blog system with FuelPHP. Create a Blog module containing a Post model with ORM relations to Category (belongs_to) and Comment (has_many). Use HMVC to embed a comment form on the post page. Expose a REST API endpoint for fetching posts as JSON. Include Oil migrations for the database schema and an observer that auto-generates URL slugs from post titles.

Mini Project — Threat Dashboard Widget: Build an HMVC widget for the Durga Antivirus Pro dashboard that displays real-time threat statistics. Create a Controller_Widget_Threats that calls Controller_Api_Stats internally via Request::forge(). The widget should show total threats blocked today, top 3 threat types, and system status. Use ORM caching to keep data fresh for 60 seconds.

FAQ

{< faq >}

What is Fuelphp?

Fuelphp refers to the core concepts and practices used to build and manage modern web applications. Understanding it is essential for web developers.

Do I need prior experience to learn Fuelphp?

Basic familiarity with web development concepts helps, but Fuelphp can be learned step by step even as a beginner.

How long does it take to learn Fuelphp?

With consistent practice, you can grasp the fundamentals in a few days to a week. Mastery takes ongoing practice and real-world projects.

Where can I use Fuelphp in real projects?

Fuelphp is used in a wide range of applications — from simple websites to complex enterprise systems, depending on the specific tools and technologies involved.

What are common tools used with Fuelphp?

The specific tools depend on the technology stack, but version control (Git), package managers, and testing frameworks are commonly used alongside most development topics.

{< /faq >}

What’s Next

What’s Next

Congratulations on completing this Fuelphp tutorial! Here’s where to go from here:

• Practice daily — Consistency is more important than long study sessions
• Build a project — Apply what you learned by building something real
• Explore related topics — Check out other tutorials in the same category
• Join the community — Discuss with other learners and share your progress

Remember: every expert was once a beginner. Keep coding!