Download the PHP package williarin/wordpress-interop without Composer

WordPress Interop

Introduction

This library aims to simplify the interaction with WordPress databases through third-party applications. It relies on Doctrine DBAL and looks like Doctrine ORM.

It can perform simple tasks out of the box such as querying posts, retrieving attachment data, etc.

You can extend it by adding your own repositories and querying methods.

Warning! Although it looks like an ORM, it's not an ORM library. It doesn't have two-way data manipulation features. See this as a simple WordPress database manipulation helper library.

Installation

This library can be used as standalone:

Or with Symfony:

Find the documentation for the Symfony bundle on the dedicated repository page.

Usage

Overview

In detail

The first thing to do is to create an entity manager linked to your DBAL connection targeting your WordPress database.

Then you can query the database:

Documentation

Basic querying

This works with any entity inherited from BaseEntity. Built-in entities are Post, Page, Attachment and Product but you can create your own.

EAV querying

_The term EAV refers to the entity-attribute-value model used by WordPress through the term "meta" as in wp_postmeta, wp_termmeta, wp_usermeta etc. Here we're talking about wp_postmeta._

The query system supports directly querying EAV attributes.

In the example below, sku and stock_status are attributes from wp_postmeta table.

_Note: Field names are mapped to match their property name. As an example, _sku becomes sku, or _wc_average_rating becomes average_rating._

If you query an EAV attribute that doesn't exist in the entity, an InvalidFieldNameException exception will be thrown.

To allow extra dynamic properties to be queried, set allow_extra_properties option to true before the query. Careful though, options are set for the repository and not the query, which means they will apply to all further queries.

Nested conditions

For more complex querying needs, you can add nested conditions.

Note: it only works with columns and not EAV attributes.

EAV relationship conditions

Query entities based on their EAV relationships.

Note: the EAV fields must have their original names, unlike mapped fields for direct EAV querying.

Term and taxonomy relationship conditions

Query entities based on their terms and taxonomies relationships.

Additionally, you can query terms from a joint entity, and specify the name of the term table.

In this example, we assume that the products have a related_product postmeta.

If not specified, the term table alias defaults to t_0, t_1, etc.

A special operator Operand::OPERATOR_IN_ALL is also provided to match exactly all values in an array.

This operator is not limited to terms querying, but it's the most obvious use case.

Post relationship conditions

Query terms based on their posts relationships.

Restrict selected columns

Querying all columns at once is slow, especially if you have a lot of entities to retrieve. You can restrict the queried columns as the example below.

It works with base columns as well as EAV attributes.

You can as well select a column which doesn't have a mapped property in your entity.

Extending the generated query

For advanced needs, it's also possible to retrieve the query builder and modify it to your needs.

_Note: use select_from_eav() function to query EAV attributes._

Create a new term

Terms are not duplicated if already existing.

Add terms to an entity

Remove terms from an entity

Field update

There's a type validation before update. You can't assign a string to a date field, a string to an int field, etc.

Entity creation or update

Create or update an entity with all its fields at once.

Limitations:

• Only the base fields (the columns in wp_posts table) are persisted, not the EAV
• All properties must be filled before object creation or update as the schema doesn't support NULL values
• No change tracking

Entity duplication

Duplicate an entity with all its EAV attributes and terms with DuplicationService. The resulting entity is already persisted and has a new ID.

Available entities and repositories

• Post and PostRepository
• Page and PageRepository
• Attachment and AttachmentRepository
• Option and OptionRepository
• PostMeta and PostMetaRepository
• Comment and CommentRepository
• Term and TermRepository
• TermTaxonomy and TermTaxonomyRepository
• User and UserRepository
• Product and ProductRepository (WooCommerce)
• ShopOrder and ShopOrderRepository (WooCommerce)
• ShopOrderItem and ShopOrderItemRepository (WooCommerce)

Get an option value

To retrieve a WordPress option, you have several choices:

Create your own entities and repositories

Say you have a custom post type named project.

First you create a simple entity:

Then a repository:

Then use it like this:

It also works if your entity is in a separate table, with some additional configuration. Take as an example ShopOrderItemRepository.

You'll have to override some constants:

Entity and repository inheritance

You might have some custom attributes for existing entities such as Post.

1. Create a new entity that extends Post with new fields
2. Create a new repository that extends PostRepository and override getEntityClassName() method to return your new MyPost entity class name
3. Add mapped fields to your PostRepository
4. Add #[RepositoryClass(MyPostRepository::class)] to your MyPost entity

Contributing

All contributions are welcome.

How to contribute:

1. Fork this repository
2. Create a new branch on your fork
3. Make some changes then run make test to ensure everything works, and make fix to fix ECS and composer.json errors
4. Commit using conventional commit syntax
5. Create a pull request on master branch of this repository

License

MIT

Copyright (c) 2022, William Arin