version=pmwiki-2.2.74 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum=pmcrypt
name=PmWiki.Functions
rev=107
targets=Cookbook.Functions,PmWiki.CustomMarkup,PmWiki.CustomActions,PmWiki.Variables,PmWiki.Internationalizations,PmWiki.FmtPageName,PmWiki.MakeLink,PmWiki.ConditionalMarkup,PmWiki.Drafts,PmWiki.UpdatePage,Cookbook.MarkupExpressionSamples,Category.PmWikiDeveloper
text=(:Summary: How some of the functions in pmwiki.php work:)%0a(:Audience: admins (advanced) :)%0a%0aThis page describes some of the internal workings of PmWiki by explaining how some of the functions in pmwiki.php work. For a more brief list/overview on functions useful to for instance cookbook writers, see Cookbook:Functions. %0a%0aTo use this functions you have to make sure that all relevant internal variables have been initialized correctly. See [[Custom Markup]] and [[(PmWiki:)Custom Actions]] for more information on how these functions are typically called via [@Markup()@] or [@$HandleActions[]@].%0a%0a!! [[#pmcrypt]] [@pmcrypt($password, $salt = null)@]%0aThe pmcrypt() function is intended to be a safe replacement for the [[http://php.net/crypt|PHP 5.6+ crypt() function]] without providing a $salt, which would raise a notice. If a salt is provided, crypt() is called to check an existing password. If a salt is not provided,  [[http://php.net/password_hash|password_hash()]] will be called to create a cryptographically strong password hash.%0a%0a!![[#PCCF]] [@PCCF($php_code, $callback_template='default', $callback_arguments = '$m')@]%0aThe PCCF() function (''PmWiki Create Callback Function'') can be used to create callback functions used with [[(http://php.net/)preg_replace_callback]]. It is required for PHP 5.5, but will also work with earlier PHP versions.%0a%0aThe first argument is the PHP code to be evaluated. %0a%0aThe second argument (optional) is the callback template, a key from the global $CallbackFnTemplates array. There are two templates that can be used by recipe authors: %0a* 'default' will pass $php_code as a function code%0a* 'return' will wrap $php_code like "return $php_code;" (since PmWiki 2.2.62)%0a%0aThe third argument (optional) is the argument of the callback function. Note that PmWiki uses the '$m' argument to pass the matches of a regular expression search, but your function can use other argument(s).%0a%0aPCCF() will create an anonymous (lambda) callback function containing the supplied code, and will cache it. On subsequent calls with the same $php_code, PCCF() will return the cached function name.%0a%0aSee http://php.net/create_function.%0a%0a!![[#PPRA]] [@PPRA($array_search_replace, $string)@]%0aThe PPRA() function (''PmWiki preg_replace array'') can be used to perform a regular expression replacement with or without evaluation, for PHP 5.5 compatibility. %0a%0aSince PmWiki 2.2.56, PmWiki uses this function to process the following arrays: $MakePageNamePatterns, $FmtP, $QualifyPatterns, $ROEPatterns, $ROSPatterns, $SaveAttrPatterns, $MakeUploadNamePatterns. Any custom settings should continue to work for PHP 5.4 and earlier, but wikis running on PHP 5.5 may need to make a few changes.%0a%0aThe first argument contains the 'search'=>'replace' pairs, the second is the  "haystack" string to be manipulated.%0a%0aThe 'replace' parts of the array can be strings or function names. If the 'replace' part is a callable function name, it will be called with the array of matches as a first argument via preg_replace_callback(). If not a callable function, a simple preg_replace() will be performed.%0a%0aPreviously, PmWiki used such constructs:%0a  $fmt = preg_replace(array_keys($FmtP), array_values($FmtP), $fmt);%0a%0aIt is now possible to use simply this:%0a  $fmt = PPRA($FmtP, $fmt);%0a%0aNote that since PHP 5.5, the search patterns cannot have an /e evaluation flag. When creating the $array_search_replace array, before PHP 5.5 we could use something like (eg. for $MakePageNamePatterns):%0a  '/(?%3c=^| )([a-z])/e' => "strtoupper('$1')",%0a%0aSince PHP 5.5, we should use this (will also work in PHP 5.4 and earlier):%0a  '/(?%3c=^| )([a-z])/' => PCCF("return strtoupper(\$m[1]);"),%0a%0aNote that the /e flag should be now omitted, instead of '$0', '$1', '$2', we should use $m[0], $m[1], $m[2], etc. in the replacement code, and there is no need to call PSS() in the replacement code, as backslashes are not automatically added.%0a%0a!![[#PPRE]] [@PPRE($search_pattern, $replacement_code, $string)@]%0aThe PPRE() function (''PmWiki preg_replace evaluate'') can be used to perform a regular expression replacement with evaluation.%0a%0aSince PHP 5.5, the preg_replace() function has deprecated the /e evaluation flag, and displays warnings when the flag is used. The PPRE() function automatically creates a callback function with the replacement code and calls it.%0a%0aBefore PHP 5.5, it was possible to use such calls:%0a  $fmt = preg_replace('/\\$([A-Z]\\w*Fmt)\\b/e','$GLOBALS["$1"]',$fmt);%0a%0aSince PHP 5.5, it is possible to replace the previous snippet with the following (also works before PHP 5.5):%0a  $fmt = PPRE('/\\$([A-Z]\\w*Fmt)\\b/','$GLOBALS[$m[1]]',$fmt);%0a%0aNote that the /e flag should be now omitted, instead of '$0', '$1', '$2', we should use $m[0], $m[1], $m[2], etc. in the replacement code, and there is no need to call PSS() in the replacement code, as backslashes are not automatically added.%0a%0a!![[#PHSC]] [@PHSC($string, $flags=ENT_COMPAT, $encoding=null)@]%0aThe PHSC() function (''PmWiki HTML special characters'') is a replacement for the PHP function [[(http://php.net/)htmlspecialchars]]. %0a%0aThe htmlspecialchars() function was modified since PHP 5.4 in two ways: it now requires a valid string for the supplied encoding, and it changes the default encoding to UTF-8. This can cause sections of the page to become blank/empty on many sites using the ISO-8859-1 encoding without having set the third argument ($encoding) when calling htmlspecialchars().%0a%0aThe PHSC() function calls htmlspecialchars() with an 8-bit encoding as third argument, whatever the encoding of the wiki. This way the string never contains invalid characters.%0a%0aIt should be safe for recipe developers to replace all calls to htmlspecialchars() with calls to PHSC(). Only the first argument is required when calling PHSC().%0a%0a%0a!![[#PSS]] [@PSS($string)@]%0a%0aThe PSS() function (''PmWiki Strip Slashes'') removes the backslashes that are%0aautomatically inserted in front of quotation marks by%0athe /e option of PHP's preg_replace function.  PSS() is%0amost commonly used in replacement arguments to Markup(),%0awhen the pattern specifies /e and one or more of the %0aparenthesized subpatterns could contain a quote or backslash.  %0a("PSS" stands for "PmWiki Strip Slashes".)%0a-->From PM: PmWiki expects PSS() to always occur inside of double-quoted strings and to contain single quoted strings internally.  The reason for this is that we don't want the $1 or $2 to accidentally contain characters that would then be interpreted inside of the double-quoted string when the PSS is evaluated.%0a--->@@Markup('foo', 'inline', '/(something)/e', 'Foo(PSS("$1"))');  # wrong@@%0a--->@@Markup('foo', 'inline', '/(something)/e', "Foo(PSS('$1'))");  # right@@%0a%0a!!! Example%0aThis is a fictitious example where PSS() should be used.%0aLet us assume that you wish to define a directive [@(:example:)@]%0asuch that [@(:example "A horse":)@] results in the HTML%0a-> [@%3cdiv>"A horse"%3c/div>@].%0aHere is how the markup rule can be created:%0a-> [@%0aMarkup('example', 'directives',%0a       '/\\(:example\\s(.*?):\\)/e',%0a       "Keep('%3cdiv>'.PSS('$1').'%3c/div>')");%0a@]%0aWe need to use PSS() around the '$1' because the matched text%0acould contain quotation marks, and the /e will add backslashes%0ain front of them.%0a%0a!![[#stripmagic]] [@stripmagic($string)@]%0a%0aThis function should be used when processing the contents of [@$_POST@] or [@_GET@] variables when they could contain quotes or backslashes. It verifies [@get_magic_quotes()@], if true,%0astrips the automatically inserted escapes from the string.%0a%0a!![[#FmtPageName]] [@FmtPageName@]($fmt, $pagename)%0a%0a[[#FmtPageName-desc]]Returns [@$fmt@], with $variable and [=$[internationalisation]=] substitutions performed, under the assumption that the current page is [@pagename@]. See [[PmWiki.Variables]] for an (incomplete) list of available variables, [[PmWiki.Internationalizations]] for internationalisation.  Security: not to be run on user-supplied data.%0a%0aThis is one of the major functions in PmWiki, see [[PmWiki.FmtPageName]] for%0alots of details.%0a%0a%0a!![[#Markup]] [@Markup@]($name, $when, $pattern, $replace)%0a%0a[[#Markup-desc]]Adds a new markup to the conversion table.  Described in greater detail at [[PmWiki.CustomMarkup]].%0a%0aThis function is used to insert translation rules into the PmWiki's%0atranslation engine. The arguments to [@Markup()@] are all strings, where:%0a%0a:[@$name@]: The string names the rule that is inserted.  If a rule of the same name already exists, then this rule is ignored.%0a:[@$when@]: This string is used to control ''when'' a rule is to be applied relative to other rules.  A specification of "[@%3cxyz@]" says to apply this rule prior to the rule named "xyz", while "[@>xyz@]" says to apply this rule after the rule "xyz".  See [[(PmWiki:)CustomMarkup]] for more details on the order of rules.%0a:[@$pattern@]: This string is a [[regular expression -> http://www.php.net/preg_replace]] that is used by the translation engine to look for occurences of this rule in the markup source.%0a:[@$replace@]: This string will replace the matched text when a match occurs.%0a%0aAlso see: [[PmWiki.CustomMarkup]] and [[Cookbook:Functions#Markup]]%0a%0a!![[#MarkupToHTML]] [@MarkupToHTML@]($pagename, $str)%0a%0a[[#MarkupToHTML-desc]] Converts the string [@$str@] containing PmWiki markup into the corresponding HTML code, assuming the current page is [@$pagename@].%0a%0aAlso see: [[Cookbook:Functions#MarkupToHTML]]%0a%0a!![[#mkdirp]] [@mkdirp@]($dir)%0a%0aThe function [@mkdirp@]($dir) creates a directory, [@$dir@], if it doesn't%0aalready exist, including any parent directories that might be needed.  For%0aeach directory created, it checks that the permissions on the directory are%0asufficient to allow PmWiki scripts to read and write files in that%0adirectory.  This includes checking for restrictions imposed by PHP's%0asafe_mode setting.  If [@mkdirp@]() is unable to successfully create a%0aread/write directory, [@mkdirp@]() aborts with an error message telling the%0aadministrator the steps to take to either create $dir manually or give%0aPmWiki sufficient permissions to be able to do it.%0a%0a!![[#MakeLink]] [@MakeLink@]($pagename, $target, $txt, $suffix, $fmt)%0a%0aThe function [@MakeLink@]($pagename, $target, $txt, $suffix, $fmt) returns an html-formatted anchor link. Its arguments are as follows:%0a $pagename is the source page%0a $target is where the link should go%0a $txt is the value to use for '$LinkText' in the output %0a $suffix is any suffix string to be added to $txt%0a $fmt is a format string to use%0a%0aIf $txt is NULL or not specified, then it is automatically computed from $target.%0a%0aIf $fmt is NULL or not specified, then MakeLink uses the default%0aformat as specified by the type of link.  For page links this%0ameans the $LinkPageExistsFmt and $LinkPageCreateFmt variables,%0afor intermap-style links it comes from either the $IMapLinkFmt%0aarray or from $UrlLinkFmt.  Inside of the formatting strings,%0a$LinkUrl is replaced by the resolved url for the link, $LinkText%0ais replaced with the appropriate text, and $LinkAlt is replaced%0aby any "title" (alternate text) information associated with the%0alink.%0a%0aAlso see: [[PmWiki:MakeLink]] and [[Cookbook:Functions#MakeLink]]%0a%0a!![[#MakeUploadName]] [@MakeUploadName@]($pagename, $x)%0a%0a@@MakeUploadName()@@ simply takes a string @@$x@@ (representing an attachment's%0aname) and converts it to a valid name by removing any unwanted characters.%0aIt also requires the name to begin and end with an alphanumeric character,%0aand as of 2.0.beta28 it forces any file extensions to lowercase.%0aThis function is defined in @@scripts/upload.php@@ and only used when uploads%0aare enabled.%0a%0a!![[#SessionAuth]] [@SessionAuth@]($pagename, $auth=NULL)%0a%0a@@SessionAuth()@@ manages keeping authentication via cookie-sessions. Session contains%0aever password or vaidated id and associated groups from previous calls.It adds%0aelements passed by @@$auth@@ to session. It also writes every element%0asaved in session to @@$AuthPw@@(passwords) and @@$AuthList@@(ids and groups).%0a%0a!![[#IsAuthorized]] [@IsAuthorized@]($chal, $source, &$from)%0a@@IsAuthorized@@ takes a pageattributesstring (e. g. "id:user1 $1$Ff3w34HASH...") in @@$chal@@.%0a@@$source@@ is simply returned and used for building the authcascade (pageattributes - groupattributes - %0a@@$DefaultPassword@@). @@$from@@ will be returned if @@$chal@@ is empty, because it is not checked %0abefore calling @@IsAuthorized()@@, this is needed for the authcascade. @@IsAuthorized()@@ returns an array%0awith three values: @@$auth@@ @@1@@ - authenticated, @@0@@ - not authenticated, @@-1@@ - refused; @@$passwd@@; %0a@@$source@@ from the parameter list.%0a%0a!![[#CondAuth]] [@CondAuth@] ($pagename, 'auth level')%0a[@CondAuth@] implements the [[ConditionalMarkup]] for [@(:if auth level:)@]. For instance [@ CondAuth($pagename,'edit')@] is true if authorization level is 'edit'. Use inside local configuration files to build conditionals with a check of authorization level, similar to using [@(:if auth level:)@] on a wiki page.%0a%0aNote that CondAuth() should be called after all authorization levels and passwords have been defined. For example, if you use it with [[Drafts]], you should include the draft.php script before calling CondAuth():%0a[@%0a   $EnableDrafts = 1;%0a   $DefaultPasswords['publish'] = pmcrypt('secret');%0a   include_once("$FarmD/scripts/draft.php");%0a   if (! CondAuth($pagename, 'edit')) { /* whatever */ }%0a@]%0aBest is to use CondAuth() near the bottom of your config.php script.%0a%0a!! [[#RetrieveAuthPage]] @@RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0)@@%0a%25comment%25 Pm words as said in http://article.gmane.org/gmane.comp.web.wiki.pmwiki.user/12493/match=retrieveauthpage%25%25%0awhere:%0a%0a   $pagename   - name of page to be read%0a   $level      - authorization level required (read/edit/auth/upload)%0a   $authprompt - true if user should be prompted for a password if needed%0a   $since      - how much of the page history to read%0a                 0 == read entire page including all of history%0a                 READPAGE_CURRENT == read page without loading history%0a                 timestamp == read history only back through timestamp%0a%0aThe $since parameter allows PmWiki to stop reading from a page file%0aas soon as it has whatever information is needed -- i.e., if an operation%0asuch as browsing isn't going to need the page's history, then specifying%0aREADPAGE_CURRENT can result in a much faster loading time.  (This can be %0aespecially important for things such as searching and page listings.)%0a%0aUse e.g. [@$page = @RetrieveAuthPage('Main.MyPage', 'read')@] to obtain a page object that contains all the information of the correspondent file in separate keys, e.g. [@$page['text']@] will contain a string with the current wiki markup of Main.MyPage. Use this generally in preference to the alternative function [@ReadPage($pagename, $since=0)@] since it respects the authorisation of the user, i.e. it checks the authorisation level before loading the page, or it can be set to do so. [@ReadPage()@] reads a page regardless of permission.%0a%0aPassing 'ALWAYS' as the authorization level (instead of 'read', 'edit', etc.) will cause RetrieveAuthPage to always read and return the page, even if it happens to be protected by a read password.%0a%0a%0a!! [[#RetrieveAuthSection]] @@RetrieveAuthSection($pagename, $pagesection, $list=NULL, $auth='read')@@%0aRetrieveAuthSection extracts a section of text from a page. If $pagesection starts with anything other than '#', it identifies the page to extract text from.  Otherwise RetrieveAuthSection looks in the pages given by $list, or in $pagename if $list is not specified. %0a* The selected page is placed in the global $RASPageName variable. %0a* The caller is responsible for calling Qualify() as needed.%0a%0aProvides a way to limit the array that is returned by ReadPage, so that it only pulls the content up to a specific section marker. For example, pulling from start of page to '##blogend':%0a->[@%0afunction FeedText($pagename, &$page, $tag) {%0a  $text = RetrieveAuthSection($pagename, '##blogend');%0a  $content = MarkupToHTML($pagename, $text);%0a  return "%3c$tag>%3c![CDATA[$content]]>%3c/$tag>";%0a}%0a@]%0a%0aThe '##blogend' argument says to read from the beginning of the page to just before the line containing the [[#blogend]] marker.  See%0a[[http://www.pmwiki.org/wiki/PmWiki/IncludeOtherPages | IncludeOtherPages]] for more information about the section specifications.%0a%0aThis version won't read text from pages that are read-protected; if you want to get text even from read-protected pages, then %0a->[@%0a  $text = RetrieveAuthSection($pagename, '##blogend', NULL, 'ALWAYS');%0a@]%0a%0a%0a!! [[#UpdatePage]] @@UpdatePage($pagename, $old (page object), $new (page object));@@%0a''[[PmWiki:UpdatePage|More Technical Notes]]''%0a%0a[@UpdatePage()@] allows cookbook recipes to mimic the behavior of editing wiki pages via the browser. Internally, PmWiki does several house keeping tasks which are accessible via this function (preserving history/diff information, updating page revision numbers, updating RecentChanges pages, sending email notifications, etc._%0a* "Page object" refers to an array pulled from [@RetrieveAuthPage($pagename, $level, $authprompt=true, $since=0);@] (preferred), or [@ReadPage($pagename); @] (disregards page security). Note that $new['text'] should contain all page data for the new version of the page. %0a* If a page doesn't exist, UpdatePage() will attempt to create it.%0a* Ignoring $old (e.g. [@UpdatePage($pagename, '', $new);@]) will erase all historical page data---a ''tabula rasa''.%0a@@UpdatePage()@@ cannot be called directly from config.php because there are necessary initializations which occur later in pmwiki.php.  It is not enough to just load stdconfig.php.  If you want to use @@UpdatePage()@@ you will need to do it within a [[PmWiki:CustomMarkup | custom markup]], a [[Cookbook:MarkupExpressionSamples | custom markup expression]], or a [[PmWiki:CustomActions | custom action]].%0a%0aCategories: [[!PmWiki Developer]]
time=1430064613
