Page object

From Apibot
Jump to: navigation, search

This object represents a wiki page.

Properties

Original properties

The object has properties matching the page properties that were fetched.

For a full list of the possible page properties, see the MediaWiki API documentation on the topic.

Editable page properties

When fetch a page with the intention to edit it, you do it together with its last revision (or with a specified one). In this case, the page will have not only the page properties you specified to fetch, but also the following attributes of the revision (if fetched):

  • $text ('*')
  • $timestamp
  • $revid
  • $parentid
  • $size
  • $user
  • $comment

Methods

Unlike most data objects, Page has a plethora of methods. Most of these are targeted at convenient editing of the page content - that is, to make use of them you need to fetch the page in an editable form.

Info methods

  • is_redirect() - whether this page is a redirect (true or false). Based on whether the text contains a redirect MW keyword, not on the page property returned by the wiki.
  • redirects_to() - the title of the page this one redirects to, or NULL if it is not a redirect.
  • is_main() - whether this is a main page (true or false), as opposed to a talk or special page.
  • is_talk() - whether this is a talk page (true or false).
  • is_special() - whether this is a special page (true or false).
  • main_page_title() - if this page is a talk one, the title of its main page; if it is a main one, its own title; if it is a special page, NULL.
  • talk_page_title() - if this page is a main one, the title of its talk page; if it is a talk one, its own title; if it is a special page, NULL.

Simple editing

  • regex_exists ( $regex ) - whether all or part of page text matches this regex (true or false).
  • string_exists ( $regex ) - whether the page text contains this string (true or false).
  • replace_regex ( $regex, $with, $limit = -1 ) - replace the match of $regex with the string $with, up to $limit times (-1 - unlimited). Returns the count of the replacements made.
  • replace_string ( $string, $with ) - replace $string with $with everywhere in the text. Returns the count of the replacements made.
  • append ( $text ) - appends $text to the current page text.
  • prepend ( $text ) - prepends $text to the current page text.
  • insert ( $text, $regexpart_before = NULL, $regexpart_after = NULL, $limit = -1 ) - inserts $text in the page text in places after a match for $regexpart_before and before a match for $regexpart_after, up to $limit number of times (-1 - unlimited). Returns the number of the inserts made.
    (The regexparts are not complete regexes - should not contain leading or trailing slash, or post-trailing-slash modifiers.)
  • delete ( $regex, $limit = -1 ) - deletes the match of $regex, up to $limit times (-1 - unlimited). Returns the count of the deletes made.

Handling wikilinks

  • wikilinks ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL ) - returns an array with all wikilinks (as arrays of parts) that match the parameters supplied:
    • $colon - only wikilinks that start with a colon (true), only ones that do not start with a colon (false), or both types (NULL)
    • $wiki - regexpart that the wiki part of the wikilink must match (NULL - any)
    • $namespace - regexpart that the namespace part of the wikilink must match (NULL - any)
    • $name - regexpart that the page name part of the wikilink must match (NULL - any)
    • $anchor - regexpart that the anchor part of the wikilink must match (NULL - any)
    • $text - regexpart that the text string part of the wikilink must match (NULL - any)

The wikilinks arrays will have the following keys and values:

    • 'colon' - true if the wikilink starts with a colon, false otherwise
    • 'wiki' - the wiki part of the wikilink (empty if one is not present)
    • 'namespace' - the namespace part of the wikilink (empty if one is not present)
    • 'name' - the name part of the wikilink (empty if one is not present)
    • 'anchor' - the anchor part of the wikilink (empty if one is not present)
    • 'text' - the text / last parameter part of the wikilink (empty if one is not present)
    • 'newline_after' - true if there is a newline after the wikilink, false otherwise
  • wikilinks_strings ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL ) - returns an array with all wikilinks (as strings) that match the parameters supplied.
  • wikilink_exists ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL ) - returns true if such a wikilink exists in the page, false if it doesn't.
  • replace_wikilink ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL, $with = NULL, $limit = -1 ) - replaces the wikilinks with such parts with $with. Returns the count of the replacements.
    The $with string can contain references for the original wikilink parts that will be replaced as follows:
    • $0 - the entire wikilink
    • $1 - the leading colon (if present)
    • $2 - the leading colon plus the wiki part (if present)
    • $3 - only the wiki part (if present)
    • $4 - the wikilink title - namespace (if present), colon (if present) and page name
    • $5 - the namespace (if present) and colon (if present)
    • $6 - the namespace only (if present)
    • $7 - the page name only (without namespace etc)
    • $8 - the sharp sign ('#') plus the anchor (if present)
    • $9 - the anchor only (if present)
    • $10 - the parameters (all bars plus texts) (if present)
    • $11 - last parameter bar plus text (if present)
    • $12 - last parameter text (if present)
    • $13 - newline after the wikilink (if present)
  • unlink_wikilink ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL, $limit = -1 ) - unlinks wikilinks matching these params (replace them with their visible texts). Returns the count of the replaces made.
  • wikilink_text_by_regex ( $regex, $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $limit = -1 ) - wikilinks texts that match this regex with the given wikilinks parts. Returns the count of the wikilinks made.
  • wikilink_text ( $text, $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $limit = -1 ) - wikilinks this text string with the given wikilinks parts. Returns the count of the wikilinks made.
  • replace_wikilink_target ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL, $new_target = NULL, $limit = -1 ) - replaces the wikilink target page (and possibly anchor) with $new_target. Returns the count of replacements made.
  • replace_wikilink_text ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL, $new_text = NULL, $limit = -1 ) - replaces the wikilink visible text with $new_text. Returns the count of replacements made.
  • add_wikilink ( $wikilink, $regexpart_before = NULL, $regexpart_after = NULL, $limit = -1 ) - inserts this wikilink in the page text in places after a match for $regexpart_before and before a match for $regexpart_after, up to $limit number of times (-1 - unlimited). Returns the number of the inserts made.
    (The regexparts are not complete regexes - should not contain leading or trailing slash, or post-trailing-slash modifiers.)
  • delete_wikilinks ( $colon = NULL, $wiki = NULL, $namespace = NULL, $name = NULL, $anchor = NULL, $text = NULL, $limit = -1 ) - deletes the wikilinks that match these parts, up to $limit times (-1 - unlimited). Returns the count of the deletes made.

Handling categories

  • categories ( $name = NULL, $sortkey = NULL, $namespace = NULL, $newline_after = NULL ) - returns an array with all categories (as arrays of parts) that match the parameters supplied:
    • $name - regexpart that the category name part of the category must match (NULL - any)
    • $sortkey - regexpart that the sortkey part of the category must match (NULL - any)
    • $namespace - regexpart that the namespace part of the category (usually "Category") must match (NULL - any)
    • $newline_after - true if there must be a newline after this category, false if there must not be, NULL - no matter if present.

The categories arrays will have the following keys and values:

    • 'title' - the full title (namespace and name) of the category (empty if one is not present)
    • 'namespace' - the namespace part of the category (empty if one is not present)
    • 'name' - the name part of the category (empty if one is not present)
    • 'sortkey' - the sortkey part of the category (empty if one is not present)
    • 'newline_after' - true if there is a newline after the category, false otherwise
  • categories_strings ( $name = NULL, $sortkey = NULL, $namespace = NULL, $newline_after = NULL ) - returns an array with all categories (as strings) that match the parameters supplied.
  • categories_names ( $name = NULL, $sortkey = NULL, $namespace = NULL, $newline_after = NULL ) - returns an array with all categories names (without the "Category:" or equivalent preface) that match the parameters supplied.
  • categories_titles ( $name = NULL, $sortkey = NULL, $namespace = NULL, $newline_after = NULL ) - returns an array with all categories titles (including the "Category:" or equivalent preface) that match the parameters supplied.
  • category_exists ( $name = NULL, $sortkey = NULL, $namespace = NULL ) - returns true if a category that matches these parameters exists, false otherwise.
    The parameters can also be supplied as an array as a first argument, with 'name', 'sortkey' and 'namespace' keys.
  • add_category_string ( $string ) - appends this string (hopefully a category) to the end of the categories list (probably at the bottom of the page).
  • add_category ( $name, $sortkey = NULL, $namespace = NULL, $newline_after = NULL ) - appends a category with these parts to the end of the categories list. (The parts can also be supplied as an array as a first parameter, and with keys 'name', 'sortkey', 'namespace' and 'newline_after'.)
  • add_categories ( $categories ) - appends the categories arrays from this array to the end of the categories list.
  • delete_categories ( $name = NULL ) - delete the categories that match this name regexpart (if NULL or not given - all categories).
  • extract_categories_strings ( $name = NULL ) - delete the categories that match this name regexpart (if NULL or not given - all categories), and return them as an array with strings.
  • extract_categories ( $name = NULL ) - delete the categories that match this name regexpart (if NULL or not given - all categories), and return them as an array with categories arrays.
  • replace_category ( $old_name, $new_name, $new_sortkey = NULL ) - replace the category named as $old_name (regexpart) with a category named as $new_name. If $new_sortkey is supplied, it will be set, otherwise the old sortkey (if present) will be preserved.
  • category_sortkey ( $name ) - return the sortkey of the category with this name (regexpart).
  • set_category_sortkey ( $name, $new_sortkey ) - replace the sortkey of the category with this name (regexpart) with $new_sortkey. If that is empty, it will effectively delete the category sortkey.
  • delete_category_sortkey ( $name ) - delete the sortkey of the category with this name (regexpart).

Handling interwikis

  • interwikis ( $wiki = '*', $namespace = NULL, $name = NULL, $newline_after = NULL ) - returns an array with all interwikis (as arrays of parts) that match the parameters supplied:
    • $wiki - regexpart that the wiki part of the interwiki must match ('*' - any interwiki listed as valid by this wiki info)
    • $namespace - regexpart that the namespace part of the interwiki must match (NULL - any)
    • $name - regexpart that the page name part of the interwiki must match (NULL - any)
    • $newline_after - true if there must be a newline after this interwiki, false if there must not be, NULL - no matter if present.

The interwikis arrays will have the following keys and values:

    • 'wiki' - the wiki part of the interwiki (empty if one is not present)
    • 'title' - the full title (namespace and name) of the interwiki page
    • 'namespace' - the namespace part of the interwiki page (empty if one is not present)
    • 'name' - the name part of the interwiki page (empty if one is not present)
    • 'newline_after' - true if there is a newline after the interwiki, false otherwise
  • interwikis_strings ( $wiki = '*', $namespace = NULL, $name = NULL, $newline_after = NULL ) - returns an array with all interwikis (as strings) that match the parameters supplied.
  • interwikis_wikis ( $wiki = '*', $namespace = NULL, $name = NULL, $newline_after = NULL ) - returns an array with all interwikis wikis that match the parameters supplied.
  • interwiki_exists ( $wiki, $namespace = NULL, $name = NULL ) - returns true if such an interwiki exists in the page text, false otherwise.
  • interwiki_target ( $wiki ) - returns the interwiki target if this interwiki exists, NULL otherwise.
  • add_interwiki_string ( $string ) - add this interwiki string, if an interwiki to this wiki doesn't exist. Returns true if the interwiki string is added, false if such an interwiki already exists.
  • add_interwiki ( $wiki, $namespace = NULL, $name = NULL, $newline_after = NULL ) - adds this interwiki array. If an interwiki to this wiki already exists, replaces it.
  • add_interwikis ( $wikis_array ) - adds the interwiki arrays in this array. Returns the count of the interwikis added.
  • delete_interwikis ( $wiki = '*' ) - delete the interwikis that match this wiki. Returns the count of the interwikis deleted.
  • extract_interwikis_strings ( $wiki = '*' ) - deletes the interwikis that match this wiki and returns them as array of strings.
  • extract_interwikis ( $wiki = '*' ) - deletes the interwikis that match this wiki and returns them as array of interwiki arrays.
  • replace_interwikis ( $old_wiki, $new_wiki, $new_title ) - replace the interwiki that matches $old_wiki with the one formed by $new_wiki and $new_title. Both $old_wiki and $new_wiki can be interwiki arrays. $old_wiki may be a regexpart, and $new_wiki and $new_title may contain parameters to be replaced by the matches from the $old_wiki regexpart.
  • set_interwiki_target ( $wiki, $new_title ) - replace the interwiki that matches $wiki target (page title) with $new_title. $wiki can be interwiki array.

Handling filelinks

  • filelinks ( $name = NULL, $namespace = NULL ) - returns an array with all filelinks (as arrays of parts) that match the parameters supplied:
    • $namespace - regexpart that the namespace part of the filelink must match (NULL - any)
    • $name - regexpart that the page name part of the filelink must match (NULL - any)

The filelinks arrays will have the following keys and values:

    • 'title' - the full title (namespace and name) of the file page
    • 'namespace' - the namespace part of the file page (empty if one is not present)
    • 'name' - the name part of the file page (empty if one is not present)
    • 'params' - an array with the following parameters (those that are not present in the filelink will be empty):
      • 'format' - the filelink format parameter (border, borderless, frame etc)
      • 'resize' - the filelink resize parameter
      • 'align' - the filelink align parameter
      • 'valign' - the filelink valign parameter
      • 'link' - the filelink link parameter
      • 'alt' - the filelink alt parameter
      • 'page' - the filelink page parameter
    • 'caption' - the caption part of the filelink (empty if not present)
  • filelinks_strings ( $name = NULL, $namespace = NULL ) - returns an array with all filelinks (as strings) that match the parameters supplied.
  • filelink_exists ( $name, $namespace = NULL ) - returns true if a filelink that matches these parameters exists in the page text, false otherwise.
  • replace_filelink ( $name, $namespace = NULL, $with = NULL, $limit = -1 ) - replaces filelinks that match these parameters with the $with string, up to $limit times (-1 - unlimited). Returns the number of the replacements made.
  • replace_filelink_name ( $old_name, $new_name, $old_namespace = NULL, $new_namespace = NULL, $limit = -1 ) - replaces filelinks whose name matches $old_name (and $old_namespace if given) with $new_name (and $new_namespace if given) , up to $limit times (-1 - unlimited). Returns the number of the replacements made.
  • replace_filelink_param ( $name, $param, $new_value, $namespace = NULL ) - replaces the value of the param $param with $new_value in filelinks whose name matches $name (and $namespace if given). Returns the number of the replacements made.
  • replace_filelink_caption ( $name, $new_caption, $namespace = NULL ) - replaces the caption with $new_caption in filelinks whose name matches $name (and $namespace if given). Returns the number of the replacements made.
  • add_filelink ( $filelink, $regexpart_before = NULL, $regexpart_after = NULL, $limit = -1 ) - inserts this filelink in the page text in places after a match for $regexpart_before and before a match for $regexpart_after, up to $limit number of times (-1 - unlimited). Returns the number of the inserts made.
    (The regexparts are not complete regexes - should not contain leading or trailing slash, or post-trailing-slash modifiers.)
  • delete_filelinks ( $name = NULL, $namespace = NULL, $limit = -1 ) - deletes the filelinks that match these parts, up to $limit times (-1 - unlimited). Returns the count of the deletes made.

Handling templates

  • templates ( $name = NULL, $namespace = NULL, $wiki = NULL ) - returns an array with all templates (as arrays of parts) that match the parameters supplied:
    • $name - regexpart that the page name part of the template must match (NULL - any)
    • $namespace - regexpart that the page namespace part of the template must match (NULL - any)
    • $wiki - regexpart that the page wiki part of the template must match (NULL - any)

The templates arrays will have the following keys and values:

    • 'title' - the full title (namespace and name) of the template page
    • 'wiki' - the wiki part of the template page (empty if one is not present)
    • 'namespace' - the namespace part of the template page (empty if one is not present)
    • 'name' - the name part of the template page (empty if one is not present)
    • 'params' - an array with the template parameters (its keys are numeric if parameters are just ordered, and string names if parameters are named):
  • templates_strings ( $name = NULL, $namespace = NULL, $wiki = NULL ) - returns an array with all templates (as strings) that match the parameters supplied.
  • template_exists ( $name, $namespace = NULL, $wiki = NULL ) - returns true if a template that matches these parameters exists in the page text, false otherwise.
  • replace_template ( $name, $namespace = NULL, $wiki = NULL, $new_template = NULL, $limit = -1 ) - replaces templates that match these parameters with the $new_template string, up to $limit times (-1 - unlimited). Returns the number of the replacements made.
  • replace_template_name ( $old_name, $new_name, $old_namespace = NULL, $new_namespace = NULL, $old_wiki = NULL, $new_wiki = NULL, $limit = -1 ) - replaces templates whose name matches $old_name (and $old_namespace and $old_wiki if given) with $new_name (and $new_namespace and $new_wiki if given), up to $limit times (-1 - unlimited). Returns the number of the replacements made.
  • replace_template_paramname ( $name, $param, $new_name, $namespace = NULL, $wiki = NULL ) - replaces the name of the param $param with $new_name in templates whose name matches $name (and $namespace and $wiki if given). Returns the number of the replacements made.
  • replace_template_paramvalue ( $name, $param, $new_value, $namespace = NULL, $wiki = NULL ) - replaces the value of the param $param with $new_value in templates whose name matches $name (and $namespace and $wiki if given). Returns the number of the replacements made.
  • add_template ( $template, $regexpart_before = NULL, $regexpart_after = NULL, $limit = -1 ) - inserts this template in the page text in places after a match for $regexpart_before and before a match for $regexpart_after, up to $limit number of times (-1 - unlimited). Returns the number of the inserts made.
    (The regexparts are not complete regexes - should not contain leading or trailing slash, or post-trailing-slash modifiers.)
  • delete_templates ( $name = NULL, $namespace = NULL, $wiki = NULL, $limit = -1 ) - deletes the templates that match these parts, up to $limit times (-1 - unlimited). Returns the count of the deletes made.

Handling sections

All methods here rely not on the MediaWiki parsing text into sections, but on page text parsing by Apibot.

Many of these methods make use of an object property named $text_sections. This property is mutually exclusive with the $text property: either one is set, or the other. Generally you should care that, when writing a page, the $text property is the set one. The rule of thumb is: make the sections handling in your scripts a contained unit, eg. function. Convert text to sections, do your sections work (and nothing else), convert sections back to text.

The property is an array, containing section structures, ordered by the section No.s (numbers, starting from 0, that reflect the section consecutive position in the page). A section structure is array with the following elements:

    • 'level' - the section level in the section hierarchy (1 - largest)
    • 'header' - the section header (section 0 may have no header: for it this field may be empty)
    • 'text' - the section text
  • text_to_sections ( $text = NULL ) - parses this text (if NULL - the page $text property) to an array of sections and returns it.
  • sections_to_text ( $sections = NULL ) - parses this sections array (if NULL - the page $text_sections property) to a text and returns it.
  • section_no_by_header ( $header ) - returns the section No. for the first section with this header.
  • section_by_header ( $header ) - returns the array structure of the first section with this header.
  • section_text_by_header ( $header ) - returns the text of the first section with this header.
  • section_with_subs ( $no ) - returns an array containing the section with this No. and all sections that are its subsections. All sections are keyed in the array by their No.s.
  • section_with_subs_by_header ( $header ) - returns an array containing the first section with this header and all sections that are its subsections. All sections are keyed in the array by their No.s.
  • modify_section_level ( $no, $by, $with_subs = true ) - change the level of the section with this No. by $by (positive numbers increase its level, negative ones decrease it). Section level cannot be set to 0 or less. If $with_subs is true, will also change by $by the level of its subsections.
  • modify_section_level_by_header ( $header, $by, $with_subs = true ) - change the level of the first section with this header by $by (positive numbers increase its level, negative ones decrease it). Section level cannot be set to 0 or less. If $with_subs is true, will also change by $by the level of its subsections.
  • set_section_level ( $no, $level, $with_subs = true ) - sets the level of the section with this No. to $level (cannot be 0 or less). If $with_subs is true, will also change accordingly the level of its subsections.
  • set_section_level_by_header ( $header, $level, $with_subs = true ) - sets the level of the first section with this header to $level (cannot be 0 or less). If $with_subs is true, will also change accordingly the level of its subsections.
  • insert_sections ( $sections, $no ) - inserts the $sections array of section structures at section position $no.
  • insert_section ( $section, $no ) - inserts this section structure at section position $no.
  • insert_sections_after_section_with_header ( $sections, $header ) - inserts the $sections array of section structures after the first section with this header.
  • insert_section_after_section_with_header ( $section, $header ) - inserts this section structure after the first section with this header.
  • delete_section ( $no, $with_subs = true ) - deletes the section at section position $no. If $with_subs is true, deletes its subsections too.
  • delete_section_by_header ( $header, $with_subs = true ) - deletes the first section with this header. If $with_subs is true, deletes its subsections too.
  • move_section ( $current_no, $after_no, $with_subs = true ) - moves the section at current section position $current_no after the section with position $after_no. If $with_subs is true, moves with it its subsections too.
  • move_section_by_header ( $header, $after_no, $with_subs = true ) - moves the first section with this header after the section with position $after_no. If $with_subs is true, moves with it its subsections too.
  • move_section_after_section_with_header ( $header, $after_header, $with_subs = true ) - moves the first section with header $header after the first section with header $after_header. If $with_subs is true, moves with it its subsections too.

Handling lists

The lists support is still rudimentary.

  • list_string ( $list_array, $ordered_list = false, $level = 1 ) - takes an array of strings and returns a MediaWiki list as a text string. Empty strings in the array are converted to empty non-array lines in the text string. If a member of the array is an array itself, it will be converted and inserted as a text string list of a higher order.
  • add_list ( $list_array, $ordered_list = false, $regexpart_before = NULL, $regexpart_after = NULL ) - converts the array $list to a MW list text string and inserts it after a match for $regexpart_before and before a match for $regexpart_after.

Miscellaneous

  • neat() - tries to make the page text neat. Moves the categories and the interwikis at the page end, each in a separate line, separated by the page text and between both groups with an empty line.

See also