Getting Started with Gateway & Eloquent ORM

Gateway is a WP plugin that integrates the famed Eloquent ORM from Laravel. This enables you to create models and work with data efficiently. Let’s get started!

Install Gateway like any other WordPress plugin. At the time of this writing the wordpress.org plugin directory submission is still under review. You can get the latest Gateway by visiting https://arcwp.ca/packages/gateway.

Your First Model

Once Gateway is installed, create a simple Post collection. In your theme or plugin, add:

<?php

namespace YourNamespace\Collections;

use \Gateway\Collection;

class Post extends Collection
{
    protected $key = 'post';
    protected $table = 'wp_posts';
}

<?php

namespace YourNamespace\Collections;

use \Gateway\Collection;

class Post extends Collection
{
    protected $key = 'post';
    protected $table = 'wp_posts';
}

Next you’ll need to include this file. In a plugin you might consider using an SPL autoloader. For now let’s do a simple require such as:

require_once plugin_dir_path(__FILE__) . 'collections/Post.php';

require_once plugin_dir_path(__FILE__) . 'collections/Post.php';

Or if you are working in theme including the file might look like this:

require_once get_template_directory() . '/collections/Post.php';

require_once get_template_directory() . '/collections/Post.php';

The typical use case of the Eloquent ORM in WordPress is to facilitate efficient use of custom database tables. However, in the example above we’ve made a model for the existing posts table included in every WordPress install. You can utilize the Eloquent ORM with any database table including existing tables.

Fetching Records with Eloquent ORM

Now let’s fetch 5 posts utilizing Eloquent ORM:

// Get 5 published posts, newest first
$posts = Post::where('post_status', 'publish')
    ->where('post_type', 'post')
    ->orderBy('post_date', 'desc')
    ->limit(5)
    ->get();

// Loop through results
foreach ($posts as $post) {
    echo $post->post_title . '<br>';
}

// Get 5 published posts, newest first
$posts = Post::where('post_status', 'publish')
    ->where('post_type', 'post')
    ->orderBy('post_date', 'desc')
    ->limit(5)
    ->get();

// Loop through results
foreach ($posts as $post) {
    echo $post->post_title . '<br>';
}

A couple of things to appreciate about the Eloquent approach. First notice the use of chaining. Model methods like where() and orderBy all return the query that is being formed. We also avoid some of the complex array structures typically found in WP Query meta queries and taxonomy queries.

Finding Records by ID

// Get post by ID
$post = Post::find(42);

// Access properties
echo $post->post_title;
echo $post->post_content;

// Get post by ID
$post = Post::find(42);

// Access properties
echo $post->post_title;
echo $post->post_content;

In this example we check if the post exists:

$post = Post::find(42);

if ($post) {
    echo $post->post_title;
} else {
    echo 'Post not found';
}

$post = Post::find(42);

if ($post) {
    echo $post->post_title;
} else {
    echo 'Post not found';
}

Another example of checking if the post exists but in this approach we use a try/catch and the findOrFail() method to fire an exception if the record does not exist:

try {
    $post = Post::findOrFail(42);
    echo $post->post_title;
} catch (Exception $e) {
    echo 'Post not found';
}

try {
    $post = Post::findOrFail(42);
    echo $post->post_title;
} catch (Exception $e) {
    echo 'Post not found';
}

Model Creation Process

When you’re building something that matters you want to get the foundation right. Models are the foundation of a modern approach to development. The Gateway approach is going to put you on track to creating performant, scalable applications within WordPress. It all starts with the model. The good news is, you can keep it very simple and progress slowly with iterations.

Let’s draft a ticket model to keep track of support tickets:

<?php

namespace TicketPro\Collections;

class Ticket extends \Gateway\Collection
{
    protected $key = 'ticket';
    protected $table = 'tickets';
}

<?php

namespace TicketPro\Collections;

class Ticket extends \Gateway\Collection
{
    protected $key = 'ticket';
    protected $table = 'tickets';
}

Now if we try to use our ticket model what should we expect would happen? It would fetch from a database table that does not yet exist. We have 3 options to add our custom database table for this WordPress site:

1. Manual table creation. If you’re working locally with Local WP or WordPress Studio or any other local dev environment, you have access either to PHPMyAdmin or Adminer. You can use that to manually create the wp_tickets table. Just be sure to make the id an auto-incrementing int column.
2. For a plugin it’s best to use the dbDelta() function in an activation hook to install the database table. The syntax for this is SQL. You can ask Claude or ChatGPT to create a table install function based on your model. Because AI has been trained on Eloquent ORM and WordPress it is quite effective at providing accurate code for both as long as you provide the context that you’re working with Eloquent in WordPress.
3. Finally for quick tests you can get AI to produce SQL create table which is the fastest way to get going.