165 lines
5.9 KiB
Plaintext
165 lines
5.9 KiB
Plaintext
= Model Introspection At Runtime =
|
|
|
|
In addition to the object and peer classes used to do C.R.U.D. operations, Propel generates an object mapping for your tables to allow runtime introspection.
|
|
|
|
The intospection objects are instances of the map classes. Propel maps databases, tables, columns, validators, and relations into objects that you can easily use.
|
|
|
|
== Retrieving a TableMap ==
|
|
|
|
The starting point for runtime introspection is usually a table map. This objects stores every possible property of a table, as defined in the `schema.xml`, but accessible at runtime.
|
|
|
|
To retrieve a table map for a table, use the `getTableMap()` static method of the related peer class. For instance, to retrieve the table map for the `book` table, just call:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookTable = BookPeer::getTableMap();
|
|
}}}
|
|
|
|
== TableMap properties ==
|
|
|
|
A `TableMap` object carries the same information as the schema. Check the following example to see how you can read the general properties of a table from its map:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
echo $bookTable->getName(); // 'table'
|
|
echo $bookTable->getPhpName(); // 'Table'
|
|
echo $bookTable->getPackage(); // 'bookstore'
|
|
echo $bookTable->isUseIdGenerator(); // true
|
|
}}}
|
|
|
|
Tip: A TableMap object also references the `DatabaseMap` that contains it. From the database map, you can also retrieve other table maps using the table name or the table phpName:
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$dbMap = $bookTable->getDatabaseMap();
|
|
$authorTable = $dbMap->getTable('author');
|
|
$authorTable = $dbMap->getTablebyPhpName('Author');
|
|
}}}
|
|
|
|
To introspect the columns of a table, use any of the `getColumns()`, `getPrimaryKeys()`, and `getForeignKeys()` `TableMap` methods. They all return an array of `ColumnMap` objects.
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookColumns = $bookTable->getColumns();
|
|
foreach ($bookColumns as $column) {
|
|
echo $column->getName();
|
|
}
|
|
}}}
|
|
|
|
Alternatively, if you know a column name, you can retrieve the corresponding ColumnMap directly using the of `getColumn($name)` method.
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookTitleColumn = $bookTable->getColumn('title');
|
|
}}}
|
|
|
|
The `DatabaseMap` object offers a shortcut to every `ColumnMap` object if you know the fully qualified column name:
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookTitleColumn = $dbMap->getColumn('book.TITLE');
|
|
}}}
|
|
|
|
== ColumnMaps ==
|
|
|
|
A `ColumnMap` instance offers a lot of information about a table column. Check the following examples:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookTitleColumn->getTableName(); // 'book'
|
|
$bookTitleColumn->getTablePhpName(); // 'Book'
|
|
$bookTitleColumn->getType(); // 'VARCHAR'
|
|
$bookTitleColumn->getSize(); // 255
|
|
$bookTitleColumn->getDefaultValue(); // null
|
|
$bookTitleColumn->isLob(); // false
|
|
$bookTitleColumn->isTemporal(); // false
|
|
$bookTitleColumn->isEpochTemporal(); // false
|
|
$bookTitleColumn->isNumeric(); // false
|
|
$bookTitleColumn->isText(); // true
|
|
$bookTitleColumn->isPrimaryKey(); // false
|
|
$bookTitleColumn->isForeignKey(); // false
|
|
$bookTitleColumn->hasValidators(); // false
|
|
}}}
|
|
|
|
`ColumnMap` objects also keep a reference to their parent `TableMap` object:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookTable = $bookTitleColumn->getTable();
|
|
}}}
|
|
|
|
Foreign key columns give access to more information, including the related table and column:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$bookPublisherIdColumn = $bookTable->getColumn('publisher_id');
|
|
echo $bookPublisherIdColumn->isForeignKey(); // true
|
|
echo $bookPublisherIdColumn->getRelatedName(); // 'publisher.ID'
|
|
echo $bookPublisherIdColumn->getRelatedTableName(); // 'publisher'
|
|
echo $bookPublisherIdColumn->getRelatedColumnName(); // 'ID'
|
|
$publisherTable = $bookPublisherIdColumn->getRelatedTable();
|
|
$publisherRelation = $bookPublisherIdColumn->getRelation();
|
|
}}}
|
|
|
|
== RelationMaps ==
|
|
|
|
To get an insight on all the relationships of a table, including the ones relying on a foreign key located in another table, you must use the `RelationMap` objects related to a table.
|
|
|
|
If you know its name, you can retrieve a `RelationMap` object using `TableMap::getRelation($relationName)`. Note that the relation name is the phpName of the related table, unless the foreign key defines a phpName in the schema. For instance, the name of the `RelationMap` object related to the `book.PUBLISHER_ID` column is 'Publisher'.
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$publisherRelation = $bookTable->getRelation('Publisher');
|
|
}}}
|
|
|
|
alternatively, you can access a `RelationMap` from a foreign key column using `ColumnMap::getRelation()`, as follows:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$publisherRelation = $bookTable->getColumn('publisher_id')->getRelation();
|
|
}}}
|
|
|
|
Once you have a `RelationMap` instance, inspect its properties using any of the following methods:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
echo $publisherRelation->getType(); // RelationMap::MANY_TO_ONE
|
|
echo $publisherRelation->getOnDelete(); // 'SET NULL'
|
|
$bookTable = $publisherRelation->getLocalTable();
|
|
$publisherTable = $publisherRelation->getForeignTable();
|
|
print_r($publisherRelation->getColumnMappings());
|
|
// array('book.PUBLISHER_ID' => 'publisher.ID')
|
|
print_r(publisherRelation->getLocalColumns());
|
|
// array($bookPublisherIdColumn)
|
|
print_r(publisherRelation->getForeignColumns());
|
|
// array($publisherBookIdColumn)
|
|
}}}
|
|
|
|
This also works for relationships referencing the current table:
|
|
|
|
{{{
|
|
#!php
|
|
<?php
|
|
$reviewRelation = $bookTable->getRelation('Review');
|
|
echo $reviewRelation->getType(); // RelationMap::ONE_TO_MANY
|
|
echo $reviewRelation->getOnDelete(); // 'CASCADE'
|
|
$reviewTable = $reviewRelation->getLocalTable();
|
|
$bookTable = $reviewRelation->getForeignTable();
|
|
print_r($reviewRelation->getColumnMappings());
|
|
// array('review.BOOK_ID' => 'book.ID')
|
|
}}}
|
|
|
|
To retrieve all the relations of a table, call `TableMap::getRelations()`. You can then iterate over an array of `RelationMap` objects.
|
|
|
|
Tip: RelationMap objects are lazy-loaded, which means that the `TableMap` will not instanciate any relation object until you call `getRelations()`. This allows the `TableMap` to remain lightweight for when you don't use relationship introspection.
|