-
diff --git a/demos/quickstart/protected/pages/Database/ActiveRecord.page b/demos/quickstart/protected/pages/Database/ActiveRecord.page
new file mode 100644
index 00000000..017b8d45
--- /dev/null
+++ b/demos/quickstart/protected/pages/Database/ActiveRecord.page
@@ -0,0 +1,360 @@
+
- Construct an instance of the Active Record from a SQL result set row. +
- Construct a new instance for later insertion into the table. +
- Finder methods to wrap commonly used SQL queries and return Active Record objects. +
- Update existing records and insert new records into the database. +
- Parameters -- name value parameter pairs. +
- OrderBy -- column name and ordering pairs. +
- Condition -- parts of the WHERE SQL conditions. +
- Limit -- maximum number of records to return. +
- Offset -- record offset in the table. +
- Fowler et. al. Patterns of Enterprise Application Architecture, + Addison Wesley, 2002. +
- Fowler et. al. Patterns of Enterprise Application Architecture, + Addison Wesley, 2002. +
- xxxx. iBatis Data Mapper, + http://www.apache.org/ibatis. +
Active Record
+Active Records are objects that wrap a row in a database table or view, + encapsulates the database access and adds domain logic on that data. + The basics of an Active Record is a business object class, e.g., a + Products class, that match very closely the record structure + of an underlying database table. Each Active Record will be responsible for + saving and loading data to and from the database.
+When to Use It
+Active Record is a good choice for domain logic that isn't too complex, + such as creates, reads, updates, and deletes. Derivations and validations + based on a single record work well in this structure. Active Record has the + primary advantage of simplicity. It's easy to build + Active Records, and they are easy to understand.
+ +However, as your business logic grows in complexity, you'll soon want + to use your object's direct relationships, collections, inheritance, and so + forth. These don't map easily onto Active Record, and adding them piecemeal + gets very messy. + Another argument against Active Record is the fact that it couples the object + design to the database design. This makes it more difficult to refactor as a project goes forward.
+ +The alternative is to use a Data Mapper that separates the roles of the
+ business object and how these objects are stored.
+ Prado provides a complimentary choice between Active Record and
+ SqlMap Data Mapper.
+ A SqlMap Data Mapper can be used to load Active Record objects, in turn, these
+ Active Record objects can be used to update the database.
+ The "relationship" between Active Records and SqlMap is illustrated in the
+ following diagram. More details regarding the SqlMap Data Mapper can be found in
+ the SqlMap Manual.
+ alt="Active Records and SqlMap DataMapper" id="fig:diagram.png" class="figure"/>
+
+ The Active Record class has methods that do the following: +
-
+
Defining an Active Record
+Let us
+ consider the following "users" table that contains two columns named "username" and "email",
+ where "username" is also the primary key.
+
Next we define our Active Record class that corresponds to the "users" table.
+
Each property of the UserRecord class must correspond to a + column with the same name in the "users" table. The static class variable + $_tablename is optional when the class name is the same as + the table name in the database, otherwise $_tablename must + specify the table name that corresponds to your Active Record class. +
+ ++ The static method finder() returns an UserRecord instance + that can be used to load records from the database. The loading of records + using the finer methods is discuss a little later. The TActiveRecord::getRecordFinder() + static method takes the name of the current Active Record class as parameter. +
+ +Setting up a database connection
+
+ A default database connection for Active Record can be set as follows.
+ See Establishing Database Connection for
+ futher details regarding creation of database connection in general.
+
+ The default database connection can also be configured using a <module>
+ tag in the application.xml
+ or config.xml as follows.
+
A ConnectionID property can be specified with value corresponding
+ to another TDataSourceConfig module configuration's ID value. This allows
+ the same database connection to be used in other modules such as SqlMap.
+
Loading data from the database
+
+ The TActiveRecord class provides many convenient methods to find
+ records from the database. The simplest is finding records by matching primary keys.
+ See the
findByPk()
+Finds one record using only the primary key or composite primary keys.
+
find()
+Finds one single record that matches the criteria. The criteria
+ can be a partial SQL string or a TActiveRecordCriteria object.
+
The TActiveRecordCriteria class has the following properties: +
-
+
findAll()
+Same as find() but returns an array of objects.
+ +findBy*() and findAllBy*()
+Dynamic find method using parts of method name as search criteria.
+Method names starting with findBy return 1 record only.
+Method names starting with findAllBy return an array of records.
+The condition is taken as part of the method name after findBy or findAllBy.
+
+The following blocks of code are equivalent:
+
+
findBySql()
+Finds records using full SQL, returns corresponding array of record objects.
+ +count()
+Find the number of matchings records.
+ +Inserting and updating records
+
+Add a new record using TActiveRecord is very simple, just create a new Active
+Record object and call the save() method. E.g.
+
+To update a record in the database, just change one or more properties of
+the Active Record object that has been loaded from the database and then
+call the save() method.
+
+
+Active Record objects have a simple life-cycle illustrated in the following diagram.
+ alt="Active Records Life Cycle" id="fig:cycle.png" class="figure"/>
+
Deleting existing records
+
+ To delete an existing record that is already loaded, just call the delete() method.
+ You can also delete records in the database by primary keys without
+ loading any records using the deleteByPk() method.
+ For example, to delete one or records with tables having a scalar primary key.
+
+For composite primary keys (determined automatically from the table definitions):
+
Transactions
+All Active Record objects contains the property DbConnection
+ that can be used to obtain a transaction object.
+
References
+-
+
Data Mapper
+Data Mappers moves data between objects and a database while keeping them + independent of each other and the mapper itself. If you started with + Active Records, you may eventually + faced with more complex business + objects as your project progresses. When you build an object model with a + lot of business logic it's valuable to use these mechanisms to better organize + the data and the behavior that goes with it. Doing so leads to variant schemas; + that is, the object schema and the relational schema don't match up. +
+ +The Data Mapper separates the in-memory objects from the database. Its responsibility + is to transfer data between the two and also to isolate them from each other. + With Data Mapper the in-memory objects needn't know even that there's a database + present; they need no SQL interface code, and certainly no knowledge of the + database schema. (The database schema is always ignorant of the objects that use it.) +
+ +When to Use It
+The primary occasion for using Data Mapper is when you want the database schema + and the object model to evolve independently. Data Mapper's primary benefit is + that when working on the business (or domain) objects you can ignore the database, both in + design and in the build and testing process. The domain objects have no idea + what the database structure is, because all the correspondence is done by the mappers. +
+ +This helps you in the code because you can understand and work with the domain objects + without having to understand how they're stored in the database. You can modify the + business models or the database without having to alter either. With complicated + mappings, particularly those involving existing databases, this is very valuable. +
+ +The price, of course, is the extra layer that you don't get with + Active Record, + so the test for using these patterns is the complexity of the business logic. + If you have fairly simple business logic, an Active Record + will probably work. + For more complicated logic a Data Mapper may be more suitable. +
+ +SqlMap Data Mapper
+The SqlMap DataMapper framework makes it easier to use a database with a PHP application. + SqlMap DataMapper couples objects with stored procedures or SQL statements using + a XML descriptor. Simplicity is the biggest advantage of the SqlMap DataMapper over + object relational mapping tools. To use SqlMap DataMapper you rely on your own objects, + XML, and SQL. There is little to learn that you don't already know. + With SqlMap DataMapper you have the full power of both SQL and stored procedures at + your fingertip +
+ +
+ alt="SqlMap Data Mapper Overview" id="fig:sqlmap.png" class="figure"/>
+
+ Here's a high level description of the work flow illustrated in the figure abov.
+ Provide a parameter, either as an object or a primitive type. The parameter can be
+ used to set runtime values in your SQL statement or stored procedure. If a runtime value
+ is not needed, the parameter can be omitted.
+
Execute the mapping by passing the parameter and the name you gave the statement or + procedure in your XML descriptor. This step is where the magic happens. The framework + will prepare the SQL statement or stored procedure, set any runtime values using your + parameter, execute the procedure or statement, and return the result. +
+ +In the case of an update, the number of rows affected is returned. In the case of a + query, a single object, or a collection of objects is returned. Like the parameter, + the result object, or collection of objects, can be a plain-old object or a primitive PHP type. +
+ +Setting up a database connection and initializing the SqlMap
+
+ A database connection for SqlMap can be set as follows.
+ See Establishing Database Connection for
+ futher details regarding creation of database connection in general.
+
+ The TSqlMapManager is responsible for setting up the database connection + and configuring the SqlMap with given XML file(s). The configureXml() + method accepts a string that points to a SqlMap XML configuration file. Once + configured, call the getSqlMapGateway() method to obtain an instance + of the SqlMap gateway interface (use this object to insert/delete/find records). +
+ +
+ SqlMap database connection can also be configured using a <module>
+ tag in the application.xml
+ or config.xml as follows.
+
+ The ConfigFile attribute should point to a SqlMap configuration file + (to be detailed later) either using absolute path, relative path or the + Prado's namespace dot notation path (must omit the ".xml" extension). + +
To obtain the SqlMap gateway interface from the <module> configuration, simply
+ do, for example,
+
A quick example
+Let us
+ consider the following "users" table that contains two columns named "username" and "email",
+ where "username" is also the primary key.
+
Next we define our plain User class as follows. Notice that
+ the User is very simple.
+
Next, we need to define a SqlMap XMl configuration file, lets name
+ the file as my-sqlmap.xml
+
The <select> tag returns defines an SQL statement. The id
+ attribute will be used as the identifier for the query. The resultClass
+ attribute value is the name of the class the the objects to be returned.
+ We can now query the objects as follows:
+
+
The above example shows demonstrates only a fraction of the capabilities + of the SqlMap Data Mapper. Further details can be found in the + SqlMap Manual. +
+ +Combining SqlMap with Active Records
+The above example may seem trival and it also seems that there is + alot work just to retrieve some data. However, notice that the User + class is totally unware of been stored in the database, and the database is + unware of the User class. +
++ One of advantages of SqlMap is the + ability to map complex object relationship, collections from an existing + database. On the other hand, Active Record + provide a very simple way + to interact with the underlying database but unable to do more complicated + relationship or collections. A good compromise is to use SqlMap to retrieve + complicated relationships and collections as Active Record objects and then using + these Active Records to do the updates, inserts and deletes. +
+Continuing with the previous example, we change the definition of the
+ User class to become an Active Record.
+
We also need to change the definition of the SqlMap XML configuration. We
+ just need to change the value of resultClass attribute to UserRecord.
+
The PHP code for retrieving the users remains the same, but SqlMap
+ returns Active Records instead, and we can take advantage of the Active Record methods.
+
+
References
+-
+