Download the PHP package highliuk/wp-eloquent without Composer

WP Eloquent

The WP Eloquent is a complete toolbox providing an ORM and schema generator. It supports MySQL, Postgres, SQL Server, and SQLite. It translates WordPress tables into Eloquent-compatible models.

No need to use the old WP_Query class anymore, we enter the world of the future by producing readable and reusable code! Additional features are also available for a custom WordPress experience.

The library ensuring compatibility with Eloquent, you can consult the documentation of the ORM if you are a little lost :)

Installation

The recommended installation method is Composer.

Setup

The connection to the database (via $ wpdb) is made on the first call of an Eloquent model. If you need to retrieve the connection instance, simply run the following code (prefer the use of use):

Supported models

Posts

Status

By default, Post returns all posts regardless of their status. This can be overridden via a local scope published to return only published posts.

It is also possible to define the status in question via the local scope status.

Post Types

By default, Post returns all content types. This can be overridden via the local scope type.

Comments

Terms

In this version Term is accessible as a model but is only accessible through an article. However, just extend Term to apply it to other custom content types.

Users

Options

In WordPress, options retrieval is done with the get_option function. With Eloquent, to avoid unnecessary loading of the WordPress Core, you can use the get function of the Option model.

You can also add other options:

You can retrieve all options as an array (watch out for performance...):

You can also specify the specific options to retrieve:

Menus

To retrieve a menu from its alias, use the syntax below. The menu items will be returned in an items variable (it's a collection of HighLiuk\Eloquent\Model\MenuItem objects).

The menu types currently supported are: Pages, Posts, Custom Links and Categories.

Once you have the MenuItem model, if you want to use the original instance (such as Page or Term, for example), just call the MenuItem::instance() method. The MenuItem object is just a post whose post_type is equal to nav_menu_item:

The instance() method will return the corresponding objects:

• Post instance for a menu item of type post;
• Page instance for a menu item of type page;
• CustomLink instance for a menu item of type custom;
• Term instance for a menu item of type category.

Multi-levels Menus

To manage multi-level menus, you can iterate to place them at the right level, for example.

You can use the MenuItem::parent() method to retrieve the parent instance of the menu item:

To group the menus by parent, you can use the ->groupBy() method in the $menu->items collection, which will group the items according to their parent ($item->parent()->ID).

For more information on the groupBy() method, see the Eloquent documentation.

 Custom Fields

The Post model supports aliases, so if you inspect a Post object you may find aliases in the static array $aliases (such as title for post_title and content for post_content.

You can extend the Post model to create your own. Just add your aliases to the extended model, it will automatically inherit those defined in the Post model:

Custom Scopes

To order Post or User models, you can use the newest() and oldest() scopes:

Pagination

To paginate the results, simply use the paginate() method of Eloquent:

To display the pagination links, use the links() method:

Meta

The Eloquent model set includes a WordPress metadata management.

Here is an example to retrieve metadata:

To create or update a user's metadata, just use the saveMeta() or saveField() methods. They return a boolean like the save() method of Eloquent.

It is possible to save multiple metadata in a single call:

The library also puts the methods createMeta() and createField(), which work how the saveX() methods, but they are only used for creation and return the object of type PostMeta created by the instance, instead of a boolean.

Query a Post from a custom field (Meta)

There are different ways to query from a meta-data (meta) using scopes on a Post model (or any other model using the HasMetaFields trait):

To check if a meta-data exists, use the hasMeta() scope:

To check if a meta-data exists and has a specific value, use the hasMeta() scope with a value.

It is also possible to perform a query by defining multiple meta-data and multiple associated values by passing an array of value to the hasMeta() scope:

If you need to match a case-insensitive string or a match with wildcard characters, you can use the hasMetaLike() scope with a value. This will use the SQL LIKE operator, so it is important to use the generic operator '%'.

Images

Retrieving an image from a Post or Page model.

To retrieve a specific image size, use the ->size() method on the object and enter the size alias in the parameter (ex. thumbnail or medium). If the thumbnail has been generated, the method returns an object with the meta-data, otherwise, it is the original url that is returned (WordPress behavior).

Advanced Custom Fields

The library makes available almost all ACF fields (with the exception of the Google Map field). It allows you to retrieve the fields in an optimal way without going through the ACF module.

Basic usage

To retrieve a value from a field, simply initialize a model of type Post and invoke the custom field:

Performance

When using $post->acf->website_url, additional requests are executed to retrieve the field according to the ACF approach. It is possible to use a specific method to avoid these additional requests. Simply enter the custom content type used as a function:

PS: The method must be called in camel case format. For example, for the date_picker type field you must write $post->acf->datePicker('fieldName'). The library converts camel case to snake case for you.

 Create a table

Docs to come

Advanced queries

The library being compatible with Eloquent, you can without problem perform complex queries without taking into account the WordPress context.

For example, to retrieve customers whose age is greater than 40 years old:

Custom models

Definition of the Eloquent model

To add your own method to an existing model, you can perform "extends" of this model. For example, for the User model, you could produce the following code:

Another example would be to define a new taxonomy to an article, for example country

To access the model of a new content type, here is an example of what could be proposed:

Queries on custom models

It is also possible to work with custom content types. You can use the type(string) method or create your own classes:

By using the type() method, the returned object will be of type HighLiuk\Eloquent\Model\Post. By using its own model, this allows you to go further in the possibilities by being able to associate custom methods and properties to it and by returning the result as a Video object for example.

Custom content type and meta-data:

Shortcode

Implementation in progress

Query logs

The connection capsule being directly attached to wpdb, all queries can be viewed on debugging tools such as Query Monitor.