feat: add methods for Post featured media Attachments (#4)

In this PR we add methods for setting and getting featured media attachments for posts.

Reviewed-on: https://codeberg.org/vlw/wp/pulls/4

src/Posts/Post.php

@@ -9,8 +9,11 @@
 	use vlw\WP\Database;
 	use vlw\WP\Tables\Posts;
 	use vlw\WP\Posts\PostMeta;
+	use vlw\WP\Posts\Taxonomy\Term;
+	use vlw\WP\Posts\Type\Attachment;
 	use function vlw\WP\Support\slugify;
 
+	require_once "Taxonomy/Term.php";
 	require_once dirname(__DIR__, 1) . "/Tables/Posts.php";
 	require_once dirname(__DIR__, 1) . "/Support/Slugify.php";
 
@@ -21,10 +24,10 @@
 		 * @param string $name
 		 * @return static|null
 		 */
-		public static function from_name(string $name): ?static {
+		public static function from_name(string $name, bool $slugify = true): ?static {
 			$query = Database::current()
-				->from(Database::get_table(Posts::NAME))
-				->where([Posts::POST_NAME->value => slugify($name)])
+				->from(Database::get_table(Posts::TABLE_NAME))
+				->where([Posts::POST_NAME->value => $slugify ? slugify($name) : $name])
 				->limit(1)
 				->select(Posts::ID->value);
 
@@ -70,7 +73,7 @@
 				Posts::COMMENT_COUNT->value         => 0
 			];
 
-			if (!parent::create(Database::get_table(Posts::NAME), $values)) {
+			if (!parent::create(Database::get_table(Posts::TABLE_NAME), $values)) {
 				throw new Exception("Failed to create database entity");
 			}
 
@@ -79,7 +82,7 @@
 
 		public function __construct(public readonly int $id) {
 			parent::__construct(
-				Database::get_table(Posts::NAME),
+				Database::get_table(Posts::TABLE_NAME),
 				Posts::values(),
 				[Posts::ID->value => (int) $id]
 			);
@@ -95,6 +98,38 @@
 			return $key ? PostMeta::get_post_meta($this, $key) : PostMeta::get_all_post_meta($this);
 		}
 
+		/**
+		 * Returns an array of all Terms assigned to this Post
+		 *
+		 * @return array
+		 */
+		public function terms(): array {
+			return Term::from_post($this);
+		}
+
+		/**
+		 * Get, set, or unset featured media for this Post
+		 *
+		 * @param Attachment|false|null $attachment Pass Attachment to set featured media, false to unset, and null (or nothing) to get featured media
+		 * @return Attachment|null Returns an Attachment if featured media is set. Null if no featured media is set
+		 */
+		public function featured_media(Attachment|false|null $featured_media = null): ?Attachment {
+			// Remove featured media from this Post
+			if ($featured_media === false) {
+				Attachment::remove_post_featured_media($this);
+				return null;
+			}
+
+			// Set Attachment as the featured media for this Post
+			if ($featured_media instanceof Attachment) {
+				$featured_media->set_post_featured($this);
+
+				return $featured_media;
+			}
+
+			return Attachment::from_post_featured($this);
+		}
+
 		public int $post_author {
 			get                    => $this->get(Posts::POST_AUTHOR->value);
 			set (int $post_author) => $this->set(Posts::POST_AUTHOR->value, $post_author);

src/Posts/PostMeta.php

@@ -22,7 +22,7 @@
 		 */
 		public static function get_post_meta(Post $post, string $key): static|false {
 			$query = Database::current()
-				->from(Database::get_table(PostMetaTable::NAME))
+				->from(Database::get_table(PostMetaTable::TABLE_NAME))
 				->where([
 					PostMetaTable::POST_ID->value => $post->id,
 					PostMetaTable::META_KEY->value => $key
@@ -41,7 +41,7 @@
 		 */
 		public static function get_all_post_meta(Post $post): array {
 			$query = Database::current()
-				->from(Database::get_table(PostMetaTable::NAME))
+				->from(Database::get_table(PostMetaTable::TABLE_NAME))
 				->where([PostMetaTable::POST_ID->value => $post->id])
 				->select(PostMetaTable::META_ID->value);
 
@@ -71,7 +71,7 @@
 				PostMetaTable::META_VALUE->value => $meta_value
 			];
 
-			if (!parent::create(Database::get_table(PostMetaTable::NAME), $values)) {
+			if (!parent::create(Database::get_table(PostMetaTable::TABLE_NAME), $values)) {
 				throw new Exception("Failed to create database entity");
 			}
 
@@ -80,12 +80,23 @@
 
 		public function __construct(public readonly int $id) {
 			parent::__construct(
-				Database::get_table(PostMetaTable::NAME),
+				Database::get_table(PostMetaTable::TABLE_NAME),
 				PostMetaTable::values(),
 				[PostMetaTable::META_ID->value => (int) $id]
 			);
 		}
 
+		/**
+		 * Delete this post meta field from the database
+		 *
+		 * @return void
+		 */
+		public function delete(): void {
+			$this->db
+				->from(PostMetaTable::TABLE_NAME)
+				->delete([PostMetaTable::META_ID->value => $this->id]);
+		}
+
 		public Post $post {
 			get              => new Post($this->get(PostMetaTable::POST_ID->value));
 			set (Post $post) => $this->set(PostMetaTable::POST_ID->value, $post->id);

src/Posts/Taxonomy/Taxonomy.php

@@ -0,0 +1,85 @@
+<?php
+
+	namespace vlw\WP\Posts\Taxonomy;
+
+	use Exception;
+	use vlw\Scaffold\Database\Model;
+
+	use vlw\WP\Database;
+	use vlw\WP\Tables\Taxonomies;
+
+	require_once dirname(__DIR__, 2) . "/Tables/Taxonomies.php";
+
+	class Taxonomy extends Model {
+		/**
+		 * Returns a Taxonomy by taxonomy name
+		 *
+		 * @param string $name
+		 * @return static|null
+		 */
+		public function from(string $taxonomy): ?static {
+			$query = Database::current()
+				->from(Database::get_table(Taxonomies::TABLE_NAME))
+				->where([Taxonomies::TAXONOMY->value => $taxonomy])
+				->limit(1)
+				->select(Taxonomies::TERM_TAXONOMY_ID->value);
+
+			return $query->num_rows === 1 ? new static($query->fetch_assoc()[Taxonomies::TERM_ID->value]) : null;
+		}
+
+		/**
+		 * Create a new post meta field for a given post
+		 *
+		 * @param string $title Post title
+		 * @param string $type Post type
+		 * @return static
+		 */
+		public static function new(string $taxonomy): static {
+			// Return existing instance of Taxonomy if it exists
+			if (self::from($taxonomy)) {
+				return self::from($taxonomy);
+			}
+
+			$values = [
+				Taxonomies::TERM_TAXONOMY_ID->value => null,
+				Taxonomies::TERM_ID->value          => 0,
+				Taxonomies::DESCRIPTION->value      => "",
+				Taxonomies::PARENT->value           => 0,
+				Taxonomies::COUNT->value            => 0
+			];
+
+			if (!parent::create(Database::get_table(Taxonomies::TABLE_NAME), $values)) {
+				throw new Exception("Failed to create database entity");
+			}
+
+			return self::from($taxonomy);
+		}
+
+		public function __construct(public readonly int $id) {
+			parent::__construct(
+				Database::get_table(Taxonomies::TABLE_NAME),
+				Taxonomies::values(),
+				[Taxonomies::TERM_TAXONOMY_ID->value => (int) $id]
+			);
+		}
+
+		public Term $term {
+			get              => new Term($this->get(Taxonomies::TERM_ID->value));
+			set (Term $term) => $this->set(Taxonomies::TERM_ID->value, $term->id);
+		}
+
+		public string $taxonomy {
+			get                    => $this->get(Taxonomies::TAXONOMY->value);
+			set (string $taxonomy) => $this->set(Taxonomies::TAXONOMY->value, $taxonomy);
+		}
+
+		public string $description {
+			get                       => $this->get(Taxonomies::DESCRIPTION->value);
+			set (string $description) => $this->set(Taxonomies::DESCRIPTION->value, $description);
+		}
+
+		public ?self $parent {
+			get                 => $this->get(Taxonomies::PARENT->value) ? new self($this->get(Taxonomies::PARENT->value)) : null;
+			set (?self $parent) => $this->set(Taxonomies::PARENT->value, $parent->id);
+		}
+	}

src/Posts/Taxonomy/Term.php

@@ -0,0 +1,155 @@
+<?php
+
+	namespace vlw\WP\Posts\Taxonomy;
+
+	use Exception;
+	use vlw\Scaffold\Database\Model;
+
+	use vlw\WP\Database;
+	use vlw\WP\Posts\Post;
+	use vlw\WP\Tables\Terms;
+	use vlw\WP\Posts\Taxonomy\Taxonomy;
+	use vlw\WP\Tables\TermRelationships;
+
+	require_once dirname(__DIR__, 1) . "/Post.php";
+	require_once dirname(__DIR__, 2) . "/Tables/Terms.php";
+	require_once dirname(__DIR__, 2) . "/Tables/TermRelationships.php";
+
+	class Term extends Model {
+		/**
+		 * Returns a Term by a name
+		 *
+		 * @param string $name
+		 * @return static|null
+		 */
+		public static function from_name(string $name): ?static {
+			$query = Database::current()
+				->from(Database::get_table(Terms::TABLE_NAME))
+				->where([Terms::NAME->value => $name])
+				->limit(1)
+				->select(Terms::TERM_ID->value);
+
+			return $query->num_rows === 1 ? new static($query->fetch_assoc()[Terms::TERM_ID->value]) : null;
+		}
+
+		/**
+		 * Returns an array of all Terms associated with a Post
+		 *
+		 * @param Post $post
+		 * @return array
+		 */
+		public static function from_post(Post $post): array {
+			$query = Database::current()
+				->from(Database::get_table(TermRelationships::TABLE_NAME))
+				->where([TermRelationships::OBJECT_ID->value => $post->id])
+				->select(TermRelationships::TERM_TAXONOMY_ID->value);
+
+			return array_map(fn(array $post_meta): static => new static($post_meta[TermRelationships::TERM_TAXONOMY_ID->value]), $query->fetch_all(MYSQLI_ASSOC));
+		}
+
+		/**
+		 * Create a new post meta field for a given post
+		 *
+		 * @param string $title Post title
+		 * @param string $type Post type
+		 * @return static
+		 */
+		public static function new(string $name, ?string $slug = null): static {
+			// Update and return meta key for existing id
+			if (self::from_name($name)) {
+				$model = self::from_name($name);
+				$model->slug = $slug;
+
+				return $model;
+			}
+
+			$values = [
+				Terms::TERM_ID->value    => null,
+				Terms::NAME->value       => $name,
+				Terms::SLUG->value       => $slug,
+				Terms::TERM_GROUP->value => 0
+			];
+
+			if (!parent::create(Database::get_table(Terms::TABLE_NAME), $values)) {
+				throw new Exception("Failed to create database entity");
+			}
+
+			return self::from_name($name);
+		}
+
+		public function __construct(public readonly int $id) {
+			parent::__construct(
+				Database::get_table(Terms::TABLE_NAME),
+				Terms::values(),
+				[Terms::TERM_ID->value => $id]
+			);
+		}
+
+		/**
+		 * Returns the corresponding Taxonomy for this Term
+		 *
+		 * @return Taxonomy
+		 */
+		public function taxonomy(): Taxonomy {
+			return new Taxonomy($this->id);
+		}
+
+		/**
+		 * Add this Term to a target Post
+		 *
+		 * @param Post $post
+		 * @return void
+		 */
+		public function add_to_post(Post $post): void {
+			// Bail out if this term has already been added to the target Post
+			if (self::from_post($post)) {
+				return;
+			}
+
+			$query = Database::current()
+				->from(Database::get_table(TermRelationships::TABLE_NAME))
+				->insert([
+					TermRelationships::OBJECT_ID->value        => $post->id,
+					TermRelationships::TERM_TAXONOMY_ID->value => $this->id,
+					TermRelationships::TERM_ORDER->value       => 0
+				]);
+
+			if ($query === false) {
+				throw new Exception("Failed to create database entity");
+			}
+		}
+
+		/**
+		 * Remove this Term from a target Post
+		 *
+		 * @param Post $post
+		 * @return void
+		 */
+		public function remove_from_post(Post $post): void {
+			$query = Database::current()
+				->from(Database::get_table(TermRelationships::TABLE_NAME))
+				->delete([
+					TermRelationships::OBJECT_ID->value        => $post->id,
+					TermRelationships::TERM_TAXONOMY_ID->value => $this->id
+				]);
+
+			if ($query === false) {
+				throw new Exception("Failed to create database entity");
+			}
+		}
+
+		public string $name {
+			get                => $this->get(Terms::NAME->value);
+			set (string $name) => $this->set(Terms::NAME->value, $name);
+		}
+
+		public string $slug {
+			get                => $this->get(Terms::SLUG->value);
+			set (string $slug) => $this->set(Terms::SLUG->value, $slug);
+		}
+
+		public int $term_group {
+			get                   => $this->get(Terms::TERM_GROUP->value);
+			set (int $term_group) => $this->set(Terms::TERM_GROUP->value, $term_group);
+		}
+	}

src/Posts/Type/Attachment.php

@@ -3,14 +3,64 @@
 	namespace vlw\WP\Posts\Type;
 
 	use vlw\WP\Posts\Post;
+	use vlw\WP\Posts\PostMeta;
 	use function vlw\WP\Support\slugify;
 
 	require_once dirname(__DIR__, 1) . "/Post.php";
+	require_once dirname(__DIR__, 1) . "/PostMeta.php";
 	require_once dirname(__DIR__, 2) . "/Support/Slugify.php";
 
 	class Attachment {
+		private const META_KEY_THUMBNAIL_ID   = "_thumbnail_id";
+		private const META_KEY_FEATURED_MEDIA = "_featured_media";
+
 		private readonly Post $post;
 
+		/**
+		 * Return featured media for a Post if it exists
+		 *
+		 * @param Post $post
+		 * @param bool $thumbnail Thumbnail is the same as the featured meta. Default to true
+		 * @return Attachment|null
+		 */
+		public static function from_post_featured(Post $post, bool $thumbnail = true): ?Attachment {
+			// Check the thumbnail for an attachment ID. This operation is slightly less demanding than unserialize
+			if ($thumbnail) {
+				$post_meta = PostMeta::get_post_meta($post, self::META_KEY_THUMBNAIL_ID);
+
+				if ($post_meta) {
+					return new static($post_meta->id);
+				}
+			}
+
+			$post_meta = PostMeta::get_post_meta($post, self::META_KEY_FEATURED_MEDIA);
+
+			// Bail out, the target Post does not have any featured media
+			if (!$post_meta) {
+				return null;
+			}
+
+			// New instance from post ID in featured media serialized object
+			return new static((int) unserialize($post_meta->meta_value)[0]);
+		}
+
+		/**
+		 * Remove featured media from a Post
+		 *
+		 * @param Post $post
+		 * @return void
+		 */
+		public static function remove_post_featured_media(Post $post): void {
+			foreach ([
+				PostMeta::get_post_meta($post, self::META_KEY_THUMBNAIL_ID),
+				PostMeta::get_post_meta($post, self::META_KEY_FEATURED_MEDIA)
+			] as $post_meta) {
+				if ($post_meta) {
+					$post_meta->delete();
+				}
+			}
+		}
+
 		/**
 		 * Create a new post
 		 *
@@ -20,8 +70,10 @@
 		 */
 		public static function new(string $title, string $url): static {
 			$post = Post::new($title);
+
 			$post->post_title = slugify($title);
 			$post->guid = $url;
+			$post->post_type = "attachment";
 
 			return new static($post->id);
 		}
@@ -30,7 +82,20 @@
 			$this->post = new Post($id);
 		}
 
-		public function get_attachment(): string {
-			return file_get_contents($this->post->guid);
+		/**
+		 * Make this Attachment the featured media of a Post
+		 *
+		 * @param Post $post
+		 * @return object
+		 */
+		public function set_post_featured(Post $post): object {
+			return (object) [
+				"thumbnail"      => PostMeta::new($post, self::META_KEY_THUMBNAIL_ID, $this->id),
+				"featured_media" => PostMeta::new($post, self::META_KEY_FEATURED_MEDIA, "a:1:{i:0;s:3:\"{$this->id}\";}")
+			];
+		}
+
+		public string|false $content {
+			get => file_get_contents($this->post->guid);
 		}
 	}

src/Shortcode/Shortcode.php

@@ -17,7 +17,7 @@
 		 * @param string $name
 		 * @return array<static>
 		 */
-		public static function get_shortcodes(string &$source, string $name): array {
+		public static function get_shortcodes(string $source, string $name): array {
 			$matches = [];
 
 			preg_match_all("/\[{$name} /", $source, $matches, PREG_OFFSET_CAPTURE);

src/Tables/PostMeta.php

@@ -7,7 +7,7 @@
 	enum PostMeta: string {
 		use xEnum;
 
-		public const NAME = "postmeta";
+		public const TABLE_NAME = "postmeta";
 
 		case META_ID    = "meta_id";
 		case POST_ID    = "post_id";

src/Tables/Posts.php

@@ -7,7 +7,7 @@
 	enum Posts: string {
 		use xEnum;
 
-		public const NAME = "posts";
+		public const TABLE_NAME = "posts";
 
 		case ID                    = 'ID';
 		case POST_AUTHOR           = 'post_author';

src/Tables/Taxonomies.php

@@ -0,0 +1,18 @@
+<?php
+
+	namespace vlw\WP\Tables;
+
+	use vlw\xEnum;
+
+	enum Taxonomies: string {
+		use xEnum;
+
+		public const TABLE_NAME = "term_taxonomy";
+
+		case TERM_TAXONOMY_ID = "term_taxonomy_id";
+		case TERM_ID          = "term_id";
+		case TAXONOMY         = "taxonomy";
+		case DESCRIPTION      = "description";
+		case PARENT           = "parent";
+		case COUNT            = "count";
+	}

src/Tables/TermRelationships.php

@@ -0,0 +1,15 @@
+<?php
+
+	namespace vlw\WP\Tables;
+
+	use vlw\xEnum;
+
+	enum TermRelationships: string {
+		use xEnum;
+
+		public const TABLE_NAME = "term_relationships";
+
+		case OBJECT_ID        = "object_id";
+		case TERM_TAXONOMY_ID = "term_taxonomy_id";
+		case TERM_ORDER       = "term_order";
+	}

src/Tables/Terms.php

@@ -0,0 +1,16 @@
+<?php
+
+	namespace vlw\WP\Tables;
+
+	use vlw\xEnum;
+
+	enum Terms: string {
+		use xEnum;
+
+		public const TABLE_NAME = "terms";
+
+		case TERM_ID    = "term_id";
+		case NAME       = "name";
+		case SLUG       = "slug";
+		case TERM_GROUP = "term_group";
+	}