Creating Entities

To create an entity, you can call the factory static method of an entity's class (in PHP), or use the new keyword (in JS and PHP). The benefit of using the factory method is that it can return an object wrapped in another object, allowing method hooking with HookPHP on entities. To check that an entity hasn't been saved yet, check that the GUID has not been set.

Creating an Entity

// BlogPost extends the Entity class.
$blogPost = BlogPost::factory();

// Using the regular instantiation method.
$definitelyBlogPostObject = new BlogPost();

// Check that the entity is new.
if (!isset($someBlogPost->guid)) {
  echo 'This blog post hasn\'t been saved yet!';
}

// BlogPost extends the Entity class.
let blogPost = new BlogPost();

// Check that the entity is new.
if (someBlogPost.guid == null) {
  alert('This blog post hasn\'t been saved yet!');
}

Much like entries in many blogging systems, entities can be organized using tags. The tags provide a fast way to query entities.

Using Tags

$blogPost->addTag('super-post');
$blogPost->save();

$superPosts = Nymph::getEntities(
  ['class' => 'BlogPost'],
  ['&', 'tag' => 'super-post']
);

$blogPost->inArray($superPosts); // true

blogPost.$addTag('super-post');
await blogPost.$save();

let superPosts = await Nymph.getEntities(
  {'class': BlogPost.class},
  {'type': '&', 'tag': 'super-post'}
);

blogPost.$inArray(superPosts); // true

Be cautious when saving an entity in another entity's property. If the referenced entity is newly created and does not have a GUID, Nymph will not be able to retrieve it later. Always save the referenced entity first.

Saving a Referenced Entity the Right Way

$entity = Entity::factory();
$entity->foo = Entity::factory();

$entity->foo->bar = 'It works!';
$entity->foo->save(); // Saving the referenced entity first! :)
$entity->save(); // now foo has been saved.

$guid = $entity->guid;
unset($entity);
$entity = Nymph::getEntity($guid);

isset($entity->foo->guid); // True
echo $entity->foo->bar; // Outputs 'It works!'.

Saving a Referenced Entity the Wrong Way

$entity = Entity::factory();
$entity->foo = Entity::factory();

$entity->save(); // foo hasn't been saved yet!

$entity->foo->bar = 'It works!';
$entity->foo->save();

$guid = $entity->guid;
unset($entity);
$entity = Nymph::getEntity($guid);

isset($entity->foo->guid); // False
echo $entity->foo->bar; // Outputs nothing.

⚠️ Caution: Since the referenced entity's class name is stored in the reference on the parent entity, if you change the class name in an update, you need to reassign all referenced entities of that class and resave.

When an entity is loaded, it does not request its referenced entities from Nymph. Instead, it creates instances without data called sleeping references. When you first access an entity's data (in PHP), if it is a sleeping reference, it will fill its data from the DB. You can call clearCache in PHP or $refresh in JavaScript to turn all the entities back into sleeping references.

In JavaScript, the $readyAll method can be used to awaken all sleeping references in the entity's data. This is the most convenient way to do this, since, unlike in PHP, the sleeping reference can't just be loaded when it is first accessed.