Skip Navigation

The Entity Selector Class

The entity selector provides a mechanism to grab sets of entities, optionally augmented with values from related fields. This class is critical to Reason development and should be the primary mechanism to access data stored in the Reason database.

Basic Usage examples

Example #1 – Select all news items from the site with unique name athletics

  1. $es = new entity_selector( id_of( 'athletics' ) );
  2. $es->add_type( id_of( 'news' ) );
  3. $results_array = $es->run_one();

The array $results_array will contain an array with all entities of the type with unique_name news on the site with unique name athletics.

Example #2 – Select all the images on a page

  1. $es = new entity_selector( $this->site_id );
  2. $es->add_type( id_of('image') );
  3. $es->add_right_relationship( $this->page_id, relationship_id_of('minisite_page_to_image');
  4. $results_array = $es->run_one();

The array $results_array will contain an array with all images on $this->site_id that are on the right side of a minisite_page_to_image relationship where the minisite_page in the relationship corresponds to $this->page_id.

Example #3 – Using the sharing options

In some cases, you may only want to select the owned entities, or perhaps just the borrowed ones. This can be done using the set sharing function.

  1. $es = new entity_selector( id_of( 'athletics' ) );
  2. $es->add_type( id_of( 'news' ) );
  3. $es->set_sharing( 'owns' ); //only get owned items
  4. $results_array = $es->run_one();

In this case, $results_array is limited to the news entities that are owned by the site with unique name athletics. Borrowed news items are excluded. If line 3 read $es->set_sharing('borrows') then the opposite would be true - only borrowed items would be included in the result set. The default behavior is to include items that are owned or borrowed.

Example #4 – Adding relations

The entity selector allows you to limit the results based upon a simple SQL statement using add_relation. For example:

  1. $es = new entity_selector( id_of( 'athletics' ) );
  2. $es->add_type( id_of( 'news' ) );
  3. $es->add_relation( 'entity.id < 2000' );
  4. $results_array = $es->run_one();

The above entity_selector selects all news items on the athletics site which have an id number below 2000.

Entity Selector Key Methods

  • entity_selector( $site_id ) – the constructor function, if $site_id is false, then selects entities from all sites, otherwise, selects entities from the site id that is given.
  • set_sharing( $args ) – sets entity selecter to select only owned, borrowed or all entities.
  • add_type( $id ) – adds a type to the entity selector.
  • add_left_relationship( $entity_id , $relationship_type ) – if relationship_type is set, makes sure any selected entities have a left relationship of that type with that type with the entity with the given entity id. Otherwise, makes sure any entities selected have any type of left relationship with the given entity id.
    • Note: This grabs entities where the type being selected is on the left (A) side of the relationship
  • add_right_relationship( $entity_id , $relationship_type ) – if relationship_type is set, makes sure any selected entities have a right relationship of that type with that type with the entity with the given entity id. Otherwise, makes sure any entities selected have any type of right relationship with the given entity id.
    • Note: This grabs entities where the type being selected is on the right (b) side of the relationship
  • add_left_relationship_field( $rel_name , $table , $field , $alias ) – adds a left relationship of type $rel_name and also selects a field of the entity ($table.$field as $alias ). All four parameters are required.
  • add_right_relationship_field( $rel_name , $table , $field , $alias ) – adds a right relationship of type $rel_name and also selects a field of the entity ($table.$field as $alias). All four parameters are required.

This file needs more updates, including information on aliasing, merging with add_right_relationship_field and add_left_relationship_field, caveats about set_num, examples involving relationship_fields, and probably more. Even so, it provides a nice intro. For the most current information, consult the entity selector documentation in the phpDocumentor generated Reason documentation.