Entity Class

As mentioned before, entities are organized using tags. To add, remove, and check tags, the methods addTag, removeTag, and hasTag are used, respectively. Each takes any number of tags or an array of tags as arguments.

Manipulating Entity Tags

```php $entity = Entity::factory();

$entity->addTag('com_foobar', 'foo', 'bar'); $entity->hasTag('foo'); // True

$entity->removeTag('foo', 'bar'); $entity->hasTag('foo'); // False

```js
var entity = new Entity();

entity.addTag('com_foobar', 'foo', 'bar');
entity.hasTag('foo'); // True

entity.removeTag('foo', 'bar');
entity.hasTag('foo'); // False

To clear the cache of referenced entities, so that the next time one is accessed it will be pulled from the database, use the clearCache method in PHP and the refresh method in JavaScript.

Clearing the Reference Entity Cache

```php $entity = Entity::factory(); $entity->foo = Entity::factory(); $entity->foo->bar = 'Old value.'; $entity->foo->save(); $entity->save();

$entity = $nymph->getEntity($entity->guid);

$instOfFoo = $nymph->getEntity($entity->foo->guid); $instOfFoo->bar = 'New value.'; $instOfFoo->save();

echo $entity->foo->bar; // Outputs 'Old value.' $entity->clearCache(); echo $entity->foo->bar; // Outputs 'New value.'

```js
// Let's just pretend the entity and foo have both been saved.
alert(entity.get('foo').get('bar')); // Outputs 'Old value.'
entity.refresh().then(function(entity){
  entity.data.foo.ready(function(foo){
    alert(entity.get('foo').get('bar')); // Outputs 'New value.'
  });
});

Much like clearing the entity cache, you may need to refresh the entity's own datan in PHP. Use the refresh method for this.

Refreshing an Entity's Data

```php $entity = Entity::factory(); $entity->foo = 'Old value.'; $entity->save();

$instOfEnt = $nymph->getEntity($entity->guid); $instOfEnt->foo = 'New value.'; $instOfEnt->save();

echo $entity->foo; // Outputs 'Old value.' $entity->refresh(); echo $entity->foo; // Outputs 'New value.'

As you've already seen in the examples, to save an entity, use the `save` method. Likewise, to delete the entity, use the `delete` method. You can also call the `saveEntity`, `deleteEntity`, and `deleteEntityById` methods of Nymph. The `Entity` class uses these methods.

<div dir="rtl">Different Ways of Saving and Deleting Entities</div>
```php
$entity = Entity::factory();

// Save the entity.
$entity->save();
// or
$nymph->saveEntity($entity);

// Delete the entity.
$entity->delete();
// or
$nymph->deleteEntity($entity);
// or
$nymph->deleteEntityById($entity->guid);

var entity = new Entity();

// Save the entity.
entity.save().then(function(entity){});
// or
Nymph.saveEntity(entity).then(function(entity){});

// Delete the entity.
entity.delete().then(function(){}, function(){alert('uh oh')});
// or
Nymph.deleteEntity(entity).then(function(){}, function(){alert('uh oh')});
// or
Nymph.deleteEntities(arrayOfEntities).then(function(){}, function(){alert('uh oh')});

Several methods are provided by entities to find and compare them with other data. Entities cannot simply be checked using the == operator. It will almost always fail because of things like entity caching and sleeping references. Instead, you can use the following entity methods.

• is - Perform a less strict comparison of two entities. To return true, the entity and the object passed must meet the following criteria.
• They must be entities.
• They must have equal GUIDs. (Or both can have no GUID.)
• If they have no GUIDs, their data must be equal.
• equals - Perform a more strict comparison of two entities. To return true, the entity and the object passed must meet the following criteria.
• They must be entities.
• They must have equal GUIDs. (Or both can have no GUID.)
• They must be instances of the same class.
• Their data must be equal.
• inArray - Check whether the entity is in an array. Takes two arguments, the array and a boolean $strict. If $strict is false, the function uses is to compare, and if it's true, the function uses equals.
• arraySearch - Search an array for the entity and return the corresponding key. Takes two arguments, the array and a boolean $strict. If $strict is false, the function uses is to compare, and if it's true, the function uses equals. This method may return 0, which evaluates to false, so you should use inArray if you are only checking whether the entity is in the array.

Comparing Entities

```php $entity = Entity::factory(35); // Assuming this entity exists. $entity2 = Entity::factory(35); $entity->is($entity2); // True

$array = array('foo' => null, 'bar' => $entity); echo $entity->arraySearch($array); // Outputs 'bar'

```js
var entityPromise = new Entity(35); // Assuming this entity exists.
var entityPromise2 = new Entity(35);
Promise.all([entityPromise, entityPromise2]).then(function(entities){
  var entity = entities[0],
      entity2 = entities[1];
  entity.is(entity2); // True

  var arr = [null, entity];
  alert(entity.arraySearch(arr)); // Outputs '1'
});

Nymph provides three methods to sort entities. Each one uses a different method of sorting.

• hsort - Sort an array of entities hierarchically by a specified property's value.
• psort - Sort an array of entities by parent and a specified property's value. If they have the same parent, their own value is used.
• sort - Sort an array of entities by a specified property's value.

Sorting Entities

```php $cats = $nymph->getEntities( array('class' => FoobarCategory), array('&', 'tag' => array('foobar', 'category') ) );

$caseSensitive = false; $reverse = false;

// Sort categories hierarchically by their name. $nymph->hsort($cats, 'name', 'parent', $caseSensitive, $reverse); // Sort categories by their parent's name. $nymph->psort($cats, 'name', 'parent', $caseSensitive, $reverse); // Sort categories by their name. $nymph->sort($cats, 'name', $caseSensitive, $reverse);

```js
var catsPromise = Nymph.getEntities(
    {'class': 'FoobarCategory'},
    {'type': '&',
      'tag': ['foobar', 'category']
    }
  );

catsPromise.then(function(cats){
  var caseSensitive = false,
      reverse = false;

  // Sort categories hierarchically by their name.
  Nymph.hsort(cats, 'name', 'parent', caseSensitive, reverse);
  // Sort categories by their parent's name.
  Nymph.psort(cats, 'name', 'parent', caseSensitive, reverse);
  // Sort categories by their name.
  Nymph.sort(cats, 'name', caseSensitive, reverse);
});

Client side Nymph entities can use the serverCall JavaScript method to call methods on a server side representation of the entity. This allows you to use a method that isn't yet, or won't be, implemented on the client side. serverCall expects three parameters: method, params, dontUpdateAfterCall. "method" is the name of the method to call on the server side object. "params" is an array of the parameters to pass to the method. You can use the arguments object for this, and it will be converted to a real array. "dontUpdateAfterCall", if set to true, will cause the method to not update the entity with the returned server side representation.

Normally, when you use this method, just before the promise is fulfilled, the entity's data will be replaced with that of the entity on the server side after the method was run. This will cause any awoken entities in the data of your entity to be replaced with sleeping entities, so you will have to run readyAll again. If you know that the server side method will not change any of the data on the entity, you can set "dontUpdateAfterCall" to true.

In order to be called from the client side, the method must be listed in the clientEnabledMethods property in the PHP class. This guards against a user submitting tailored AJAX calls to perform potentially dangerous tasks on the server side. If the method is not listed, the AJAX request will fail with a 403 Forbidden status.

Server Side Methods

```js todo.serverCall('archive', []).then(function(success){ if (!success) alert("Couldn't archive "+todo.get('name')); }, function(errObj){ alert("Error: "+errObj.textStatus+"\nCouldn't archive "+todo.get('name')); });

// You can also create a shortcut function to do the same thing in your class prototype. // You can see this actually done in the class definition in examples/classes/Todo.js Todo.prototype.archive = function(){ return Todo.serverCall('archive', arguments); }; todo.archive().then(/* ... */);