From 1a27a0c907aad2235c4017858800150bc38d7539 Mon Sep 17 00:00:00 2001 From: zYne Date: Fri, 15 Dec 2006 22:32:34 +0000 Subject: [PATCH] added some new docs --- ...nents - Connection - Availible drivers.php | 0 ...tion modules - Export - Altering table.php | 39 ++++++++++ ... modules - Export - Creating new table.php | 22 ++++++ ...nents - Connection - Availible drivers.php | 0 ...Components - Query - HAVING conditions.php | 14 ++++ ...etting attributes - Identifier quoting.php | 50 ++++++++++++ ...ion - Setting attributes - Portability.php | 78 +++++++++++++++++++ ...agement - Connection-component binding.php | 23 ++++++ ...tion modules - Export - Altering table.php | 55 +++++++++++++ 9 files changed, 281 insertions(+) create mode 100644 manual/codes/Basic Components - Connection - Availible drivers.php create mode 100644 manual/codes/Connection modules - Export - Altering table.php create mode 100644 manual/codes/Connection modules - Export - Creating new table.php create mode 100644 manual/docs/Basic Components - Connection - Availible drivers.php create mode 100644 manual/docs/Basic Components - Query - HAVING conditions.php create mode 100644 manual/docs/Configuration - Setting attributes - Identifier quoting.php create mode 100644 manual/docs/Configuration - Setting attributes - Portability.php create mode 100644 manual/docs/Connection management - Connection-component binding.php create mode 100644 manual/docs/Connection modules - Export - Altering table.php diff --git a/manual/codes/Basic Components - Connection - Availible drivers.php b/manual/codes/Basic Components - Connection - Availible drivers.php new file mode 100644 index 000000000..e69de29bb diff --git a/manual/codes/Connection modules - Export - Altering table.php b/manual/codes/Connection modules - Export - Altering table.php new file mode 100644 index 000000000..4533b6661 --- /dev/null +++ b/manual/codes/Connection modules - Export - Altering table.php @@ -0,0 +1,39 @@ + 'userlist', + 'add' => array( + 'quota' => array( + 'type' => 'integer', + 'unsigned' => 1 + ) + ), + 'remove' => array( + 'file_limit' => array(), + 'time_limit' => array() + ), + 'change' => array( + 'name' => array( + 'length' => '20', + 'definition' => array( + 'type' => 'text', + 'length' => 20 + ) + ) + ), + 'rename' => array( + 'sex' => array( + 'name' => 'gender', + 'definition' => array( + 'type' => 'text', + 'length' => 1, + 'default' => 'M' + ) + ) + ) + + ); + +$dbh = new PDO('dsn','username','pw'); +$conn = Doctrine_Manager::getInstance()->openConnection($dbh); + +$conn->export->alterTable('mytable', $a); +?> diff --git a/manual/codes/Connection modules - Export - Creating new table.php b/manual/codes/Connection modules - Export - Creating new table.php new file mode 100644 index 000000000..9632ea4f2 --- /dev/null +++ b/manual/codes/Connection modules - Export - Creating new table.php @@ -0,0 +1,22 @@ +openConnection($dbh); + +$fields = array('id' => array( + 'type' => 'integer', + 'autoincrement' => true), + 'name' => array( + 'type' => 'string', + 'fixed' => true, + 'length' => 8) + ); +// the following option is mysql specific and +// skipped by other drivers +$options = array('type' => 'MYISAM'); + +$conn->export->createTable('mytable', $fields); + +// on mysql this executes query: +// CREATE TABLE mytable (id INT AUTO_INCREMENT PRIMARY KEY, +// name CHAR(8)); +?> diff --git a/manual/docs/Basic Components - Connection - Availible drivers.php b/manual/docs/Basic Components - Connection - Availible drivers.php new file mode 100644 index 000000000..e69de29bb diff --git a/manual/docs/Basic Components - Query - HAVING conditions.php b/manual/docs/Basic Components - Query - HAVING conditions.php new file mode 100644 index 000000000..1fb8206e4 --- /dev/null +++ b/manual/docs/Basic Components - Query - HAVING conditions.php @@ -0,0 +1,14 @@ + +Doctrine_Query provides having() method for adding HAVING conditions to the DQL query. This method is identical in function to the Doctrine_Query::where() method. +

+If you call having() multiple times, the conditions are ANDed together; if you want to OR a condition, use orHaving().

+select('u.name') + ->from('User u') + ->leftJoin('u.Phonenumber p'); + ->having('COUNT(p.id) > 3'); +?>"); +?> diff --git a/manual/docs/Configuration - Setting attributes - Identifier quoting.php b/manual/docs/Configuration - Setting attributes - Identifier quoting.php new file mode 100644 index 000000000..8f1eb1ae4 --- /dev/null +++ b/manual/docs/Configuration - Setting attributes - Identifier quoting.php @@ -0,0 +1,50 @@ + +You can quote the db identifiers (table and field names) with quoteIdentifier(). The delimiting style depends on which database driver is being used. NOTE: just because you CAN use delimited identifiers, it doesn't mean you SHOULD use them. In general, they end up causing way more problems than they solve. Anyway, it may be necessary when you have a reserved word as a field name (in this case, we suggest you to change it, if you can). + +Some of the internal Doctrine methods generate queries. Enabling the "quote_identifier" attribute of Doctrine you can tell Doctrine to quote the identifiers in these generated queries. For all user supplied queries this option is irrelevant. + +Portability is broken by using the following characters inside delimited identifiers: +

+ + + +Delimited identifiers are known to generally work correctly under the following drivers: +
+ + + +When using the quoteIdentifiers option, all of the field identifiers will be automatically quoted in the resulting SQL statements: +

+setAttribute('quote_identifiers', true); +?>"); +?> +

+ + +will result in a SQL statement that all the field names are quoted with the backtick '`' operator (in MySQL). +
+
SELECT * FROM `sometable` WHERE `id` = '123'
+
+as opposed to: +
+
SELECT * FROM sometable WHERE id='123'
diff --git a/manual/docs/Configuration - Setting attributes - Portability.php b/manual/docs/Configuration - Setting attributes - Portability.php new file mode 100644 index 000000000..75e7976f9 --- /dev/null +++ b/manual/docs/Configuration - Setting attributes - Portability.php @@ -0,0 +1,78 @@ + +Each database management system (DBMS) has it's own behaviors. For example, some databases capitalize field names in their output, some lowercase them, while others leave them alone. These quirks make it difficult to port your scripts over to another server type. PEAR Doctrine:: strives to overcome these differences so your program can switch between DBMS's without any changes. + +You control which portability modes are enabled by using the portability configuration option. Configuration options are set via factory() and setOption(). + +The portability modes are bitwised, so they can be combined using | and removed using ^. See the examples section below on how to do this. +

+Portability Mode Constants +

+ +Doctrine::PORTABILITY_ALL (default) +

+turn on all portability features. this is the default setting. +

+Doctrine::PORTABILITY_DELETE_COUNT +

+Force reporting the number of rows deleted. Some DBMS's don't count the number of rows deleted when performing simple DELETE FROM tablename queries. This mode tricks such DBMS's into telling the count by adding WHERE 1=1 to the end of DELETE queries. +

+Doctrine::PORTABILITY_EMPTY_TO_NULL +

+Convert empty strings values to null in data in and output. Needed because Oracle considers empty strings to be null, while most other DBMS's know the difference between empty and null. +

+Doctrine::PORTABILITY_ERRORS +

+Makes certain error messages in certain drivers compatible with those from other DBMS's +

+ +Table 33-1. Error Code Re-mappings + +Driver Description Old Constant New Constant +mysql, mysqli unique and primary key constraints Doctrine::ERROR_ALREADY_EXISTS Doctrine::ERROR_CONSTRAINT +mysql, mysqli not-null constraints Doctrine::ERROR_CONSTRAINT Doctrine::ERROR_CONSTRAINT_NOT_NULL + +

+Doctrine::PORTABILITY_FIX_ASSOC_FIELD_NAMES +

+This removes any qualifiers from keys in associative fetches. some RDBMS , like for example SQLite, will be default use the fully qualified name for a column in assoc fetches if it is qualified in a query. +

+Doctrine::PORTABILITY_FIX_CASE +

+Convert names of tables and fields to lower or upper case in all methods. The case depends on the 'field_case' option that may be set to either CASE_LOWER (default) or CASE_UPPER +

+Doctrine::PORTABILITY_NONE +

+Turn off all portability features +

+Doctrine::PORTABILITY_NUMROWS +

+Enable hack that makes numRows() work in Oracle +

+Doctrine::PORTABILITY_RTRIM +

+Right trim the data output for all data fetches. This does not applied in drivers for RDBMS that automatically right trim values of fixed length character values, even if they do not right trim value of variable length character values. +

+ + +Using setAttribute() to enable portability for lowercasing and trimming +

+setAttribute('portability', + Doctrine::PORTABILITY_FIX_CASE | Doctrine::PORTABILITY_RTRIM); + +?>"); +?> + + + +

+Using setAttribute() to enable all portability options except trimming +

+ +setAttribute('portability', + Doctrine::PORTABILITY_ALL ^ Doctrine::PORTABILITY_RTRIM); +?>"); +?> diff --git a/manual/docs/Connection management - Connection-component binding.php b/manual/docs/Connection management - Connection-component binding.php new file mode 100644 index 000000000..fd4fbfdcd --- /dev/null +++ b/manual/docs/Connection management - Connection-component binding.php @@ -0,0 +1,23 @@ + +Doctrine allows you to bind connections to components (= your ActiveRecord classes). This means everytime a component issues a query +or data is being fetched from the table the component is pointing at Doctrine will use the bound connection. +

+openConnection(new PDO('dsn','username','password'), 'connection 1'); + +\$conn2 = \$manager->openConnection(new PDO('dsn2','username2','password2'), 'connection 2'); + +\$manager->bindComponent('User', 'connection 1'); + +\$manager->bindComponent('Group', 'connection 2'); + +\$q = new Doctrine_Query(); + +// Doctrine uses 'connection 1' for fetching here +\$users = \$q->from('User u')->where('u.id IN (1,2,3)')->execute(); + +// Doctrine uses 'connection 2' for fetching here +\$groups = \$q->from('Group g')->where('g.id IN (1,2,3)')->execute(); +?>"); +?> diff --git a/manual/docs/Connection modules - Export - Altering table.php b/manual/docs/Connection modules - Export - Altering table.php new file mode 100644 index 000000000..d79aa70c1 --- /dev/null +++ b/manual/docs/Connection modules - Export - Altering table.php @@ -0,0 +1,55 @@ + +Doctrine_Export drivers provide an easy database portable way of altering existing database tables. +

+NOTE: if you only want to get the generated sql (and not execute it) use Doctrine_Export::alterTableSql() +

+openConnection(\$dbh); + +\$a = array('add' => array('name' => array('type' => 'string', 'length' => 255))); + + +\$conn->export->alterTableSql('mytable', \$a); + +// On mysql this method returns: +// ALTER TABLE mytable ADD COLUMN name VARCHAR(255) +?>"); +?> +

+Doctrine_Export::alterTable() takes two parameters: +

+string $name +
name of the table that is intended to be changed.
+array $changes + + + + +
associative array that contains the details of each type of change that is intended to be performed. +The types of changes that are currently supported are defined as follows: + +The value of each entry of the array should be set to another associative array with the properties of the fields to that are meant to be changed as array entries. These entries should be assigned to the new values of the respective properties. The properties of the fields should be the same as defined by the Doctrine parser. +