Eloquent Laravel Package

Getting Started

First Steps

1. Installation

   composer require wenprise/eloquent
   

   Add to config/app.php under providers:

   Wenprise\Eloquent\EloquentServiceProvider::class,
   

   Publish the config file:

   php artisan vendor:publish --provider="Wenprise\Eloquent\EloquentServiceProvider" --tag="config"
   

2. Basic Setup

   • Configure wp_db.php in config/wenprise-eloquent.php to match your WordPress database.
   • Register the service provider in AppServiceProvider (if not auto-loaded):

     public function boot()
     {
         $this->app->register(\Wenprise\Eloquent\EloquentServiceProvider::class);
     }
     

3. First Query

   use Wenprise\Eloquent\Eloquent;
   
   $posts = Eloquent::table('wp_posts')->where('post_status', 'publish')->get();
   

First Use Case: Fetching WordPress Posts

// Fetch published posts with a limit
$posts = Eloquent::table('wp_posts')
    ->select('ID', 'post_title', 'post_content')
    ->where('post_type', 'post')
    ->where('post_status', 'publish')
    ->limit(10)
    ->get();

// Access data like a Laravel collection
foreach ($posts as $post) {
    echo $post->post_title;
}

Implementation Patterns

1. Query Builder Integration

Leverage Laravel’s query builder for WordPress tables:

// Join with wp_postmeta
$posts = Eloquent::table('wp_posts')
    ->join('wp_postmeta', 'wp_posts.ID', '=', 'wp_postmeta.post_id')
    ->where('wp_postmeta.meta_key', '_custom_field')
    ->select('wp_posts.*', 'wp_postmeta.meta_value')
    ->get();

2. Eloquent Model Abstraction

Extend Laravel’s Model to interact with WordPress tables:

use Wenprise\Eloquent\Eloquent;
use Illuminate\Database\Eloquent\Model;

class WPPost extends Model
{
    protected $table = 'wp_posts';
    public $timestamps = false; // WordPress uses 'post_date' instead

    protected $primaryKey = 'ID';
    public $incrementing = false; // Auto-increment may not apply

    // Custom accessors
    public function getTitleAttribute()
    {
        return $this->post_title;
    }
}

// Usage
$post = WPPost::where('post_status', 'publish')->first();
echo $post->title;

3. Relationships with WordPress Tables

Define relationships like Laravel, but target WordPress tables:

class WPPost extends Model
{
    public function comments()
    {
        return $this->hasMany(WPComment::class, 'comment_post_ID', 'ID');
    }
}

class WPComment extends Model
{
    protected $table = 'wp_comments';
    public $primaryKey = 'comment_ID';
}

4. Handling WordPress-Specific Fields

WordPress uses meta_key/meta_value for custom fields. Create accessors:

class WPPost extends Model
{
    public function getCustomFieldAttribute($key)
    {
        return $this->meta()->where('meta_key', $key)->value('meta_value');
    }

    public function meta()
    {
        return $this->hasMany(WPPostMeta::class, 'post_id', 'ID');
    }
}

5. Bulk Operations

Use Laravel’s chunking for large WordPress datasets:

WPPost::where('post_status', 'draft')
    ->chunk(200, function ($posts) {
        foreach ($posts as $post) {
            $post->update(['post_status' => 'publish']);
        }
    });

6. Events and Observers

Attach Laravel observers to WordPress models:

// app/Observers/WPPostObserver.php
class WPPostObserver
{
    public function saved(WPPost $post)
    {
        // Log or trigger actions after save
    }
}

// Register in AppServiceProvider
WPPost::observe(WPPostObserver::class);

Gotchas and Tips

Pitfalls

1. Primary Key Mismatch WordPress uses ID (not id) as the primary key for most tables. Always set:

   public $primaryKey = 'ID';
   public $incrementing = false;
   

2. Timestamps WordPress uses post_date (datetime) instead of Laravel’s created_at/updated_at. Disable auto-timestamps:

   public $timestamps = false;
   

3. Soft Deletes WordPress doesn’t support soft deletes natively. Use a custom scope:

   public function scopeActive($query)
   {
       return $query->where('post_status', '!=', 'trash');
   }
   

4. Case Sensitivity WordPress table/column names are case-sensitive on some hosts. Stick to lowercase:

   protected $table = 'wp_posts'; // Not 'WP_Posts'
   

5. Memory Limits Large queries (e.g., wp_options) may hit PHP memory limits. Use cursors or chunking:

   WPOption::cursor()->get();
   

Debugging Tips

1. Query Logging Enable Laravel’s query logging in config/database.php:

   'log' => true,
   'log_queries' => true,
   

   Check logs in storage/logs/laravel.log.

2. DD() for Debugging Use Laravel’s dd() to inspect query results:

   $posts = WPPost::where('post_type', 'page')->get();
   dd($posts->toArray());
   

3. WP Debug Mode Temporarily enable WordPress debug in wp-config.php:

   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true); // Logs to /wp-content/debug.log
   

Extension Points

1. Custom Query Builder Extensions Extend the query builder for WordPress-specific methods:

   // app/Providers/EloquentServiceProvider.php
   use Wenprise\Eloquent\Eloquent;
   
   Eloquent::macro('published', function () {
       return $this->where('post_status', 'publish');
   });
   
   // Usage
   $posts = WPPost::published()->get();
   

2. Model Events for WordPress Hook into WordPress actions via Laravel events:

   // In a service provider
   WPPost::saved(function ($post) {
       do_action('wp_insert_post', $post->ID, $post->post);
   });
   

3. Caching Strategies Cache frequent WordPress queries using Laravel’s cache:

   $posts = Cache::remember('published_posts', now()->addHours(1), function () {
       return WPPost::published()->get();
   });
   

4. Migrations for WordPress Tables Use Laravel migrations to manage WordPress table structures (caution: risky for core tables):

   Schema::table('wp_posts', function (Blueprint $table) {
       $table->string('custom_field')->nullable()->after('post_content');
   });
   

Performance Tips

1. Select Specific Columns Avoid SELECT *:

   // Bad
   WPPost::all();
   
   // Good
   WPPost::select('ID', 'post_title')->get();
   

2. Use Indexes Ensure WordPress tables are indexed (e.g., post_status, post_type). Add indexes via migrations if needed.

3. Batch Processing For bulk updates, use Laravel’s update() with chunking:

   WPPost::where('post_status', 'draft')
       ->update(['post_status' => 'publish']);
   

4. Avoid N+1 Queries Eager-load relationships:

   WPPost::with('comments')->where('post_status', 'publish')->get();