Setup Guide

App Template Setup

You can use the app template to set up Nymph and Nymph PubSub for you. All you need to install is Docker.

Nymph App Template

Manual Setup

You can manually set up Nymph if you don't want to use the app template. You need to install a DB (MySQL/PostgreSQL/SQLite3), an HTTP server (eg. Apache or nginx), PHP, Composer, and NPM.

Database Setup

If you're using SQLite3, you don't need to create anything. Nymph will create a SQLite3 database in whatever file you put in your config.

If you're using MySQL or PostgreSQL, before you can set up Nymph, you must create a database for it. Make sure that your database is accessible from the hosts that will run Nymph. You don't need to create any tables in the database; Nymph will do that for you.

Configuration

Create a new config.php file and put something like this in it:

// Nymph's configuration.

\Nymph\Nymph::configure([
  'MySQL' => [
    'host' => 'mysqlhost.yourdomain.com',
    'post' => 3306,
    'database' => 'yourdatabase',
    'user' => 'youruser',
    'password' => 'yourpassword'
  ]
]);

By default, Nymph will use the MySQL driver. If you're using PostgreSQL instead, you must set driver to 'PostgreSQL':

\Nymph\Nymph::configure([
  'driver' => 'PostgreSQL',
  'PostgreSQL' => [
    'host' => 'pgsqlhost.yourdomain.com',
    'port' => 5432,
    'database' => 'yourdatabase',
    'user' => 'youruser',
    'password' => 'yourpassword'
  ]
]);

And for SQLite3:

\Nymph\Nymph::configure([
  'driver' => 'SQLite3',
  'SQLite3' => [
    'filename' => '/path/to/mydatabase.sqlite'
  ]
]);

You can look in the conf/defaults.php file in the nymph-server repo to see the other configuration options.

If you're using PostgreSQL, your PCRE queries (the "match" clause) will be greatly improved if you can install the PL/Perl Procedural Language. If you can install it, you can turn the feature on, by setting the 'use_plperl' option to true.

Now you can start writing the PHP file that will load Nymph.

Loading Nymph in PHP

Requirements

Composer will download all the necessary requirements, and you can use the vendor/autoload.php file it creates to include everything you need.

Loading the Nymph Object

Load your configuration file.

require 'config.php';

When using Nymph, you will surely be writing your own classes to extend Entity. You will need to load these classes before you can start using them. In this example, we'll include the ones from the examples in the repository. It will also be easier to use Nymph instead of \Nymph\Nymph with a use statement.

use Nymph\Nymph as Nymph;
require 'nymph/examples/test/Employee.php';
require 'nymph/examples/sudoku/Game.php';
require 'nymph/examples/todo/Todo.php';

Now, you can begin using Nymph in PHP.

// Create an entity.
$newEntity = new Employee();
$newEntity->name = 'John Doe';
$newEntity->title = 'Senior Person';
$newEntity->salary = 5000000;
$newEntity->start_date = time();
$newEntity->save();

// Retrieve an entity.
$entity = Nymph::getEntity(['class' => Employee], ['&', 'strict' => ['name', 'John Doe']]);

Setting Up a Nymph REST Endpoint

Once you've loaded Nymph, you can set up a REST endpoint for the Nymph Client. You do this using the REST class. You can see an example of a Nymph REST endpoint in the rest.php example file.

$NymphREST = new \Nymph\REST();
$NymphREST->respond();

Now you are ready to load Nymph in your JavaScript.

Loading Nymph in JavaScript

Requirements

Nymph requires Promises. Promises may already be supported in your target browsers, but if they aren't, you can use a polyfill.

Loading the Nymph Object

Your configuration can be assigned to a global variable named NymphOptions before Nymph is loaded, or provided to Nymph later with init.

<script>
  // Providing your options as a global.
  NymphOptions = {
    restURL: 'path/to/your/rest/endpoint',
    pubsubURL: 'wss://websockethost.yourdomain.com'
  };
</script>

// Providing your options directly to Nymph.
import { Nymph, PubSub } from 'nymph-client';

let NymphOptions = {
  restURL: 'path/to/your/rest.php',
  pubsubURL: 'wss://websockethost.yourdomain.com'
};

Nymph.init(NymphOptions);
PubSub.init(NymphOptions);

If you're not using a bundler, include the client files.

<script src="node-modules/nymph-client/dist/NymphClient.js"></script>
<!-- And include all your custom classes. Again, we'll include the ones from the examples repo here. -->
<script src="vendor/sciactive/nymph-examples/examples/test/Employee.js"></script>
<script src="vendor/sciactive/nymph-examples/examples/sudoku/Game.js"></script>
<script src="vendor/sciactive/nymph-examples/examples/todo/Todo.js"></script>

Now, you can begin using Nymph in JavaScript.

import { Nymph } from 'nymph-client';
import Employee from 'Employee';

// Create an entity.
let entity = new Employee();
entity.name = 'John Doe';
entity.title = 'Senior Person';
entity.salary = 5000000;
entity.start_date = (new Date().getTime()) / 1000;
try {
  await entity.$save();
  alert("Yay, it worked. Here's John: \n" + JSON.stringify(entity));
} catch (errObj) {
  alert("Uh oh, it didn't work. Here's the error: \n" + errObj.textStatus);
}

// Retrieve an entity.
try {
  const entity = await Nymph.getEntity(
    {
      class: Employee.class
    },
    {
      type: '&',
      strict: ['name', 'John Doe']
    }
  );
  alert("Here's an employee: \n" + JSON.stringify(entity));
} catch (errObj) {
  alert("Uh oh, it didn't work. Here's the error: \n" + errObj.textStatus);
}

😀 Congratulations! You've set up a Nymph server and client!

Now go build an amazing app!