Merge pull request #4966 from tractorcow/pulls/3.2/fix-docs

BUG Revert lost documentation
This commit is contained in:
Ingo Schommer 2016-01-22 13:08:51 +13:00
commit 88f8acff5a
2 changed files with 248 additions and 38 deletions

View File

@ -59,6 +59,48 @@ The relationship can also be navigated in [templates](../templates).
<% end_if %> <% end_if %>
<% end_with %> <% end_with %>
## Polymorphic has_one
A has_one can also be polymorphic, which allows any type of object to be associated.
This is useful where there could be many use cases for a particular data structure.
An additional column is created called "`<relationship-name>`Class", which along
with the ID column identifies the object.
To specify that a has_one relation is polymorphic set the type to 'DataObject'.
Ideally, the associated has_many (or belongs_to) should be specified with dot notation.
::php
class Player extends DataObject {
private static $has_many = array(
"Fans" => "Fan.FanOf"
);
}
class Team extends DataObject {
private static $has_many = array(
"Fans" => "Fan.FanOf"
);
}
// Type of object returned by $fan->FanOf() will vary
class Fan extends DataObject {
// Generates columns FanOfID and FanOfClass
private static $has_one = array(
"FanOf" => "DataObject"
);
}
<div class="warning" markdown='1'>
Note: The use of polymorphic relationships can affect query performance, especially
on joins, and also increases the complexity of the database and necessary user code.
They should be used sparingly, and only where additional complexity would otherwise
be necessary. E.g. Additional parent classes for each respective relationship, or
duplication of code.
</div>
## has_many ## has_many
Defines 1-to-many joins. As you can see from the previous example, `$has_many` goes hand in hand with `$has_one`. Defines 1-to-many joins. As you can see from the previous example, `$has_many` goes hand in hand with `$has_one`.

View File

@ -1,13 +1,22 @@
title: SQLQuery title: SQL Queries
summary: Write and modify direct database queries through SQLQuery. summary: Write and modify direct database queries through SQLExpression subclasses.
# SQLQuery # SQLSelect
A [api:SQLQuery] object represents a SQL query, which can be serialized into a SQL statement. Dealing with low-level ## Introduction
SQL such as `mysql_query()` is not encouraged, since the ORM provides powerful abstraction API's.
For example, if you want to run a simple `COUNT` SQL statement, the following three statements are functionally An object representing a SQL select query, which can be serialized into a SQL statement.
equivalent: It is easier to deal with object-wrappers than string-parsing a raw SQL-query.
This object is used by the SilverStripe ORM internally.
Dealing with low-level SQL is not encouraged, since the ORM provides
powerful abstraction APIs (see [datamodel](/developer_guides/data_model_and_orm).
Starting with SilverStripe 3, records in collections are lazy loaded,
and these collections have the ability to run efficient SQL
such as counts or returning a single column.
For example, if you want to run a simple `COUNT` SQL statement,
the following three statements are functionally equivalent:
:::php :::php
// Through raw SQL. // Through raw SQL.
@ -20,95 +29,254 @@ equivalent:
// Through the ORM. // Through the ORM.
$count = Member::get()->count(); $count = Member::get()->count();
If you do use raw SQL, you'll run the risk of breaking
various assumptions the ORM and code based on it have:
<div class="info"> * Custom getters/setters (object property can differ from database column)
The SQLQuery object is used by the SilverStripe ORM internally. By understanding SQLQuery, you can modify the SQL that * DataObject hooks like onBeforeWrite() and onBeforeDelete()
the ORM creates. * Automatic casting
* Default values set through objects
* Database abstraction
We'll explain some ways to use *SELECT* with the full power of SQL,
but still maintain a connection to the ORM where possible.
<div class="warning" markdown="1">
Please read our [security topic](/developer_guides/security) to find out
how to properly prepare user input and variables for use in queries
</div> </div>
## Usage ## Usage
### Select ### SELECT
Selection can be done by creating an instance of `SQLSelect`, which allows
management of all elements of a SQL SELECT query, including columns, joined tables,
conditional filters, grouping, limiting, and sorting.
E.g.
:::php :::php
$sqlQuery = new SQLQuery(); <?php
$sqlQuery = new SQLSelect();
$sqlQuery->setFrom('Player'); $sqlQuery->setFrom('Player');
$sqlQuery->selectField('FieldName', 'Name'); $sqlQuery->selectField('FieldName', 'Name');
$sqlQuery->selectField('YEAR("Birthday")', 'Birthyear'); $sqlQuery->selectField('YEAR("Birthday")', 'Birthyear');
$sqlQuery->addLeftJoin('Team','"Player"."TeamID" = "Team"."ID"'); $sqlQuery->addLeftJoin('Team','"Player"."TeamID" = "Team"."ID"');
$sqlQuery->addWhere('YEAR("Birthday") = 1982'); $sqlQuery->addWhere(array('YEAR("Birthday") = ?' => 1982));
// $sqlQuery->setOrderBy(...); // $sqlQuery->setOrderBy(...);
// $sqlQuery->setGroupBy(...); // $sqlQuery->setGroupBy(...);
// $sqlQuery->setHaving(...); // $sqlQuery->setHaving(...);
// $sqlQuery->setLimit(...); // $sqlQuery->setLimit(...);
// $sqlQuery->setDistinct(true); // $sqlQuery->setDistinct(true);
// Get the raw SQL (optional) // Get the raw SQL (optional) and parameters
$rawSQL = $sqlQuery->sql(); $rawSQL = $sqlQuery->sql($parameters);
// Execute and return a Query object // Execute and return a Query object
$result = $sqlQuery->execute(); $result = $sqlQuery->execute();
// Iterate over results // Iterate over results
foreach($result as $row) { foreach($result as $row) {
echo $row['BirthYear']; echo $row['BirthYear'];
} }
The `$result` is an array lightly wrapped in a database-specific subclass of `[api:Query]`. This class implements the The result of `SQLSelect::execute()` is an array lightly wrapped in a database-specific subclass of `[api:SS_Query]`.
*Iterator*-interface, and provides convenience-methods for accessing the data. This class implements the *Iterator*-interface, and provides convenience-methods for accessing the data.
### Delete ### DELETE
Deletion can be done either by calling `DB::query`/`DB::prepared_query` directly,
by creating a `SQLDelete` object, or by transforming a `SQLQuery` into a `SQLDelete`
object instead.
For example, creating a `SQLDelete` object
:::php :::php
$sqlQuery->setDelete(true); <?php
### Insert / Update $query = SQLDelete::create()
->setFrom('"SiteTree"')
->setWhere(array('"SiteTree"."ShowInMenus"' => 0));
$query->execute();
<div class="alert" markdown="1"> Alternatively, turning an existing `SQLQuery` into a delete
Currently not supported through the `SQLQuery` class, please use raw `DB::query()` calls instead.
</div>
:::php :::php
DB::query('UPDATE "Player" SET "Status"=\'Active\''); <?php
### Joins $query = SQLQuery::create()
->setFrom('"SiteTree"')
->setWhere(array('"SiteTree"."ShowInMenus"' => 0))
->toDelete();
$query->execute();
Directly querying the database
:::php
<?php
DB::prepared_query('DELETE FROM "SiteTree" WHERE "SiteTree"."ShowInMenus" = ?', array(0));
### INSERT/UPDATE
INSERT and UPDATE can be performed using the `SQLInsert` and `SQLUpdate` classes.
These both have similar aspects in that they can modify content in
the database, but each are different in the way in which they behave.
Previously, similar operations could be performed by using the `DB::manipulate`
function which would build the INSERT and UPDATE queries on the fly. This method
still exists, but internally uses `SQLUpdate` / `SQLInsert`, although the actual
query construction is now done by the `DBQueryBuilder` object.
Each of these classes implements the interface `SQLWriteExpression`, noting that each
accepts write key/value pairs in a number of similar ways. These include the following
api methods:
* `addAssignments` - Takes a list of assignments as an associative array of key -> value pairs,
but also supports SQL expressions as values if necessary.
* `setAssignments` - Replaces all existing assignments with the specified list
* `getAssignments` - Returns all currently given assignments, as an associative array
in the format `array('Column' => array('SQL' => array('parameters)))`
* `assign` - Singular form of addAssignments, but only assigns a single column value.
* `assignSQL` - Assigns a column the value of a specified SQL expression without parameters
`assignSQL('Column', 'SQL)` is shorthand for `assign('Column', array('SQL' => array()))`
SQLUpdate also includes the following api methods:
* `clear` - Clears all assignments
* `getTable` - Gets the table to update
* `setTable` - Sets the table to update. This should be ANSI quoted.
E.g. `$query->setTable('"SiteTree"');`
SQLInsert also includes the following api methods:
* `clear` - Clears all rows
* `clearRow` - Clears all assignments on the current row
* `addRow` - Adds another row of assignments, and sets the current row to the new row
* `addRows` - Adds a number of arrays, each representing a list of assignment rows,
and sets the current row to the last one.
* `getColumns` - Gets the names of all distinct columns assigned
* `getInto` - Gets the table to insert into
* `setInto` - Sets the table to insert into. This should be ANSI quoted.
E.g. `$query->setInto('"SiteTree"');`
E.g.
:::php
<?php
$update = SQLUpdate::create('"SiteTree"')->where(array('ID' => 3));
// assigning a list of items
$update->addAssignments(array(
'"Title"' => 'Our Products',
'"MenuTitle"' => 'Products'
));
// Assigning a single value
$update->assign('"MenuTitle"', 'Products');
// Assigning a value using parameterised expression
$title = 'Products';
$update->assign('"MenuTitle"', array(
'CASE WHEN LENGTH("MenuTitle") > LENGTH(?) THEN "MenuTitle" ELSE ? END' =>
array($title, $title)
));
// Assigning a value using a pure SQL expression
$update->assignSQL('"Date"', 'NOW()');
// Perform the update
$update->execute();
In addition to assigning values, the SQLInsert object also supports multi-row
inserts. For database connectors and API that don't have multi-row insert support
these are translated internally as multiple single row inserts.
For example,
:::php
<?php
$insert = SQLInsert::create('"SiteTree"');
// Add multiple rows in a single call. Note that column names do not need
// to be symmetric
$insert->addRows(array(
array('"Title"' => 'Home', '"Content"' => '<p>This is our home page</p>'),
array('"Title"' => 'About Us', '"ClassName"' => 'AboutPage')
));
// Adjust an assignment on the last row
$insert->assign('"Content"', '<p>This is about us</p>');
// Add another row
$insert->addRow(array('"Title"' => 'Contact Us'));
$columns = $insert->getColumns();
// $columns will be array('"Title"', '"Content"', '"ClassName"');
$insert->execute();
### Value Checks
Raw SQL is handy for performance-optimized calls,
e.g. when you want a single column rather than a full-blown object representation.
Example: Get the count from a relationship.
:::php :::php
$sqlQuery = new SQLQuery(); $sqlQuery = new SQLQuery();
$sqlQuery->setFrom('Player'); $sqlQuery->setFrom('Player');
$sqlQuery->addSelect('COUNT("Player"."ID")'); $sqlQuery->addSelect('COUNT("Player"."ID")');
$sqlQuery->addWhere('"Team"."ID" = 99'); $sqlQuery->addWhere(array('"Team"."ID"' => 99));
$sqlQuery->addLeftJoin('Team', '"Team"."ID" = "Player"."TeamID"'); $sqlQuery->addLeftJoin('Team', '"Team"."ID" = "Player"."TeamID"');
$count = $sqlQuery->execute()->value(); $count = $sqlQuery->execute()->value();
Note that in the ORM, this call would be executed in an efficient manner as well:
:::php
$count = $myTeam->Players()->count();
### Mapping ### Mapping
Creates a map based on the first two columns of the query result. Creates a map based on the first two columns of the query result.
This can be useful for creating dropdowns.
Example: Show player names with their birth year, but set their birth dates as values.
:::php :::php
$sqlQuery = new SQLQuery(); $sqlQuery = new SQLSelect();
$sqlQuery->setFrom('Player'); $sqlQuery->setFrom('Player');
$sqlQuery->setSelect('ID'); $sqlQuery->setSelect('Birthdate');
$sqlQuery->selectField('CONCAT("Name", ' - ', YEAR("Birthdate")', 'NameWithBirthyear'); $sqlQuery->selectField('CONCAT("Name", ' - ', YEAR("Birthdate")', 'NameWithBirthyear');
$map = $sqlQuery->execute()->map(); $map = $sqlQuery->execute()->map();
$field = new DropdownField('Birthdates', 'Birthdates', $map);
echo $map; Note that going through SQLSelect is just necessary here
because of the custom SQL value transformation (`YEAR()`).
An alternative approach would be a custom getter in the object definition.
// returns array( :::php
// 1 => "Foo - 1920", class Player extends DataObject {
// 2 => "Bar - 1936" private static $db = array(
// ); 'Name' => 'Varchar',
'Birthdate' => 'Date'
);
function getNameWithBirthyear() {
return date('y', $this->Birthdate);
}
}
$players = Player::get();
$map = $players->map('Name', 'NameWithBirthyear');
## Related Documentation ## Related
* [Introduction to the Data Model and ORM](data_model_and_orm) * [Introduction to the Data Model and ORM](data_model_and_orm)
## API Documentation ## API Documentation
* [api:DataObject] * [api:DataObject]
* [api:SQLQuery] * [api:SQLSelect]
* [api:DB] * [api:DB]
* [api:Query] * [api:Query]
* [api:Database] * [api:Database]