Models are Sodapop's object-relational mapping layer, and are significantly different than models in other web frameworks. They support a relatively limited (but useful!) set of features by design. Sodapop does not seek to replace SQL as doing so often results in a set of unsavory compromises for any non-trivial application. 1 These include:

  • In inflexible data model in which the schema is defined both in the SQL layer and the code layer, and must be kept synchronized whenever one changes.
  • A convoluted find() syntax which eventually grows to rival SQL in complexity and offering none of the flexibility, while being framework-specific to boot.
  • A difficult decoupling process when the application matures to the point where raw SQL is necessary for performance reasons, and everything needs to be rewritten.

Using Models

In the typical case using models in Sodapop is very easy. One of the unique features of the framework is that it automatically creates PHP classes for database tables dynamically the first time they are used. For instance, if there is a database table with the following definition:

Within a controller, this table can be accessed in this way:

Note that the column names are converted to camel-capitalized object properties, and that the class name is the singular form of the plural table name. Sodapop also requires that saving a model explicitly specifies the operation to be performed, either insert(), update() or delete() in keeping with its principle of easy discoverability when reading code.

Multi-column Primary Keys

Sodapop reads the database's schema when building its model classes and uses this information to determine the table's primary key(s). If there are multiple columns listed the object can be instantiated by passing in an associative array with the appropriate values assigned to the keys.

Extending Models

Those requiring their models to provide more functionality, additional fields or more methods are free to extend Sodapop's models. There are two methods for doing so.

Extending Automatically-Generated Model Classes

If Sodapop's default models are an adequate starting point, they can be extended in the following manner:

Extending Sodapop_Model_<ClassName> will give the class all of the properties of the automatically-generated model, allowing for easy extension with custom methods and fields.

Extending the Base Model Class

There are certain instances in which it is impractical to extend Sodapop's automatically-generated models. For instance, if application is being built with a legacy schema and the table names don't follow the conventions. In this case, users can extend Sodapop_Database_Table_Abstract.

The $tableName and $fieldDefinitions members are required to be defined, and the $primaryKey member is required if the table has primary key with a column name different than id. If the application has multiple database connections 2 and the table exists in a different database than the default specified in sodapop.json, the $connectionIdentifier member must also be defined.

Public Methods

asArray() (array)
Returns an array with this model's data.
delete() (boolean)
Deletes this model's row from the database.
getConnection() (Sodapop_Database_Abstract)
Returns the connection object used by this model. Can be used for running SQL queries.
insert() (boolean)
Inserts the model into the database.
loadData() (boolean)
Loads data from the database for the model. Called automatically when the user attempts to get a model property.
update() (boolean)
Updates the row for this model in the database.