Extending Lima

Application structure
Custom base controllers
Custom views
Runtime config
Using your own services

Application structure

Lima is intentionally small, so most application-specific decisions belong in your project rather than in the framework. The recommended structure from Getting Started is a good default, but you can move controllers, models, and templates when a project needs something different.

Use .env for the paths Lima needs at boot:

LIMA_CONTROLLER_PATH=Controllers
LIMA_MODEL_PATH=Models
LIMA_TEMPLATE_DIR=views

The controller and model paths are relative to the app folder. The template directory is relative to your project root.

Custom base controllers

One of the easiest ways to extend Lima is to create a controller that your application controls.

use Lima\Core\Controller;

class AppController extends Controller
{
    protected function sharedViewData(): array
    {
        return [
            'siteName' => 'My Lima App',
        ];
    }

    protected function render($template, array $data = []): bool
    {
        return $this->view($template, array_merge($this->sharedViewData(), $data));
    }
}

Then extend it in your controllers:

class Home extends AppController
{
    public function index(): void
    {
        $this->render('home');
    }
}

This is a practical place for authentication checks, shared view data, redirects, or service access.

Custom views

Lima's view object can be replaced through system/overrides.php.

<?php

$overrides = [
    'View' => App\Support\AppView::class,
];

Your custom view can extend the core view and add helpers used across templates.

namespace App\Support;

class AppView extends \Lima\Core\View
{
    public function asset(string $path): string
    {
        return '/assets/' . ltrim($path, '/');
    }
}

After this, $view inside your PHP templates will be an instance of your custom class.

<link rel="stylesheet" href="<?php echo $view->asset('css/style.css'); ?>">

Runtime config

The Lima\Core\Config class provides a small in-memory config store.

use Lima\Core\Config;

Config::set('site.name', 'My Lima App');

$name = Config::get('site.name');

This is useful for values built at runtime, feature flags, or application settings that you don't want to pass through every method call. For sensitive values and deployment-specific settings, keep using .env.

Using your own services

Lima doesn't force a service container or application layer on you. For small projects, creating services directly in a controller can be enough.

class Newsletter extends \Lima\Core\Controller
{
    public function subscribe(): void
    {
        $service = new NewsletterService();
        $service->subscribe($_POST['email'] ?? '');

        $this->view('newsletter/thanks');
    }
}

For larger projects, build a small application layer of your own and call it from controllers. This keeps controllers thin while leaving Lima's core untouched.

class Account extends AppController
{
    public function update(): void
    {
        $this->accounts->updateProfile($_POST);

        header('Location: /account');
        exit;
    }
}

The important idea is to let Lima handle the request flow, then keep your business logic in classes that make sense for your project.

What to read next

If you're extending the framework around request handling, read Routing and Controllers and Views. If you're extending data behaviour, read Models and Database.

The Docs