PEAR Manual
Prev |  | Next

# ->getLinks()

->getLinks() -- load related objects

## Synopsis

``boolean $DB_DataObject->getLinks` ([string $variableFormat])`

## Description

Loads the all the related objects into the main object, by using the links.ini relationships, and sets the calling objects variables with the row name prefixed with an underscode (`_`) to the resulting objects.

Using this with the earlier column naming convention is depreciated, and links.ini files should be used.

## Parameter

- `string $variableFormat` - the default behavior is to assign the resulting objects to variables with the row name prefixed with an underscode (`_`), however, you can use this value to format the variable differently

  Example 33-1. examples of formaters
      if room.occupied_by is linked to a person.id

      without a modifier - eg _%s

      results in the equivilant of
      $object->_occupied_by =  $object->getLink('occupied_by');

      with a modifier - eg link_%s

      results in the equivilant of
      $object->link_occupied_by = $object->getLink('occupied_by');

## Return value

`boolean` - `TRUE` on success and `FALSE` on failure

## Note

This function can not be called statically.

## See

DB_DataObject::getLink()

## Example

Example 33-2. Two Example Tables
    Person
    +---------------+---------------+------+-----+---------+----------------+
    | Field         | Type          | Null | Key | Default | Extra          |
    +---------------+---------------+------+-----+---------+----------------+
    | id            | mediumint(9)  |      | PRI | 0       | auto_increment |
    | first_name    | varchar(80)   | YES  |     | NULL    |                |
    | last_name     | varchar(80)   |      | MUL |         |                |
    | middle_name   | varchar(80)   | YES  |     | NULL    |                |
    | badge_number  | smallint(6)   | YES  |     | NULL    |                |
    | street        | varchar(80)   | YES  |     | NULL    |                |
    | city          | varchar(80)   | YES  |     | NULL    |                |
    | state         | varchar(80)   | YES  |     | NULL    |                |
    | zip           | varchar(15)   | YES  |     | NULL    |                |
    | phone         | varchar(15)   | YES  |     | NULL    |                |
    | reg_type      | varchar(80)   | YES  |     | NULL    |                |
    | judge         | varchar(10)   | YES  |     | NULL    |                |
    | staff         | varchar(10)   | YES  |     | NULL    |                |
    | volunteer     | varchar(10)   | YES  |     | NULL    |                |
    | rpga_number   | mediumint(9)  | YES  |     | NULL    |                |
    | total_fee     | float(10,2)   | YES  |     | NULL    |                |
    | email_address | varchar(80)   | YES  |     | NULL    |                |
    | country       | varchar(30)   | YES  |     | NULL    |                |
    | convention_id | int(11)       |      |     | 0       |                |
    | last_modified | timestamp(14) | YES  |     | NULL    |                |
    +---------------+---------------+------+-----+---------+----------------+

    Convention
    +----------------------+---------------+------+-----+---------+----------------+
    | Field                | Type          | Null | Key | Default | Extra          |
    +----------------------+---------------+------+-----+---------+----------------+
    | id                   | int(11)       |      | PRI | 0       | auto_increment |
    | name                 | varchar(50)   |      |     |         |                |
    | sponsor_organization | varchar(50)   |      |     |         |                |
    | rpga_convention_code | varchar(20)   |      |     |         |                |
    | web_site_url         | varchar(200)  |      |     |         |                |
    | last_modified        | timestamp(14) | YES  |     | NULL    |                |
    | room_id              | int(11)       |      |     |         |                |
    +----------------------+---------------+------+-----+---------+----------------+

    Room
    +----------------------+---------------+------+-----+---------+----------------+
    | Field                | Type          | Null | Key | Default | Extra          |
    +----------------------+---------------+------+-----+---------+----------------+
    | room_id              | int(11)       |      | PRI | 0       | auto_increment |
    | name                 | varchar(50)   |      |     |         |                |
    +----------------------+---------------+------+-----+---------+----------------+

Example 33-3. Loading all the related objects
    $person = new DataObjects_Person;
    $person->get(1079);
    $person->getLinks();
    print_r($person);

Example 33-4. Resulting SQL
    SELECT * FROM person WHERE id=1079
    SELECT * FROM convention WHERE id=1

Example 33-5. Resulting Output
    Object:dataobjects_person Object
    (
        [_DB_DataObject_version] => 1.0
        [__table] => person
        [_database_dsn] =>
        [_database_dsn_md5] => 3974043abbccdd6412fb156a1d10b98377
        [_database] => testing
        [_condition] =>
        [_group_by] =>
        [_order_by] =>
        [_limit] =>
        [_data_select] => *
        [_link_loaded] => 1
        [_lastError] => pear_error Object
            (
                [error_message_prefix] =>
                [mode] => 1
                [level] => 1024
                [code] => -3
                [message] => getLink:Could not find class for row last_modified, table last
                [userinfo] =>
                [callback] =>
            )

        [id] => 1079
        [N] => 1
        [_DB_resultid] => 2
        [first_name] => Tim
        [last_name] => White
        [middle_name] =>
        [badge_number] => 123
        [street] => 334411 N Washington
        [city] => Texas
        [state] => CO
        [zip] => 12345
        [phone] => 343412323232
        [reg_type] => Staff
        [judge] =>
        [staff] => CHECKED
        [volunteer] =>
        [rpga_number] => 1232323
        [total_fee] => 0.00
        [email_address] => tim@example.com
        [country] => USA
        [convention_id] => 1
        [last_modified] => 20020711084539
        [_first_name] =>
        [_last_name] =>
        [_middle_name] =>
        [_badge_number] =>
        [_reg_type] =>
        [_rpga_number] =>
        [_total_fee] =>
        [_email_address] =>
        [_convention_id] => dataobjects_convention Object
            (
                [_DB_DataObject_version] => 1.0
                [__table] => convention
                [_database_dsn] =>
                [_database_dsn_md5] => 3974043abbcc86412fb156a1d10b98377
                [_database] => testing
                [_condition] =>
                [_group_by] =>
                [_order_by] =>
                [_limit] =>
                [_data_select] => *
                [_link_loaded] =>
                [_lastError] =>
                [id] => 1
                [N] => 1
                [_DB_resultid] => 3
                [name] => ABCD XYZ
                [sponsor_organization] => some sponser
                [rpga_convention_code] => ABCD_XYZ
                [web_site_url] => http://example.com
                [last_modified] => 20020703143828
                [room_id] => 1
            )

        [_last_modified] =>
    )

Example 33-6. Example with three tables join
    /**
     * The following example show a three tables join.
     *
     * More joins can be nested as you see fit.
     */
    $person = new DataObjects_Person;

    $data = array();
    if ($person->find()) {
        while ($person->fetch()) {
            $person->getLinks();
            // Following is another call to getLinks for the second join
            $person->_convention_id->getLinks();
            $data[] = $person->_convention_id->_room_id->ToArray();
        }
    }

    print_r($data);

Example 33-7. databasename.links.ini
    ; this ini file is for the three tables join example above.
    [person]
    person_id = convention:person_id

    [room]
    room_id = convention:room_id

Prev | Home | Next
->getLink() | Up | ->selectAs()