Server : Apache System : Linux server2.corals.io 4.18.0-348.2.1.el8_5.x86_64 #1 SMP Mon Nov 15 09:17:08 EST 2021 x86_64 User : corals ( 1002) PHP Version : 7.4.33 Disable Function : exec,passthru,shell_exec,system Directory : /home/corals/dceprojects.corals.io/vendor/nesk/rialto/docs/ |
# Creating your first bridge with Rialto
We will create a bridge to use [Node's File System module](https://nodejs.org/api/fs.html) in PHP. This is not especially useful but it will show you how Rialto works and handles pretty much everything for you.
## Importing Rialto
Import Rialto in your project:
```
composer require nesk/rialto
npm install @nesk/rialto
```
## The essential files
You will need to create at least two files for your package:
- **An entry point** (`FileSystem.php`): this PHP class inherits [`AbstractEntryPoint`](../src/AbstractEntryPoint.php) and its instanciation creates the Node process. Every instruction (calling a method, setting a property, etc…) made on this class will be intercepted and sent to Node.
```php
use Nesk\Rialto\AbstractEntryPoint;
class FileSystem extends AbstractEntryPoint
{
public function __construct()
{
parent::__construct(__DIR__.'/FileSystemConnectionDelegate.js');
}
}
```
- **A connection delegate** (`FileSystemConnectionDelegate.js`): this JavaScript class inherits [`ConnectionDelegate`](../src/node-process/ConnectionDelegate.js) and will execute the instructions made with PHP (calling a method, setting a property, etc…).
```js
const fs = require('fs'),
{ConnectionDelegate} = require('@nesk/rialto');
module.exports = class FileSystemConnectionDelegate extends ConnectionDelegate
{
handleInstruction(instruction, responseHandler, errorHandler)
{
// Define on which resource the instruction should be applied by default,
// here we want to apply them on the "fs" module.
instruction.setDefaultResource(fs);
let value = null;
try {
// Try to execute the instruction
value = instruction.execute();
} catch (error) {
// If the instruction fails and the user asked to catch errors (see the `tryCatch` property in the API),
// send it with the error handler.
if (instruction.shouldCatchErrors()) {
return errorHandler(error);
}
throw error;
}
// Send back the value returned by the instruction
responseHandler(value);
}
}
```
With these two files, you should already be able to use your bridge:
```php
use Nesk\Puphpeteer\Fs\FileSystem;
$fs = new FileSystem;
$stats = $fs->statSync('/valid/file/path'); // Returns a basic resource representing a Stats instance
$stats->isFile(); // Returns true if the path points to a file
```
**Note:** You should use the synchronous methods of Node's FileSystem module. There is no way to handle asynchronous callbacks with Rialto for the moment.
## Creating specific resources
The example above returns a [`BasicResource`](../src/Data/BasicResource.php) class when the JavaScript API returns a resource (typically, a class instance). See this example:
```php
$buffer = $fs->readFileSync('/valid/file/path'); // Returns a basic resource representing a Buffer instance
$stats = $fs->statSync('/valid/file/path'); // Returns a basic resource representing a Stats instance
```
Its possible to know the name of the resource class:
```php
$buffer->getResourceIdentity()->className(); // Returns "Buffer"
$stats->getResourceIdentity()->className(); // Returns "Stats"
```
However, this is not convenient. That's why you can create specific resources to improve that. We will create 3 files:
- **A process delegate** (`FileSystemProcessDelegate.php`): this PHP class implements [`ShouldHandleProcessDelegation`](../src/Interfaces/ShouldHandleProcessDelegation.php) and is responsible to return the class names of the specific and default resources.
```php
use Nesk\Rialto\Traits\UsesBasicResourceAsDefault;
use Nesk\Rialto\Interfaces\ShouldHandleProcessDelegation;
class FileSystemProcessDelegate implements ShouldHandleProcessDelegation
{
// Define that we want to use the BasicResource class as a default if resourceFromOriginalClassName() returns null
use UsesBasicResourceAsDefault;
public function resourceFromOriginalClassName(string $jsClassName): ?string
{
// Generate the appropriate class name for PHP
$class = "{$jsClassName}Resource";
// If the PHP class doesn't exist, return null, it will automatically create a basic resource.
return class_exists($class) ? $class : null;
}
}
```
- **A resource to represent Buffer instances** (`BufferResource.php`): this class inherits `BasicResource` by convenience but the only requirement is to implement the [`ShouldIdentifyResource`](../src/Interfaces/ShouldIdentifyResource.php) interface.
```php
use Nesk\Rialto\Data\BasicResource;
class BufferResource extends BasicResource
{
}
```
- **A resource to represent Stats instances** (`StatsResource.php`):
```php
use Nesk\Rialto\Data\BasicResource;
class StatsResource extends BasicResource
{
}
```
Once those 3 files are created, you will have to register the process delegate in your entry point (`FileSystem.php`):
```php
use Nesk\Rialto\AbstractEntryPoint;
class FileSystem extends AbstractEntryPoint
{
public function __construct()
{
// Add the process delegate in addition to the connection delegate
parent::__construct(__DIR__.'/FileSystemConnectionDelegate.js', new FileSystemProcessDelegate);
}
}
```
Now you will get specific resources instead of the default one:
```php
$fs->readFileSync('/valid/file/path'); // Returns BufferResource
$fs->statSync('/valid/file/path'); // Returns StatsResource
$fs->statSync('/valid/file/path')->birthtime; // Returns a basic resource representing a Date instance
```
Specific resources can also help you to improve your API by adding methods to them:
```php
use Nesk\Rialto\Data\BasicResource;
class StatsResource extends BasicResource
{
public function birthtime(): \DateTime
{
return (new \DateTime)->setTimestamp($this->birthtimeMs / 1000);
}
}
```
```php
$fs->statSync('/valid/file/path')->birthtime(); // Returns a PHP's DateTime instance
```
## Learn more
Your first bridge with Rialto is ready, you can learn more by reading the [API documentation](api.md).