Propel Column Types

In this chapter we will take a closer look at the column types available to you in Propel. The column types you choose will affect both the SQL that is generated for your RDBMS and in some cases the behavior of the generated OM classes. The column types in Propel are mapped directly column types available in Creole, the db abstraction layer used by Propel, and the Creole column types are based on a simplified version of the JDBC Types.

The Propel generator classes translate the generic Propel column types into native column types for your RDBMS, and the generated OM classes and the Propel runtime framework ensure that data is properly transformed so that your calling script doesn't need to concern itself with the database implementation.

Boolean Column Types

There is a single BOOLEAN type in Propel:

This type is used to represent TRUE / FALSe values. In databases that don't have a BOOLEAN/BIT native datatype, an INTEGER (or SMALLINT) column will be used instead (0 = false, 1 = true).

<table name="bool_test">
  <column name="boolval" type="BOOLEAN" defaultValue="true"/>
</table>

In PostgreSQL, for example, this will generate:

CREATE TABLE bool_test (
  boolval bit NOT NULL default 't'
);

The accessor methods in the generated OM classes (e.g. getBoolval()) will always return boolean values, regardless of the database implementation.

Numeric Column Types

There are several numeric types available:

You may use the size and scale attributes for applicable numeric column types. Whether these are included in the generated SQL files will depend on your RDBMS.

<table name="num_test">
  <column name="num" type="FLOAT" size="10" scale="2"/>
</table>

In MySQL, for example, this will generate:

CREATE TABLE num_test (
  num FLOAT(10,2) NOT NULL
) Type=MyISAM;

The numeric types only affect the generated SQL and not the generated OM classes.

Note that you may very well be able to store numbers with greater precision in your database than you can in PHP. See the precision setting in your php.ini file if you encounter truncation.

String Column Types

There are several string types in Propel:

These columns map to the equivalents for the RDBMS. CHAR is for representing fixed length strings, while VARCHAR strings can vary in size. You can specify a size attribute for both of these. Generally the size attribute for LONGVARCHAR will be ignored. Some databases (e.g. MySQL, PostgreSQL, MS SQL Server) use a TEXT datatype for LONGVARCHAR.

Columns of these types will always store string values and will be returned as string values. Note that the values returned will always have any trailing whitespace trimmed. Some RDBMS will do this automatically (e.g. MySQL) while others will not (e.g. PostgreSQL).

LOB Column Types

LOB stands for Locator OBject. There are two LOB column types in Propel:

These datatype deserve special attention because they are handled slightly differently from other datatypes in Propel. Results for LOB datatypes are returned as objects of type creole.util.Blob or creole.util.Clob, depending on the column type. These classes provide some useful methods (e.g. for writing to file or dumping to buffer); they also provide a __toString() method so that your calling code can choose to ignore the objects. Note: in PHP5.0.0RC1 the automatic __toString() invocation for (string) cast has been disaled! For now, you must explicitly invoke the __toString() methods on objects.

Take the following schema, for example:

<table name="lob_test">
  <column name="photo" type="BLOB"/>
</table>

The calling PHP code would need to cast the results of these columns to string explicitly (to call the __toString() method) - for now you must explicitly call the __toString() method in PHP.:

$lob = LobTestPeer::doSelectOne(new Criteria());
$bits = $lob->getPhoto()->__toString(); // yuk, we know; convince php devs to restore automatic __toString()

... or you could call the Lob::getContents() method directly:

$bits = $lob->getPhoto()->getContents();

... or you could use the utility method to save them to file:

$lob->getPhoto()->writeToFile('/tmp/photo.gif');

... or you could dump the contents to buffer:

$lob->getPhoto()->dump();

Date & Time Column Types

The date and time column types in Propel are:

Most databases have direct equivalents for these Propel types. It's worth noting that for MySQL the TIMESTAMP datatype actually maps to DATETIME. The Creole layer actually transforms dates and times into the default values for your locale, providing consistency across database backends.

<table name="date_test">
  <column name="birth_date" type="DATE"/>
  <column name="birth_time" type="TIME"/>
  <column name="updated" type="TIMESTAMP"/>
</table>

The following example PHP code:

print $obj->getBirthDate() . "\n";
print $obj->getBirthTime() . "\n";
print $obj->getUpdate() . "\n";

Would have the following output on a system with en_US locale:

03/02/1998
12:34:23 AM
2003-12-21 18:32:01

... but the following output on a system with de_DE locale:

02.03.1998
00:34:23
2003-12-21 18:32:01

Notice that using the PHP setlocale() function will change the return values of accessors for DATE or TIME columns. The TIMESTAMP values are formatting using ISO 8601 regardless of the locale.

Custom Date Formats

Importantly, you can now also pass a date format string to the accessor methods for date/time columns. You can also pass NULL to have the methods return the integer unix timestamp.

print $obj->getBirthDate('n/j') . "\n";
print $obj->getBirthTime('%X') . "\n";
print $obj->getUpdate(null) . "\n";

Would have the following output on a system with en_US locale (in this example, the locale only affects the getBirthTime() call, which is using a locale-sensitive strftime()-type format string):

3/2
12:34:23 AM
1072049521