Download the PHP package pollora/colt without Composer

Colt is a set of Eloquent models that read and write a WordPress database directly: posts, pages, custom post types, meta, taxonomies, menus, options and users. Use WordPress as the admin and content store, and query its data from Laravel (or any Composer-based PHP app) with the query builder you already know, without loading WordPress.

Colt is a fork of Corcel, created by Junior Grossi, kept up to date with current Laravel releases. Corcel's API is preserved, under the Pollora\Colt namespace.

Part of Pollora, the Laravel framework for WordPress. In a Pollora project it is already installed: use the Pollora\Models\* models (Post, Page, Term, User…), which extend Colt's.

Installation

Requires PHP 8.2+.

Laravel 11 is covered by the 8.0 branch only (no tagged release). For older Laravel versions, use Corcel.

Quick start

Configuration

Laravel

Colt registers its service provider through package auto-discovery. Publish the configuration file:

This creates config/colt.php, where you set the database connection used for the WordPress tables, and register custom post types and shortcodes.

Suppose config/database.php has a connection for WordPress next to the application one:

Then point Colt at it in config/colt.php:

Other PHP frameworks

Load the Composer autoloader if it is not already loaded, then connect to the WordPress database:

You can pass any Eloquent connection parameter. These have defaults you can override:

Usage

The examples below use the models of the Pollora\Colt\Model namespace (Post, Page, Taxonomy, Menu, Option, User…). If you extend them with your own classes, call your class instead (App\Models\Post::published()).

Posts

Your own model classes

Extending Pollora\Colt\Model\Post lets you add your own methods and, if needed, use another connection than Colt's default one:

Extending is optional: the Colt models work as they are.

Meta data (custom fields)

Read meta values from any post:

Create or update meta with saveMeta() or saveField(). They return a bool, like Eloquent's save():

createMeta() and createField() only create, and return the PostMeta instance instead of a bool:

Querying by meta

Any model using the MetaFields trait (Post, User, Term, Comment…) has meta scopes.

hasMetaLike() uses SQL LIKE: matching is case-insensitive and % is a wildcard.

Field aliases

Post defines aliases in its static $aliases array, such as title for post_title and content for post_content:

Subclasses can add their own; they inherit the parent's:

Ordering and pagination

Post and User have newest() and oldest() scopes:

Paginate with Eloquent's paginate():

Custom post types

Use the type() scope, or a class of your own:

type() returns Pollora\Colt\Model\Post objects; your own class returns Video objects, with your methods and properties. Meta works the same way:

Returning your class for a post type

By default, Post::type('video')->first() returns a Post. Map post types to classes and Colt returns your class for that type everywhere, which matters when a collection mixes types (the items of a menu, for example).

In config/colt.php:

Or at runtime:

This also works for the built-in types: register your own class for page or post.

Pages

Pages are a post type: use Post::type('page') or the Page class.

Taxonomies and categories

Post format

Like WordPress's get_post_format():

Attachments and revisions

Thumbnails

size() returns the metadata of a generated size (e.g. thumbnail or medium), or the original image URL when that size does not exist:

Shortcodes

Registered shortcodes in post_content are rendered when you read $post->content.

From the configuration (Laravel)

Map shortcodes to classes under the shortcodes key of config/colt.php. Each class implements Pollora\Colt\Shortcode, which requires a render() method:

At runtime

In Laravel, register runtime shortcodes in the boot() method of a service provider, such as App\Providers\AppServiceProvider.

Parser

Shortcodes are parsed with thunderer/shortcode. The default RegularParser suits most cases. If parsing looks off, switch to WordpressParser, which follows WordPress's shortcode regex more closely, or to a parser of your own, in config/colt.php:

Outside Laravel, call setShortcodeParser() on any model using the Shortcodes trait, such as Post:

Options

Option reads and writes the wp_options table:

Menus

Get a menu by its slug. Its items are a collection of MenuItem objects (posts of type nav_menu_item). Supported items are pages, posts, custom links and categories; instance() returns the object behind an item:

instance() returns a Post for post items, a Page for page items, a CustomLink for custom items and a Term for category items.

Multi-level menus

MenuItem::parent() returns the parent of an item (Post, Page, CustomLink or Term):

To build levels, group the items by parent with the collection's groupBy(), on $item->parent()->ID.

Users

Authentication

With Laravel

Colt registers a colt user provider. Declare it in config/auth.php so Laravel logs in WordPress users:

For password resets, the Pollora\Colt\Laravel\Auth\ResetsPasswords trait provides a resetPassword() method that stores the new password with WordPress's hashing. Use it in the class that resets passwords, in place of Laravel's own implementation:

Without Laravel

Authenticate with AuthUserProvider directly. Both username and email work as credentials:

Documentation

How Colt relates to Corcel and to Pollora's models: pollora.dev/compare.

Testing

The suite uses Pest with an in-memory SQLite database, built from the factories and migrations in tests/database.

A second suite runs against a real WordPress installation, in .wordpress or the path set in WP_PATH (see the wordpress job of .github/workflows/ci.yml):

Contributing

Contributions are welcome: see the contributing guide. Report security issues privately, as described in the security policy.

License

Colt is open-source software licensed under the RuBee group