WP Data Objects

Powerful data objects for WordPress.

Requirements

• Sage >= 10.0
• Acorn >= 3.0

Installation

You can install this package with Composer:

composer require yard/data

You can publish the config file with:

wp acorn vendor:publish --provider="Yard\Data\Providers\DataServiceProvider"

Usage

PostData

Creating PostData

PostData can be created from the global \WP_Post object:

global$post;
$postData = \Yard\Data\PostData::from($post);

From an array:

$postData = \Yard\Data\PostData::from(
[
'id' => 42,
'author' => 1,
'title' => 'Hello, World!',
'content' => 'This is a test post.',
'excerpt' => 'This is a test post.',
'status' => 'publish',
'date' => '2021-01-01 00:00:00',
'modified' => '2021-01-01 00:00:00',
'postType' => 'post',
'slug'=> 'hello-world',
]
);

Or from an Eloquent Model using Corcel:

$model = \Corcel\Model\Post::find(get_the_ID());
$postData = \Yard\Data\PostData::from($model);

Custom PostData

Creating a VacancyData object by extending PostData:

namespaceApp\Data;
useYard\Data\PostData;
class VacancyData extends PostData
{
}

Enables you to create VacancyData object in the same way as PostData:

global$post;
$postData = \App\Data\VacancyData::from($post);

Configuring the returning Instance

Every time you call Yard\Data\PostData::from($post) you receive an instance of Yard\Data\PostData.

If you choose to create a new data class for your custom post type, you can have this class be returned for all instances of that post type.

To do this, you need to add the Fully Qualified Class Name (FQCN) of your custom data class to the supports array when registering your custom post type:

register_post_type('vacancy', [
'supports' => [
'data-class' => ['classFQN' => App\Data\KnowledgebaseData::class],
],
]);

Another option is to create a mapping in the config/yard-data.php file. The mapping in the project config takes precedence over the register_post_type supports args.

'post_types' => [
'vacancy' => App\Data\VacancyData::class,
'employee' => App\Data\EmployeeData::class,

Now every time you call Yard\Data\PostData::from($post) on a custom post type the mapped instance will be returned.

Meta Fields

Using the Meta Attribute

Adding a meta field with a meta_key of vacancy_email to your VacancyData looks like this:

namespaceApp\Data;
useYard\Data\Attributes\Meta;
useYard\Data\PostData;
class VacancyData extends PostData
{
#[Meta(metaKey: 'vacancy_email')]
publicstring$email;
}

This approach is functionally equivalent to using:

#[Meta]
public string $vacancyEmail;

You can also specify any available Data Object, and the meta value will be cast to that Data Object:

#[Meta]
public EmployeeData $vacancyEmployee;

The MetaPrefix Class Attribute

If all of your meta fields are prefixed with the same prefix you can use the MetaPrefix attribute:

namespaceApp\Data;
useYard\Data\Attributes\MetaPrefix;
useYard\Data\Attributes\Meta;
useYard\Data\PostData;
#[MetaPrefix(prefix: 'vacancy')]
class VacancyData extends PostData
{
#[Meta]
publicstring$email;
}

It doesn’t matter if your meta keys are in snake_case and your attributes are in camelCase. For instance, let’s say your meta key is vacancy_members_only:

#[MetaPrefix(prefix: 'vacancy')]
class VacancyData extends PostData
{
#[Meta]
publicbool$membersOnly;
}

Taxonomy Terms

Adding terms to your Data Object

For every taxonomy that has been registered with your custom post type you can add a Collection of TermData like this:

namespaceApp\Data;
useIlluminate\Support\Collection;
useYard\Data\Attributes\Terms;
useYard\Data\PostData;
class VacancyData extends PostData
{
#[Terms(taxonomy: 'vacancy_location')]
/** @var Collection<int, TermData> */publicCollection$locations;
}

This approach is functionally equivalent to using:

#[Terms]
/** @var Collection<int, TermData> */public Collection $vacancyLocation;

or:

#[Terms]
/** @var Collection<int, TermData> */public Collection $vacancyLocations;

The TaxonomyPrefix Class Attribute

If all of your taxonomies are prefixed with the same prefix you can use the TaxonomyPrefix attribute:

namespaceApp\Data;
useIlluminate\Support\Collection;
useYard\Data\Attributes\TaxonomyPrefix;
useYard\Data\Attributes\Terms;
useYard\Data\PostData;
#[TaxonomyPrefix(prefix: 'vacancy')]
class VacancyData extends PostData
{
#[Terms]
/** @var Collection<int, TermData> */publicCollection$locations;
}

Reading Terms from your Data Object

Because Terms are a Collection you can use any of the available collection methods to read the terms from your data object. Here are some common examples:

$vacancyData->locations->contains('slug', 'amsterdam'); // true$postData->locations->firstWhere('slug', 'utrecht')->name; // Utrecht$vacancyData->locations->implode('name', ', '), // Almere, Amsterdam, Utrecht

Extending TermData

You can add extra meta fields to taxonomies by extending the default TermData object

namespaceApp\Data;
useYard\Data\TermData;
class TypeTermData extends TermData {
#[Meta()]
publicstring$icon;
}

In your PostData object you have to specify the data class used for a specific taxonomy:

namespaceApp\Data;
useIlluminate\Support\Collection;
useYard\Data\Attributes\TaxonomyPrefix;
useYard\Data\Attributes\Terms;
useYard\Data\PostData;
class VacancyData extends PostData
{
#[Terms(dataClass: TypeTermData::class)]
/** @var Collection<int, TypeTermData> */publicCollection$type;
}

$vacancyTypeIcon = $vacancyData->type->first()?->icon;

Reading comments for your Data Objects

If the post type of the data object supports comments, you can retrieve them as a collection of CommentData

$postData->comments()->first()?->authorEmail;

Extending CommentData

You can add extra meta fields to comments by extending the default CommentData object

namespaceApp\Data;
useYard\Data\CommentData;
class LinkedInCommmentData extends CommentDataData {
#[Meta()]
publicstring$linkedInUserName;
}

UserData

Create UserData from current user:

$userData = UserData::from(wp_get_current_user());

About us