The new parser is fully object orientated, which gives us the chance to provide functions we can use as API calls. We've already decided on a few handy ones:
string $phase->makeURL($id, $alias, $args); (implemented)
This takes an id and optionally an alias, and using the Phase configuration settings, figures out and returns the appropriate link. The args parameter is to supply additional querystring data.
$phase->messageQuit($msg (string), $query (string), $is_error (bool)); (implemented)
This call will kill Phase's parsing of the current document. The variables are $msg, which can contains the message to show, $query can contain the SQL statement Phase was working with and $is_error (true or false) tells Phase that the message is either an error or a debug message. This function can be called, for example, if an sql statement in a snippet returns invalid results. For production sites not very handy, for developing snippets and the like a great boon, because if the user is also logged into the manager (i.e. an administrator previewing a document), a lot of debug info is shown, which may help you track down what's going wrong.
mixed $phase->getActiveChildren($id, $sortField, $sortDir, $fields); (implemented)
This function will return an array containing all active (i.e. published and not deleted) documents in the folder with id $id. Leaving out $id will return all active children documents of the Phase root (i.e. $id = 0).
$sortField will specify which field the results should be sorted on, and $sortDir will specify in how they should be sorted. getActiveChildren(14, 'createdon', 'DESC') will return all active children documents of folder 14, sorted descending on field 'createdon'. You can even specify what you want returned, using the $fields parameter. If not set, it'll return id, pagetitle, alias and description. Returns FALSE on failure.
mixed $phase->getAllChildren($id, $sortField, $sortDir, $fields); (implemented)
This function is the same as the previous function, except all documents are returned, be they published/ deleted or not. Returns FALSE on failure.
mixed $phase->getConfig($setting); (implemented)
Gets the setting you specify. Returns FALSE if the setting does not exist or Phase could not retrieve it.
array $phase->getVersionData(); (implemented)
Returns an array containing named values 'release_codename', 'version' (always to be three part, i.e. 0.5.2, not 0.5.2.1), 'patchlevel'.
bool $phase->sendRedirect($url[, $type]); (implemented)
Redirects to the given URL. Returns TRUE on success and FALSE on failure (unlikely). The optional parameter 'type' should not be specified unless absolutely neccesary, as the Phase Configuration should usually specify this (it does as default). Possible parameters are: REDIRECT_HEADER (sends a 'Location: URL' header), REDIRECT_REFRESH (sends a 'Refresh: 0;URL=URL' header), REDIRECT_META (sends a '<meta http-equiv="Refresh" ... />' header).
Please note that these are not strings. Correct usage is.. $phase->sendRedirect('URL', REDIRECT_HEADER);
Note that in 99.9% of cases you will not have to specify the second parameter.
string $phase->snippetName(); (implemented)
Returns the name of the snippet that calls it, that is, the current snippet. Returns FALSE if cannot be retrieved for some reason (unlikely).
bool $phase->clearCache(); (implemented)
Clears the cache. Returns true on succes, False on failure. Note: this, like all snippets, will not work in cached pages.
mixed $phase->getParent([$pid=0, $active=1, $fields='id, pagetitle, description, alias, parent']); (implemented)
Gets some info about the current document's parent. Alternatively, you can specify a different document to do this for, whether the parent must be active to be returned (i.e. published and not deleted), and which fields you want to retrieve. $phase->getParent will return an array with the id, pagetitle, alias and parent of the current document's parent, unless of course the current document is in the root, in which case it will return false.
mixed $phase->makeList($array [, $ulroot='', $ulprefix='', $type='', $ordered=false]); (implemented, but may be removed)
Takes the array passed, and returns it as a (HTML) string containing an unordered list (or an ordered list, if $ordered is true), the type of list (alpha, roman numerals etc) can be set with $type, and $ulroot, if set, is the ID written into the first ul root. Any sub ul's after that are named the same, prepended with $ulprefix.
mixed $phase->getUserData(); (implemented)
Returns an array containg information about the visitors browser. A lot of information is returned in the array. Here's a screenshot of a simple dump I made of the array:
This API function uses the excellent phpSniff class!
mixed $phase->isManagerLoggedIn(); (implemented)
Gets if the user is logged into the manager or not. Good for inline editing and such. Returns an array containing id => userid, username => username, or false if not logged in.
mixed $phase->putChunk($chunkName); (implemented)
Returns the html contained in chunk $chunkName, or '' if it doesn't exist.
mixed $phase->evalSnippet($snippetName, $parameters); (implemented)
Runs the snippet named $snippetName, and returns the output string, or False if the snippet doesn't exist or fails (which will stop the parser). You can parameters to the snippet as an array:
$parameters = array("id" => 5, "text" => "this is a test");
mixed $phase->changeTemplate($templateName); (not yet implemented)
Switches from the current template to $templateName, and re-parses the document (this may affect generation time somewhat). Returns false if the template doesn't exist. This is still in the planning stage, and may or may not be implemented.
mixed $phase->getKeywords($id=0); (implemented)
Retrieves an array containing the keywords referenced to the current document. If you specify an $id in the function call, the keywords referenced to that $id will be retrieved.
mixed $phase->getStats([$scope="document" [, $id=0]]); (implemented)
Retrieves an array containing visit statistics for the document, or for the whole site. If it is called without any parameters, it gets the statistics for the current document. If it is called with $scope="document", and the $id of another document, it gets the hits for that document. If it is called with $scope="site", it retrieves the stats for the entire site. For documents, it retrieves the following information: unique visitors today, unique visitors this month, unique visitors all time. For the whole site, it gets the same information, plus the following: visits today, visits this month, visits all time. I may expand this to allow you to specify a time range (i.e. get all the information on this document for from 1-1-2004 to 1-2-2004). If I do, the dates you pass will need to be php timestamps.
Also note: If the document containing this snippet is cached, then the results will be cached too, which means they won't update with every page impression, only when the cache is emptied.
Now I'd like to hear if you have any suggestions for other API calls you might find helpful. Be sure to describe the variables, and give a concise, detailed of the expected functionality of the function.
Oh yeah, don't worry, exisiting snippets will still work
(although once you've translated your snippets, you can turn 'old snippet support' off, for improved speed. I've been mucking around with this for a week now, and translating old snippets to new snippets is very, very easy
P.S. Since editing a post doesn't bump the topic as new posts, every time the post is updated, the number in the subject will increase by one. -Snuffkin
