Usage

Simple integration

SpfPhp has no preference in terms of any templating engine or preexisting workflow. All it needs is access to some built-in PHP functions and some extra tags in your HTML.

All that you may need to do is just wrap your render code a little bit:

use SpfPhp\SpfPhp; // You will need this line somewhere in your file.

SpfPhp::beginCapture(); // Start SpfPhp

// Your render code, i.e. this:
echo $twig->render($page, $vars);

SpfPhp::autoRender(); // Tell SpfPhp to render what it caught

Really, that's all you need to do.

If you wish to manually specify element IDs to capture without the use of its x-tag, you may pass a semicolon delineated string or string array as the first argument to autoRender() like such:

SpfPhp::autoRender([
    // Update the class of #body, but don't change its content
    "@body<class>",
    // Update the attributes class and data-page-type, 
    // as well as the content, of #content
    "content<class, data-page-type>",
    // Update only the content of #navigation
    "navigation"
]);

Parsing methods

In addition to the aforementioned autoRender() method, there are two other methods that can be used for parsing HTML through SpfPhp.

Method	Description	Example
parse()	Parse a HTML string and return the SPF response as a string or an object, depending on the skipSerialisation option.	SpfPhp::parse($html, $ids, $options)
display()	Just like parse(), except the output is immediately echoed.	SpfPhp::display($html, $ids, $options
autoRender()	Automatically parse the page and display it, depending on whether or not SPF was requested.	SpfPhp::autoRender($ids, $options)

Detecting an SPF request

SpfPhp exposes a method to easily detect an SPF request: SpfPhp::isSpfRequested()

Options

The following options may be passed to the parsing methods:

Option	Description
skipSerialisation	Skip the encoding of a parse() output into a JSON string.
skipSerialization	Alias for skipSerialisation.
useFullHead	Controls whether or not the full HTML head should be used in output, as opposed to only links and scripts.
url	An optional URL control parameter. If unspecified, the URL will be assumed from the request, with the SPF parameters omitted.

X-Tags

X-Tags are special attributes, beginning in x-spfphp hence the name, that inform SpfPhp's behaviour. You don't have to use them for most functionality, but they are a nice alternative, especially when you have variable tags to output.

Here is a list of all x-tags and their behaviours:

Attribute	Type	Description
x-spfphp-capture	bool	The most simple function, this simply makes SpfPhp include an element in its response. In order for this to work, an element must have an ID
x-spfphp-ignore-body	bool	If true, ignore the contents of captured element. This is useful when you want to control for the attributes, but not the content.
x-spfphp-listener-attributes	string	A comma-separated string mentioning attribute names. Missing attributes will be ignored. Example: x-spfphp-listener-attributes="class, data-name"
x-spfphp-direct-render-callback	string	Name of a function to callback instead of rendering the body given. This is mostly useful for optimisation of large bodies that may take a long time to parse.

In addition to the provided x-tags, any custom x-tag may be used for miscellaneous purposes.

Notice

When using x-tags, you probably don't want them to echo in your code. Due to the nature of SPF.js, this is not a problem through SPF unless you have nested x-tags. However, SpfPhp only controls output directly if using the autoRender() method.

Therefore, as an alternative to conditionally including x-tags, you can remove them from a HTML string using the following function:

echo SpfPhp\XTag::erradicate($html);

Advanced use

Direct rendering

Sometimes, you'll find something that is a bit too much for SpfPhp. Maybe some really repetitive list. To help in these cases, SpfPhp provides a way for you to pass render behaviour for an element to a PHP function.

In order to use this, you will need to register a direct render callback.

SpfPhp::registerDirectRenderCallback("hello_world", function ($tags) {
    return "<div>Hello world!</div>";
});

Then in order to use this in SpfPhp, you will need to use the x-spfphp-direct-render-callback x-tag. This is the only functionality provided in the library that is only possible to do via x-tags, however it integrates with other methods well.

<!-- Unless you are using the second argument of the parse or display methods, you must also capture this. -->
<div id="content" x-spfphp-direct-render-callback="hello_world"></div>

The only argument given to the callback function is a list of all of the x-tags. For sharing state, you must use another x-tag. It is recommended to use the prefix x-spfphp-data in order to avoid future conflicts. For example, to make Hi the contents of this element:

SpfPhp::registerDirectRenderCallback("get_text", function ($tags) {
    if (isset($tags["data-text"]))
    {
        return $tags["data-text"];
    }
    else
    {
        return "";
    }
});

<div id="hello" x-spfphp-data-text="Hi" x-spfphp-direct-render-callback="get_text"></div>

Including additional data

Sometimes it's useful to include additional data in the response, i.e. for telling another JS component to update or restart. This can be processed in JavaScript using SPF's events.

In order to use additional data in an SpfPhp response, you will have to manually invoke and wrap the parsing. It is also important that you pass the skipSerialisation option in order to be able to modify the object.

if (SpfPhp::isSpfRequested())
{
   header("Content-Type: application/json");
   $spfResponse = SpfPhp::parse($html, $ids, ["skipSerialisation" => true]);
   $spfResponse->data = $myData;
   echo json_encode($spfResponse);
}
else
{
   // ... //
}