[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Post API: WP_Post class
   4   *
   5   * @package WordPress
   6   * @subpackage Post
   7   * @since 4.4.0
   8   */
   9  
  10  /**
  11   * Core class used to implement the WP_Post object.
  12   *
  13   * @since 3.5.0
  14   *
  15   * @property string $page_template
  16   *
  17   * @property-read list<non-negative-int> $ancestors
  18   * @property-read list<non-negative-int> $post_category
  19   * @property-read list<non-empty-string> $tags_input
  20   *
  21   * @phpstan-type Data_Array array{
  22   *     ID: non-negative-int,
  23   *     post_author: numeric-string|'',
  24   *     post_date: string,
  25   *     post_date_gmt: string,
  26   *     post_content: string,
  27   *     post_title: string,
  28   *     post_excerpt: string,
  29   *     post_status: non-empty-string,
  30   *     comment_status: non-empty-string,
  31   *     ping_status: non-empty-string,
  32   *     post_password: string,
  33   *     post_name: string,
  34   *     to_ping: string,
  35   *     pinged: string,
  36   *     post_modified: string,
  37   *     post_modified_gmt: string,
  38   *     post_content_filtered: string,
  39   *     post_parent: non-negative-int,
  40   *     guid: string,
  41   *     menu_order: int,
  42   *     post_type: non-empty-string,
  43   *     post_mime_type: string,
  44   *     comment_count: numeric-string,
  45   *     filter: 'raw'|'edit'|'db'|'display'|'attribute'|'js'|'sample'|null,
  46   *     ancestors: list<non-negative-int>,
  47   *     page_template: string,
  48   *     post_category: list<non-negative-int>,
  49   *     tags_input: list<non-empty-string>,
  50   *     ...
  51   * }
  52   */
  53  #[AllowDynamicProperties]
  54  final class WP_Post {
  55  
  56      /**
  57       * Post ID.
  58       *
  59       * @since 3.5.0
  60       * @var int
  61       * @phpstan-var non-negative-int
  62       */
  63      public $ID;
  64  
  65      /**
  66       * ID of post author.
  67       *
  68       * A numeric string, for compatibility reasons. May be an empty string for a
  69       * default post that has not yet been assigned an author.
  70       *
  71       * @since 3.5.0
  72       * @var string
  73       * @phpstan-var numeric-string|''
  74       */
  75      public $post_author = '0';
  76  
  77      /**
  78       * The post's local publication time.
  79       *
  80       * @since 3.5.0
  81       * @var string
  82       */
  83      public $post_date = '0000-00-00 00:00:00';
  84  
  85      /**
  86       * The post's GMT publication time.
  87       *
  88       * @since 3.5.0
  89       * @var string
  90       */
  91      public $post_date_gmt = '0000-00-00 00:00:00';
  92  
  93      /**
  94       * The post's content.
  95       *
  96       * @since 3.5.0
  97       * @var string
  98       */
  99      public $post_content = '';
 100  
 101      /**
 102       * The post's title.
 103       *
 104       * @since 3.5.0
 105       * @var string
 106       */
 107      public $post_title = '';
 108  
 109      /**
 110       * The post's excerpt.
 111       *
 112       * @since 3.5.0
 113       * @var string
 114       */
 115      public $post_excerpt = '';
 116  
 117      /**
 118       * The post's status.
 119       *
 120       * @since 3.5.0
 121       * @var string
 122       * @phpstan-var non-empty-string
 123       */
 124      public $post_status = 'publish';
 125  
 126      /**
 127       * Whether comments are allowed.
 128       *
 129       * @since 3.5.0
 130       * @var string
 131       * @phpstan-var non-empty-string
 132       */
 133      public $comment_status = 'open';
 134  
 135      /**
 136       * Whether pings are allowed.
 137       *
 138       * @since 3.5.0
 139       * @var string
 140       * @phpstan-var non-empty-string
 141       */
 142      public $ping_status = 'open';
 143  
 144      /**
 145       * The post's password in plain text.
 146       *
 147       * @since 3.5.0
 148       * @var string
 149       */
 150      public $post_password = '';
 151  
 152      /**
 153       * The post's slug.
 154       *
 155       * @since 3.5.0
 156       * @var string
 157       */
 158      public $post_name = '';
 159  
 160      /**
 161       * URLs queued to be pinged.
 162       *
 163       * @since 3.5.0
 164       * @var string
 165       */
 166      public $to_ping = '';
 167  
 168      /**
 169       * URLs that have been pinged.
 170       *
 171       * @since 3.5.0
 172       * @var string
 173       */
 174      public $pinged = '';
 175  
 176      /**
 177       * The post's local modified time.
 178       *
 179       * @since 3.5.0
 180       * @var string
 181       */
 182      public $post_modified = '0000-00-00 00:00:00';
 183  
 184      /**
 185       * The post's GMT modified time.
 186       *
 187       * @since 3.5.0
 188       * @var string
 189       */
 190      public $post_modified_gmt = '0000-00-00 00:00:00';
 191  
 192      /**
 193       * A utility DB field for post content.
 194       *
 195       * @since 3.5.0
 196       * @var string
 197       */
 198      public $post_content_filtered = '';
 199  
 200      /**
 201       * ID of a post's parent post.
 202       *
 203       * @since 3.5.0
 204       * @var int
 205       * @phpstan-var non-negative-int
 206       */
 207      public $post_parent = 0;
 208  
 209      /**
 210       * The unique identifier for a post, not necessarily a URL, used as the feed GUID.
 211       *
 212       * @since 3.5.0
 213       * @var string
 214       */
 215      public $guid = '';
 216  
 217      /**
 218       * A field used for ordering posts.
 219       *
 220       * @since 3.5.0
 221       * @var int
 222       */
 223      public $menu_order = 0;
 224  
 225      /**
 226       * The post's type, like post or page.
 227       *
 228       * @since 3.5.0
 229       * @var string
 230       * @phpstan-var non-empty-string
 231       */
 232      public $post_type = 'post';
 233  
 234      /**
 235       * An attachment's mime type.
 236       *
 237       * @since 3.5.0
 238       * @var string
 239       */
 240      public $post_mime_type = '';
 241  
 242      /**
 243       * Cached comment count.
 244       *
 245       * A numeric string, for compatibility reasons.
 246       *
 247       * @since 3.5.0
 248       * @var string
 249       * @phpstan-var numeric-string
 250       */
 251      public $comment_count = '0';
 252  
 253      /**
 254       * Stores the post object's sanitization level.
 255       *
 256       * Does not correspond to a DB field.
 257       *
 258       * The 'sample' value is set exclusively by {@see get_sample_permalink()} and is read during permalink previewing.
 259       *
 260       * @since 3.5.0
 261       * @var string|null
 262       * @phpstan-var 'raw'|'edit'|'db'|'display'|'attribute'|'js'|'sample'|null
 263       */
 264      public $filter;
 265  
 266      /**
 267       * Retrieve WP_Post instance.
 268       *
 269       * @since 3.5.0
 270       * @since 7.2.0 Cache values that are not usable as a post object are now treated as a cache miss and replaced.
 271       *
 272       * @global wpdb $wpdb WordPress database abstraction object.
 273       *
 274       * @param int $post_id Post ID.
 275       * @return WP_Post|false Post object, false otherwise.
 276       *
 277       * @phpstan-param int|numeric-string $post_id
 278       */
 279  	public static function get_instance( $post_id ) {
 280          global $wpdb;
 281  
 282          $post_id = (int) $post_id;
 283          if ( $post_id <= 0 ) {
 284              return false;
 285          }
 286  
 287          $_post = wp_cache_get( $post_id, 'posts' );
 288  
 289          // A cached value that is not usable as a post is treated as a cache miss.
 290          if ( ! ( $_post instanceof stdClass || $_post instanceof WP_Post ) || ! isset( $_post->ID ) ) {
 291              $_post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d LIMIT 1", $post_id ) );
 292  
 293              if ( ! $_post ) {
 294                  return false;
 295              }
 296  
 297              $_post = sanitize_post( $_post, 'raw' );
 298  
 299              // Not wp_cache_add(), since an unusable cached value may still be present and must be replaced.
 300              wp_cache_set( (int) $_post->ID, $_post, 'posts' );
 301          } elseif ( empty( $_post->filter ) || 'raw' !== $_post->filter ) {
 302              $_post = sanitize_post( $_post, 'raw' );
 303          }
 304  
 305          return new WP_Post( $_post );
 306      }
 307  
 308      /**
 309       * Constructor.
 310       *
 311       * @since 3.5.0
 312       *
 313       * @param object $post Post object.
 314       */
 315  	public function __construct( $post ) {
 316          foreach ( get_object_vars( $post ) as $key => $value ) {
 317              $this->$key = $value;
 318          }
 319      }
 320  
 321      /**
 322       * Isset-er.
 323       *
 324       * @since 3.5.0
 325       *
 326       * @param string $key Property to check if set.
 327       * @return bool
 328       */
 329  	public function __isset( $key ) {
 330          if ( 'ancestors' === $key ) {
 331              return true;
 332          }
 333  
 334          if ( 'page_template' === $key ) {
 335              return true;
 336          }
 337  
 338          if ( 'post_category' === $key ) {
 339              return true;
 340          }
 341  
 342          if ( 'tags_input' === $key ) {
 343              return true;
 344          }
 345  
 346          return metadata_exists( 'post', $this->ID, $key );
 347      }
 348  
 349      /**
 350       * Getter.
 351       *
 352       * @since 3.5.0
 353       *
 354       * @param string $key Key to get.
 355       * @return mixed
 356       */
 357  	public function __get( $key ) {
 358          if ( 'page_template' === $key && $this->__isset( $key ) ) {
 359              return get_post_meta( $this->ID, '_wp_page_template', true );
 360          }
 361  
 362          if ( 'post_category' === $key ) {
 363              if ( is_object_in_taxonomy( $this->post_type, 'category' ) ) {
 364                  $terms = get_the_terms( $this, 'category' );
 365              }
 366  
 367              if ( empty( $terms ) || $terms instanceof WP_Error ) {
 368                  return array();
 369              }
 370  
 371              return wp_list_pluck( $terms, 'term_id' );
 372          }
 373  
 374          if ( 'tags_input' === $key ) {
 375              if ( is_object_in_taxonomy( $this->post_type, 'post_tag' ) ) {
 376                  $terms = get_the_terms( $this, 'post_tag' );
 377              }
 378  
 379              if ( empty( $terms ) || $terms instanceof WP_Error ) {
 380                  return array();
 381              }
 382  
 383              return wp_list_pluck( $terms, 'name' );
 384          }
 385  
 386          // Rest of the values need filtering.
 387          if ( 'ancestors' === $key ) {
 388              $value = get_post_ancestors( $this );
 389          } else {
 390              $value = get_post_meta( $this->ID, $key, true );
 391          }
 392  
 393          if ( $this->filter ) {
 394              $value = sanitize_post_field( $key, $value, $this->ID, $this->filter );
 395          }
 396  
 397          return $value;
 398      }
 399  
 400      /**
 401       * Applies the provided context filter for the current post.
 402       *
 403       * If the requested filter was already applied, then it returns without any changes.
 404       *
 405       * If the 'raw' filter is supplied, then a new instance of the post is obtained and this method _may_ return false
 406       * in case the underlying post was deleted.
 407       *
 408       * @since 3.5.0
 409       *
 410       * @param string $filter Filter.
 411       * @return WP_Post|false
 412       *
 413       * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js' $filter
 414       * @phpstan-return (
 415       *     $filter is 'raw' ? WP_Post|false : WP_Post
 416       * )
 417       */
 418  	public function filter( $filter ) {
 419          if ( $this->filter === $filter ) {
 420              return $this;
 421          }
 422  
 423          if ( 'raw' === $filter ) {
 424              return self::get_instance( $this->ID );
 425          }
 426  
 427          return sanitize_post( $this, $filter );
 428      }
 429  
 430      /**
 431       * Convert object to array.
 432       *
 433       * @since 3.5.0
 434       *
 435       * @return array<string, mixed> Object as array.
 436       *
 437       * @phpstan-return Data_Array
 438       */
 439  	public function to_array() {
 440          $post = get_object_vars( $this );
 441  
 442          foreach ( array( 'ancestors', 'page_template', 'post_category', 'tags_input' ) as $key ) {
 443              if ( $this->__isset( $key ) ) {
 444                  $post[ $key ] = $this->__get( $key );
 445              }
 446          }
 447  
 448          /** @var Data_Array $post */
 449          return $post;
 450      }
 451  }