\

Classes

ids Provides an interface to interact with page ids.
page_renderer Renders the HTML page that is sent to the client.
PeppermintParsedown
search Holds a collection to methods to manipulate various types of search index.
Slimdown Modified by Starbeamrainbowlabs (starbeamrainbowlabs)

Functions

add_action()

add_action(string  $action_name, \function  $func) 

Registers a new action handler.

Parameters

string $action_name

The action to register.

\function $func

The function to call when the specified action is requested.

add_help_section()

add_help_section(string  $index, string  $title, string  $content) 

Adds a new help section to the help page.

Parameters

string $index

The string to index the new section under.

string $title

The title to display above the section.

string $content

The content to display.

add_parser()

add_parser(string  $name, \function  $parser_code) 

Registers a new parser.

Parameters

string $name

The name of the new parser to register.

\function $parser_code

The function to register as a new parser.

add_recent_change()

add_recent_change(array  $rchange) 

Adds a new recent change to the recent changes file.

Parameters

array $rchange

The new change to add.

check_subpage_parents()

check_subpage_parents(  $pagename) 

Makes sure that a subpage's parents exist.

Note this doesn't check the pagename itself.

Parameters

$pagename

The pagename to check.

delete_comment()

delete_comment(array  $comment_data, string  $target_id) : boolean

Deletes the first comment found with the specified id.

Parameters

array $comment_data

An array of threaded comments to delete the comment from.

string $target_id

The id of the comment to delete.

Returns

boolean —

Whether the comment was found and deleted or not.

do_password_hash_code_update()

do_password_hash_code_update() 

Recalculates and updates the password hashing cost.

email_user()

email_user(string  $username, string  $subject, string  $body) : boolean

Sends a plain text email to a user, replacing {username} with the specified username.

Parameters

string $username

The username to send the email to.

string $subject

The subject of the email.

string $body

The body of the email.

Returns

boolean —

Whether the email was sent successfully or not. Currently, this may fail if the user doesn't have a registered email address.

email_users()

email_users(array<mixed,string>  $usernames, string  $subject, string  $body) : integer

Sends a plain text email to a list of users, replacing {username} with each user's name.

Parameters

array<mixed,string> $usernames

A list of usernames to email.

string $subject

The subject of the email.

string $body

The body of the email.

Returns

integer —

The number of emails sent successfully.

endsWith()

endsWith(string  $whole, string  $end) : boolean

Tests whether a string ends with a given substring.

Parameters

string $whole

The string to test against.

string $end

The substring test for.

Returns

boolean —

Whether $whole ends in $end.

errorimage()

errorimage(string  $text, integer  $target_size = null) : \image

Creates an images containing the specified text.

Useful for sending errors back to the client.

Parameters

string $text

The text to include in the image.

integer $target_size

The target width to aim for when creating the image.

Returns

\image —

The handle to the generated GD image.

extract_user_from_userpage()

extract_user_from_userpage(string  $userPagename) : string

Extracts a username from a user page path.

Parameters

string $userPagename

The suer page path to extract from.

Returns

string —

The name of the user that the user page belongs to.

fetch_comment_thread()

fetch_comment_thread(array  $comment_data, string  $comment_id) : array<mixed,object>

Fetches all the parent comments of the specified comment id, including the comment itself at the end.

Useful for figuring out who needs notifying when a new comment is posted.

Parameters

array $comment_data

The comment data to search.

string $comment_id

The comment id to fetch the thread for.

Returns

array<mixed,object> —

A list of the comments in the thread, with the deepest one at the end.

find_comment()

find_comment(array  $comment_data, string  $comment_id) : object

Finds the comment with specified id by way of an almost-breadth-first search.

Parameters

array $comment_data

The comment data to search.

string $comment_id

The id of the comment to find.

Returns

object —

The comment data with the specified id, or false if it wasn't found.

full_url()

full_url(array  $s = false, boolean  $use_forwarded_host = false) : string

Get the full url, as requested by the client.

Parameters

array $s

The $_SERVER variable. Defaults to $_SERVER.

boolean $use_forwarded_host

Whether to take the X-Forwarded-Host header into account.

Returns

string —

The full url, as requested by the client.

generate_comment_id()

generate_comment_id() : string

Generates a new random comment id.

Returns

string —

A new random comment id.

generate_page_list()

generate_page_list(array<mixed,string>  $pagelist) : string

Renders a list of pages as HTML.

Parameters

array<mixed,string> $pagelist

A list of page names to include in the list.

Returns

string —

The specified list of pages as HTML.

generate_password()

generate_password(string  $length) : string

Generates a new (cryptographically secure) random password that's also readable (i.e. consonant-vowel-consonant).

This implementation may be changed in the future to use random dictionary words instead - ref https://xkcd.com/936/

Parameters

string $length

The length of password to generate.

Returns

string —

The generated random password.

get_all_tags()

get_all_tags() : array<mixed,string>

Gets a list of all the tags currently used across the wiki.

Returns

array<mixed,string> —

A list of all unique tags present on all pages across the wiki.

get_comment_filename()

get_comment_filename(string  $pagename) : string

Given a page name, returns the absolute file path in which that page's comments are stored.

Parameters

string $pagename

The name pf the page to fetch the comments filename for.

Returns

string —

The path to the file that the

get_max_upload_size()

get_max_upload_size() : integer

Calculates the actual maximum upload size supported by the server Returns a file size limit in bytes based on the PHP upload_max_filesize and post_max_size

Returns

integer —

The maximum upload size supported bythe server, in bytes.

get_page_parent()

get_page_parent(string  $pagename) : string|boolean

Gets the name of the parent page to the specified page.

Parameters

string $pagename

The child page to get the parent page name for.

Returns

string|boolean

get_subpages()

get_subpages(object  $pageindex, string  $pagename) : object

Gets a list of all the sub pages of the current page.

Parameters

object $pageindex

The pageindex to use to search.

string $pagename

The name of the page to list the sub pages of.

Returns

object —

An object containing all the subpages and their respective distances from the given page name in the pageindex tree.

get_user_pagename()

get_user_pagename(string  $username) : string

Figures out the path to the user page for a given username.

Does not check to make sure the user acutally exists.

Parameters

string $username

The username to get the path to their user page for.

Returns

string —

The path to the given user's page.

getallheaders()

getallheaders() 

Polyfill for PHP's native getallheaders() function on platforms that don't have it.

getsvgsize()

getsvgsize(string  $svgFilename) : array<mixed,integer>

Calculates the size of the specified SVG file.

Parameters

string $svgFilename

The filename to calculate the size of.

Returns

array<mixed,integer> —

The width and height respectively of the specified SVG file.

glob_recursive()

glob_recursive(string  $pattern, integer  $flags) : array

A recursive glob() function.

Parameters

string $pattern

The glob pattern to use to find filenames.

integer $flags

The glob flags to use when finding filenames.

Returns

array —

An array of the filepaths that match the given glob.

has_action()

has_action(string  $action_name) : boolean

Figures out whether a given action is currently registered.

Only guaranteed to be accurate in inside an existing action function

Parameters

string $action_name

The name of the action to search for

Returns

boolean —

Whether an action with the specified name exists.

has_statistic()

has_statistic(string  $stat_id) : boolean

Checks whether a specified statistic has been registered.

Parameters

string $stat_id

The id of the statistic to check the existence of.

Returns

boolean —

Whether the specified statistic has been registered.

hash_password()

hash_password(string  $pass) : string

Hashes the given password according to the current settings defined in $settings.

Parameters

string $pass

The password to hash.

Returns

string —

The hashed password. Uses sha3 if $settings->use_sha3 is enabled, or sha256 otherwise.

hash_password_compute_cost()

hash_password_compute_cost(  $verbose = false) : integer

Computes the appropriate cost value for password_hash based on the settings automatically.

Starts at 10 and works upwards in increments of 1. Goes on until a value is found that's greater than the target - or 10x the target time elapses.

Parameters

$verbose

Returns

integer —

The automatically calculated password hashing cost.

hash_password_properties()

hash_password_properties() : array

Figures out the appropriate algorithm & options for hashing passwords based on the current settings.

Returns

array —

The appropriate password hashing algorithm and options.

hash_password_update()

hash_password_update(string  $pass, string  $hash) : string|null

Determines if the provided password needs re-hashing or not.

Parameters

string $pass

The password to check.

string $hash

The hash of the provided password to check.

Returns

string|null —

Returns null if an updaste is not required - otherwise returns the new updated hash.

hide_email()

hide_email(string  $str) : string

Hides an email address from bots by adding random html entities.

Parameters

string $str

The original email address

Returns

string —

The mangled email address.

history_add_revision()

history_add_revision(object  $pageinfo, string  $newsource, string  $oldsource, boolean  $save_pageindex = true, string  $change_type = "edit") 

Adds a history revision against a page.

Note: Does not updaate the current page content! This function only records a new revision against a page name. Thus it is possible to have a disparaty between the history revisions and the actual content displayed in the current revision if you're not careful!

Parameters

object $pageinfo

The pageindex object of the page to operate on.

string $newsource

The page content to save as the new revision.

string $oldsource

The old page content that is the current revision (before the update).

boolean $save_pageindex

Whether the page index should be saved to disk.

string $change_type

The type of change to record this as in the history revision log

human_filesize()

human_filesize(\number  $bytes, \number  $decimals = 2) : string

Converts a filesize into a human-readable string.

Parameters

\number $bytes

The number of bytes to convert.

\number $decimals

The number of decimal places to preserve.

Returns

string —

A human-readable filesize.

human_time()

human_time(integer  $seconds) : string

Renders a given number of seconds as something that humans can understand more easily.

Parameters

integer $seconds

The number of seconds to render.

Returns

string —

The rendered time.

human_time_since()

human_time_since(integer  $time) : string

Calculates the time since a particular timestamp and returns a human-readable result.

Parameters

integer $time

The timestamp to convert.

Returns

string —

The time since the given timestamp as a human-readable string.

makepathsafe()

makepathsafe(string  $string) : string

Makes a path (or page name) safe.

A safe path / page name may not contain: Forward-slashes at the beginning Multiple dots in a row Odd characters (e.g. ?%*:|"<>() etc.) A safe path may, however, contain unicode characters such as éôà etc.

Parameters

string $string

The string to make safe.

Returns

string —

A safe version of the given string.

mb_stripos_all()

mb_stripos_all(string  $haystack, string  $needle) : array|false

Case-insensitively finds all occurrences of $needle in $haystack. Handles UTF-8 characters correctly.

Parameters

string $haystack

The string to search.

string $needle

The string to find.

Returns

array|false —

An array of match indices, or false if nothing was found.

module_exists()

module_exists(string  $id) : boolean

Checks to see whether a module with the given id exists.

Parameters

string $id

The id to search for.

Returns

boolean —

Whether a module is currently loaded with the given id.

parse_page_source()

parse_page_source(string  $source) : string

Parses the specified page source using the parser specified in the settings into HTML.

The specified parser may (though it's unilkely) render it to other things.

Parameters

string $source

The source to render.

Returns

string —

The source rendered to HTML.

parse_size()

parse_size(string  $size) : integer

Parses a PHP size to an integer

Parameters

string $size

The size to parse.

Returns

integer —

The number of bytees represented by the specified size string.

register_module()

register_module(array  $moduledata) 

Registers a module.

Parameters

array $moduledata

The module data to register.

register_remote_file()

register_remote_file(array  $remote_file_def) 

Registers a request for a remote file to be downloaded before execution. Will block until all files are downloaded.

Example definition: [ "local_filename" => "file.ext", "remote_url": "https://example.com" ]

Parameters

array $remote_file_def

The remote file definition to register.

Throws

\Exception

Exception Throws an exception if a definition for the requested local file already exists.

register_save_preprocessor()

register_save_preprocessor(\function  $func) 

Register a new proprocessor that will be executed just before an edit is saved.

Parameters

\function $func

The function to register.

render_comments()

render_comments(array<mixed,object>  $comments_data, integer  $depth) : string

Renders a given comments tree to html.

Parameters

array<mixed,object> $comments_data

The comments tree to render.

integer $depth

For internal use only. Specifies the depth at which the comments are being rendered.

Returns

string —

The given comments tree as html.

render_editor()

render_editor(string  $editorName) : string

Renders an editor's or a group of editors name(s) in HTML.

Parameters

string $editorName

The name of the editor to render.

Returns

string —

HTML representing the given editor's name.

render_pagename()

render_pagename(object  $rchange) : string

Renders a page name in HTML.

Parameters

object $rchange

The recent change to render as a page name

Returns

string —

HTML representing the name of the given page.

render_recent_change()

render_recent_change(object  $rchange) : string

Renders a single recent change

Parameters

object $rchange

The recent change to render.

Returns

string —

The recent change, rendered to HTML.

render_recent_changes()

render_recent_changes(array  $recent_changes) : string

Renders a list of recent changes to HTML.

Parameters

array $recent_changes

The recent changes to render.

Returns

string —

The given recent changes as HTML.

render_sidebar()

render_sidebar(array  $pageindex, string  $root_pagename = "") : string

Renders the sidebar for a given pageindex.

Parameters

array $pageindex

The pageindex to render the sidebar for

string $root_pagename

The pagename that should be considered the root of the rendering. You don't usually need to use this, it is used by the algorithm itself since it is recursive.

Returns

string —

A HTML rendering of the sidebar for the given pageindex.

render_timestamp()

render_timestamp(integer  $timestamp) : string

Renders a timestamp in HTML.

Parameters

integer $timestamp

The timestamp to render.

Returns

string —

HTML representing the given timestamp.

save_settings()

save_settings() : boolean

Saves the settings file back to peppermint.json.

Returns

boolean —

Whether the settings were saved successfully.

save_userdata()

save_userdata() : boolean

Saves the currently logged in user's data back to peppermint.json.

Returns

boolean —

Whether the user's data was saved successfully. Returns false if the user isn't logged in.

stack_trace()

stack_trace(boolean  $log_trace = true, boolean  $full = false) : string

Generates a stack trace.

Parameters

boolean $log_trace

Whether to send the stack trace to the error log.

boolean $full

Whether to output a full description of all the variables involved.

Returns

string —

A string prepresentation of a stack trace.

starts_with()

starts_with(string  $haystack, string  $needle) : boolean

Checks to see if $haystack starts with $needle.

Parameters

string $haystack

The string to search.

string $needle

The string to search for at the beginning of $haystack.

Returns

boolean —

Whether $needle can be found at the beginning of $haystack.

startsWith()

startsWith(string  $haystack, string  $needle) : boolean

Tests whether a string starts with a specified substring.

Parameters

string $haystack

The string to check against.

string $needle

The substring to look for.

Returns

boolean —

Whether the string starts with the specified substring.

statistic_add()

statistic_add(array  $stat_data) 

Registers a statistic calculator against the system.

Parameters

array $stat_data

The statistic object to register.

stats_load()

stats_load() : object

Loads and returns the statistics cache file.

Returns

object —

The loaded & decoded statistics.

stats_save()

stats_save(  $stats) : boolean

Saves the statistics back to disk.

Parameters

$stats

Returns

boolean —

Whether saving succeeded or not.

str_replace_once()

str_replace_once(string  $find, string  $replace, string  $subject) : string

Replaces the first occurrence of $find with $replace.

Parameters

string $find

The string to search for.

string $replace

The string to replace the search string with.

string $subject

The string ot perform the search and replace on.

Returns

string —

The source string after the find and replace has been performed.

system_extension_mime_type()

system_extension_mime_type(string  $ext) : string

Converts a given file extension to it's associated mime type.

Parameters

string $ext

The extension to convert.

Returns

string —

The mime type associated with the given extension.

system_extension_mime_types()

system_extension_mime_types() : array

Returns the system MIME type mapping of extensions to MIME types.

Returns

array —

An array mapping file extensions to their associated mime types.

system_mime_type_extension()

system_mime_type_extension(string  $type) : string

Converts a given mime type to it's associated file extension.

Parameters

string $type

The mime type to convert.

Returns

string —

The extension for the given mime type.

system_mime_type_extensions()

system_mime_type_extensions() : array

Returns the system's mime type mappings, considering the first extension listed to be cacnonical.

Returns

array —

An array of mime type mappings.

update_redirect_metadata()

update_redirect_metadata(object  $index_entry, string  $pagedata) 

Updates the metadata associated with redirects in the pageindex entry specified utilising the provided page content.

Parameters

object $index_entry

The page index entry object to update.

string $pagedata

The page content to operate on.

update_statistics()

update_statistics(boolean  $update_all = false, boolean  $force = false) 

Updates the wiki's statistics.

Parameters

boolean $update_all

Whether all the statistics should be checked and recalculated, or just as many as we have time for according to the settings.

boolean $force

Whether we should recalculate statistics that don't currently require recalculating anyway.

upload_check_svg()

upload_check_svg(string  $temp_filename) : array<mixed,integer>

Checks an uploaded SVG file to make sure it's (at least somewhat) safe.

Sends an error to the client if a problem is found.

Parameters

string $temp_filename

The filename of the SVG file to check.

Returns

array<mixed,integer> —

The size of the SVG image.

url_origin()

url_origin(array  $s = false, boolean  $use_forwarded_host = false) : string

Get the actual absolute origin of the request sent by the user.

Parameters

array $s

The $_SERVER variable contents. Defaults to $_SERVER.

boolean $use_forwarded_host

Whether to utilise the X-Forwarded-Host header when calculating the actual origin.

Returns

string —

The actual origin of the user's request.

var_dump_ret()

var_dump_ret(mixed  $var) : string

Calls var_dump() and returns the output.

Parameters

mixed $var

The thing to pass to var_dump().

Returns

string —

The output captured from var_dump().

var_dump_short()

var_dump_short(mixed  $var) : string

Calls var_dump(), shortening the output for various types.

Parameters

mixed $var

The thing to pass to var_dump().

Returns

string —

A shortened version of the var_dump() output.

verify_password()

verify_password(string  $pass, string  $hash) : boolean

Verifies a user's password against a pre-generated hash.

Parameters

string $pass

The user's password.

string $hash

The hash to compare against.

Returns

boolean —

Whether the password matches the has or not.