Getting Started

This release is primarily a compatibility release: v6.0.0 adds Laravel 12 support and Corcel v9 support. There are no new day-to-day APIs described, so the main action is to verify your Laravel/PHP/Corcel version matrix before upgrading.

Minimal steps:

Confirm your application is on a supported stack:
- Laravel 12 for this release line.
- PHP version required by Laravel 12 and Corcel v9.
- Corcel v9 if you are using the underlying Corcel models directly.
Install/upgrade with Composer and review the Corcel v9 upgrade notes alongside this package’s changelog:
```
composer require <vendor>/<package>:^6.0
```
Configure a separate WordPress database connection in config/database.php. Do not point this at your Laravel application database unless WordPress and Laravel intentionally share one.

Publish any package config if available and set the WordPress table prefix and connection name:

// config/corcel.php or equivalent package config
'connection' => 'wordpress',
'table_prefix' => 'wp_',

Look first at the package’s config file and its model/registry layer. That is where connection, table prefix, and model mappings are usually defined.
First use case: read published posts from WordPress and render them in a Laravel controller or API resource:
```
$posts = Corcel\Models\Post::published()
    ->with('meta')
    ->latest('post_date')
    ->paginate(20);
```

The first thing to validate after upgrading is that the package can resolve the WordPress connection and hydrate a basic Post model. If that works, most other features are variations on the same Eloquent-over-WordPress-schema pattern.

Implementation Patterns

Treat the package as an Eloquent adapter over the WordPress schema, not as a replacement for WordPress itself.

Separate connection and model layer

Keep the WordPress connection isolated:

// config/database.php
'wordpress' => [
    'driver' => 'mysql',
    'host' => env('WP_DB_HOST'),
    'database' => env('WP_DB_DATABASE'),
    'username' => env('WP_DB_USERNAME'),
    'password' => env('WP_DB_PASSWORD'),
    'prefix' => '',
    'charset' => 'utf8mb4',
    'collation' => 'utf8mb4_unicode_ci',
],

Then wrap package models in application-level models or repositories so you do not spread WordPress-specific assumptions through controllers:

namespace App\Models\WordPress;

class Post extends \Corcel\Models\Post
{
    protected $connection = 'wordpress';
}

This gives you one place to add scopes, casts, accessors, and eager-loading defaults.

Custom post types and taxonomies

The common daily pattern is defining a small model per custom post type:

class CaseStudy extends \Corcel\Models\Post
{
    protected $postType = 'case_study';
}

Use similar thin wrappers for taxonomies and terms. Keep business logic in services or query objects rather than in the WordPress model subclasses.

Querying and eager loading

Use Eloquent normally, but eager-load relationships deliberately:

$posts = Post::published()
    ->with(['meta', 'taxonomies', 'terms', 'attachment'])
    ->latest('post_date')
    ->paginate(20);

For API endpoints, prefer explicit query objects or scopes:

final class PublishedPostsQuery
{
    public function handle(int $perPage = 20)
    {
        return Post::query()
            ->where('post_status', 'publish')
            ->where('post_type', 'post')
            ->with('meta')
            ->orderByDesc('post_date')
            ->paginate($perPage);
    }
}

Content rendering

WordPress content is stored as HTML/markup. In Laravel views, render it intentionally:

{!! $post->content !!}

Only do this for trusted editorial content. If content can come from untrusted authors, sanitize it before rendering.

For WordPress-style formatting, decide explicitly whether to apply paragraph formatting, shortcode expansion, or neither. Do not assume Corcel applies the full WordPress rendering pipeline.

Caching

WordPress reads are often slower than native Laravel queries because of post/meta joins. Cache list pages and expensive meta lookups:

$posts = Cache::remember("wp.posts.page.{$page}", 300, fn () => $query->handle());

Invalidate by time or by a WordPress-side webhook/event. Avoid caching user-specific or draft content without a per-user key.

Auth and users

You can read WordPress users through the package, but do not assume Laravel authentication will “just work.” WordPress password hashes and Laravel’s hasher are different. The safe pattern is:

Use the package to read user/profile data.
Keep Laravel authentication on Laravel’s own user table, or implement an explicit WordPress password verification bridge.
Do not silently migrate WordPress hashes into Laravel’s password column without a verification strategy.

Multi-site

If you use WordPress multisite, isolate site switching in a service or middleware. Do not scatter switch_to_blog-style logic across controllers. Cache keys and model scopes should include the site identifier.

Gotchas and Tips

This is a compatibility release, not a feature release

The headline changes are Laravel 12 and Corcel v9 support. Before upgrading:

Check the Corcel v9 changelog for model/API changes.
Check your PHP version against Laravel 12 requirements.
Run your test suite against a real WordPress database fixture, not SQLite.
Pay particular attention if you extend Corcel models directly; parent-class changes can break custom models.

Do not run Laravel migrations against the WordPress database

The package reads and sometimes writes WordPress tables. Those tables are owned by WordPress. Use WordPress migrations/plugins or explicit SQL changes for schema, not Laravel migrations.

Table prefix is a common failure point

Symptoms: “table not found,” empty results, or queries hitting the wrong tables. Verify:

The WordPress connection’s prefix setting.
The package config’s table prefix.
Whether your WordPress install uses the default wp_ prefix or a custom one.

Permissions and read/write behavior

Many teams use this package read-only. If that is your intent, use a database user with SELECT only. If you allow writes, test post/meta/term writes carefully: WordPress stores serialized data and maintains its own invariants that Eloquent will not enforce.

Meta queries can be slow

Post meta is stored in a key/value table. Filtering by multiple meta keys often produces expensive joins. For high-traffic endpoints:

Prefer taxonomies or custom tables for filtering.
Cache meta-heavy queries.
Avoid unbounded meta_query-style filtering in public APIs.

Serialized meta values

Some meta values are PHP-serialized. Do not treat every meta value as a scalar string. If the package does not already deserialize a field, handle it explicitly and fail safely on malformed data.

Content is not automatically “WordPress-rendered”

Shortcodes, blocks, embeds, and wpautop formatting may not be applied by the package. If your frontend depends on WordPress rendering, define a rendering layer or call WordPress rendering endpoints rather than assuming the package reproduces it.

Dates and timestamps

WordPress uses columns such as post_date, post_date_gmt, and post_modified. Do not assume Laravel’s created_at/updated_at conventions apply. Cast and format dates explicitly in API resources.

Attachments and URLs

Attachment models expose WordPress metadata, but public URLs depend on your WordPress upload directory and domain configuration. Centralize attachment URL generation in a helper or presenter rather than reconstructing paths in views.

Testing strategy

Use a dedicated test WordPress database or a schema fixture. Do not rely on SQLite: the WordPress schema and MySQL-specific behavior are part of the contract. For CI, seed a minimal set of posts, terms, and meta rows.

Upgrade checklist for v6.0.0

Laravel upgraded to 12 where required.
PHP version matches Laravel 12 and Corcel v9 requirements.
Corcel v9 upgrade notes reviewed.
Custom model subclasses re-tested.
WordPress connection and table prefix verified.
Read-only database permissions confirmed if writes are not intended.
Cached queries and API endpoints smoke-tested.
Auth/user integration re-tested if WordPress users are exposed to Laravel.

Woocommerce Laravel Package