Object-Relational Mapping (ORM) Lite for WordPress Plugins

Previously in this course, we covered High-Concurrency Data Handling in WordPress Plugins, focusing on row-level locking and transaction integrity. While those techniques ensure database reliability, writing raw SQL for every CRUD operation quickly leads to unmaintainable code. In this lesson, we’ll implement an ORM Lite layer to bridge the gap between our database schema and clean, object-oriented PHP.

Why Build an ORM Lite?

In a professional plugin like our Knowledge Base, you often deal with dozens of custom tables. Writing $wpdb queries everywhere creates tight coupling: if you rename a column, you have to hunt down every query. An ORM Lite approach uses Entities (representing a single record) and Query Builders (representing a collection) to encapsulate SQL logic.

By moving from raw SQL to an object-based API, you gain:

1. Type Safety: Methods that return specific objects rather than associative arrays.
2. Encapsulation: Logic for calculating fields or formatting data resides in the entity, not the controller.
3. DRY Code: Shared query logic (like pagination or status filtering) can be reused across repositories.

Creating the Base Entity Class

The BaseEntity acts as a data container. It should be lightweight, handling property assignment and basic data normalization.

PHP
namespace KnowledgeBase\ORM;

abstract class BaseEntity {
    protected array $data = [];

    public function __construct(array $data = []) {
        $this->data = $data;
    }

    public function __get($key) {
        return $this->data[$key] ?? null;
    }

    public function toArray(): array {
        return $this->data;
    }
}

By using the magic __get method, we create a flexible interface that allows us to add custom getters later (e.g., getTitle() or getFormattedDate()) without breaking existing code.

Implementing Dynamic Field Mapping

To make this useful, we need a way to transform database rows into specific entity classes. We use a Mapper or a static factory method. Let’s extend our Knowledge Base Article entity.

PHP
namespace KnowledgeBase\Entities;

use KnowledgeBase\ORM\BaseEntity;

class Article extends BaseEntity {
    public function getExcerpt(int $length = 50): string {
        return wp_trim_words($this->content, $length);
    }
}

The mapping logic resides in our repository, ensuring that every database result is cast into an Article object automatically. This is significantly safer than passing raw arrays around, as it prevents Insecure Deserialization issues by strictly defining the object structure.

Building the Query Builder

A Query Builder constructs SQL strings dynamically based on method calls. This allows us to chain filters without concatenating strings manually.

PHP
namespace KnowledgeBase\ORM;

class QueryBuilder {
    protected string $table;
    protected array $wheres = [];

    public function __construct(string $table) {
        $this->table = $table;
    }

    public function where(string $column, string $value): self {
        $this->wheres[] = "$column = '$value'";
        return $this;
    }

    public function get(): array {
        global $wpdb;
        $sql = "SELECT * FROM {$this->table}";
        if (!empty($this->wheres)) {
            $sql .= " WHERE " . implode(' AND ', $this->wheres);
        }
        return $wpdb->get_results($sql, ARRAY_A);
    }
}

Note: In production, always use $wpdb->prepare() within the get() method to prevent SQL injection.

Hands-on Exercise: Implement a Repository

1. Create a KnowledgeBase\Repositories\ArticleRepository class.
2. In the constructor, inject the database table name.
3. Add a find(int $id) method that uses the QueryBuilder to fetch a single record.
4. Return an instance of Article using the data returned from the database.

Common Pitfalls

• Over-Engineering: Don't try to build a full-featured ORM like Doctrine. Keep it "Lite." If your queries involve complex JOINs across five tables, stick to raw SQL via a repository method.
• Performance: Loading thousands of objects into memory can exhaust the PHP memory limit. Use yield generators or limit result sets when fetching large collections.
• Ignoring $wpdb->prepare: Even when using an ORM, the underlying data should never be concatenated directly into SQL strings. Always pass values through the prepare() method.

Recap

We’ve moved from raw SQL to an object-oriented approach by creating a BaseEntity for data representation and a QueryBuilder for SQL abstraction. This pattern keeps the Knowledge Base plugin modular and makes data manipulation predictable. You can now easily expand your data layer without duplicating logic or risking manual query errors.

Up next: Advanced Query Filters, where we’ll allow developers to extend our repository queries using WordPress hooks.