README

A clean, typed, PSR-compliant OOP abstraction layer over WordPress core functions. Ships as a Composer package consumed by WordPress plugins.

What is Tavriia?

Tavriia is a framework that provides typed wrappers, contracts, and DTOs over raw WordPress APIs. It is not a plugin. It is a Composer library you pull into your plugin projects.

Without Tavriia:

$post = get_post($id);
if (!$post instanceof \WP_Post) {
    // handle missing
}
$meta = get_post_meta($id, 'some_field', true);
$result = wp_insert_post($args);
if (is_wp_error($result)) {
    // handle error
}

With Tavriia:

$post = $this->postRepository->findById($id); // throws PostNotFoundException or returns PostDTO
$meta = $this->postRepository->metaFor($id)->getString('some_field');
$newId = $this->postFactory->create($dto); // throws or returns int

Installation

composer require thewildfields/tavriia

Requires PHP 8.2+ and WordPress (no minimum version enforced).

Quick Start

1. Create a module

use TheWildFields\Tavriia\AbstractModule;
use TheWildFields\Tavriia\Post\PostFactory;
use TheWildFields\Tavriia\Post\PostRepository;

final class EventsModule extends AbstractModule
{
    public function __construct(
        private readonly PostFactory $postFactory,
        private readonly PostRepository $postRepository,
    ) {}

    public function register_hooks(): void
    {
        add_action('init', [$this, 'registerPostType']);
        add_action('save_post_event', [$this, 'onSaveEvent'], 10, 2);
    }
}

2. Create posts with typed DTOs

use TheWildFields\Tavriia\DTO\PostDTO;

$dto = new PostDTO(
    title: 'Summer Concert',
    content: 'Annual summer concert in the park.',
    status: 'publish',
    postType: 'event',
    meta: ['venue_id' => 42],
);

$eventId = $this->postFactory->create($dto);

3. Query posts fluently

use TheWildFields\Tavriia\Query\QueryBuilder;

$results = (new QueryBuilder())
    ->postType('event')
    ->metaQuery('venue_id', 42)
    ->orderBy('date', 'DESC')
    ->limit(10)
    ->get();

foreach ($results as $post) {
    echo $post->title;
}

4. Make HTTP requests

use TheWildFields\Tavriia\Http\RequestBuilder;
use TheWildFields\Tavriia\Http\HttpClient;
use TheWildFields\Tavriia\Http\ResponseProcessor;

$client = new HttpClient(new ResponseProcessor());

$response = $client->get('https://api.example.com/events');
$data = $response->json();

Features

Design Principles

WP_Error never escapes the framework. Every wrapper converts WP_Error into a typed exception at the WordPress boundary. Plugin code never calls is_wp_error().

Factories return IDs, repositories return DTOs. PostFactory::create() returns int. PostRepository::findById() returns PostDTO or throws PostNotFoundException.

All concrete classes are final. Only AbstractModule and abstract base classes are non-final.

All DTOs are readonly. Immutable value objects with named constructors where appropriate.

Typed meta accessors. MetaManager::getString(), ::getInt(), ::getBool(), ::getArray() — never raw meta values.

Documentation

• Getting Started
• Core Concepts
• Modules
• Posts & Meta
• Taxonomy & Terms
• Query Builder
• HTTP Client
• REST API
• Admin Helpers
• Exception Handling
• API Reference

Contributing

This is a private framework package for The Wild Fields. See CLAUDE.md for architectural guidelines.

License

MIT