Getting Started

Minimal Setup Steps

Installation:
- Add the custom repositories and extra configurations to composer.json as specified.
- Run composer require laravel-admin/headless-wordpress.
- Register the service provider in config/app.php.
- Publish public files with php artisan vendor:publish --tag="public".
Initial Configuration:
- Ensure .env is properly configured (e.g., APP_URL, database settings).
- Navigate to /wordpress/wp-admin to complete WordPress setup (e.g., admin credentials, site title).

First Use Case:

Create a custom post type (CPT) in WordPress via /wp-admin/edit.php?post_type=your_cpt.

Fetch CPT data in Laravel using:

use LaravelAdmin\HeadlessWordpress\Facades\Wordpress;
$posts = Wordpress::posts()->where('post_type', 'your_cpt')->get();

Display data in a Laravel Blade template:

@foreach($posts as $post)
    <h2>{{ $post->post_title }}</h2>
    <p>{{ $post->post_content }}</p>
@endforeach

Implementation Patterns

Core Workflows

Hybrid CMS + Laravel:
- Use WordPress for content management (e.g., posts, media, taxonomies).
- Use Laravel for business logic, APIs, and frontend rendering.
- Example: Serve WordPress-generated content via Laravel routes:
```
Route::get('/blog', function () {
    return view('blog.index', [
        'posts' => Wordpress::posts()->get()
    ]);
});
```

Custom Post Types (CPTs) as Data Sources:

Query CPTs in Laravel:

$events = Wordpress::posts()
    ->where('post_type', 'events')
    ->where('post_status', 'publish')
    ->orderBy('event_date', 'ASC')
    ->get();

Taxonomy Integration:

Use WordPress taxonomies (e.g., categories, tags) to filter Laravel queries:

$categories = Wordpress::terms()->where('taxonomy', 'event_category')->get();
$filteredEvents = Wordpress::posts()
    ->whereHas('terms', function ($query) {
        $query->where('taxonomy', 'event_category')->where('term_id', 5);
    })
    ->get();

Media Handling:

Upload media to WordPress (/wp-admin/upload.php).

Fetch media URLs in Laravel:

$featuredImage = Wordpress::posts()
    ->where('post_type', 'your_cpt')
    ->first()
    ->featured_media()
    ->url;

API-First Approach:
- Expose WordPress data via Laravel APIs:
```
Route::get('/api/posts', function () {
    return Wordpress::posts()->get();
});
```
- Use Laravel’s built-in API resources for structured responses.

Integration Tips

Laravel Eloquent Relationships: Map WordPress data to Laravel models for consistency:

class Event extends Model {
    public function categories() {
        return $this->belongsToMany(Term::class, 'term_relationships')
            ->where('taxonomy', 'event_category');
    }
}

Caching: Cache frequent WordPress queries to reduce database load:

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

Middleware: Restrict WordPress admin access to specific IPs or roles:

Route::middleware(['ip', 'admin'])->group(function () {
    Route::prefix('wordpress')->group(...);
});

Gotchas and Tips

Pitfalls

Outdated Package:
- Last updated in 2017; may not support modern Laravel/WordPress versions.
- Workaround: Fork the repository and update dependencies manually (e.g., laravel/framework, wp-cli).
- Test thoroughly with your WordPress/Laravel versions.
Database Conflicts:
- WordPress and Laravel share the same database by default, risking schema collisions.
- Solution: Use separate databases or prefix WordPress tables (e.g., wp_ → wp_old_).
File Permissions:
- WordPress requires writable directories (public/wordpress, public/uploads).
- Fix: Run chmod -R 755 public/wordpress and ensure storage/ is writable.
Caching Headaches:
- WordPress object cache (e.g., wp_cache) may conflict with Laravel’s cache.
- Tip: Disable WordPress caching during development:
```
// In WordpressServiceProvider or a custom plugin
define('WP_CACHE', false);
```
Plugin/Theme Dependencies:
- Some WordPress plugins/themes may break Laravel routes or assets.
- Tip: Use Must-Use Plugins (public/mu-plugins) for critical functionality to avoid conflicts.

Debugging

Query Logs: Enable WordPress query logging to debug slow queries:
```
// In a custom plugin or service provider
define('SAVEQUERIES', true);
```
Check logs in /wp-admin/tools.php or via global $wpdb; print_r($wpdb->queries).
Laravel + WordPress Logs:
- Laravel logs: storage/logs/laravel.log.
- WordPress logs: Use a plugin like WP Debugging or check error_log.
Common Errors:
- "Table doesn’t exist": Ensure WordPress tables are created (run /wordpress/wp-admin/install.php).
- 404 Routes: Clear Laravel routes cache (php artisan route:clear) and WordPress rewrite rules (/wordpress/wp-admin/options-permalink.php).

Extension Points

Custom Query Builders: Extend the package’s query builder to support custom fields (ACF, Pods):

// Example: Add ACF support
Wordpress::extend(function ($query) {
    $query->addSelect('post_meta.meta_value as acf_field')
          ->leftJoin('wp_postmeta as post_meta', 'posts.ID', '=', 'post_meta.post_id')
          ->where('post_meta.meta_key', 'like', 'acf_%');
});

Webhooks for Real-Time Updates: Use WordPress actions to trigger Laravel events:

// In a custom plugin
add_action('save_post', function ($postId) {
    event(new \App\Events\WordpressPostUpdated($postId));
});

Headless Mode: Disable WordPress frontend rendering entirely by redirecting all requests to Laravel:

// In a custom middleware
public function handle($request, Closure $next) {
    if ($request->is('wordpress/*')) {
        abort(404); // Or redirect to Laravel
    }
    return $next($request);
}

Localization: Override WordPress translations in Laravel:

// In a service provider
add_filter('gettext', function ($translated, $text, $domain) {
    if ($domain === 'default' && strpos($text, 'WordPress') !== false) {
        return 'Laravel + WordPress';
    }
    return $translated;
}, 10, 3);

Configuration Quirks

.env Variables: Ensure these are set for WordPress:

WP_HOME=https://your-app.com
WP_SITEURL=https://your-app.com/wordpress

Asset Pipeline: WordPress enqueues scripts/styles globally. To avoid conflicts:

// In a custom plugin
add_action('wp_enqueue_scripts', function () {
    wp_dequeue_script('jquery');
    wp_enqueue_script('jquery', asset('js/jquery.min.js'), [], null, true);
}, 9999);

Git Ignore: Add these to .gitignore to avoid bloating repositories:

public/wordpress/wp-config.php
public/uploads/
public/languages/

Wordpress Helpers Laravel Package