DocumentationDatabaseIlluminate Eloquent ORM

Illuminate Eloquent ORM

Instead of using the WP Bones light version of Query Builder, you may include the original Illuminate Eloquent ORM.

Installing third-party packages is not recommended in the WordPress environment. You have to be sure that your plugin will be the only one using the package. Otherwise, you may get unexpected results.

It provides a beautiful, simple ActiveRecord implementation for working with your database. Each database table has a corresponding “Model” which is used to interact with that table. Models allow you to query for data in your tables, as well as insert new records into the table.

You’ll find a complete demo of the database model in the WP Kirk demo branch:

git clone -b main https://github.com/wpbones/WPKirk.git <your plugin folder>

Here you’ll also find a migration example. For more details, see Migrations.

Install Eloquent ORM out of the box

You can install Eloquent ORM in your plugin by using

composer install illuminate/database

Also you need to include laravel/serializable-closure in order to serialize objects for debug and to avoid errors on save instances of your model.

composer require laravel/serializable-closure

We decided to remove the illuminate/database Eloquent ORM package from the WP Bones core because it could cause some issues in the WordPress environment.

🚦Installing this package will require you to have PHP version 8.2 or higher.

Remember that the Namespace inside the WordPress plugins architecture should be unique. Nonetheless, we aim to support the Eloquent ORM features, so we opted to remove it from the core, although you will still be able to use it separately.

Defining Models

To get started, let’s create a database model. Models typically live in the plugin directory, but you are free to place them anywhere that can be auto-loaded according to your composer.json file. All database models extend Illuminate\Database\Eloquent\Model class.

The easiest way to create a model instance is by using the make:eloquent-model artisan command. You can create a model for either existing WordPress tables or your own database table:

php bones make:eloquent-model Product

The above command will create a file Product.php within the plugin/Models folder:

<?php
namespace WPKirk\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class Product extends Model
{
 
}

Table names with WordPress prefix

By convention, the “snake case”, the plural name of the class will be used as the table name unless another name is explicitly specified. So, in this case, the model will assume the Product model stores records in the products table. If your table is following the WordPress prefix, the table name will be {prefix}_products. In this case, the correct model to support the WordPress prefix is:

namespace WPKirk\Models;
 
use Illuminate\Database\Eloquent\Model;
use WPKirk\WPBones\Database\DB;
 
class Product extends Model
{
  /**
   * Get the table associated with the model.
   *
   * @return string
   */
  public function getTable()
  {
    return DB::getTableName('Products');
  }
}

The DB::getTableName('Products'); method or DB::getTableName('products'); will return the table name with the WordPress prefix. In this case {prefix}_products. Another way is to use the protected $table property:

namespace WPKirk\Models;
 
use Illuminate\Database\Eloquent\Model;
 
class Product extends Model
{
  /**
   * The table associated with the model.
   *
   * @var string
   */
  protected $table = 'wp_products';
}

Laravel Eloquent ORM

Since WP Bones uses the complete Illuminate database package, for further documentation on using the various database facilities this library provides, consult the Laravel framework documentation