Custom Libraries

What are Libraries?

In programming, a library is just a collection of code designed to do a specific job. Think of it like a toolkit. If you're a plumber, you don't build a new wrench every time you visit a house. You have a trusted wrench in your toolbox that you use over and over. A custom library in CodeIgniter is your software wrench—a reusable class that you can call from anywhere in your application.

You've already used CodeIgniter's built-in libraries for things like handling sessions or emails. But what happens when you have your own special logic that you need in multiple controllers? You could copy and paste the code, but that's messy and hard to maintain. A better way is to package that logic into your own custom library.

Libraries help you follow the Don't Repeat Yourself (DRY) principle, leading to cleaner, more modular, and easier-to-manage code.

Building Your First Library

Let's create a simple library to manage user-related tasks. We'll call it UserTools. Its job will be to take a user's first and last name and format them into a full name.

First, create a new file inside your app/Libraries directory. CodeIgniter looks in this specific folder for custom libraries. Name the file UserTools.php. The filename must match the class name.

<?php

namespace App\Libraries;

class UserTools
{
    public function formatName(string $firstName, string $lastName): string
    {
        // Trim whitespace and capitalize the first letter of each name.
        $first = ucfirst(trim($firstName));
        $last = ucfirst(trim($lastName));

        return "{$first} {$last}";
    }
}

Notice the namespace is App\Libraries. This is crucial for CodeIgniter's autoloader to find your class. Inside the class, we have a single public method, formatName, which does our logic. It's simple, but it's a perfect candidate for a library because you might need to format names in many different parts of your application.

Using and Autoloading

Now that our library exists, how do we use it? You can load it manually within any controller method.

<?php

namespace App\Controllers;

class Profile extends BaseController
{
    public function show()
    {
        $userTools = new \App\Libraries\UserTools();
        $fullName = $userTools->formatName('john', ' doe ');

        echo $fullName; // Outputs: "John Doe"
    }
}

This works, but creating a new instance every time is tedious. What if you want your library to be available everywhere, just like a built-in one? That's where autoloading comes in.

To make our UserTools library available globally, we can register it as a service. Services are a powerful feature in CodeIgniter 4 that manage class instances for you. Open the app/Config/Services.php file.

Inside this file, you can add a new static method for your library. The convention is to name the method after your library in camelCase.

// Inside app/Config/Services.php

use App\Libraries\UserTools;
use Config\BaseService;

class Services extends BaseService
{
    // ... other services

    public static function userTools($getShared = true)
    {
        if ($getShared) {
            return static::getSharedInstance('userTools');
        }

        return new UserTools();
    }
}

The getSharedInstance part ensures that you get the same single instance of your library every time you ask for it, which is efficient. Now, you can access your library from any controller, model, or even another library using the service() function.

// In any controller
public function show()
{
    $userTools = service('userTools');
    $fullName = $userTools->formatName('jane', ' smith');

    echo $fullName; // Outputs: "Jane Smith"
}

Best Practices

As you build more complex libraries, keep a few guidelines in mind:

Single Responsibility: A library should do one thing and do it well. Our UserTools library handles user-related utility functions. Don't add unrelated logic, like payment processing, to it. Create a new PaymentGateway library instead.
Statelessness: Whenever possible, make your library methods stateless. This means they don't rely on previous interactions. The formatName method is a perfect example; its output depends only on the inputs you give it right now. This makes the code predictable and easier to test.
Dependencies: If your library needs other CodeIgniter components (like the database service), load them inside the library's constructor. This keeps all the dependencies clearly defined in one place.

<?php

namespace App\Libraries;

class AuditTrail
{
    protected $db;

    public function __construct()
    {
        $this->db = \Config\Database::connect();
    }

    public function logAction(string $message)
    {
        // Code to write the message to a database log table
    }
}

Following these practices will ensure your custom libraries enhance your application's architecture, making your code a pleasure to work with as it grows.

Ready to check your understanding?

Quiz Questions 1/5

In a CodeIgniter 4 application, where should you create the file for a new custom library?

Quiz Questions 2/5

If you name your custom library class InvoiceManager, what must the filename be?

By building your own libraries, you take a big step toward writing professional, maintainable, and highly organized applications in CodeIgniter.

Advanced CodeIgniter 4 Development