[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       *
 271       * @global wpdb $wpdb WordPress database abstraction object.
 272       *
 273       * @param int $post_id Post ID.
 274       * @return WP_Post|false Post object, false otherwise.
 275       *
 276       * @phpstan-param int|numeric-string $post_id
 277       */
 278  	public static function get_instance( $post_id ) {
 279          global $wpdb;
 280  
 281          $post_id = (int) $post_id;
 282          if ( $post_id <= 0 ) {
 283              return false;
 284          }
 285  
 286          $_post = wp_cache_get( $post_id, 'posts' );
 287  
 288          if ( ! ( $_post instanceof stdClass ) && ! ( $_post instanceof WP_Post ) ) {
 289              $_post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d LIMIT 1", $post_id ) );
 290  
 291              if ( ! $_post ) {
 292                  return false;
 293              }
 294  
 295              $_post = sanitize_post( $_post, 'raw' );
 296              wp_cache_add( (int) $_post->ID, $_post, 'posts' );
 297          } elseif ( empty( $_post->filter ) || 'raw' !== $_post->filter ) {
 298              $_post = sanitize_post( $_post, 'raw' );
 299          }
 300  
 301          return new WP_Post( $_post );
 302      }
 303  
 304      /**
 305       * Constructor.
 306       *
 307       * @since 3.5.0
 308       *
 309       * @param object $post Post object.
 310       */
 311  	public function __construct( $post ) {
 312          foreach ( get_object_vars( $post ) as $key => $value ) {
 313              $this->$key = $value;
 314          }
 315      }
 316  
 317      /**
 318       * Isset-er.
 319       *
 320       * @since 3.5.0
 321       *
 322       * @param string $key Property to check if set.
 323       * @return bool
 324       */
 325  	public function __isset( $key ) {
 326          if ( 'ancestors' === $key ) {
 327              return true;
 328          }
 329  
 330          if ( 'page_template' === $key ) {
 331              return true;
 332          }
 333  
 334          if ( 'post_category' === $key ) {
 335              return true;
 336          }
 337  
 338          if ( 'tags_input' === $key ) {
 339              return true;
 340          }
 341  
 342          return metadata_exists( 'post', $this->ID, $key );
 343      }
 344  
 345      /**
 346       * Getter.
 347       *
 348       * @since 3.5.0
 349       *
 350       * @param string $key Key to get.
 351       * @return mixed
 352       */
 353  	public function __get( $key ) {
 354          if ( 'page_template' === $key && $this->__isset( $key ) ) {
 355              return get_post_meta( $this->ID, '_wp_page_template', true );
 356          }
 357  
 358          if ( 'post_category' === $key ) {
 359              if ( is_object_in_taxonomy( $this->post_type, 'category' ) ) {
 360                  $terms = get_the_terms( $this, 'category' );
 361              }
 362  
 363              if ( empty( $terms ) || $terms instanceof WP_Error ) {
 364                  return array();
 365              }
 366  
 367              return wp_list_pluck( $terms, 'term_id' );
 368          }
 369  
 370          if ( 'tags_input' === $key ) {
 371              if ( is_object_in_taxonomy( $this->post_type, 'post_tag' ) ) {
 372                  $terms = get_the_terms( $this, 'post_tag' );
 373              }
 374  
 375              if ( empty( $terms ) || $terms instanceof WP_Error ) {
 376                  return array();
 377              }
 378  
 379              return wp_list_pluck( $terms, 'name' );
 380          }
 381  
 382          // Rest of the values need filtering.
 383          if ( 'ancestors' === $key ) {
 384              $value = get_post_ancestors( $this );
 385          } else {
 386              $value = get_post_meta( $this->ID, $key, true );
 387          }
 388  
 389          if ( $this->filter ) {
 390              $value = sanitize_post_field( $key, $value, $this->ID, $this->filter );
 391          }
 392  
 393          return $value;
 394      }
 395  
 396      /**
 397       * Applies the provided context filter for the current post.
 398       *
 399       * If the requested filter was already applied, then it returns without any changes.
 400       *
 401       * If the 'raw' filter is supplied, then a new instance of the post is obtained and this method _may_ return false
 402       * in case the underlying post was deleted.
 403       *
 404       * @since 3.5.0
 405       *
 406       * @param string $filter Filter.
 407       * @return WP_Post|false
 408       *
 409       * @phpstan-param 'raw'|'edit'|'db'|'display'|'attribute'|'js' $filter
 410       * @phpstan-return (
 411       *     $filter is 'raw' ? WP_Post|false : WP_Post
 412       * )
 413       */
 414  	public function filter( $filter ) {
 415          if ( $this->filter === $filter ) {
 416              return $this;
 417          }
 418  
 419          if ( 'raw' === $filter ) {
 420              return self::get_instance( $this->ID );
 421          }
 422  
 423          return sanitize_post( $this, $filter );
 424      }
 425  
 426      /**
 427       * Convert object to array.
 428       *
 429       * @since 3.5.0
 430       *
 431       * @return array<string, mixed> Object as array.
 432       *
 433       * @phpstan-return Data_Array
 434       */
 435  	public function to_array() {
 436          $post = get_object_vars( $this );
 437  
 438          foreach ( array( 'ancestors', 'page_template', 'post_category', 'tags_input' ) as $key ) {
 439              if ( $this->__isset( $key ) ) {
 440                  $post[ $key ] = $this->__get( $key );
 441              }
 442          }
 443  
 444          /** @var Data_Array $post */
 445          return $post;
 446      }
 447  }