diff options
34 files changed, 856 insertions, 166 deletions
diff --git a/.gitattributes b/.gitattributes index 333c1d80..a007f8b1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -617,6 +617,7 @@ buildscripts/phing/tasks/PhpLintTask.php -text buildscripts/phing/tasks/PradoDocTask.php -text buildscripts/phing/tasks/PradoPackageTask.php -text buildscripts/phing/tasks/PradoPearTask.php -text +buildscripts/phing/tasks/PradoQuickStartDocs.php -text buildscripts/phing/tasks/PradoTestTask.php -text buildscripts/phing/tasks/PradoVersionTask.php -text buildscripts/phing/tasks/QuickstartIndexTask.php -text @@ -17,7 +17,10 @@ Upgrading from v3.1b - Comment tag <!-- ... ---> (introduced in v3.1a) is changed to <!--- ... --->
- When TDataList.RepeatLayout is Raw, the items will render <div> instead of <span>
+
- TActiveRecord finder methods will always return a new object instance (identity mapping was removed).
+- TActiveRecord::findBySql() will return an object rather than an array
+- TActiveRecord::findAllBySql() will return an array of objects.
Upgrading from v3.1a
---------------------
@@ -14,6 +14,7 @@ <taskdef name="prado-api-index" classname="ManualIndexTask" classpath="buildscripts/phing/tasks"/> <!-- <taskdef name="prado-test" classname="PradoTestTask" classpath="buildscripts/phing/tasks"/>-->
<taskdef name="compact-package" classname="PradoPackageTask" classpath="buildscripts/phing/tasks"/> + <taskdef name="prado-quickstart-docs" classname="PradoQuickStartDocs" classpath="buildscripts/phing/tasks" /> <!-- generates ${prado.version} and ${prado.revision} --> <prado-version-check /> @@ -149,11 +150,12 @@ - snapshot: generate nightly snapshot; </echo> </target>
-
+
<!-- bulid compact prado package definitions -->
<target name="compact-collections" description="Collections">
<mkdir dir="${build.compact.dir}" />
+ <mkdir dir="${build.compact.dir}/docs" /> <compact-package output="${build.compact.dir}/collections.php" strip="${compact-strip-comments}">
<filelist dir="framework" files="PradoBase.php,TComponent.php,Exceptions/TException.php,interfaces.php" />
<filelist dir="framework/Collections" files="TList.php,TMap.php,TAttributeCollection.php,TPagedList.php,TPagedDataSource.php" />
@@ -163,8 +165,11 @@ <copy file="COPYRIGHT" tofile="${build.compact.dir}/COPYRIGHT" />
<copy file="HISTORY" tofile="${build.compact.dir}/HISTORY" />
<delete file="${build.compact.dir}/readme.txt" />
- <append text="PRADO Framework for PHP 5, version ${prado.version}. See http://www.pradosoft.com/ for Documentation."
+ <append text="PRADO Framework for PHP 5, version ${prado.version}. See docs/ directory for documentation."
destFile="${build.compact.dir}/readme.txt" />
+ + <prado-quickstart-docs output="${build.compact.dir}/docs" + pages="Advanced/Collections.page,Fundamentals/Components.page"/> </target>
<target name="compact-db" description="Database" depends="compact-collections">
@@ -174,6 +179,7 @@ <filelist dir="framework/Data/Common"
files="TDbTableInfo.php, TDbTableColumn.php, TDbCommandBuilder.php, TDbMetaData.php" />
</compact-package>
+ <prado-quickstart-docs output="${build.compact.dir}/docs" pages="Database/DAO.page" /> </target>
<target name="compact-db-sqlite" description="Sqlite Database" depends="compact-db">
@@ -223,6 +229,7 @@ </compact-package>
<append file="framework/Data/ActiveRecord/Exceptions/messages.txt"
destfile="${build.compact.dir}/messages.txt" />
+ <prado-quickstart-docs output="${build.compact.dir}/docs" pages="Database/ActiveRecord.page" /> </target> <target name="compact-sqlmap" description="Package Active Record" depends="compact-db-all">
@@ -237,6 +244,7 @@ </compact-package>
<append file="framework/Data/SqlMap/DataMapper/messages.txt"
destfile="${build.compact.dir}/messages.txt" />
+ <prado-quickstart-docs output="${build.compact.dir}/docs" pages="Database/SqlMap.page" /> </target>
<target name="compact-all" description="All packages" depends="compact-active-record,compact-sqlmap" />
diff --git a/buildscripts/chmbuilder/ChmQuickstartBuilder.php b/buildscripts/chmbuilder/ChmQuickstartBuilder.php index 678310a6..43b55d12 100644 --- a/buildscripts/chmbuilder/ChmQuickstartBuilder.php +++ b/buildscripts/chmbuilder/ChmQuickstartBuilder.php @@ -13,12 +13,12 @@ class ChmQuickstartBuilder public function __construct($base,$output)
{
$this->base = $base;
- $this->output_dir = $output.'/quickstart';
+ $this->output_dir = $output;
- if(!is_dir($this->output_dir))
+ if(!is_dir($this->output_dir) || !is_dir($this->output_dir.'/assets'))
{
- mkdir($this->output_dir);
- mkdir($this->output_dir.'/assets/');
+ @mkdir($this->output_dir);
+ @mkdir($this->output_dir.'/assets/');
copy(dirname(__FILE__).'/chm_style.css', $this->output_dir.'/assets/chm_style.css');
}
@@ -58,7 +58,7 @@ class ChmQuickstartBuilder file_put_contents($this->output_dir.'/'.$file, $html);
}
- protected function getApplicationContent()
+ public function getApplicationContent()
{
ob_start();
$this->initApp();
@@ -68,7 +68,7 @@ class ChmQuickstartBuilder return $content;
}
- protected function parseHtmlContent($content)
+ public function parseHtmlContent($content)
{
$html = preg_replace('/<input.*name="PRADO_PAGESTATE" [^>]+\/>/m', '', $content);
$html = str_replace('<div id="header">
@@ -89,6 +89,10 @@ Copyright © 2005-2007 <a href="http://www.pradosoft.com">PradoSoft</a>.</di $html = preg_replace('/(src|href)=("?)\//', '$1=$2assets/',$html);
$html = str_replace('http://www.pradosoft.com/docs/manual', '../manual/CHMdefaultConverter', $html);
$html = str_replace('target="_blank">View Source', '>View Source', $html);
+ $html = preg_replace('/action="[^"]+"/', '', $html);
+ $html = preg_replace('/<script[^>]+><\/script>/', '', $html); //remove js
+ $html = preg_replace('/href="C:[^"]+"/', 'href="#"', $html);
+
$html = preg_replace_callback('/href="\?page=ViewSource&(amp;){0,1}path=([a-zA-z0-9\.\/]+)"/',
array($this, 'update_source_url'), $html);
diff --git a/buildscripts/chmbuilder/build.php b/buildscripts/chmbuilder/build.php index a85d9763..aeef4ad5 100644 --- a/buildscripts/chmbuilder/build.php +++ b/buildscripts/chmbuilder/build.php @@ -53,7 +53,7 @@ else $pages['Control Reference : Standard Controls'][] = 'Controls/Standard.page';
- $quickstart= new ChmQuickstartBuilder($base,$output_dir);
+ $quickstart= new ChmQuickstartBuilder($base,$output_dir.'/quickstart');
$quickstart->buildDoc($pages);
//move class data to protected data directory for prado app.
diff --git a/buildscripts/chmbuilder/chm_style.css b/buildscripts/chmbuilder/chm_style.css index 344d3176..6b2ae955 100644 --- a/buildscripts/chmbuilder/chm_style.css +++ b/buildscripts/chmbuilder/chm_style.css @@ -627,3 +627,21 @@ table.tabular td {
color: red;
}
+
+div.last-modified
+{
+ font-size: 0.8em;
+ color: #999;
+ margin-top: 5em;
+ margin-bottom: -3em;
+}
+
+p.since-version, p.requires-version
+{
+ display: none;
+}
+
+div.languages
+{
+ display: none;
+}
\ No newline at end of file diff --git a/buildscripts/phing/tasks/PradoQuickStartDocs.php b/buildscripts/phing/tasks/PradoQuickStartDocs.php new file mode 100644 index 00000000..06c30a14 --- /dev/null +++ b/buildscripts/phing/tasks/PradoQuickStartDocs.php @@ -0,0 +1,85 @@ +<?php
+require_once 'phing/Task.php';
+
+require_once(dirname(__FILE__).'/../../chmbuilder/ChmQuickstartBuilder.php');
+include(dirname(__FILE__).'/../../../framework/PradoBase.php');
+class Prado extends PradoBase
+{
+ protected static $app;
+
+ public static function setApplication($application)
+ {
+ self::$app=$application;
+ }
+
+ public static function getApplication()
+ {
+ return self::$app;
+ }
+
+ public static function setPathOfAlias($alias,$path)
+ {
+ $aliases = self::getPathAliases();
+ if(!isset($aliases[$alias]))
+ parent::setPathOfAlias($alias,$path);
+ }
+}
+
+include(dirname(__FILE__).'/../../../framework/prado.php');
+
+/**
+ * Task to run phpDocumentor for PRADO API docs.
+ */
+class PradoQuickStartDocs extends Task
+{
+ private $base_dir;
+
+ private $destdir;
+
+ private $page;
+
+ /**
+ * Set the destination directory for the generated documentation
+ */
+ function setOutput(PhingFile $destdir)
+ {
+ $this->destdir = $destdir;
+ }
+
+ function setPages($page)
+ {
+ $this->page = $page;
+ }
+
+ /**
+ * Main entrypoint of the task
+ */
+ function main()
+ {
+ $output = $this->destdir->getAbsolutePath();
+ $base = dirname(__FILE__).'/../../../demos/quickstart/protected/';
+ error_reporting(0);
+ $quickstart= new ChmQuickstartBuilder($base,$output);
+
+ foreach(preg_split('/\s*[, ]+\s*/', $this->page) as $page)
+ {
+ $file = str_replace(array('/','.page'), array('_','.html'),$page);
+ $this->log("Parsing $page");
+ file_put_contents($output.'/'.$file, $this->parsePage($quickstart,$page));
+ $this->log("Writing $file");
+ }
+ }
+
+ protected function parsePage($quickstart, $page)
+ {
+ $_GET['page'] = str_replace(array('/','.page'),array('.',''),$page);
+ $_GET['notheme'] = 'true';
+ $content = $quickstart->parseHtmlContent($quickstart->getApplicationContent());
+ //hide prado specific content
+ $content = str_replace('<body>', '<style type="text/css">.prado-specific {display:none;}</style><body>', $content);
+ return $content;
+ }
+
+}
+
+?>
\ No newline at end of file diff --git a/buildscripts/texbuilder/Page2Tex.php b/buildscripts/texbuilder/Page2Tex.php index 7ee4a171..ad712183 100644 --- a/buildscripts/texbuilder/Page2Tex.php +++ b/buildscripts/texbuilder/Page2Tex.php @@ -174,7 +174,7 @@ class Page2Tex //text modifiers
$html = preg_replace('/<(b|strong)[^>]*>([^<]*)<\/(b|strong)>/', '\textbf{$2}', $html);
- $html = preg_replace('/<i[^>]*>([^<]*)+?<\/i>/', '\emph{$1}', $html);
+ $html = preg_replace('/<i [^>]*>([^<]*)+?<\/i>/', '\emph{$1}', $html);
$html = preg_replace_callback('/<tt>([^<]*)<\/tt>/', array($this,'texttt'), $html);
//links
@@ -213,6 +213,8 @@ class Page2Tex $html = preg_replace('/<!--(.*)-->/', '', $html);
$html = preg_replace('/<div class="last-modified">((.|\n)*?)<\/div>/', '', $html);
+ //since
+ $html = preg_replace('/<com:SinceVersion[^>]+>/', '', $html);
$html = html_entity_decode($html);
diff --git a/buildscripts/texbuilder/quickstart/build.php b/buildscripts/texbuilder/quickstart/build.php index 2cee7fee..81a12d4c 100644 --- a/buildscripts/texbuilder/quickstart/build.php +++ b/buildscripts/texbuilder/quickstart/build.php @@ -42,7 +42,7 @@ foreach($pages as $chapter => $sections) $content .= $parser->get_section_label($section);
$file_content = file_get_contents($page);
- $tex =
+ //$tex =
$content .= $parser->parse_html($page,$file_content);
}
diff --git a/demos/quickstart/protected/pages/Advanced/Performance.page b/demos/quickstart/protected/pages/Advanced/Performance.page index c4eb9ef0..9d557150 100644 --- a/demos/quickstart/protected/pages/Advanced/Performance.page +++ b/demos/quickstart/protected/pages/Advanced/Performance.page @@ -33,7 +33,7 @@ if($application->Cache) { where <tt>$keyName</tt> should be a string that uniquely identifies the data item stored in cache.
</p>
-<p>
+<p id="840059" class="block-content">
Since v3.1.0, a new control called <a href="?page=Controls.OutputCache">TOutputCache</a> has been introduced. This control allows users to selectively cache parts of a page's output. When used appropriately, this technique can significant improve pages' performance because the underlying controls are not created at all if the cached versions are hit.
</p>
diff --git a/demos/quickstart/protected/pages/Advanced/Scripts3.page b/demos/quickstart/protected/pages/Advanced/Scripts3.page index 86e8bab9..96420219 100644 --- a/demos/quickstart/protected/pages/Advanced/Scripts3.page +++ b/demos/quickstart/protected/pages/Advanced/Scripts3.page @@ -1,7 +1,7 @@ <com:TContent ID="body" >
<h1 id="6801">Javascript in PRADO, Questions and Answers</h1>
<h2 id="6802">How do I include the Javascript libraries distributed with Prado?</h2>
-<p>The javascript libraries distributed with Prado can be found in the
+<p id="880060" class="block-content">The javascript libraries distributed with Prado can be found in the
<tt>framework/Web/Javascripts/source</tt> directory. The <tt>packages.php</tt>
file in that directory defines a list of available package names available
to be loaded. They can be loaded as follows.
@@ -36,7 +36,7 @@ and its dependencies will be automatically included on the page.</p> <p id="850762" class="block-content">See <a href="?page=Controls.ClientScript">TClientScript</a> for options of adding
your custom Javascript code to the page.</p>
-<h2>Publishing Javascript Libraries as Assets</h2>
+<h2 id="176028">Publishing Javascript Libraries as Assets</h2>
<com:SinceVersion Version="3.1b" />
<p class="block-content">Use <a href="?page=Controls.ClientScriptLoader">TClientScriptLoader</a> to publish and combine multiple existing javascript files (e.g. javascript libraries distributed with Prado or otherwise)
as packages.</p> For greater control on what and when to publish, use the
diff --git a/demos/quickstart/protected/pages/Configurations/Templates1.page b/demos/quickstart/protected/pages/Configurations/Templates1.page index 93f5662f..1252f8a7 100644 --- a/demos/quickstart/protected/pages/Configurations/Templates1.page +++ b/demos/quickstart/protected/pages/Configurations/Templates1.page @@ -41,7 +41,7 @@ To facilitate initializing properties with big trunk of data, the following prop PropertyValue
</prop:PropertyName>
</com:TTextHighlighter>
-<p>
+<p id="200007" class="block-content">
Since version 3.1.0, the property initialization tag can also be used to initialize a set of subproperties who share the same parent property. For example, the following is equivalent to <tt>HeaderStyle.BackColor="black"</tt> and <tt>HeaderStyle.ForeColor="red"</tt>.
</p>
<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_180075">
diff --git a/demos/quickstart/protected/pages/Controls/Validation.page b/demos/quickstart/protected/pages/Controls/Validation.page index 78ec0a4e..74db7b07 100644 --- a/demos/quickstart/protected/pages/Controls/Validation.page +++ b/demos/quickstart/protected/pages/Controls/Validation.page @@ -31,7 +31,7 @@ Validators share a common set of properties, which are defined in the base class <li><tt>FocusElementID</tt> - the ID of the HTML element that will receive focus if validation fails and <tt>FocusOnError</tt> is true.</li>
</ul>
-<h1>Prado Validation Controls</h1>
+<h1 id="116008">Prado Validation Controls</h1>
<a name="TRequiredFieldValidator"></a>
<h2 id="4902">TRequiredFieldValidator</h2>
<p id="560340" class="block-content">
@@ -160,7 +160,7 @@ The summary can be displayed as a list, a bulleted list, or a single paragraph b <com:RunBar PagePath="Controls.Samples.TValidationSummary.Home" />
<h1 id="123123">Interacting the Validators</h1>
-<h2>Resetting or Clearing of Validators</h2>
+<h2 id="116009">Resetting or Clearing of Validators</h2>
<p id="1212323">
Validators can be reset on the client-side using javascript by calling the
<tt>Prado.Validation.reset(groupID)</tt> where <tt>groupID</tt> is the validator
diff --git a/demos/quickstart/protected/pages/Database/ActiveRecord.page b/demos/quickstart/protected/pages/Database/ActiveRecord.page index 1e3c69c5..87d83740 100644 --- a/demos/quickstart/protected/pages/Database/ActiveRecord.page +++ b/demos/quickstart/protected/pages/Database/ActiveRecord.page @@ -3,15 +3,16 @@ <h1 id="138046">Active Record</h1> <com:SinceVersion Version="3.1a" /> <p id="690478" class="block-content">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 + encapsulate the database access and add domain logic on that data. + The basics of an Active Record are business classes, e.g., a <tt>Products</tt> 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. </p> <div class="info"><b class="note">Info:</b> - The data structure of an Active Record should match exactly that of a table + The data structure of an Active Record should match that of a table in the database. - Each field in the class must correspond to one column in the table. + Each column of a table should have a corresponding member variable or property in the + Active Record class the represents the table. </div> <h2 id="138047">When to Use It</h2> @@ -32,7 +33,7 @@ business object and how these objects are stored. Prado provides a complimentary choice between Active Record and <a href="?page=Database.SqlMap">SqlMap Data Mapper</a>. - A SqlMap Data Mapper can be used to load Active Record objects, in turn, these + 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 <a href="?page=Database.SqlMap">SqlMap</a> is illustrated in the following diagram. More details regarding the SqlMap Data Mapper can be found in @@ -41,15 +42,15 @@ </p> <p id="690482" class="block-content"> - The Active Record class has methods that do the following: + The Active Record class has functionality to perform the following tasks. </p> <ul id="u1" class="block-content"> - <li>Construct an instance of the Active Record from a SQL result set row.</li> - <li>Construct a new instance for later insertion into the table.</li> + <li>Create, Retrieve, Update and Delete records.</li> <li>Finder methods to wrap commonly used SQL queries and return Active Record objects.</li> - <li>Update existing records and insert new records into the database.</li> + <li>Fetch relationships (related foreign objects) such as "has many", "has one", "belongs to" and "has many" via association table.</li> + <li>Lazy loading of relationships.</li> </ul> -<h2>Database Supported</h2> +<h2 id="142010">Database Supported</h2> <p id="p1" class="block-content"> The Active Record implementation utilizes the <a href="?page=Database.DAO">Prado DAO</a> classes for data access. The current Active Record implementation supports the following database. @@ -60,12 +61,12 @@ The current Active Record implementation supports the following database. <li><a href="http://www.sqlite.org">SQLite 2 and 3</a></li> <li><a href="#">MS SQL 2000 or later</a></li> </ul> -<p>Support for other databases can be provided when there are sufficient demand.</p> +<p id="710009" class="block-content">Support for other databases can be provided when there are sufficient demands.</p> <h1 id="138048">Defining an Active Record</h1> <p id="690483" class="block-content">Let us - consider the following "users" table that contains two columns named "username" and "email", - where "username" is also the primary key. + consider the following "<tt>users</tt>" table that contains two columns named "<tt>username</tt>" and "<tt>email</tt>", + where "<tt>username</tt>" is also the primary key. <com:TTextHighlighter Language="sql" CssClass="source block-content" id="code_690147"> CREATE TABLE users ( @@ -75,7 +76,7 @@ CREATE TABLE users ); </com:TTextHighlighter> </p> -<p id="690484" class="block-content">Next we define our Active Record class that corresponds to the "users" table. +<p id="690484" class="block-content">Next we define our Active Record class that corresponds to the "<tt>users</tt>" table. <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690148"> class UserRecord extends TActiveRecord { @@ -94,8 +95,10 @@ class UserRecord extends TActiveRecord } </com:TTextHighlighter> </p> -<p id="690485" class="block-content">Each property of the <tt>UserRecord</tt> class must correspond to a - column with the same name in the "users" table. The class constant +<p id="690485" class="block-content">Each column of the "<tt>users</tt>" table must have corresponding + property of the same name as the column name in the <tt>UserRecord</tt> class. + Of course, you also define additional member variables or properties that does not exist in the table structure. + The class constant <tt>TABLE</tt> is optional when the class name is the same as the table name in the database, otherwise <tt>TABLE</tt> must specify the table name that corresponds to your Active Record class. @@ -123,6 +126,9 @@ class UserRecord extends TActiveRecord { } } </com:TTextHighlighter> +<p id="710010" class="block-content">More details regarding TComponent can be found in the <a href="?page=Fundamentals.Components">Components documentation</a>. +Later we shall use the getter/setters to allow for lazy loading of relationship objects. +</p> <div class="info"><b class="note">Info:</b> <tt>TActiveRecord</tt> can also work with database views by specifying the constant <tt>TABLE</tt> @@ -134,23 +140,54 @@ will raise an exception. <p id="690486" class="block-content"> The static method <tt>finder()</tt> returns an <tt>UserRecord</tt> 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 <tt>TActiveRecord::finder()</tt> - static method takes the name of the current Active Record class as parameter. + using the finer methods is discussed a little later. The <tt>TActiveRecord::finder()</tt> + static method takes the name of an Active Record class as parameter. </p> <h2 id="138049">Setting up a database connection</h2> <p id="690487" class="block-content"> A default database connection for Active Record can be set as follows. See <a href="?page=Database.DAO">Establishing Database Connection</a> for - futher details regarding creation of database connection in general. + further details regarding creation of database connection in general. +</p> <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690150"> //create a connection and give it to the Active Record manager. $dsn = 'pgsql:host=localhost;dbname=test'; //Postgres SQL $conn = new TDbConnection($dsn, 'dbuser','dbpass'); TActiveRecordManager::getInstance()->setDbConnection($conn); </com:TTextHighlighter> + +<p id="710011" class="block-content">Alternatively, you can create a base class and override the <tt>getDbConnection()</tt> +method to return a database connection. This is a simple way to permit multiple +connections and multiple databases. The following code demonstrates defining +the database connection in a base class (not need to set the DB connection anywhere else). </p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +class MyDb1Record extends TActiveRecord +{ + public function getDbConnection() + { + static $conn; + if($conn===null) + $conn = new TDbConnection('xxx','yyy','zzz'); + return $conn; + } +} +class MyDb2Record extends TActiveRecord +{ + public function getDbConnection() + { + static $conn; + if($conn===null) + $conn = new TDbConnection('aaa','bbb','ccc'); + return $conn; + } +} +</com:TTextHighlighter> + +<h3 class="prado-specific">Using <tt>application.xml</tt> within the Prado Framework</h3> +<div class="prado-specific"> <p id="690488" class="block-content"> The default database connection can also be configured using a <tt><module></tt> tag in the <a href="?page=Configurations.AppConfig">application.xml</a> @@ -167,7 +204,7 @@ TActiveRecordManager::getInstance()->setDbConnection($conn); The <tt>EnableCache</tt> attribute when set to "true" will cache the table meta data, that is, the table columns names, indexes and constraints are saved in the cache and reused. You must clear or disable the cache if you - wish to see chanages made to your table definitions. A <a href="?page=Advanced.Performance#6402">cache + wish to see changes made to your table definitions. A <a href="?page=Advanced.Performance#6402">cache module</a> must also be defined for the cache to function. </div> </p> @@ -190,33 +227,43 @@ TActiveRecordManager::getInstance()->setDbConnection($conn); </modules> </com:TTextHighlighter> </p> +</div> <h2 id="138050">Loading data from the database</h2> <p id="690490" class="block-content"> The <tt>TActiveRecord</tt> class provides many convenient methods to find - records from the database. The simplest is finding records by matching primary keys. + records from the database. The simplest is finding one record by matching a primary key or a + composite key (primary keys that consists of multiple columns). See the <com:DocLink ClassPath="System.Data.ActiveRecord.TActiveRecord" /> for more details. </p> - <h3 id="138055"><tt>findByPk()</tt></h3> - <p id="690491" class="block-content">Finds one record using only the primary key or composite primary keys. + +<div class="info"><b class="note">Info:</b> +All finder methods that may return 1 record only will return <tt>null</tt> if no matching data +is found. All finder methods that return an array of records will return an empty array if no +matching data is found. +</div> + + <h3 id="138055"><tt>findByPk()</tt></h3> + <p id="690491" class="block-content">Finds one record using only a primary key or a composite key. <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690153"> $finder = UserRecord::finder(); $user = $finder->findByPk($primaryKey); -//when the table uses composite keys +//when the table uses a composite key $record = $finder->findByPk($key1, $key2, ...); $record = $finder->findByPk(array($key1, $key2,...)); </com:TTextHighlighter> </p> <h3 id="138056"><tt>findAllByPks()</tt></h3> - <p id="690492" class="block-content">Finds multiple records using a list of primary keys or composite primary keys. -The following are equivalent for scalar primary keys (primary key consisting of only one column/field). + <p id="690492" class="block-content">Finds multiple records using a list of primary keys or composite keys. +The following are equivalent for primary keys (primary key consisting of only one column/field). +</p> <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690154"> $finder = UserRecord::finder(); -$users = $finder->findAllByPk($key1, $key2, ...); -$users = $finder->findAllByPk(array($key1, $key2, ...)); +$users = $finder->findAllByPks($key1, $key2, ...); +$users = $finder->findAllByPks(array($key1, $key2, ...)); </com:TTextHighlighter> The following are equivalent for composite keys. <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690155"> @@ -225,9 +272,7 @@ $record = $finder->findAllByPks(array($key1, $key2), array($key3, $key4), ...); $keys = array( array($key1, $key2), array($key3, $key4), ... ); $record = $finder->findAllByPks($keys); - </com:TTextHighlighter> -</p> <h3 id="138057"><tt>find()</tt></h3> @@ -270,13 +315,24 @@ $criteria->Limit = 10; $criteria->Offset = 20; </com:TTextHighlighter> +<div class="note"><b class="note">Note:</b> +For MSSQL and when <tt>Limit</tt> and <tt>Offset</tt> are positive integer values. The +actual query to be executed is modified by the +<com:DocLink ClassPath="System.Data.ActiveRecord.Common.Mssql.TMssqlCommandBuilder" +Text="TMssqlCommandBuilder" +/> +class according to +<a href="http://troels.arvin.dk/db/rdbms/#select-limit-offset">http://troels.arvin.dk/db/rdbms/</a> +to emulate the <tt>Limit</tt> and <tt>Offset</tt> conditions. +</div> + <h3 id="138058"><tt>findAll()</tt></h3> <p id="690495" class="block-content">Same as <tt>find()</tt> but returns an array of objects.</p> <h3 id="138059"><tt>findBy*()</tt> and <tt>findAllBy*()</tt></h3> -<p id="690496" class="block-content">Dynamic find method using parts of method name as search criteria. -Method names starting with <tt>findBy</tt> return 1 record only. -Method names starting with <tt>findAllBy</tt> return an array of records. +<p id="690496" class="block-content">Dynamic find method using parts of the method name as search criteria. +Method names starting with <tt>findBy</tt> return 1 record only +and method names starting with <tt>findAllBy</tt> return an array of records. The condition is taken as part of the method name after <tt>findBy</tt> or <tt>findAllBy</tt>. The following blocks of code are equivalent: @@ -298,14 +354,25 @@ $finder->findAll('Age = ?', $age); </com:TTextHighlighter> <div class="tip"><b class="note">Tip:</b> -You may also use <tt>OR</tt> as a condition in the dynamic methods. +You may also use a combination of <tt>AND</tt> and <tt>OR</tt> as a condition in the dynamic methods. </div> -<h3 id="138060"><tt>findBySql()</tt></h3> -<p id="690497" class="block-content">Finds records using full SQL, returns corresponding array of record objects.</p> - +<h3 id="138060"><tt>findBySql()</tt> and <tt>findAllBySql()</tt></h3> +<p id="690497" class="block-content">Finds records using full SQL where <tt>findBySql()</tt> +return an Active Record and <tt>findAllBySql()</tt>returns an array of record objects. +For each column returned, the corresponding Active Record class must define a member variable or +property for each corresponding column name. +<com:TTextHighlighter Language="php" CssClass="source block-content"> +class UserRecord2 extends UserRecord +{ + public $another_value; +} +$sql = "SELECT users.*, 'hello' as another_value FROM users"; +$users = TActiveRecord::finder('UserRecord2')->findAllBySql($sql); +</com:TTextHighlighter> +</p> <h3 id="138061"><tt>count()</tt></h3> -<p id="690498" class="block-content">Find the number of matchings records.</p> +<p id="690498" class="block-content">Find the number of matchings records, accepts same parameters as the <tt>findAll()</tt> method.</p> <h2 id="138051">Inserting and updating records</h2> <p id="690499" class="block-content"> @@ -327,7 +394,7 @@ The objects are update with the primary key of those the tables that contains definitions that automatically creates a primary key for the newly insert records. For example, if you insert a new record into a MySQL table that has columns defined with "autoincrement", the Active Record objects will be updated with the new -incremented values.</div> +incremented value.</div> <p id="690500" class="block-content"> To update a record in the database, just change one or more properties of @@ -341,7 +408,7 @@ $user->save(); //update it. </com:TTextHighlighter> </p> -<p> +<p id="710012" class="block-content"> Active Record objects have a simple life-cycle illustrated in the following diagram. </p> <img src=<%~ object_states.png %> alt="Active Records Life Cycle" id="fig:cycle.png" class="figure"/> @@ -350,43 +417,43 @@ We see that new TActiveRecord objects are created by either using one of the <tt methods or using creating a new instance by using PHP's <tt>new</tt> keyword. Objects created by a <tt>find*()</tt> method starts with <tt>clean</tt> state. New instance of TActiveRecord created other than by a <tt>find*()</tt> method starts with <tt>new</tt> state. -When ever you +Whenever you call the <tt>save()</tt> method on the TActiveRecord object, the object enters the <tt>clean</tt> state. Objects in the <tt>clean</tt> becomes <tt>dirty</tt> whenever one of more of its internal states are changed. Calling the <tt>delete()</tt> method on the object -ends the object life-cycle, no futher actions can be performed on the object. +ends the object life-cycle, no further actions can be performed on the object. </p> <h2 id="138052">Deleting existing records</h2> <p id="690502" class="block-content"> To delete an existing record that is already loaded, just call the <tt>delete()</tt> method. You can also delete records in the database by primary keys without - loading any records using the <tt>deleteByPk()</tt> method. - For example, to delete one or records with tables having a scalar primary key. + loading any records using the <tt>deleteByPk()</tt> method (and equivalently the <tt>deleteAllByPks()</tt> method). + For example, to delete one or records with tables using one or more primary keys. </p> <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690163"> $finder->deleteByPk($primaryKey); //delete 1 record -$finder->deleteByPk($key1,$key2,...); //delete multiple records -$finder->deleteByPk(array($key1,$key2,...)); //delete multiple records +$finder->deleteAllByPks($key1,$key2,...); //delete multiple records +$finder->deleteAllByPks(array($key1,$key2,...)); //delete multiple records </com:TTextHighlighter> <p id="690503" class="block-content"> -For composite primary keys (determined automatically from the table definitions): +For composite keys (determined automatically from the table definitions): </p> <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690164"> $finder->deleteByPk(array($key1,$key2)); //delete 1 record //delete multiple records -$finder->deleteByPk(array($key1,$key2), array($key3,$key4),...); +$finder->deleteAllByPks(array($key1,$key2), array($key3,$key4),...); //delete multiple records -$finder->deleteByPk(array( array($key1,$key2), array($key3,$key4), .. )); +$finder->deleteAllByPks(array( array($key1,$key2), array($key3,$key4), .. )); </com:TTextHighlighter> <h3 id="138052a"><tt>deleteAll()</tt> and <tt>deleteBy*()</tt></h3> <p id="690502a" class="block-content"> To delete by a criteria, use <tt>deleteAll($criteria)</tt> and <tt>deleteBy*()</tt> -with similar synatx to <tt>findAll($criteria)</tt> and <tt>findAllBy*()</tt> as +with similar syntax to <tt>findAll($criteria)</tt> and <tt>findAllBy*()</tt> as described above. </p> <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690163a"> @@ -399,7 +466,7 @@ $finder->deleteBy_Username_And_Password($name,$pass); </com:TTextHighlighter> <h2 id="138053">Transactions</h2> -<p id="690504" class="block-content">All Active Record objects contains the property <tt>DbConnection</tt> +<p id="690504" class="block-content">All Active Record objects contain the property <tt>DbConnection</tt> that can be used to obtain a transaction object. <com:TTextHighlighter Language="php" CssClass="source block-content" id="code_690165"> $finder = UserRecord::finder(); @@ -418,25 +485,76 @@ catch(Exception $e) // an exception is raised if a query fails } </com:TTextHighlighter> +<h2 id="142011">Events</h2> +<p id="710013" class="block-content"> +The TActiveRecord offers two events, <tt>OnCreateCommand</tt> and <tt>OnExecuteCommand</tt>. +</p> + +<p id="710014" class="block-content">The <tt>OnCreateCommand</tt> event is raised when a command is prepared and +parameter binding is completed. The parameter object is <tt>TDataGatewayEventParameter</tt> of which the +<tt>Command</tt> property can be inspected to obtain the SQL query to be executed. +</p> + +<p id="710015" class="block-content"> +The <tt>OnExecuteCommand</tt> event is raised when a command is executed and the +result from the database was returned. The parameter object is <tt>TDataGatewayResultEventParameter</tt> +of which the <tt>Result</tt> property contains the data return from the database. +The data returned can be changed by setting the <tt>Result</tt> property. +</p> + +<h3 id="142016">Logging Example</h3> +<p id="710016" class="block-content">Using the <tt>OnExecuteCommand</tt> we can attach an event handler to log +the entire SQL query executed for a given TActiveRecord class or instance. For example, we define +a base class and override either the <tt>getDbConnection()</tt> or the constructor. +</p> + +<com:TTextHighlighter Language="php" CssClass="source block-content"> +class MyDb1Record extends TActiveRecord +{ + public function getDbConnection() + { + static $conn; + if($conn===null) + { + $conn = new TDbConnection('xxx','yyy','zzz'); + $this->OnExecuteCommand[] = array($this,'logger'); + } + return $conn; + } + public function logger($sender,$param) + { + var_dump($param->Command->Text); + } +} +//alternatively as per instance of per finder object +function logger($sender,$param) +{ + var_dump($param->Command->Text); +} +TActiveRecord::finder('MyRecord')->OnExecuteCommand[] = 'logger'; +$obj->OnExecuteCommand[] = array($logger, 'log'); //any valid PHP callback. +</com:TTextHighlighter> + <h1 id="ar_relations">Active Record Relationships</h1> +<com:SinceVersion Version="3.1rc1" /> <p id="690504a" class="block-content"> The Prado Active Record implementation supports the foreign key mappings for database -that supports foreign key contraints. For ActiveRecord relationships to function the -underlying database must support foreign key constraints (e.g. MySQL with InnoDB). +that supports foreign key constraints. For Active Record relationships to function the +underlying database must support foreign key constraints (e.g. MySQL using InnoDB). </p> -<p> +<p id="710017" class="block-content"> In the following sections we shall consider the following table relationships between <tt>Teams</tt>, <tt>Players</tt>, <tt>Skills</tt> and <tt>Profiles</tt>. </p> -<img src="<%~ ar_relations.png %>" class="figure" /> +<img src=<%~ ar_relations.png %> class="figure" /> -<p>The goal is to obtain object models that represents to some degree the entity +<p id="710018" class="block-content">The goal is to obtain object models that represent to some degree the entity relationships in the above figure. </p> -<img src="<%~ ar_objects.png %>" class="figure"> +<img src=<%~ ar_objects.png %> class="figure" /> <p class="block-content"> There is a mismatch between relationships with objects and table relationships. @@ -449,14 +567,33 @@ structure between objects and tables. The approach taken in the Prado Active Rec design is to use the table foreign key constraints to derive object relationships. This implies that the underlying database must support foreign key constraints. </p> -<h2>Foreign Key Mapping</h2> +<div class="tip"><b class="note">Tip:</b> +For SQLite database, you may create tables that defines the foreign key +constraints such as the example below. However, these constraints are <b>NOT</b> +enforced by the SQLite database itself. +<com:TTextHighlighter Language="sql" CssClass="source block-content"> +CREATE TABLE foo +( + id INTEGER NOT NULL PRIMARY KEY, + id2 CHAR(2) +); +CREATE TABLE bar +( + id INTEGER NOT NULL PRIMARY KEY, + foo_id INTEGER + CONSTRAINT fk_foo_id REFERENCES foo(id) ON DELETE CASCADE +); +</com:TTextHighlighter> +</div> + +<h2 id="142012">Foreign Key Mapping</h2> <p class="block-content">The entity relationship between the <tt>Teams</tt> and <tt>Players</tt> table is what is known as an 1-M relationship. That is, one Team may contain 0 or more Players. In terms of -object relationships, we say that the <tt>Team</tt> object <b>has many</b> <tt>Player</tt> objects. +object relationships, we say that a <tt>TeamRecord</tt> object <b>has many</b> <tt>PlayerRecord</tt> objects. (Notice the reversal of the reversal of the direction of relationships between tables and objects.) -<p> -<h3>Has Many Relationship</h3> -<p> +<p id="710019" class="block-content"> +<h3 id="142017">Has Many Relationship</h3> +<p id="710020" class="block-content"> We model the <tt>Team</tt> object as the following Active Record classes. </p> <com:TTextHighlighter Language="php" CssClass="source block-content"> @@ -480,50 +617,50 @@ class TeamRecord extends TActiveRecord } } </com:TTextHighlighter> -<p> +<p id="710021" class="block-content"> The static <tt>$RELATIONS</tt> property of <tt>TeamRecord</tt> defines that the -property <tt>$players</tt> has many <tt>PlayerRecord</tt>s. Multiple relationships +property <tt>$players</tt> <b>has many</b> <tt>PlayerRecord</tt>s. Multiple relationships is permitted by defining each relationship with an entry in the <tt>$RELATIONS</tt> array where array key for the entry corresponds to the property name. In <tt>array(self::HAS_MANY, 'PlayerRecord')</tt>, the first element defines the -relationship type, the valid types are <strong><tt>self::HAS_MANY</tt></strong>, -<strong><tt>self::HAS_ONE</tt></strong> and <strong><tt>self::BELONGS_TO</tt></strong>. +relationship type, the valid types are <tt>self::HAS_MANY</tt>, +<tt>self::HAS_ONE</tt> and <tt>self::BELONGS_TO</tt>. The second element is a string <tt>'PlayerRecord'</tt> that corresponds to the class name of the <tt>PlayerRecord</tt> class. </p> -<p> +<p id="710022" class="block-content"> The foreign key constraint of the <tt>Players</tt> table is used to determine the corresponding <tt>Teams</tt> table's corresponding key names. This is done automatically handled in Active Record by inspecting the <tt>Players</tt> and <tt>Teams</tt> table definitions. </p> <div class="info"><b class="note">Info:</b> -Active Record supports multiple table foreign key relationships with the restiction -that each relationship correponds to a unique table. For example, the <tt>Players</tt> +Active Record supports multiple table foreign key relationships with the restriction +that each relationship corresponds to a unique table. For example, the <tt>Players</tt> table may only have one set of foreign key relationship with table <tt>Teams</tt>, it may have other relationships that corresponds to other tables (including the <tt>Players</tt> table itself). </div> -<p>The has many relationship is not fetched automatically when you use any of the Active Record finder methods. +<p id="710023" class="block-content">The "has many" relationship is not fetched automatically when you use any of the Active Record finder methods. You will need to explicitly fetch the related objects as follows. In the code below, both lines are equivalent and the method names are case insensitive. </p> <com:TTextHighlighter Language="php" CssClass="source block-content"> $team = TeamRecord::finder()->withPlayers()->findAll(); $team = TeamRecord::finder()->with_players()->findAll(); //equivalent -</com:TTextHighlighter Language="php"> -<p> +</com:TTextHighlighter> +<p id="710024" class="block-content"> The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property -name, in this case, <tt>players</tt>) fetchs the corresponding PlayerRecords using +name, in this case, <tt>players</tt>) fetches the corresponding PlayerRecords using a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same -arguments as other finder methods of TActiveRecord, e.g. <tt>with_players('age < ?', 35)</tt>. +arguments as other finder methods of TActiveRecord, e.g. <tt>with_players('age = ?', 35)</tt>. </p> <div class="note"><b class="note">Note:</b> It is essential to understand that the related objects are fetched using additional -queries. The first query fetches the source object, .e.g the <tt>TeamRecord</tt> in the above example code. -A second query is used to fetche the corresponding related <tt>PlayerRecord</tt> objects. +queries. The first query fetches the source object, e.g. the <tt>TeamRecord</tt> in the above example code. +A second query is used to fetch the corresponding related <tt>PlayerRecord</tt> objects. The usage of the two query is similar to a single query using Left-Outer join with the exception that null results on the right table are not returned. The consequence of using two or more queries is that the aggregates @@ -531,8 +668,15 @@ and other join conditions are not feasible using Active Records. For queries out scope of Active Record the <a href="?page=Database.SqlMap">SqlMap Data Mapper</a> may be considered. </div> -<h3>Belongs To Relationship</h3> - +<h3 id="142018">Belongs To Relationship</h3> +<p id="710025" class="block-content">The "has many" relationship in the above section defines a collection of foreign +objects. In particular, we have that a <tt>TeamRecord</tt> has many (zero or more) +<tt>PlayerRecord</tt> objects. We can also add a back pointer by adding a property +in the <tt>PlayerRecord</tt> class that links back to the <tt>TeamRecord</tt> object, +effectively making the association bidirectional. +We say that the <tt>$team</tt> property in <tt>PlayerRecord</tt> class <tt>belongs to</tt> a <tt>TeamRecord</tt> object. +The following code defines the complete <tt>PlayerRecord</tt> class with 3 relationships. +</p> <com:TTextHighlighter Language="php" CssClass="source block-content"> class PlayerRecord extends TActiveRecord { @@ -558,9 +702,41 @@ class PlayerRecord extends TActiveRecord } } </com:TTextHighlighter> +<p id="710026" class="block-content"> +The static <tt>$RELATIONS</tt> property of <tt>PlayerRecord</tt> defines that the +property <tt>$team</tt> <b>belongs to</b> a <tt>TeamRecord</tt>. +The <tt>$RELATIONS</tt> array also defines two other relationships that we +shall examine in later sections below. +In <tt>array(self::BELONGS_TO, 'TeamRecord')</tt>, the first element defines the +relationship type, in this case <strong><tt>self::BELONGS_TO</tt></strong> and +the second element is a string <tt>'TeamRecord'</tt> that corresponds to the +class name of the <tt>TeamRecord</tt> class. +A player object with the corresponding team object may be fetched as follows. +</p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +$players = PlayerRecord::finder()->with_team()->findAll(); +</com:TTextHighlighter> + +<p id="710027" class="block-content"> + The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property + name, in this case, <tt>team</tt>) fetches the corresponding <tt>TeamRecords</tt> using + a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same +arguments as other finder methods of <tt>TActiveRecord</tt>, e.g. +<tt>with_team('location = ?', 'Madrid')</tt>. +</p> -<h3>Has One Relationship</h3> +<div class="tip"><b class="note">Tip:</b> +Additional relationships may be fetched by chaining the <tt>with_xxx()</tt> together as the following +example demonstrates. +<com:TTextHighlighter Language="php" CssClass="source block-content"> +$players = PlayerRecord::finder()->with_team()->with_skills()->findAll(); +</com:TTextHighlighter> +Each <tt>with_xxx()</tt> method will execute an additional SQL query. Every +<tt>with_xxx()</tt> accepts arguments similar to those in the <tt>findAll()</tt> method and is only +applied to that particular relationship query. +</div> +<p id="710028" class="block-content">The "belongs to" relationship of <tt>ProfileRecord</tt> class is defined similarly.</p> <com:TTextHighlighter Language="php" CssClass="source block-content"> class ProfileRecord extends TActiveRecord { @@ -582,8 +758,84 @@ class ProfileRecord extends TActiveRecord } </com:TTextHighlighter> +<p id="710029" class="block-content">In essence, there exists a "<b>belongs to</b>" relationship for objects corresponding to +entities that has column which are foreign keys. In particular, we see that +the <tt>Profiles</tt> table has a foreign key constraint on the column <tt>player_id</tt> +that relates to the <tt>Players</tt> table's <tt>player_id</tt> column. Thus, the <tt>ProfileRecord</tt> +object has a property (<tt>$player</tt>) that <b>belongs to</b> a <tt>PlayerRecord</tt> object. +Similarly, the <tt>Players</tt> table has a foreign key constraint on the column <tt>team_name</tt> that relates to the +<tt>Teams</tt> table's <tt>name</tt> column. +Thus, the <tt>PlayerRecord</tt> object has a property (<tt>$team</tt>) that <b>belongs to</b> a +<tt>TeamRecord</tt> object. +</p> + +<h3 id="142019">Has One Relationship</h3> +<p id="710030" class="block-content">The entity relationship between <tt>Players</tt> and <tt>Profiles</tt> is one to one. That is, +each <tt>PlayerRecord</tt> object <b>has one</b> <tt>ProfileRecord</tt> object (may be none or null). +A <b>has one</b> relationship is nearly identical to a <b>has many</b> relationship with the exception +that the related object is only one object (not a collection of objects). +</p> + +<h3 id="142020">Parent Child Relationships</h3> +<p id="710031" class="block-content">A parent child relationship can be defined using a combination of <tt>has many</tt> and <tt>belongs to</tt> +relationship that refers to the same class. The following example shows a parent children relationship between +"categories" and a "parent category". +</p> + +<com:TTextHighlighter Language="php" CssClass="source block-content"> +class Category extends TActiveRecord +{ + public $cat_id; + public $category_name; + public $parent_cat_id; + + public $parent_category; + public $child_categories=array(); + + protected static $RELATIONS=array + ( + 'parent_category' => array(self::BELONGS_TO, 'Category'), + 'child_categories' => array(self::HAS_MANY, 'Category'), + ); +} +</com:TTextHighlighter> + -<h2>Association Table Mapping</h2> +<h2 id="142013">Association Table Mapping</h2> +<p id="710032" class="block-content"> +Objects can handle multivalued fields quite easily by using collections as field values. +Relational databases don't have this feature and are constrained to single-valued fields only. +When you're mapping a one-to-many association you can handle this using <b>has many</b> relationships, +essentially using a foreign key for the single-valued end of the association. +But a many-to-many association can't do this because there is no single-valued end to +hold the foreign key. +</p> +<p id="710033" class="block-content"> +The answer is the classic resolution that's been used by relational data people +for decades: create an extra table (an association table) to record the relationship. +The basic idea is using an association table to store the association. This table +has only the foreign key IDs for the two tables that are linked together, it has one +row for each pair of associated objects. +</p> +<p id="710034" class="block-content"> +The association table has no corresponding in-memory object and its primary key is the +compound of the two primary keys of the tables that are associated. +In simple terms, to load data from the association table you perform two queries (in general, it may also be achieved using one query consisting of joins). +Consider loading the <tt>SkillRecord</tt> collection for a list <tt>PlayerRecord</tt> objects. +In this case, you do queries in two stages. +The first stage queries the <tt>Players</tt> table to find all the rows of the players you want. +The second stage finds the <tt>SkillRecord</tt> object for the related player ID for each row +in the <tt>Player_Skills</tt> association table using an inner join. +</p> + +<p id="710035" class="block-content">The Prado Active Record design implements the two stage approach. For the +<tt>Players</tt>-<tt>Skills</tt> M-N (many-to-many) entity relationship, we need +to define a <b>has many</b> relationship in the <tt>PlayerRecord</tt> class and +in addition define a <b>has many</b> relationship in the <tt>SkillRecord</tt> class as well. +The following sample code defines the complete <tt>SkillRecord</tt> class with a +many-to-many relationship with the <tt>PlayerRecord</tt> class. (See the <tt>PlayerRecord</tt> +class definition above to the corresponding many-to-many relationship with the <tt>SkillRecord</tt> class.) +</p> <com:TTextHighlighter Language="php" CssClass="source block-content"> class SkillRecord extends TActiveRecord @@ -606,6 +858,186 @@ class SkillRecord extends TActiveRecord } </com:TTextHighlighter> +<p id="710036" class="block-content"> +The static <tt>$RELATIONS</tt> property of SkillRecord defines that the +property <tt>$players</tt> has many <tt>PlayerRecord</tt>s via an association table '<tt>Player_Skills</tt>'. +In <tt>array(self::HAS_MANY, 'PlayerRecord', 'Player_Skills')</tt>, the first element defines the +relationship type, in this case <strong><tt>self::HAS_MANY</tt></strong>, +the second element is a string <tt>'PlayerRecord'</tt> that corresponds to the +class name of the <tt>PlayerRecord</tt> class, and the third element is the name +of the association table name. +</p> +<p id="710037" class="block-content"> +A list of player objects with the corresponding collection of skill objects may be fetched as follows. +</p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +$players = PlayerRecord::finder()->withSkills()->findAll(); +</com:TTextHighlighter> +<p id="710038" class="block-content"> +The method <tt>with_xxx()</tt> (where <tt>xxx</tt> is the relationship property +name, in this case, <tt>Skill</tt>) fetches the corresponding <tt>SkillRecords</tt> using +a second query (not by using a join). The <tt>with_xxx()</tt> accepts the same +arguments as other finder methods of <tt>TActiveRecord</tt>. +</p> + +<h3 id="142021">Self Referenced Association Tables</h3> +<p id="710039" class="block-content"> +For self referenced association tables, that is, the association points to the same +table. For example, consider the <tt>items</tt> table with M-N related +item via the <tt>related_items</tt> association table. The syntax in the following +example is valid for a PostgreSQL database. For other database, consult their respective documentation for +defining the foreign key constraints. +<com:TTextHighlighter Language="sql" CssClass="source block-content"> +CREATE TABLE items +( + "item_id" SERIAL, + "name" VARCHAR(128) NOT NULL, + PRIMARY KEY("item_id") +); +CREATE TABLE "related_items" +( + "item_id" INTEGER NOT NULL, + "related_item_id" INTEGER NOT NULL, + CONSTRAINT "related_items_pkey" PRIMARY KEY("item_id", "related_item_id"), + CONSTRAINT "related_items_item_id_fkey" FOREIGN KEY ("item_id") + REFERENCES "items"("item_id") + ON DELETE CASCADE + ON UPDATE NO ACTION + NOT DEFERRABLE, + CONSTRAINT "related_items_related_item_id_fkey" FOREIGN KEY ("related_item_id") + REFERENCES "items"("item_id") + ON DELETE CASCADE + ON UPDATE NO ACTION + NOT DEFERRABLE +); +</com:TTextHighlighter> + +<p id="710040" class="block-content">The association table name in third element of the relationship array may +contain the foreign table column names. The columns defined in the association +table must also be defined in the record class (e.g. the <tt>$related_item_id</tt> property +corresponds to the <tt>related_item_id</tt> column in the <tt>related_items</tt> table). +</p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +class Item extends TActiveRecord +{ + const TABLE="items"; + public $item_id; + public $details; + + //additional foreign item id defined in the association table + public $related_item_id; + public $related_items=array(); + + protected static $RELATIONS=array + ( + 'related_items' => array(self::HAS_MANY, + 'Item', 'related_items.related_item_id'), + ); +} +</com:TTextHighlighter> +<div class="tip"><b class="note">Tip:</b> +Compound keys in the foreign table can +be specified as comma separated values between brackets. E.g. +<tt>'related_items.(id1,id2)'</tt>. +</div> + +<h2 id="142014">Adding/Removing/Updating Related Objects</h2> + +<p id="710041" class="block-content">Related objects can be simply inserted/updated by first adding those related objects to +the current source object (i.e. the object currently been worked on) and then call +the <tt>save()</tt> method on the source object. The related object's references +and the association reference (if required) will be added and/or updated. +For example, to add two new players to the team (assuming that 'Team A' exists), we can simply do the following. +</p> + +<com:TTextHighlighter Language="php" CssClass="source block-content"> +$team = TeamRecord::finder()->findByPk('Team A'); +$team->players[] = new PlayerRecord(array('age'=>20)); +$team->players[] = new PlayerRecord(array('age'=>25)); +$team->save(); +</com:TTextHighlighter> +<p id="710042" class="block-content"> +Since the <tt>TeamRecord</tt> class contains a <b>has many</b> relationship with the <tt>PlayerRecord</tt>, +then saving a <tt>TeamRecord</tt> object will also update the corresponding foreign objects in <tt>$players</tt> array. +That is, the objects in <tt>$players</tt> are inserted/updated in the database and the +<tt>$team_name</tt> property of those objects will contain the foreign key value that corresponds to the <tt>$team</tt> object's primary key value. +</p> + +<p id="710043" class="block-content">To delete a particular foreign object (or any Active Record object), simply call +the object's <tt>delete()</tt> method. You may setup the database table's foreign key constraints such that +when deleting a particular data in the database it will delete the referenced data as well (it may also be achieved using database +triggers). E.g. such as having a "<tt>ON DELETE CASCADE</tt>" constraint. +Deleting foreign objects by either setting the property value to null or removing the object from an array will <b>NOT</b> +remove the corresponding data in the database. +</p> + +<p id="710044" class="block-content">To remove associations for the many-to-many relationships via an association table, an Active Record +that corresponds to the association table can be used. Then the association can be removed by calling the <tt>deleteByPk()</tt> method, for example: +</p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +PlayerSkillAssocation::finder()->deleteByPk(array('fk1','fk2')); +//where 'fk1' is the primary key value of a player +// and 'fk2' is the primary key value of a skill +</com:TTextHighlighter> + +<h2 id="142015">Lazy Loading Related Objects</h2> +<p id="710045" class="block-content">Using the <tt>with_xxx()</tt> methods will load the relationship record on demand. Retrieving the +related record using lazy loading (that is, only when those related objects are accessed) can be +achieved by using a feature of the <tt>TComponent</tt> that provides accessor methods. In particular, +we define a pair of getter and setter methods where the getter method will retrieve the relationship +conditionally. The following example illustrates that the <tt>PlayerRecord</tt> can retrieve its +<tt>$skills</tt> foreign objects conditionally. +</p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +class PlayerRecord extends BaseFkRecord +{ + //... other properties and methods as before + + private $_skills; //change to private and default as null + + public function getSkills() + { + if($this->_skills===null && $this->player_id !==null) + { + //lazy load the skill records + $this->setSkills($this->withSkills()->findByPk($this->player_id)->skills); + } + else if($this->_skills===null) + { + //create new TList; + $this->setSkills(new TList()); + } + + return $this->_skills; + } + + public function setSkills($value) + { + $this->_skills = $value instanceof TList ? $value : new TList($value); + } +} +</com:TTextHighlighter> +<p id="710046" class="block-content">We first need to change the <tt>$skills=array()</tt> declaration to a private property +<tt>$_skills</tt> (notice the underscore) and set it to null instead. This allows us +to define the <tt>skills</tt> property using getter/setter methods +(see <a href="?page=Fundamentals.Components">Components</a> for details). The <tt>getSkills()</tt> +getter method for the <tt>skills</tt> property will lazy load the corresponding skills foreign record +when it is used as follows. Notice that we only do a lazy load when its <tt>$player_id</tt> is +not null (that is, when the record is already fetched from the database or player id was already set). +</p> +<com:TTextHighlighter Language="php" CssClass="source block-content"> +$player = PlayerRecord::finder()->findByPk(1); +var_dump($player->skills); //lazy load it on first access +var_dump($player->skills[0]); //already loaded skills property +$player->skills[] = new SkillRecord(); //add skill +</com:TTextHighlighter> + +<p id="710047" class="block-content">The <tt>setSkills()</tt> ensures that the <tt>skills</tt> property will always be a TList. +Using a TList allows us to set the elements of the <tt>skills</tt> property as if they were +arrays. E.g. <tt>$player->skills[] = new SkillRecord()</tt>. If <tt>array</tt> was used, a PHP error +will be thrown. +</p> + <h2 id="138054">References</h2> <ul id="u3" class="block-content"> <li>Fowler et. al. <i>Patterns of Enterprise Application Architecture</i>, diff --git a/demos/quickstart/protected/pages/Database/Scaffold.page b/demos/quickstart/protected/pages/Database/Scaffold.page index 9afe4a3f..759e55d1 100644 --- a/demos/quickstart/protected/pages/Database/Scaffold.page +++ b/demos/quickstart/protected/pages/Database/Scaffold.page @@ -1,8 +1,8 @@ <com:TContent ID="body" >
<!-- $Id$ -->
-<h1>Active Record Scaffold Views</h1>
+<h1 id="144022">Active Record Scaffold Views</h1>
<com:SinceVersion Version="3.1b" />
-<p><a href="?page=Database.ActiveRecord">Active Record</a> classes can be used together with
+<p id="720048" class="block-content"><a href="?page=Database.ActiveRecord">Active Record</a> classes can be used together with
<com:DocLink ClassPath="System.Data.ActiveRecord.Scaffold.TScaffoldListView" Text="TScaffoldListView"/>
and
<com:DocLink ClassPath="System.Data.ActiveRecord.Scaffold.TScaffoldEditView" Text="TScaffoldEditView"/>
@@ -10,7 +10,7 @@ and links both <tt>TScaffoldListView</tt> and <tt>TScaffoldEditView</tt>) to create
<i>simple</i> Create/Read/Update/Delete (CRUD) web applications.</p>
-<p>The scaffold views are intended to assist in prototyping web application,
+<p id="720049" class="block-content">The scaffold views are intended to assist in prototyping web application,
they are not designed to be as customiziable as more complex components such as
<a href="?page=Controls.DataGrid">TDataGrid</a>. The scaffold views provide
the following builtin functionality:
@@ -27,18 +27,18 @@ the following builtin functionality: <li>Presents specialized controls such as date pickers.</li>
</ul>
-<p>Scaffold views are dependent on Active Records and currently supports
+<p id="720050" class="block-content">Scaffold views are dependent on Active Records and currently supports
the following databases: Mysql, Sqlite and Postgres SQL. Support for other databases
can be considered when there are sufficient demand.</p>
-<h2>Setting up a Scaffold View</h2>
-<p>To use the scaffold view, we first define an <a href="?page=Database.ActiveRecord">Active Record</a>
+<h2 id="144023">Setting up a Scaffold View</h2>
+<p id="720051" class="block-content">To use the scaffold view, we first define an <a href="?page=Database.ActiveRecord">Active Record</a>
class that represents a table or view in the database. Consider the following
Active Record class that corresponds to the <tt>users</tt>
table as defined in the <a href="?page=Database.ActiveRecord">Active Record</a> quickstart page.
</p>
-<com:TTextHighlighter Language="php" CssClass="source">
+<com:TTextHighlighter Language="php" CssClass="source block-content" id="code_720188">
class UserRecord extends TActiveRecord
{
const TABLE='users';
@@ -48,7 +48,7 @@ class UserRecord extends TActiveRecord }
</com:TTextHighlighter>
-<p>The scaffold view classes are in the <tt>System.Data.ActiveRecord.Scaffold.*</tt>
+<p id="720052" class="block-content">The scaffold view classes are in the <tt>System.Data.ActiveRecord.Scaffold.*</tt>
<a href="?page=Fundamentals.Components#704">namespace</a>.
This <a href="?page=Fundamentals.Components#704">namespace</a> can be "imported" in the
<a href="?page=Configurations.AppConfig">Application Configuration</a>
@@ -59,11 +59,11 @@ simply set the <tt>RecordClass</tt> property value equal to an Active Record class name.
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_720189">
<com:TScaffoldView RecordClass="UserRecord" />
</com:TTextHighlighter>
-<p>The above code will list the current records in the <tt>users</tt> table.
+<p id="720053" class="block-content">The above code will list the current records in the <tt>users</tt> table.
Each record can be edited by clicking on the "edit" button and deleted by
clicking on the "delete" button. A new record can be added by clicking on the
"Add new record" button, enter some data (notice the automatic validation of required fields and data types), and click the "save" button.
@@ -71,20 +71,20 @@ Specifying search terms in the search textbox to find particular records. Finall record list can be sorted for each column by changing the sorting column and order.
</p>
-<p>The <tt>TScaffoldView</tt> is a template control composed of other scaffold controls.
+<p id="720054" class="block-content">The <tt>TScaffoldView</tt> is a template control composed of other scaffold controls.
The following properties gives access to these composite controls.</p>
<ul>
<li><b><tt>ListView</tt></b> -- the <tt>TScaffoldListView</tt> displaying the record list. </li>
<li><b><tt>EditView</tt></b> -- the <tt>TScaffoldEditView</tt> that renders the inputs for editing and adding records.</li>
<li><b><tt>SearchControl</tt></b> -- the <tt>TScaffoldSearch</tt> responsible to the search user interface.</li>
</ul>
-<p>
+<p id="720055" class="block-content">
All these composite controls can be customized as we shall see below.
</p>
-<h2>TScaffoldListView</h2>
+<h2 id="144024">TScaffoldListView</h2>
-<p>A list of Active Records can be displayed using the <tt>TScaffoldListView</tt>
+<p id="720056" class="block-content">A list of Active Records can be displayed using the <tt>TScaffoldListView</tt>
with the following useful properties.</p>
<ul>
<li><b><tt>Header</tt></b> -- a <a href="?page=Controls.Repeater">TRepeater</a>
@@ -96,7 +96,7 @@ the links and/or buttons that navigate to different pages in the Active Record d <li><b><tt>List</tt></b> -- a <a href="?page=Controls.Repeater">TRepeater</a> that renders a row of Active Record data.</li>
</ul>
-<p>Custom rendering of the each Active Record can be achieved by specifying
+<p id="720057" class="block-content">Custom rendering of the each Active Record can be achieved by specifying
the <tt>ItemTemplate</tt> and/or <tt>AlternatingItemTemplate</tt> property of the <tt>List</tt>
repeater.
The <tt>TScaffoldListView</tt> will listen for two command events named "delete" and
@@ -106,7 +106,7 @@ An "edit" command will push the record data to be edited by a The following example lists the usernames only with bold formatting.
</p>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_720190">
<com:TScaffoldListView RecordClass="UserRecord" >
<prop:List.ItemTemplate>
<strong><%# $this->Data->username %></strong>
@@ -120,27 +120,27 @@ Thus, the subproperty <tt>ListView.List.ItemTemplate</tt> on <tt>TScaffoldView</ is equivalent to the <tt>List.ItemTemplate</tt> subproperty of <tt>TScaffoldListView</tt> in the above example.
</div>
-<p>The <tt>SearchCondition</tt> property and
+<p id="720058" class="block-content">The <tt>SearchCondition</tt> property and
<tt>SearchParameters</tt> property (takes array values) can be
specified to customize the records to be shown. The <tt>SearchCondition</tt>
will be used as the <tt>Condition</tt> property of <tt>TActiveRecordCriteria</tt>
and the <tt>SearchParameters</tt> property corresponds to
<tt>Parameters</tt> property of <tt>TActiveRecordCriteria</tt>.</p>
-<h2>TScaffoldEditView</h2>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<h2 id="144025">TScaffoldEditView</h2>
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_720191">
<com:TScaffoldEditView RecordPk="user1" RecordClass="UserRecord" />
</com:TTextHighlighter>
-<h2>Combining list + edit views</h2>
+<h2 id="144026">Combining list + edit views</h2>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_720192">
<com:TScaffoldEditView ID="edit_view" RecordClass="UserRecord" />
<com:TScaffoldListView EditViewID="edit_view" RecordClass="UserRecord" />
</com:TTextHighlighter>
-<h2>Customizing the TScaffoldView</h2>
-<com:TTextHighlighter Language="prado" CssClass="source">
+<h2 id="144027">Customizing the TScaffoldView</h2>
+<com:TTextHighlighter Language="prado" CssClass="source block-content" id="code_720193">
<com:TScaffoldView RecordClass="UserRecord" >
<prop:ListView.List.ItemTemplate>
<%# $this->DataItem->username %>
diff --git a/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page b/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page index 1d40a8d9..42e4346f 100644 --- a/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page +++ b/demos/quickstart/protected/pages/GettingStarted/AboutPrado.page @@ -49,8 +49,8 @@ PRADO is often quoted as a unique framework. Its uniqueness mainly lies in the c Most PHP frameworks mainly focuses on separating presentation and logic and promotes the MVC (model-view-controller) design pattern. PRADO achieves the same goal naturally by requiring logic be stored in classes and presentation in templates. PRADO does much more on aspects other than MVC. It fills lot of blank area in PHP Web programming with its component-based programming paradigm, its rich set of Web controls, its powerful database support, its flexible error handling and logging feature, and many others.
</p>
-<h2>Is PRADO Stable Enough?</h2>
-<p>
+<h2 id="4004">Is PRADO Stable Enough?</h2>
+<p id="20004" class="block-content">
Yes. PRADO was initially released in August 2004. Many test suites have been written and conducted frequently to ensure its quality. It has been used by thousands of developers and many Web applications have been developed based on it. Bugs and feature requests are managed through TRAC system and we have a great user community and development team to ensure all questions are answered in a timely fashion.
</p>
diff --git a/demos/quickstart/protected/pages/GettingStarted/Introduction.page b/demos/quickstart/protected/pages/GettingStarted/Introduction.page index f267d23d..3fd67d5d 100644 --- a/demos/quickstart/protected/pages/GettingStarted/Introduction.page +++ b/demos/quickstart/protected/pages/GettingStarted/Introduction.page @@ -4,14 +4,14 @@ <p id="10001">
This Quickstart tutorial is provided to help you quickly start building your own Web applications based on PRADO version 3.x.
</p>
-<p>
+<p id="10001" class="block-content">
If you are an existing PRADO 3.x user and would like to learn what enhancements are available for each new version, please check out the <a href="?page=GettingStarted.NewFeatures">new features</a> page. Otherwise, the following sections are helpful for newbies.
</p>
<!--
<div class="start-page">
<div class="concepts start-block">
- <h2>How PRADO Works</h2>
- <p>Concepts and fundamentals</p>
+ <h2 id="2001">How PRADO Works</h2>
+ <p id="10002" class="block-content">Concepts and fundamentals</p>
<ol>
<li><a href="#">Building web applications with PRADO</a></li>
<li><a href="#">Web controls and events</a></li>
@@ -21,7 +21,7 @@ If you are an existing PRADO 3.x user and would like to learn what enhancements </ol>
</div>
<div class="examples start-block">
- <h2>Examples and Demos</h2>
+ <h2 id="2002">Examples and Demos</h2>
<ul>
<li><a href="../helloworld/">Hello World</a></li>
<li><a href="../currency-convert/">Currency Converter</a></li>
@@ -30,13 +30,13 @@ If you are an existing PRADO 3.x user and would like to learn what enhancements <li><a href="../chat/">AJAX Chat</a></li>
<li><a href="../time-tracker/">Project Time Tracker</a></li>
</ul>
- <p>More examples in <a href="?page=Controls.Standard">Standard Controls</a>,
+ <p id="10003" class="block-content">More examples in <a href="?page=Controls.Standard">Standard Controls</a>,
<a href="?page=Controls.Validation">Validation Controls</a> and
<a href="?page=Controls.Data">Data Controls</a>.
</div>
<div class="tutorials start-block">
- <h2>Tutorials and Help</h2>
+ <h2 id="2003">Tutorials and Help</h2>
<ul>
<li><a href="?page=GettingStarted.HelloWorld">Hello World in detail</a></li>
<li><a href="?page=Tutorial.CurrencyConverter">Currency Converter Tutorial</a></li>
diff --git a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page index 4aff6d47..2271bf75 100644 --- a/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page +++ b/demos/quickstart/protected/pages/GettingStarted/NewFeatures.page @@ -1,12 +1,12 @@ <com:TContent ID="body" >
-<h1>New Features</h1>
+<h1 id="8005">New Features</h1>
-<p>
+<p id="40005" class="block-content">
This page summarizes the main new features that are introduced in each PRADO release.
</p>
-<h2>Version 3.1.0</h2>
+<h2 id="8006">Version 3.1.0</h2>
<ul>
<li>Added seamless AJAX support. A whole array of AJAX-enabled controls, called active controls, are introduced. The usage of these active controls is very similar to their non-AJAX counterparts, i.e., plug in and use. For more details, see the tutorial about <a href="?page=ActiveControls.Home">active controls</a>.</li>
diff --git a/demos/quickstart/protected/pages/Services/SoapService.page b/demos/quickstart/protected/pages/Services/SoapService.page index 57d44c3b..29c59c10 100644 --- a/demos/quickstart/protected/pages/Services/SoapService.page +++ b/demos/quickstart/protected/pages/Services/SoapService.page @@ -139,7 +139,7 @@ A very useful tool to test out your web services is the free tool <a href="http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=65a1d4ea-0f7a-41bd-8494-e916ebc4159c">WebServiceStudio 2.0</a>. It can invoke webmethods interactively. The user can provide a WSDL endpoint. On clicking button Get the tool fetches the WSDL, generates .NET proxy from the WSDL and displays the list of methods available. The user can choose any method and provide the required input parameters.
The tool requires a MS .NET runtime to be installed.
-<p>A similar tool is available for Mac OS X Tiger from
+<p id="690008" class="block-content">A similar tool is available for Mac OS X Tiger from
<a href="http://www.ditchnet.org/soapclient/">http://www.ditchnet.org/soapclient/</a>
</p>
</div>
diff --git a/demos/quickstart/protected/pages/Tutorial/AddressBook.page b/demos/quickstart/protected/pages/Tutorial/AddressBook.page index 896521b1..f028a636 100644 --- a/demos/quickstart/protected/pages/Tutorial/AddressBook.page +++ b/demos/quickstart/protected/pages/Tutorial/AddressBook.page @@ -1,6 +1,6 @@ <com:TContent ID="body">
- <h1>A Simple Address Book</h1>
- <p>This tutorial introduces the basics of connecting to a database
+ <h1 id="22007">A Simple Address Book</h1>
+ <p id="110006" class="block-content">This tutorial introduces the basics of connecting to a database
using <a href="?page=Database.ActiveRecord">ActiveRecord</a>
and using <a href="?page=Database.Scaffold">Active Record scaffolds </a>to quickly
build a simple address book.
diff --git a/demos/quickstart/themes/PradoSoft/style.css b/demos/quickstart/themes/PradoSoft/style.css index 468d1386..d7150066 100644 --- a/demos/quickstart/themes/PradoSoft/style.css +++ b/demos/quickstart/themes/PradoSoft/style.css @@ -28,15 +28,15 @@ h1, h2 }
h1 {
- font-size:13pt;
+ font-size:14pt;
}
h2 {
- font-size:12pt;
+ font-size:13pt;
}
h3 {
- font-size:10pt;
+ font-size:12pt;
font-weight:bold;
}
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php index 9374af64..02d0b0e3 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordBelongsTo.php @@ -51,7 +51,7 @@ Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelation'); * }
* </code>
* The static <tt>$RELATIONS</tt> property of PlayerRecord defines that the
- * property <tt>$team</tt> belongs to (or is a) <tt>TeamRecord</tt>s.
+ * property <tt>$team</tt> belongs to a <tt>TeamRecord</tt>.
*
* The team object may be fetched as follows.
* <code>
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php index e83ca37f..65989639 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordHasManyAssociation.php @@ -158,13 +158,16 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation }
/**
- * @return TDbCommandBuilder
+ * @return TDataGatewayCommand
*/
protected function getCommandBuilder()
{
return $this->getSourceRecord()->getRecordGateway()->getCommand($this->getSourceRecord());
}
+ /**
+ * @return TDataGatewayCommand
+ */
protected function getForeignCommandBuilder()
{
$obj = $this->getContext()->getForeignRecordFinder();
@@ -314,13 +317,16 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation return $success;
}
+ /**
+ * @return TDbCommandBuilder
+ */
protected function getAssociationTableCommandBuilder()
{
$conn = $this->getContext()->getSourceRecord()->getDbConnection();
return $this->getAssociationTable()->createCommandBuilder($conn);
}
- protected function hasAssociationData($builder,$data)
+ private function hasAssociationData($builder,$data)
{
$condition=array();
$table = $this->getAssociationTable();
@@ -331,13 +337,13 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation return intval($result) > 0;
}
- protected function addAssociationData($builder,$data)
+ private function addAssociationData($builder,$data)
{
$command = $builder->createInsertCommand($data);
return $this->getCommandBuilder()->onExecuteCommand($command, $command->execute()) > 0;
}
- protected function updateAssociationTable($obj,$fkObjects, $builder)
+ private function updateAssociationTable($obj,$fkObjects, $builder)
{
$source = $this->getSourceRecordValues($obj);
$foreignKeys = $this->findForeignKeys($this->getAssociationTable(), $fkObjects[0]);
@@ -351,7 +357,7 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation return $success;
}
- protected function getSourceRecordValues($obj)
+ private function getSourceRecordValues($obj)
{
$sourceKeys = $this->findForeignKeys($this->getAssociationTable(), $obj);
$indexValues = $this->getIndexValues(array_values($sourceKeys), $obj);
@@ -362,7 +368,7 @@ class TActiveRecordHasManyAssociation extends TActiveRecordRelation return $data;
}
- protected function getForeignObjectValues($foreignKeys,$fkObject)
+ private function getForeignObjectValues($foreignKeys,$fkObject)
{
$data=array();
foreach($foreignKeys as $name=>$fKey)
diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php index 4dc9743f..60afef89 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelation.php @@ -191,10 +191,6 @@ abstract class TActiveRecordRelation $prop = $this->getContext()->getProperty();
$source->{$prop} = isset($collections[$hash]) ? $collections[$hash] : array();
}
-
- public function updateAssociatedRecords()
- {
- }
}
?>
\ No newline at end of file diff --git a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php index 12f2a874..16b29861 100644 --- a/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php +++ b/framework/Data/ActiveRecord/Relations/TActiveRecordRelationContext.php @@ -182,7 +182,6 @@ class TActiveRecordRelationContext */
public function updateAssociatedRecords($updateBelongsTo=false)
{
- Prado::using('System.Data.ActiveRecord.Relations.TActiveRecordRelationCommand');
$success=true;
foreach($this->getRecordRelationships() as $property=>$relation)
{
@@ -190,7 +189,7 @@ class TActiveRecordRelationContext if(($updateBelongsTo && $belongsTo) || (!$updateBelongsTo && !$belongsTo))
{
$obj = $this->getSourceRecord();
- if(!empty($obj->{$property}))
+ if(!$this->isEmptyFkObject($obj->{$property}))
{
$context = new self($this->getSourceRecord(),$property);
$success = $context->getRelationHandler()->updateAssociatedRecords() && $success;
@@ -199,6 +198,16 @@ class TActiveRecordRelationContext }
return $success;
}
+
+ protected function isEmptyFkObject($obj)
+ {
+ if(is_object($obj))
+ return $obj instanceof TList ? $obj->count() === 0 : false;
+ else if(is_array($obj))
+ return count($obj)===0;
+ else
+ return empty($obj);
+ }
}
?>
\ No newline at end of file diff --git a/framework/Data/ActiveRecord/TActiveRecord.php b/framework/Data/ActiveRecord/TActiveRecord.php index 1f482e6a..a66ab21c 100644 --- a/framework/Data/ActiveRecord/TActiveRecord.php +++ b/framework/Data/ActiveRecord/TActiveRecord.php @@ -289,7 +289,15 @@ abstract class TActiveRecord extends TComponent return $this->getRecordGateway()->deleteRecordsByPk($this,(array)$keys); } - + /** + * Alias for deleteByPk() + */ + public function deleteAllByPks($keys) + { + if(func_num_args() > 1) + $keys = func_get_args(); + return $this->deleteByPk($keys); + } /** * Delete multiple records using a criteria. * @param string|TActiveRecordCriteria SQL condition or criteria object. @@ -434,12 +442,28 @@ abstract class TActiveRecord extends TComponent * class. * @param string select SQL * @param array $parameters - * @return array matching active records. + * @return TActiveRecord */ public function findBySql($sql,$parameters=array()) { $args = func_num_args() > 1 ? array_slice(func_get_args(),1) : null; $criteria = $this->getCriteria($sql,$parameters, $args); + $data = $this->getRecordGateway()->findRecordBySql($this,$criteria); + return $this->populateObject(get_class($this), $data); + } + + /** + * Find records using full SQL, returns corresponding record object. + * The names of the column retrieved must be defined in your Active Record + * class. + * @param string select SQL + * @param array $parameters + * @return array matching active records. + */ + public function findAllBySql($sql,$parameters=array()) + { + $args = func_num_args() > 1 ? array_slice(func_get_args(),1) : null; + $criteria = $this->getCriteria($sql,$parameters, $args); $result = $this->getRecordGateway()->findRecordsBySql($this,$criteria); return $this->collectObjects($result); } @@ -533,6 +557,8 @@ abstract class TActiveRecord extends TComponent $condition = $method[9]==='_' ? substr($method,10) : substr($method,9); else if($delete = substr(strtolower($method),0,8)==='deleteby') $condition = $method[8]==='_' ? substr($method,9) : substr($method,8); + else if($delete = substr(strtolower($method),0,11)==='deleteallby') + $condition = $method[11]==='_' ? substr($method,12) : substr($method,11); else return null;//throw new TActiveRecordException('ar_invalid_finder_method',$method); diff --git a/framework/Data/ActiveRecord/TActiveRecordGateway.php b/framework/Data/ActiveRecord/TActiveRecordGateway.php index d97844f7..80ce40c0 100644 --- a/framework/Data/ActiveRecord/TActiveRecordGateway.php +++ b/framework/Data/ActiveRecord/TActiveRecordGateway.php @@ -214,11 +214,22 @@ class TActiveRecordGateway extends TComponent * Return record data from sql query.
* @param TActiveRecord active record finder instance.
* @param TActiveRecordCriteria sql query
+ * @return array result.
+ */
+ public function findRecordBySql(TActiveRecord $record, $criteria)
+ {
+ return $this->getCommand($record)->findBySql($criteria);
+ }
+
+ /**
+ * Return record data from sql query.
+ * @param TActiveRecord active record finder instance.
+ * @param TActiveRecordCriteria sql query
* @return TDbDataReader result iterator.
*/
public function findRecordsBySql(TActiveRecord $record, $criteria)
{
- return $this->getCommand($record)->findBySql($criteria);
+ return $this->getCommand($record)->findAllBySql($criteria);
}
public function findRecordsByIndex(TActiveRecord $record, $criteria, $fields, $values)
diff --git a/framework/Data/Common/Sqlite/TSqliteMetaData.php b/framework/Data/Common/Sqlite/TSqliteMetaData.php index 1a72622e..5e1c5f77 100644 --- a/framework/Data/Common/Sqlite/TSqliteMetaData.php +++ b/framework/Data/Common/Sqlite/TSqliteMetaData.php @@ -164,9 +164,8 @@ CREATE TABLE foo CREATE TABLE bar
(
id INTEGER NOT NULL PRIMARY KEY,
- foo_id INTEGER NOT NULL CONSTRAINT fk_foo_id REFERENCES foo(id) ON DELETE CASCADE,
- foo_id2 CHAR(2) CONSTRAINT fk_foo_id REFERENCES foo(id2) ON DELETE CASCADE,
- bar_id INTEGER NOT NULL CONSTRAINT fk_bar_id REFERENCES bar(id)
+ foo_id INTEGER
+ CONSTRAINT fk_foo_id REFERENCES foo(id) ON DELETE CASCADE
);
*/
diff --git a/framework/Data/DataGateway/TDataGatewayCommand.php b/framework/Data/DataGateway/TDataGatewayCommand.php index 80856a0e..60db80d6 100644 --- a/framework/Data/DataGateway/TDataGatewayCommand.php +++ b/framework/Data/DataGateway/TDataGatewayCommand.php @@ -280,13 +280,24 @@ class TDataGatewayCommand extends TComponent }
/**
- * Find one or more matching records for arbituary SQL.
+ * Find one matching records for arbituary SQL.
* @param TSqlCriteria $criteria
* @return TDbDataReader record reader.
*/
public function findBySql($criteria)
{
$command = $this->getSqlCommand($criteria);
+ return $this->onExecuteCommand($command, $command->queryRow());
+ }
+
+ /**
+ * Find zero or more matching records for arbituary SQL.
+ * @param TSqlCriteria $criteria
+ * @return TDbDataReader record reader.
+ */
+ public function findAllBySql($criteria)
+ {
+ $command = $this->getSqlCommand($criteria);
return $this->onExecuteCommand($command, $command->query());
}
diff --git a/framework/Data/DataGateway/TTableGateway.php b/framework/Data/DataGateway/TTableGateway.php index f278eed5..e389a98e 100644 --- a/framework/Data/DataGateway/TTableGateway.php +++ b/framework/Data/DataGateway/TTableGateway.php @@ -175,7 +175,7 @@ class TTableGateway extends TComponent * Execute arbituary sql command with binding parameters.
* @param string SQL query string.
* @param array binding parameters, positional or named.
- * @return TDbDataReader query results.
+ * @return array query results.
*/
public function findBySql($sql, $parameters=array())
{
@@ -185,6 +185,19 @@ class TTableGateway extends TComponent }
/**
+ * Execute arbituary sql command with binding parameters.
+ * @param string SQL query string.
+ * @param array binding parameters, positional or named.
+ * @return TDbDataReader query results.
+ */
+ public function findAllBySql($sql, $parameters=array())
+ {
+ $args = func_num_args() > 1 ? array_slice(func_get_args(),1) : null;
+ $criteria = $this->getCriteria($sql,$parameters, $args);
+ return $this->getCommand()->findAllBySql($criteria);
+ }
+
+ /**
* Find one single record that matches the criteria.
*
* Usage:
@@ -314,6 +327,16 @@ class TTableGateway extends TComponent }
/**
+ * Alias for deleteByPk()
+ */
+ public function deleteAllByPks($keys)
+ {
+ if(func_num_args() > 1)
+ $keys = func_get_args();
+ return $this->deleteByPk($keys);
+ }
+
+ /**
* Find the number of records.
* @param string|TSqlCriteria SQL condition or criteria object.
* @param mixed parameter values.
@@ -428,6 +451,8 @@ class TTableGateway extends TComponent $condition = $method[9]==='_' ? substr($method,10) : substr($method,9);
else if($delete = substr(strtolower($method),0,8)==='deleteby')
$condition = $method[8]==='_' ? substr($method,9) : substr($method,8);
+ else if($delete = substr(strtolower($method),0,11)==='deleteallby')
+ $condition = $method[11]==='_' ? substr($method,12) : substr($method,11);
else
return null;
diff --git a/tests/simple_unit/ActiveRecord/FindBySqlTestCase.php b/tests/simple_unit/ActiveRecord/FindBySqlTestCase.php index 953f83e6..7f22afc5 100644 --- a/tests/simple_unit/ActiveRecord/FindBySqlTestCase.php +++ b/tests/simple_unit/ActiveRecord/FindBySqlTestCase.php @@ -1,7 +1,20 @@ -<?php -
+<?php
Prado::using('System.Data.ActiveRecord.TActiveRecord');
require_once(dirname(__FILE__).'/records/DepartmentRecord.php');
+require_once(dirname(__FILE__).'/records/UserRecord.php');
+
+class UserRecord2 extends UserRecord
+{
+ public $another_value;
+}
+
+class SqlTest extends TActiveRecord
+{
+ public $category;
+ public $item;
+
+ const TABLE='items';
+}
class FindBySqlTestCase extends UnitTestCase
{
@@ -16,6 +29,18 @@ class FindBySqlTestCase extends UnitTestCase $deps = DepartmentRecord::finder()->findBySql('SELECT * FROM departments');
$this->assertTrue(count($deps) > 0);
}
+
+ function test_find_by_sql_arb()
+ {
+ $sql = 'SELECT c.name as category, i.name as item
+ FROM items i, categories c
+ WHERE i.category_id = c.category_id LIMIT 2';
+ $items = TActiveRecord::finder('SqlTest')->findBySql($sql);
+
+ $sql = "SELECT users.*, 'hello' as another_value FROM users LIMIT 2";
+ $users = TActiveRecord::finder('UserRecord2')->findBySql($sql);
+ var_dump($users);
+ }
}
?>
\ No newline at end of file diff --git a/tests/simple_unit/ActiveRecord/ForeignObjectUpdateTest.php b/tests/simple_unit/ActiveRecord/ForeignObjectUpdateTest.php index 77b9cdf3..ad64e4b6 100644 --- a/tests/simple_unit/ActiveRecord/ForeignObjectUpdateTest.php +++ b/tests/simple_unit/ActiveRecord/ForeignObjectUpdateTest.php @@ -47,7 +47,7 @@ class PlayerRecord extends BaseFkRecord public $team_name;
public $team;
- public $skills=array();
+ private $_skills;
public $profile;
protected static $RELATIONS=array
@@ -61,6 +61,26 @@ class PlayerRecord extends BaseFkRecord {
return parent::finder($className);
}
+
+ public function getSkills()
+ {
+ if($this->_skills===null && $this->player_id !==null)
+ {
+ //lazy load the skill records
+ $this->setSkills($this->withSkills()->findByPk($this->player_id)->skills);
+ }
+ else if($this->_skills===null)
+ {
+ //create new TList;
+ $this->setSkills(new TList());
+ }
+ return $this->_skills;
+ }
+
+ public function setSkills($value)
+ {
+ $this->_skills = $value instanceof TList ? $value : new TList($value);
+ }
}
class ProfileRecord extends BaseFkRecord
@@ -99,6 +119,8 @@ class SkillRecord extends BaseFkRecord {
return parent::finder($className);
}
+
+
}
class ForeignObjectUpdateTest extends UnitTestCase
@@ -205,6 +227,14 @@ class ForeignObjectUpdateTest extends UnitTestCase $this->assertEqual($player3->skills[0]->name, 'Bash');
$this->assertEqual($player3->skills[1]->name, 'Push');
$this->assertEqual($player3->skills[2]->name, 'Skip');
+
+ //test lazy load
+ $player4 = PlayerRecord::finder()->findByAge(37);
+ $this->assertEqual(count($player4->skills), 3);
+
+ $this->assertEqual($player4->skills[0]->name, 'Bash');
+ $this->assertEqual($player4->skills[1]->name, 'Skip');
+ $this->assertEqual($player4->skills[2]->name, 'Push');
}
}
diff --git a/tests/simple_unit/DbCommon/SqliteColumnTest.php b/tests/simple_unit/DbCommon/SqliteColumnTest.php index 6567106c..36a4baab 100644 --- a/tests/simple_unit/DbCommon/SqliteColumnTest.php +++ b/tests/simple_unit/DbCommon/SqliteColumnTest.php @@ -1,5 +1,4 @@ -<?php -
+<?php
Prado::using('System.Data.*');
Prado::using('System.Data.Common.Sqlite.TSqliteMetaData');
Prado::using('System.Data.DataGateway.TTableGateway');
@@ -16,14 +15,14 @@ class SqliteColumnTest extends UnitTestCase function test_it()
{
- $table = $this->meta_data()->getTableInfo('foo');
+ //$table = $this->meta_data()->getTableInfo('foo');
//var_dump($table);
}
function test_table()
{
$conn = new TDbConnection('sqlite:c:/test.db');
- $table = new TTableGateway('Accounts', $conn);
+ //$table = new TTableGateway('Accounts', $conn);
// var_dump($table->findAll()->readAll());
}
} diff --git a/tests/simple_unit/TableGateway/TableGatewayPgsqlTest.php b/tests/simple_unit/TableGateway/TableGatewayPgsqlTest.php index 973e8d21..4d1077f7 100644 --- a/tests/simple_unit/TableGateway/TableGatewayPgsqlTest.php +++ b/tests/simple_unit/TableGateway/TableGatewayPgsqlTest.php @@ -48,7 +48,7 @@ class TableGatewayPgsqlTest extends BaseGatewayTest $results = $this->getGateway()->findAll('true')->readAll();
$this->assertEqual(count($results), 2);
- $result = $this->getGateway()->findBySql('SELECT username FROM address WHERE phone = ?', '45233')->read();
+ $result = $this->getGateway()->findAllBySql('SELECT username FROM address WHERE phone = ?', '45233')->read();
$this->assertEqual($result['username'], 'record2');
}
|