README

SSR

Server-side rendering of javascript UI components from PHP. Out of the box, it supports React, however you can add any JS UI library.

Prerequisites

Composer
NodeJS
(optional) PHPV8JS
Some JS bundler eg. Webpack

Supports

JS engines:

NodeJS
PHP v8js
Custom JS engines.

UI libraries:

React
Custom UI library.

Step-by-step Example

This example uses Webpack to bundle JS. You can use your favorite JS bundler.

Create the MyTest folder with the following file structure.

.
..
├── package.json
├── webpack.config.js
├── meow.jsx
├── index.js
└── index.php

Inside MyTest folder install all necessary packages.

npm install react
npm install react-dom
npm install @webiik/render-js-components
composer require webiik/ssr

Create a component.

Edit meow.jsx to:

import * as React from 'react';

export const Meow = (props) => {
    return (<h1>Meow {props.name}!</h1>);
}

Edit index.js to:

import {registerReactComponent} from '@webiik/render-js-components';
import {Meow} from 'meow';

registerReactComponent({Meow});

Configure Webpack.

Edit webpack.config.js to:

const webpack = require('webpack');
const path = require('path');
module.exports = {
    entry: {
        'index': 'index.js'
    },
    output: {
        filename: '[name].js',
        path: path.resolve(__dirname + '/build/')
    },
    resolve: {
        extensions: ['.js', '.jsx']
    }        
};

Bundle index.js to build/index.js. Remember, build/index.js MUST contain all code dependencies required to render the component with javascript.
```
webpack -p --colors --progress     
```

Render the component from PHP.

Edit index.php to:

// Render the component on server
$ssr = new \Webiik\Ssr\Ssr();
$engine = new \Webiik\Ssr\Engines\NodeJs();
$engine->setTmpDir(__DIR__);
$ssr->useEngine($engine);
$html = $ssr->render('build/index.js', 'Meow', ['name' => 'Dolly'], [
    'ssr' => true,
]);

// Load JS libs on client 
echo '<script src="build/index.js"></script>';

// Print server-side rendered component on client
echo $html;

Cache

You can use cache to store rendered components.

// To enable cache you MUST set cache dir and add 'cache' key to $renderOptions.
// To prevent cache conflicts cache key MUST be unique.
$ssr->setCacheDir(__DIR__);
$html = $ssr->render('index.js', 'Meow', ['name' => 'Dolly'], [
    'ssr' => true,
    'cache' => 'Meow',
    'expires' => 1, // 1 = one hour, 0 = never expires
]);

Custom UI library

SSR supports React out of the box, however, you can add support for your favorite UI library.

JS - Create a component registrar. Use registerReactComponent.tsx as template. The purpose of component registrar is to register function that renders component on a server and client.
PHP - Use method setFwJsMask() to tell SSR how to call the component registrar from step 1.
```
$ssr->setFwJsMask('vue', 'window.WebiikVue.%1$s("%2$s", "%3$s", "%4$s")');
```

PHP - Tell SSR that you want to use the component registrar from step 2.

$ssr->setDefaultFramework('vue');

$html = $ssr->render('index.js', 'Meow', ['name' => 'Dolly'], [
    'fw' => 'vue',
]);

If you need it. You can use more UI libraries at once.

Custom JS engine

The engine is a PHP class that processes JS and returns the result as a string. The engine MUST implement EngineInterface. See the code of current engines to learn more.

PHP - Create your engine.

PHP - Tell SSR to use your engine.

$ssr->useEngine(new YourCustomEngine());

webiik / ssr

Maintainers

Details