Custom Libraries

We usually recommend abstracting repetitive code into helpers, but sometimes you need logic that doesnt quite fit into a controller, model, or helper. Thats where custom libraries come in.

Say you need a function to calculate the distance between two points on a map. Instead of scattering this logic across your app, you can create a reusable library and use it anywhere: in controllers, helpers, or views.

Custom libraries arent stored in the app folder because Leaf MVC doesnt autoload them by default. Instead, store them in the lib folder, and Leaf will pick them up. This allows flexibility, especially when working with libraries that dont follow an autoloadable structure and need to be required manually.

Autoloading Libraries

Leaf MVC only loads items in the app folder by default. To add any external library to your project, you need to set Leaf MVC up for it using the console. You can do this by running the following command:

leaf config:lib

That's it! A lib folder will be created in your application root and Leaf will now autoload any library you place in this folder.

Creating a Library

To create a library, simply create a new file in the lib folder. For example, let's create a library called Math.php:

<?php

namespace MyRandom\Name\Space;

class Math {
  public static function add(int $a, int $b): int {
    return $a + $b;
  }
}

Using a Library

To use a library, you must first import it. You can then use it like any other class. For example, let's import the Math library we created above:

<?php

namespace App\Controllers;

use MyRandom\Name\Space\Math;

class HomeController extends Controller {
  public function index() {
    $sum = Math::add(1, 2);
    echo view('home', ['sum' => $sum]);
  }
}

Library Structure

As mentioned above, libraries can be just about anything. They are completely based on your own preference. However, it is recommended that you keep your libraries as simple as possible. Below is the same Math library from above, but this time it is a simple function instead of a class:

<?php

namespace Lib;

function add(int $a, int $b): int {
  return $a + $b;
}

You can then use this library like so:

<?php

namespace App\Controllers;

use function Lib\add;

class HomeController extends Controller {
    public function index() {
        $sum = add(1, 2);
        echo view('home', ['sum' => $sum]);
    }
}

Using a non-autoloadable library

Some older libraries may not follow the autoloadable structure but are linked together using require statements. You can still use these libraries in your Leaf MVC application.

To use such a library, you need to add it's index file to the lib folder and require any other files it needs in the index file. For example, let's say you have a library called MyLibrary that has the following structure:

MyLibrary/
  index.php
  file1.php
  file2.php

You can add this library to your Leaf MVC application by moving the MyLibrary folder to the lib folder and creating an index.php file in the MyLibrary folder that requires the other files:

app/
lib/
  mylibrary.php
  MyLibrary/
    index.php
    file1.php
    file2.php

And in lib/mylibrary.php:

<?php

require __DIR__ . '/MyLibrary/index.php';

From here, you can use MyLibrary and all it's functions in your Leaf MVC application.