| @@ -1,6 +1,8 @@ | ||
| 1 | 1 | <?php |
| 2 | 2 | /** |
| 3 | + * The Polylang public API. | |
| 4 | + * | |
| 3 | 5 | * @package Polylang |
| 4 | 6 | */ |
| 5 | 7 | |
| 6 | 8 | /** |
| @@ -28,8 +30,12 @@ | ||
| 28 | 30 | * } |
| 29 | 31 | * @return string|array Either the html markup of the switcher or the raw elements to build a custom language switcher. |
| 30 | 32 | */ |
| 31 | 33 | function pll_the_languages( $args = array() ) { |
| 34 | + if ( empty( PLL()->links ) ) { | |
| 35 | + return empty( $args['raw'] ) ? '' : array(); | |
| 36 | + } | |
| 37 | + | |
| 32 | 38 | $switcher = new PLL_Switcher(); |
| 33 | 39 | return $switcher->the_languages( PLL()->links, $args ); |
| 34 | 40 | } |
| 35 | 41 | |
| @@ -34,21 +40,36 @@ | ||
| 34 | 40 | } |
| 35 | 41 | |
| 36 | 42 | /** |
| 37 | 43 | * Returns the current language on frontend. |
| 38 | - * Returns the language set in admin language filter on backend ( false if set to all languages ). | |
| 44 | + * Returns the language set in admin language filter on backend (false if set to all languages). | |
| 39 | 45 | * |
| 40 | 46 | * @api |
| 41 | 47 | * @since 0.8.1 |
| 48 | + * @since 3.4 Accepts composite values. | |
| 42 | 49 | * |
| 43 | - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. Pass OBJECT constant to get the language object. | |
| 44 | - * @return string|PLL_Language|false The requested field for the current language. | |
| 50 | + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`. | |
| 51 | + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language | |
| 52 | + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see | |
| 53 | + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`. | |
| 54 | + * @return string|int|bool|string[]|PLL_Language The requested field or object for the current language, `false` if the field isn't set or if current language doesn't exist yet. | |
| 55 | + * | |
| 56 | + * @phpstan-return ( | |
| 57 | + * $field is \OBJECT ? PLL_Language : ( | |
| 58 | + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string> | |
| 59 | + * ) | |
| 60 | + * )|false | |
| 45 | 61 | */ |
| 46 | 62 | function pll_current_language( $field = 'slug' ) { |
| 47 | - if ( OBJECT === $field ) { | |
| 63 | + if ( empty( PLL()->curlang ) ) { | |
| 64 | + return false; | |
| 65 | + } | |
| 66 | + | |
| 67 | + if ( \OBJECT === $field ) { | |
| 48 | 68 | return PLL()->curlang; |
| 49 | 69 | } |
| 50 | - return isset( PLL()->curlang->$field ) ? PLL()->curlang->$field : false; | |
| 70 | + | |
| 71 | + return PLL()->curlang->get_prop( $field ); | |
| 51 | 72 | } |
| 52 | 73 | |
| 53 | 74 | /** |
| 54 | 75 | * Returns the default language. |
| @@ -54,51 +75,82 @@ | ||
| 54 | 75 | * Returns the default language. |
| 55 | 76 | * |
| 56 | 77 | * @api |
| 57 | 78 | * @since 1.0 |
| 79 | + * @since 3.4 Accepts composite values. | |
| 58 | 80 | * |
| 59 | - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. Pass OBJECT constant to get the language object. | |
| 60 | - * @return string|PLL_Language|false The requested field for the default language. | |
| 81 | + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`. | |
| 82 | + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language | |
| 83 | + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see | |
| 84 | + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`. | |
| 85 | + * @return string|int|bool|string[]|PLL_Language The requested field or object for the default language, `false` if the field isn't set or if default language doesn't exist yet. | |
| 86 | + * | |
| 87 | + * @phpstan-return ( | |
| 88 | + * $field is \OBJECT ? PLL_Language : ( | |
| 89 | + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string> | |
| 90 | + * ) | |
| 91 | + * )|false | |
| 61 | 92 | */ |
| 62 | 93 | function pll_default_language( $field = 'slug' ) { |
| 63 | - if ( isset( PLL()->options['default_lang'] ) ) { | |
| 64 | - $lang = PLL()->model->get_language( PLL()->options['default_lang'] ); | |
| 65 | - if ( $lang ) { | |
| 66 | - if ( OBJECT === $field ) { | |
| 67 | - return $lang; | |
| 68 | - } | |
| 69 | - return isset( $lang->$field ) ? $lang->$field : false; | |
| 70 | - } | |
| 94 | + $lang = PLL()->model->get_default_language(); | |
| 95 | + | |
| 96 | + if ( empty( $lang ) ) { | |
| 97 | + return false; | |
| 71 | 98 | } |
| 72 | - return false; | |
| 99 | + | |
| 100 | + if ( \OBJECT === $field ) { | |
| 101 | + return $lang; | |
| 102 | + } | |
| 103 | + | |
| 104 | + return $lang->get_prop( $field ); | |
| 73 | 105 | } |
| 74 | 106 | |
| 75 | 107 | /** |
| 76 | - * Among the post and its translations, returns the id of the post which is in the language represented by $lang. | |
| 108 | + * Among the post and its translations, returns the ID of the post which is in the language represented by $lang. | |
| 77 | 109 | * |
| 78 | 110 | * @api |
| 79 | 111 | * @since 0.5 |
| 112 | + * @since 3.4 Returns `0` instead of `false` if not translated or if the post has no language. | |
| 113 | + * @since 3.4 $lang accepts `PLL_Language` or string. | |
| 80 | 114 | * |
| 81 | - * @param int $post_id Post id. | |
| 82 | - * @param string $lang Optional language code, defaults to the current language. | |
| 83 | - * @return int|false|null Post id of the translation if it exists, false otherwise, null if the current language is not defined yet. | |
| 115 | + * @param int $post_id Post ID. | |
| 116 | + * @param PLL_Language|string $lang Optional language (object or slug), defaults to the current language. | |
| 117 | + * @return int The translation post ID if exists. 0 if not translated, the post has no language or if the language doesn't exist. | |
| 118 | + * | |
| 119 | + * @phpstan-return int<0, max> | |
| 84 | 120 | */ |
| 85 | 121 | function pll_get_post( $post_id, $lang = '' ) { |
| 86 | - return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->post->get( $post_id, $lang ) : null; | |
| 122 | + $lang = $lang ?: pll_current_language(); | |
| 123 | + | |
| 124 | + if ( empty( $lang ) ) { | |
| 125 | + return 0; | |
| 126 | + } | |
| 127 | + | |
| 128 | + return PLL()->model->post->get( $post_id, $lang ); | |
| 87 | 129 | } |
| 88 | 130 | |
| 89 | 131 | /** |
| 90 | - * Among the term and its translations, returns the id of the term which is in the language represented by $lang. | |
| 132 | + * Among the term and its translations, returns the ID of the term which is in the language represented by $lang. | |
| 91 | 133 | * |
| 92 | 134 | * @api |
| 93 | 135 | * @since 0.5 |
| 136 | + * @since 3.4 Returns `0` instead of `false` if not translated or if the term has no language. | |
| 137 | + * @since 3.4 $lang accepts PLL_Language or string. | |
| 94 | 138 | * |
| 95 | - * @param int $term_id Term id. | |
| 96 | - * @param string $lang Optional language code, defaults to the current language. | |
| 97 | - * @return int|false|null Term id of the translation if it exists, false otherwise, null if the current language is not defined yet. | |
| 139 | + * @param int $term_id Term ID. | |
| 140 | + * @param PLL_Language|string $lang Optional language (object or slug), defaults to the current language. | |
| 141 | + * @return int The translation term ID if exists. 0 if not translated, the term has no language or if the language doesn't exist. | |
| 142 | + * | |
| 143 | + * @phpstan-return int<0, max> | |
| 98 | 144 | */ |
| 99 | 145 | function pll_get_term( $term_id, $lang = '' ) { |
| 100 | - return ( $lang = $lang ? $lang : pll_current_language() ) ? PLL()->model->term->get( $term_id, $lang ) : null; | |
| 146 | + $lang = $lang ?: pll_current_language(); | |
| 147 | + | |
| 148 | + if ( empty( $lang ) ) { | |
| 149 | + return 0; | |
| 150 | + } | |
| 151 | + | |
| 152 | + return PLL()->model->term->get( $term_id, $lang ); | |
| 101 | 153 | } |
| 102 | 154 | |
| 103 | 155 | /** |
| 104 | 156 | * Returns the home url in a language. |
| @@ -113,9 +165,13 @@ | ||
| 113 | 165 | if ( empty( $lang ) ) { |
| 114 | 166 | $lang = pll_current_language(); |
| 115 | 167 | } |
| 116 | 168 | |
| 117 | - return empty( $lang ) ? home_url( '/' ) : PLL()->links->get_home_url( $lang ); | |
| 169 | + if ( empty( $lang ) || empty( PLL()->links ) ) { | |
| 170 | + return home_url( '/' ); | |
| 171 | + } | |
| 172 | + | |
| 173 | + return PLL()->links->get_home_url( $lang ); | |
| 118 | 174 | } |
| 119 | 175 | |
| 120 | 176 | /** |
| 121 | 177 | * Registers a string for translation in the "strings translation" panel. |
| @@ -145,9 +201,13 @@ | ||
| 145 | 201 | * @param string $string The string to translate. |
| 146 | 202 | * @return string The string translated in the current language. |
| 147 | 203 | */ |
| 148 | 204 | function pll__( $string ) { |
| 149 | - return is_scalar( $string ) ? __( $string, 'pll_string' ) : $string; // PHPCS:ignore WordPress.WP.I18n | |
| 205 | + if ( ! is_scalar( $string ) || '' === $string ) { | |
| 206 | + return $string; | |
| 207 | + } | |
| 208 | + | |
| 209 | + return __( $string, 'pll_string' ); // PHPCS:ignore WordPress.WP.I18n | |
| 150 | 210 | } |
| 151 | 211 | |
| 152 | 212 | /** |
| 153 | 213 | * Translates a string ( previously registered with pll_register_string ) and escapes it for safe use in HTML output. |
| @@ -225,27 +285,24 @@ | ||
| 225 | 285 | * @param string $lang Language code. |
| 226 | 286 | * @return string The string translated in the requested language. |
| 227 | 287 | */ |
| 228 | 288 | function pll_translate_string( $string, $lang ) { |
| 229 | - if ( PLL() instanceof PLL_Frontend && pll_current_language() == $lang ) { | |
| 289 | + if ( PLL() instanceof PLL_Frontend && pll_current_language() === $lang ) { | |
| 230 | 290 | return pll__( $string ); |
| 231 | 291 | } |
| 232 | 292 | |
| 233 | - if ( ! is_scalar( $string ) ) { | |
| 293 | + if ( ! is_scalar( $string ) || '' === $string ) { | |
| 234 | 294 | return $string; |
| 235 | 295 | } |
| 236 | 296 | |
| 237 | - static $cache; // Cache object to avoid loading the same translations object several times. | |
| 297 | + $lang = PLL()->model->get_language( $lang ); | |
| 238 | 298 | |
| 239 | - if ( empty( $cache ) ) { | |
| 240 | - $cache = new PLL_Cache(); | |
| 299 | + if ( empty( $lang ) ) { | |
| 300 | + return $string; | |
| 241 | 301 | } |
| 242 | 302 | |
| 243 | - if ( false === $mo = $cache->get( $lang ) ) { | |
| 244 | - $mo = new PLL_MO(); | |
| 245 | - $mo->import_from_db( PLL()->model->get_language( $lang ) ); | |
| 246 | - $cache->set( $lang, $mo ); | |
| 247 | - } | |
| 303 | + $mo = new PLL_MO(); | |
| 304 | + $mo->import_from_db( $lang ); | |
| 248 | 305 | |
| 249 | 306 | return $mo->translate( $string ); |
| 250 | 307 | } |
| 251 | 308 | |
| @@ -298,15 +355,18 @@ | ||
| 298 | 355 | * Sets the post language. |
| 299 | 356 | * |
| 300 | 357 | * @api |
| 301 | 358 | * @since 1.5 |
| 359 | + * @since 3.4 $lang accepts PLL_Language or string. | |
| 360 | + * @since 3.4 Returns a boolean. | |
| 302 | 361 | * |
| 303 | - * @param int $id Post id. | |
| 304 | - * @param string $lang Language code. | |
| 305 | - * @return void | |
| 362 | + * @param int $id Post ID. | |
| 363 | + * @param PLL_Language|string $lang Language (object or slug). | |
| 364 | + * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to | |
| 365 | + * the post). | |
| 306 | 366 | */ |
| 307 | 367 | function pll_set_post_language( $id, $lang ) { |
| 308 | - PLL()->model->post->set_language( $id, $lang ); | |
| 368 | + return PLL()->model->post->set_language( $id, $lang ); | |
| 309 | 369 | } |
| 310 | 370 | |
| 311 | 371 | /** |
| 312 | 372 | * Sets the term language. |
| @@ -312,15 +372,18 @@ | ||
| 312 | 372 | * Sets the term language. |
| 313 | 373 | * |
| 314 | 374 | * @api |
| 315 | 375 | * @since 1.5 |
| 376 | + * @since 3.4 $lang accepts PLL_Language or string. | |
| 377 | + * @since 3.4 Returns a boolean. | |
| 316 | 378 | * |
| 317 | - * @param int $id Term id. | |
| 318 | - * @param string $lang Language code. | |
| 319 | - * @return void | |
| 379 | + * @param int $id Term ID. | |
| 380 | + * @param PLL_Language|string $lang Language (object or slug). | |
| 381 | + * @return bool True when successfully assigned. False otherwise (or if the given language is already assigned to | |
| 382 | + * the term). | |
| 320 | 383 | */ |
| 321 | 384 | function pll_set_term_language( $id, $lang ) { |
| 322 | - PLL()->model->term->set_language( $id, $lang ); | |
| 385 | + return PLL()->model->term->set_language( $id, $lang ); | |
| 323 | 386 | } |
| 324 | 387 | |
| 325 | 388 | /** |
| 326 | 389 | * Save posts translations. |
| @@ -326,14 +389,22 @@ | ||
| 326 | 389 | * Save posts translations. |
| 327 | 390 | * |
| 328 | 391 | * @api |
| 329 | 392 | * @since 1.5 |
| 393 | + * @since 3.4 Returns an associative array of translations. | |
| 330 | 394 | * |
| 331 | - * @param int[] $arr An associative array of translations with language code as key and post id as value. | |
| 332 | - * @return void | |
| 395 | + * @param int[] $arr An associative array of translations with language code as key and post ID as value. | |
| 396 | + * @return int[] An associative array with language codes as key and post IDs as values. | |
| 397 | + * | |
| 398 | + * @phpstan-return array<non-empty-string, positive-int> | |
| 333 | 399 | */ |
| 334 | 400 | function pll_save_post_translations( $arr ) { |
| 335 | - PLL()->model->post->save_translations( reset( $arr ), $arr ); | |
| 401 | + $id = reset( $arr ); | |
| 402 | + if ( $id ) { | |
| 403 | + return PLL()->model->post->save_translations( $id, $arr ); | |
| 404 | + } | |
| 405 | + | |
| 406 | + return array(); | |
| 336 | 407 | } |
| 337 | 408 | |
| 338 | 409 | /** |
| 339 | 410 | * Save terms translations |
| @@ -339,14 +410,22 @@ | ||
| 339 | 410 | * Save terms translations |
| 340 | 411 | * |
| 341 | 412 | * @api |
| 342 | 413 | * @since 1.5 |
| 414 | + * @since 3.4 Returns an associative array of translations. | |
| 343 | 415 | * |
| 344 | - * @param int[] $arr An associative array of translations with language code as key and term id as value. | |
| 345 | - * @return void | |
| 416 | + * @param int[] $arr An associative array of translations with language code as key and term ID as value. | |
| 417 | + * @return int[] An associative array with language codes as key and term IDs as values. | |
| 418 | + * | |
| 419 | + * @phpstan-return array<non-empty-string, positive-int> | |
| 346 | 420 | */ |
| 347 | 421 | function pll_save_term_translations( $arr ) { |
| 348 | - PLL()->model->term->save_translations( reset( $arr ), $arr ); | |
| 422 | + $id = reset( $arr ); | |
| 423 | + if ( $id ) { | |
| 424 | + return PLL()->model->term->save_translations( $id, $arr ); | |
| 425 | + } | |
| 426 | + | |
| 427 | + return array(); | |
| 349 | 428 | } |
| 350 | 429 | |
| 351 | 430 | /** |
| 352 | 431 | * Returns the post language. |
| @@ -352,15 +431,31 @@ | ||
| 352 | 431 | * Returns the post language. |
| 353 | 432 | * |
| 354 | 433 | * @api |
| 355 | 434 | * @since 1.5.4 |
| 435 | + * @since 3.4 Accepts composite values for `$field`. | |
| 356 | 436 | * |
| 357 | - * @param int $post_id Post id. | |
| 358 | - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. | |
| 359 | - * @return string|false The requested field for the post language, false if no language is associated to that post. | |
| 437 | + * @param int $post_id Post ID. | |
| 438 | + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`. | |
| 439 | + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language | |
| 440 | + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see | |
| 441 | + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`. | |
| 442 | + * @return string|int|bool|string[]|PLL_Language The requested field or object for the post language, `false` if no language is associated to that post. | |
| 443 | + * | |
| 444 | + * @phpstan-return ( | |
| 445 | + * $field is \OBJECT ? PLL_Language : ( | |
| 446 | + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string> | |
| 447 | + * ) | |
| 448 | + * )|false | |
| 360 | 449 | */ |
| 361 | 450 | function pll_get_post_language( $post_id, $field = 'slug' ) { |
| 362 | - return ( $lang = PLL()->model->post->get_language( $post_id ) ) ? $lang->$field : false; | |
| 451 | + $lang = PLL()->model->post->get_language( $post_id ); | |
| 452 | + | |
| 453 | + if ( empty( $lang ) || \OBJECT === $field ) { | |
| 454 | + return $lang; | |
| 455 | + } | |
| 456 | + | |
| 457 | + return $lang->get_prop( $field ); | |
| 363 | 458 | } |
| 364 | 459 | |
| 365 | 460 | /** |
| 366 | 461 | * Returns the term language. |
| @@ -366,15 +461,31 @@ | ||
| 366 | 461 | * Returns the term language. |
| 367 | 462 | * |
| 368 | 463 | * @api |
| 369 | 464 | * @since 1.5.4 |
| 465 | + * @since 3.4 Accepts composite values for `$field`. | |
| 370 | 466 | * |
| 371 | - * @param int $term_id Term id. | |
| 372 | - * @param string $field Optional, the language field to return ( @see PLL_Language ), defaults to 'slug'. | |
| 373 | - * @return string|false The requested field for the term language, false if no language is associated to that term. | |
| 467 | + * @param int $term_id Term ID. | |
| 468 | + * @param string $field Optional, the language field to return (@see PLL_Language), defaults to `'slug'`. | |
| 469 | + * Pass `\OBJECT` constant to get the language object. A composite value can be used for language | |
| 470 | + * term property values, in the form of `{language_taxonomy_name}:{property_name}` (see | |
| 471 | + * {@see PLL_Language::get_tax_prop()} for the possible values). Ex: `term_language:term_taxonomy_id`. | |
| 472 | + * @return string|int|bool|string[]|PLL_Language The requested field or object for the post language, `false` if no language is associated to that term. | |
| 473 | + * | |
| 474 | + * @phpstan-return ( | |
| 475 | + * $field is \OBJECT ? PLL_Language : ( | |
| 476 | + * $field is 'slug' ? non-empty-string : string|int|bool|list<non-empty-string> | |
| 477 | + * ) | |
| 478 | + * )|false | |
| 374 | 479 | */ |
| 375 | 480 | function pll_get_term_language( $term_id, $field = 'slug' ) { |
| 376 | - return ( $lang = PLL()->model->term->get_language( $term_id ) ) ? $lang->$field : false; | |
| 481 | + $lang = PLL()->model->term->get_language( $term_id ); | |
| 482 | + | |
| 483 | + if ( empty( $lang ) || \OBJECT === $field ) { | |
| 484 | + return $lang; | |
| 485 | + } | |
| 486 | + | |
| 487 | + return $lang->get_prop( $field ); | |
| 377 | 488 | } |
| 378 | 489 | |
| 379 | 490 | /** |
| 380 | 491 | * Returns an array of translations of a post. |
| @@ -381,10 +492,12 @@ | ||
| 381 | 492 | * |
| 382 | 493 | * @api |
| 383 | 494 | * @since 1.8 |
| 384 | 495 | * |
| 385 | - * @param int $post_id Post id. | |
| 386 | - * @return int[] An associative array of translations with language code as key and translation post id as value. | |
| 496 | + * @param int $post_id Post ID. | |
| 497 | + * @return int[] An associative array of translations with language code as key and translation post ID as value. | |
| 498 | + * | |
| 499 | + * @phpstan-return array<non-empty-string, positive-int> | |
| 387 | 500 | */ |
| 388 | 501 | function pll_get_post_translations( $post_id ) { |
| 389 | 502 | return PLL()->model->post->get_translations( $post_id ); |
| 390 | 503 | } |
| @@ -394,10 +507,12 @@ | ||
| 394 | 507 | * |
| 395 | 508 | * @api |
| 396 | 509 | * @since 1.8 |
| 397 | 510 | * |
| 398 | - * @param int $term_id Term id. | |
| 399 | - * @return int[] An associative array of translations with language code as key and translation term id as value. | |
| 511 | + * @param int $term_id Term ID. | |
| 512 | + * @return int[] An associative array of translations with language code as key and translation term ID as value. | |
| 513 | + * | |
| 514 | + * @phpstan-return array<non-empty-string, positive-int> | |
| 400 | 515 | */ |
| 401 | 516 | function pll_get_term_translations( $term_id ) { |
| 402 | 517 | return PLL()->model->term->get_translations( $term_id ); |
| 403 | 518 | } |
| @@ -409,10 +524,9 @@ | ||
| 409 | 524 | * @since 1.5 |
| 410 | 525 | * |
| 411 | 526 | * @param string $lang Language code. |
| 412 | 527 | * @param array $args { |
| 413 | - * Optional arguments. | |
| 414 | - * Accepted keys: | |
| 528 | + * Optional array of arguments. | |
| 415 | 529 | * |
| 416 | 530 | * @type string $post_type Post type. |
| 417 | 531 | * @type int $m YearMonth ( ex: 201307 ). |
| 418 | 532 | * @type int $year 4 digit year. |
| @@ -425,9 +539,121 @@ | ||
| 425 | 539 | * } |
| 426 | 540 | * @return int Posts count. |
| 427 | 541 | */ |
| 428 | 542 | function pll_count_posts( $lang, $args = array() ) { |
| 429 | - return PLL()->model->count_posts( PLL()->model->get_language( $lang ), $args ); | |
| 543 | + $lang = PLL()->model->get_language( $lang ); | |
| 544 | + | |
| 545 | + if ( empty( $lang ) ) { | |
| 546 | + return 0; | |
| 547 | + } | |
| 548 | + | |
| 549 | + return PLL()->model->count_posts( $lang, $args ); | |
| 550 | +} | |
| 551 | + | |
| 552 | +/** | |
| 553 | + * Wraps `wp_insert_post` with language feature. | |
| 554 | + * | |
| 555 | + * @since 3.7 | |
| 556 | + * | |
| 557 | + * @param array $postarr { | |
| 558 | + * An array of elements that make up a post to insert. | |
| 559 | + * @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments. | |
| 560 | + * | |
| 561 | + * @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values. | |
| 562 | + * } | |
| 563 | + * @param PLL_Language|string $language The post language object or slug. | |
| 564 | + * @return int|WP_Error The post ID on success. The value `WP_Error` on failure. | |
| 565 | + */ | |
| 566 | +function pll_insert_post( array $postarr, $language ) { | |
| 567 | + $language = PLL()->model->get_language( $language ); | |
| 568 | + | |
| 569 | + if ( ! $language instanceof PLL_Language ) { | |
| 570 | + return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) ); | |
| 571 | + } | |
| 572 | + | |
| 573 | + return PLL()->model->post->insert( $postarr, $language ); | |
| 574 | +} | |
| 575 | + | |
| 576 | +/** | |
| 577 | + * Wraps `wp_insert_term` with language feature. | |
| 578 | + * | |
| 579 | + * @since 3.7 | |
| 580 | + * | |
| 581 | + * @param string $term The term name to add. | |
| 582 | + * @param string $taxonomy The taxonomy to which to add the term. | |
| 583 | + * @param PLL_Language|string $language The term language object or slug. | |
| 584 | + * @param array $args { | |
| 585 | + * Optional. Array of arguments for inserting a term. | |
| 586 | + * | |
| 587 | + * @type string $alias_of Slug of the term to make this term an alias of. | |
| 588 | + * Default empty string. Accepts a term slug. | |
| 589 | + * @type string $description The term description. Default empty string. | |
| 590 | + * @type int $parent The id of the parent term. Default 0. | |
| 591 | + * @type string $slug The term slug to use. Default empty string. | |
| 592 | + * @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values. | |
| 593 | + * } | |
| 594 | + * @return array|WP_Error { | |
| 595 | + * An array of the new term data, `WP_Error` otherwise. | |
| 596 | + * | |
| 597 | + * @type int $term_id The new term ID. | |
| 598 | + * @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string. | |
| 599 | + * } | |
| 600 | + */ | |
| 601 | +function pll_insert_term( string $term, string $taxonomy, $language, array $args = array() ) { | |
| 602 | + $language = PLL()->model->get_language( $language ); | |
| 603 | + | |
| 604 | + if ( ! $language instanceof PLL_Language ) { | |
| 605 | + return new WP_Error( 'invalid_language', __( 'Please provide a valid language.', 'polylang' ) ); | |
| 606 | + } | |
| 607 | + | |
| 608 | + return PLL()->model->term->insert( $term, $taxonomy, $language, $args ); | |
| 609 | +} | |
| 610 | + | |
| 611 | +/** | |
| 612 | + * Wraps `wp_update_post` with language feature. | |
| 613 | + * | |
| 614 | + * @since 3.7 | |
| 615 | + * | |
| 616 | + * @param array $postarr { | |
| 617 | + * Optional. An array of elements that make up a post to update. | |
| 618 | + * @See https://developer.wordpress.org/reference/functions/wp_insert_post/ wp_insert_post() for accepted arguments. | |
| 619 | + * | |
| 620 | + * @type PLL_Language|string $lang The post language object or slug. | |
| 621 | + * @type string[] $translations The translation group to assign to the post with language slug as keys and post ID as values. | |
| 622 | + * } | |
| 623 | + * @return int|WP_Error The post ID on success. The value `WP_Error` on failure. | |
| 624 | + */ | |
| 625 | +function pll_update_post( array $postarr ) { | |
| 626 | + return PLL()->model->post->update( $postarr ); | |
| 627 | +} | |
| 628 | + | |
| 629 | +/** | |
| 630 | + * Wraps `wp_update_term` with language feature. | |
| 631 | + * | |
| 632 | + * @since 3.7 | |
| 633 | + * | |
| 634 | + * @param int $term_id The ID of the term. | |
| 635 | + * @param array $args { | |
| 636 | + * Optional. Array of arguments for updating a term. | |
| 637 | + * | |
| 638 | + * @type string $alias_of Slug of the term to make this term an alias of. | |
| 639 | + * Default empty string. Accepts a term slug. | |
| 640 | + * @type string $description The term description. Default empty string. | |
| 641 | + * @type int $parent The id of the parent term. Default 0. | |
| 642 | + * @type string $slug The term slug to use. Default empty string. | |
| 643 | + * @type string $name The term name. | |
| 644 | + * @type PLL_Language|string $lang The term language object or slug. | |
| 645 | + * @type string[] $translations The translation group to assign to the term with language slug as keys and `term_id` as values. | |
| 646 | + * } | |
| 647 | + * @return array|WP_Error { | |
| 648 | + * An array containing the `term_id` and `term_taxonomy_id`, `WP_Error` otherwise. | |
| 649 | + * | |
| 650 | + * @type int $term_id The new term ID. | |
| 651 | + * @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string. | |
| 652 | + * } | |
| 653 | + */ | |
| 654 | +function pll_update_term( int $term_id, array $args = array() ) { | |
| 655 | + return PLL()->model->term->update( $term_id, $args ); | |
| 430 | 656 | } |
| 431 | 657 | |
| 432 | 658 | /** |
| 433 | 659 | * Allows to access the Polylang instance. |
