1
0
mirror of synced 2024-12-05 03:06:05 +03:00

Clean up, initial entry of root txt files, fixed a few broken unit tests. New documentation.

This commit is contained in:
Jonathan.Wage 2007-11-01 19:45:36 +00:00
parent 146098c3d6
commit 8bfbd6a7c7
20 changed files with 513 additions and 231 deletions

10
CHANGELOG Normal file
View File

@ -0,0 +1,10 @@
Beta 2
------
* exportSchema() replaced by createTablesFromModels()
* exportSql() replaced by generateSqlFromModels()
* importSchema() replaced by generateModelsFromDb()
* loadAll() replaced by loadAllRuntimeClasses()
Beta 1
------

29
COPYRIGHT Normal file
View File

@ -0,0 +1,29 @@
Copyrights
----------
Doctrine
--------
Doctrine is a Object Relational Mapper built from scratch with PHP5. It contains a few ports of other popular PHP classes/libraries.
Url: http://www.phpdoctrine.net
Copyright: 2005-2007 Konsta Vesterinen
License: GPL - see LICENSE file
symfony
-------
Doctrine contains ports of a few symfony classes/libraries
Url: http://www.symfony-project.com/
Copyright: Fabien Potencier
License: MIT - see LICENSE file
Spyc
----
Doctrine contains a port of the Spyc software
Url: http://spyc.sourceforge.net/
Copyright: 2005-2006 Chris Wanstrath
License: MIT - http://www.opensource.org/licenses/mit-license.php

7
LICENSE Normal file
View File

@ -0,0 +1,7 @@
Copyright (c) 2005-2007 Konsta Vesterinen
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

0
README Normal file
View File

View File

@ -485,69 +485,6 @@ final class Doctrine
return self::$_path;
}
/**
* loadAll
* loads all runtime classes
*
* @return void
*/
public static function loadAll()
{
return self::loadAllRuntimeClasses();
}
/**
* importSchema
* method for importing existing schema to Doctrine_Record classes
*
* @param string $directory Directory to write your models to
* @param array $databases Array of databases to generate models for
* @return boolean
*/
public static function importSchema($directory, array $databases = array())
{
return self::generateModelsFromDb($directory, $databases);
}
/**
* exportSchema
* method for exporting Doctrine_Record classes to a schema
*
* @param string $directory Directory containing your models
* @return void
*/
public static function exportSchema($directory = null)
{
return self::createTablesFromModels($directory);
}
/**
* exportSql
* method for exporting Doctrine_Record classes to a schema
*
* @param string $directory
*/
public static function exportSql($directory = null)
{
return self::generateSqlFromModels($directory);
}
/**
* loadAllRuntimeClasses
*
* loads all runtime classes
*
* @return void
*/
public static function loadAllRuntimeClasses()
{
$classes = Doctrine_Compiler::getRuntimeClasses();
foreach ($classes as $class) {
self::autoload($class);
}
}
/**
* loadModels
*
@ -592,6 +529,7 @@ final class Doctrine
{
if ($classes === null) {
$classes = get_declared_classes();
$classes = array_merge($classes, array_keys(self::$_loadedModels));
}
$parent = new ReflectionClass('Doctrine_Record');
@ -693,7 +631,7 @@ final class Doctrine
public static function generateModelsFromYaml($yamlPath, $directory, $options = array())
{
$import = new Doctrine_Import_Schema();
$import->setOption('generateBaseClasses', true);
$import->setOptions($options);
return $import->importSchema($yamlPath, 'yml', $directory);
}
@ -860,26 +798,6 @@ final class Doctrine
return $data->importData($yamlPath, 'yml');
}
/**
* loadDummyData
*
* Populdate your models with dummy data
*
* @param string $append Whether or not to append the data
* @param string $num Number of records to populate
* @return void
*/
public static function loadDummyData($append, $num = 5)
{
$data = new Doctrine_Data();
if ( ! $append) {
$data->purge();
}
return $data->importDummyData($num);
}
/**
* migrate
*
@ -951,18 +869,6 @@ final class Doctrine
return Doctrine_Manager::table($tableName);
}
/**
* connection
*
* @param string $adapter
* @param string $name
* @return void
*/
public static function connection($adapter, $name = null)
{
return Doctrine_Manager::connection($adapter, $name);
}
/**
* fileFinder
*
@ -982,7 +888,7 @@ final class Doctrine
* cases dozens of files) can improve performance by an order of magnitude
*
* @param string $target
*
* @param array $includedDrivers
* @throws Doctrine_Exception
* @return void
*/

View File

@ -413,4 +413,4 @@ class Doctrine_Export_Sqlite extends Doctrine_Export
return 'ALTER TABLE ' . $name . ' ' . $query;
}
}
}

View File

@ -1,6 +1,6 @@
+ Getting started
+ Sandbox
+ Command Line Interface
+ Facade
+ Connection management
+ Basic schema mapping
+ Relations

View File

@ -213,10 +213,225 @@ class AuthTemplate extends Doctrine_Template
}
</code>
++ Working with multiple templates
Each class can consists of multiple templates. If the templates contain similar definitions the most recently loaded template always overrides the former.
++ Core Templates
Doctrine comes bundled with some templates that offer out of the box functionality for your models. You can enable these templates in your models very easily. You can do it directly in your Doctrine_Records or you can specify them in your yaml schema if you are managing your models with a yaml schema file.
+++ Versionable
PHP Example
<code type="php">
class User extends Doctrine_Record
{
public function setTableDefinition()
{
$this->hasColumn('username', 'string', 125);
$this->hasColumn('password', 'string', 255);
}
public function setUp()
{
$this->actAs('Versionable', array('versionColumn' => 'version', 'className' => '%CLASS%Version'));
}
}
</code>
YAML Example
<code type="yaml">
---
User:
actAs:
Versionable:
versionColumn: version
className: %CLASS%Version
columns:
username:
type: string(125)
password:
type: string(255)
</code>
+++ Timestampable
The 2nd argument array is not required. It defaults to all the values that are present in the example below.
PHP Example
<code type="php">
class User extends Doctrine_Record
{
public function setTableDefinition()
{
$this->hasColumn('username', 'string', 125);
$this->hasColumn('password', 'string', 255);
}
public function setUp()
{
$this->actAs('Timestampable', array('created' => array('name' => 'created_at',
'type' => 'timestamp',
'format' => 'Y-m-d H:i:s',
'options' => array()),
'updated' => array('name' => 'updated_at',
'type' => 'timestamp',
'format' => 'Y-m-d H:i:s',
'options' => array())));
}
}
</code>
YAML Example
<code type="yaml">
---
User:
actAs:
Timestampable:
created:
name: created_at
type: timestamp
format:Y-m-d H:i:s
options: []
updated:
name: updated_at
type: timestamp
format: Y-m-d H:i:s
options: []
columns:
username:
type: string(125)
password:
type: string(255)
</code>
+++ Sluggable
If you do not specify the columns to create the slug from, it will default to just using the toString() method on the model.
PHP Example
<code type="php">
class User extends Doctrine_Record
{
public function setTableDefinition()
{
$this->hasColumn('username', 'string', 125);
$this->hasColumn('password', 'string', 255);
}
public function setUp()
{
$this->actAs('Sluggable', array('columns' => array('username')));
}
}
</code>
YAML Example
<code type="yaml">
---
User:
actAs:
Sluggable:
columns: [username]
columns:
username:
type: string(125)
password:
type: string(255)
</code>
+++ I18n
PHP Example
<code type="php">
class User extends Doctrine_Record
{
public function setTableDefinition()
{
$this->hasColumn('username', 'string', 125);
$this->hasColumn('password', 'string', 255);
}
public function setUp()
{
$this->actAs('I18n', array('fields' => array('title')));
}
}
</code>
YAML Example
<code type="yaml">
---
User:
actAs:
I18n:
fields: [title]
columns:
username:
type: string(125)
password:
type: string(255)
</code>
+++ NestedSet
PHP Example
<code type="php">
class User extends Doctrine_Record
{
public function setTableDefinition()
{
$this->hasColumn('username', 'string', 125);
$this->hasColumn('password', 'string', 255);
}
public function setUp()
{
$this->actAs('NestedSet', array('hasManyRoots' => true, 'rootColumnName' => 'root_id'));
}
}
</code>
YAML Example
<code type="yaml">
---
User:
actAs:
NestedSet:
hasManyRoots: true
rootColumnName: root_id
columns:
username:
type: string(125)
password:
type: string(255)
</code>
+++ Searchable
PHP Example
<code type="php">
class User extends Doctrine_Record
{
public function setTableDefinition()
{
$this->hasColumn('username', 'string', 125);
$this->hasColumn('password', 'string', 255);
}
public function setUp()
{
$this->actAs('Searchable', array('fields' => array('title', 'content')));
}
}
</code>
YAML Example
<code type="yaml">
---
User:
actAs:
Searchable:
fields: [title, content]
columns:
username:
type: string(125)
password:
type: string(255)
</code>

View File

@ -1,87 +0,0 @@
++ Introduction
The Doctrine Cli is a collection of tasks that help you with your day to do development and testing with your Doctrine implementation. Typically with the examples in this manual, you setup php scripts to perform whatever tasks you may need. This Cli tool is aimed at providing an out of the box solution for those tasks.
++ Tasks
Below is a list of available tasks for managing your Doctrine implementation.
<code>
./cli build-all
./cli build-all-load
./cli build-all-reload
./cli compile
./cli create-db
./cli create-tables
./cli dql
./cli drop-db
./cli dump-data
./cli generate-migration
./cli generate-migrations-from-db
./cli generate-migrations-from-models
./cli generate-models-from-db
./cli generate-models-from-yaml
./cli generate-sql
./cli generate-yaml-from-db
./cli generate-yaml-from-models
./cli load-data
./cli load-dummy-data
./cli migrate
./cli rebuild-db
</code>
The tasks for the CLI are separate from the CLI and can be used standalone. Below is an example.
<code type="php">
$task = new Doctrine_Task_GenerateModelsFromYaml();
$args = array('yaml_schema_path' => '/path/to/schema',
'models_path' => '/path/to/models');
$task->setArguments($args);
try {
if ($task->validate()) {
$task->execute();
}
} catch (Exception $e) {
throw new Doctrine_Cli_Exception($e->getMessage());
}
</code>
++ Usage
File named "cli" that is set to executable
<code>
#!/usr/bin/env php
<?php
chdir(dirname(__FILE__));
include('cli.php');
</code>
Actual php file named "cli.php" that implements the Doctrine_Cli.
<code type="php">
// Include your Doctrine configuration/setup here, your connections, models, etc.
// Configure Doctrine Cli
// Normally these are arguments to the cli tasks but if they are set here the arguments will be auto-filled and are not required for you to enter them.
$config = array('data_fixtures_path' => '/path/to/data/fixtures',
'models_path' => '/path/to/models',
'migrations_path' => '/path/to/migrations',
'sql_path' => '/path/to/data/sql',
'yaml_schema_path' => '/path/to/schema');
$cli = new Doctrine_Cli($config);
$cli->run($_SERVER['argv']);
</code>
Now you can begin executing commands.
<code>
./cli generate-models-from-yaml
./cli create-tables
</code>

View File

@ -14,6 +14,7 @@
++ LIMIT and OFFSET clauses
++ Examples
++ The Query Registry
Doctrine_Query_Registry is a class for registering and naming queries. It helps with the organization of your applications queries and along with that it offers some very nice convenience stuff.
The queries are added using the add() method of the registry object. It takes two parameters, the query name and the actual DQL query.
@ -44,3 +45,27 @@ $users = $user->find('all');
</code>
++ BNF
++ Magic Finders
Doctrine offers some magic finders for your Doctrine models that allow you to find a record by any column that is present in the model. This is helpful for simply finding a user by their username, or finding a group by the name of it. Normally this would require writing a Doctrine_Query instance and storing this somewhere so it can be reused. That is no longer needed for simple situations like that.
The basic pattern for the finder methods are as follows: findBy%s($value) or findOneBy%s($value). The %s can be a column name or a relation alias. If you give a column name you must give the value you are looking for. If you specify a relationship alias, you can either pass an instance of the relation class to find, or give the actual primary key value.
Examples:
<code type="php">
// The normal find by primary key method
$userTable = Doctrine::getTable('User');
$user = $userTable->find(1);
// Find one user by the username
$userTable = Doctrine::getTable('User');
$user = $userTable->findOneByUsername('jonwage');
// Find phonenumbers for the user above
$phoneTable = Doctrine::getTable('Phonenumber');
$phonenumbers = $phoneTable->findByUser($user);
</code>

210
manual/docs/en/facade.txt Normal file
View File

@ -0,0 +1,210 @@
++ Convenience Methods
Doctrine offers static convenience methods available in the main Doctrine class. These methods perform some of the most used functionality of Doctrine with one method. Most of these methods are using in the Doctrine_Task system. These tasks are also what are executed from the Doctrine_Cli.
<code type="php">
// Turn debug on/off and check for whether it is on/off
Doctrine::debug(true);
if (Doctrine::debug()) {
echo 'debugging is on';
} else {
echo 'debugging is off';
}
// Get the path to your Doctrine libraries
$path = Doctrine::getPath();
// Load your models so that they are present and loaded for Doctrine to work with
// Returns an array of the Doctrine_Records that were found and loaded
$models = Doctrine::loadModels('/path/to/models');
print_r($models);
// Get array of all the models loaded and present to Doctrine
$models = Doctrine::getLoadedModels();
// Pass an array of classes to the above method and it will filter out the ones that are not Doctrine_Records
$models = Doctrine::getLoadedModels(array('User', 'Formatter', 'Doctrine_Record'));
print_r($models); // would return array('User') because Formatter and Doctrine_Record are not Doctrine_Records
// Get Doctrine_Connection object for an actual table name
$conn = Doctrine::getConnectionByTableName('user'); // returns the connection object that the table name is associated with
// Generate your models from an existing database
Doctrine::generateModelsFromDb('/path/to/generate/models');
// Generate YAML schema from an existing database
Doctrine::generateYamlFromDb('/path/to/dump/schema.yml');
// Generate your models from YAML schema
Doctrine::generateModelsFromYaml('/path/to/schema.yml', '/path/to/generate/models');
// Create all your tables from an existing set of models
Doctrine::createTablesFromModels('/path/to/models');
// Generate string of sql commands from an existing set of models
Doctrine::generateSqlFromModels('/path/to/models');
// Generate YAML schema from an existing set of models
Doctrine::generateYamlFromModels('/path/to/schema.yml', '/path/to/models');
// It is required your connection name to be the same as your database name in order for the drop/create functionality below to work.
// Create all databases for connections.
Doctrine::createDatabases();
// Drop all databases for connections
Doctrine::dropDatabases();
// Dump all data for your models to a yaml fixtures file
// 2nd argument is a bool value for whether or not to generate individual fixture files for each model. If true you need to specify a folder instead of a file.
Doctrine::dumpData('/path/to/dump/data.yml', true);
// Load data from yaml fixtures files
// 2nd argument is a bool value for whether or not to append the data when loading or delete all data first before loading
Doctrine::loadData('/path/to/fixture/files', true);
// Run a migration process for a set of migration classes
$num = 5; // migrate to version #5
Doctrine::migration('/path/to/migrations', $num);
// Generate a blank migration class template
Doctrine::generateMigrationClass('ClassName', '/path/to/migrations');
// Generate all migration classes for an existing database
Doctrine::generateMigrationsFromDb('/path/to/migrations');
// Generate all migration classes for an existing set of models
// 2nd argument is optional if you have already loaded your models using loadModels()
Doctrine::generateMigrationsFromModels('/path/to/migrations', '/path/to/models');
// Get Doctrine_Table instance for a model
$userTable = Doctrine::getTable('User');
// Compile doctrine in to a single php file
$drivers = array('mysql'); // specify the array of drivers you want to include in this compiled version
Doctrine::compile('/path/to/write/compiled/doctrine', $drivers);
// Dump doctrine objects for debugging
$conn = Doctrine_Manager::connection();
Doctrine::dump($conn);
</code>
++ Tasks
Tasks are classes which bundle some of the core convenience methods in to tasks that can be easily executed by setting the required arguments. These tasks are directly used in the Doctrine command line interface.
<code>
BuildAll
BuildAllLoad
BuildAllReload
Compile
CreateDb
CreateTables
Dql
DropDb
DumpData
Exception
GenerateMigration
GenerateMigrationsDb
GenerateMigrationsModels
GenerateModelsDb
GenerateModelsYaml
GenerateSql
GenerateYamlDb
GenerateYamlModels
LoadData
LoadDummyData
Migrate
RebuildDb
</code>
You can read below about how to execute Doctrine Tasks standalone in your own scripts.
++ Command Line Interface
+++ Introduction
The Doctrine Cli is a collection of tasks that help you with your day to do development and testing with your Doctrine implementation. Typically with the examples in this manual, you setup php scripts to perform whatever tasks you may need. This Cli tool is aimed at providing an out of the box solution for those tasks.
+++ Tasks
Below is a list of available tasks for managing your Doctrine implementation.
<code>
./cli build-all
./cli build-all-load
./cli build-all-reload
./cli compile
./cli create-db
./cli create-tables
./cli dql
./cli drop-db
./cli dump-data
./cli generate-migration
./cli generate-migrations-from-db
./cli generate-migrations-from-models
./cli generate-models-from-db
./cli generate-models-from-yaml
./cli generate-sql
./cli generate-yaml-from-db
./cli generate-yaml-from-models
./cli load-data
./cli load-dummy-data
./cli migrate
./cli rebuild-db
</code>
The tasks for the CLI are separate from the CLI and can be used standalone. Below is an example.
<code type="php">
$task = new Doctrine_Task_GenerateModelsFromYaml();
$args = array('yaml_schema_path' => '/path/to/schema',
'models_path' => '/path/to/models');
$task->setArguments($args);
try {
if ($task->validate()) {
$task->execute();
}
} catch (Exception $e) {
throw new Doctrine_Exception($e->getMessage());
}
</code>
+++ Usage
File named "cli" that is set to executable
<code>
#!/usr/bin/env php
<?php
chdir(dirname(__FILE__));
include('cli.php');
</code>
Actual php file named "cli.php" that implements the Doctrine_Cli.
<code type="php">
// Include your Doctrine configuration/setup here, your connections, models, etc.
// Configure Doctrine Cli
// Normally these are arguments to the cli tasks but if they are set here the arguments will be auto-filled and are not required for you to enter them.
$config = array('data_fixtures_path' => '/path/to/data/fixtures',
'models_path' => '/path/to/models',
'migrations_path' => '/path/to/migrations',
'sql_path' => '/path/to/data/sql',
'yaml_schema_path' => '/path/to/schema');
$cli = new Doctrine_Cli($config);
$cli->run($_SERVER['argv']);
</code>
Now you can begin executing commands.
<code>
./cli generate-models-from-yaml
./cli create-tables
</code>

View File

@ -66,7 +66,7 @@ spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();
$conn = $manager->openConnection('pgsql://user:pass@localhost/test');
Doctrine::exportSchema('models');
Doctrine::createTablesFromModels('models');
</code>
This would execute the following queries on mysql.
@ -94,44 +94,12 @@ spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();
$conn = $manager->openConnection('pgsql://user:pass@localhost/test');
$queries = Doctrine::exportSql('models');
$queries = Doctrine::generateSqlFromModels('models');
print_r($queries);
echo $queries;
</code>
Note that the methods Doctrine::exportSchema() and Doctrine::exportSql() are just short cuts for Doctrine_Export::exportSchema() and Doctrine_Export::exportSql(). So the following code is equivalent with the previous example:
<code type="php">
require_once('path-to-doctrine/lib/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();
$conn = $manager->openConnection('pgsql://user:pass@localhost/test');
$queries = $conn->export->exportSql('models');
print_r($queries);
</code>
+++ Convenience methods
In the previous example we exported all record classes within a directory. Sometimes you may want to export specific classes. It can be achieved by giving exportClasses() an array of class names:
<code type="php">
require_once('path-to-doctrine/lib/Doctrine.php');
spl_autoload_register(array('Doctrine', 'autoload'));
$manager = Doctrine_Manager::getInstance();
$conn = $manager->openConnection('pgsql://user:pass@localhost/test');
$conn->export->exportClasses(array('User', 'Phonenumber'));
</code>
Consider the same situation and you want to get the array of sql queries needed to perform the exporting. It can be achieved with Doctrine_Export::exportClassesSql().
Consider the same situation and you want to get the string of sql queries needed to perform the exporting. It can be achieved with Doctrine::generateSqlFromModels().
+++ Export options
@ -148,4 +116,6 @@ $manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_TABLES ^
// turn off exporting
$manager->setAttribute(Doctrine::ATTR_EXPORT, Doctrine::EXPORT_NONE);
$sql = Doctrine::generateSqlFromModels();
</code>

View File

@ -96,7 +96,7 @@ class Doctrine_Export_Record_TestCase extends Doctrine_UnitTestCase
public function testExportModelFromDirectory()
{
Doctrine::exportSchema(dirname(__FILE__) . DIRECTORY_SEPARATOR .'..' . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'models' . DIRECTORY_SEPARATOR . 'export');
Doctrine::createTablesFromModels(dirname(__FILE__) . DIRECTORY_SEPARATOR .'..' . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'models' . DIRECTORY_SEPARATOR . 'export');
$this->assertEqual($this->adapter->pop(), 'COMMIT');
$this->assertEqual($this->adapter->pop(), 'ALTER TABLE cms__category_languages ADD FOREIGN KEY (category_id) REFERENCES cms__category(id) ON DELETE CASCADE');

View File

@ -40,13 +40,10 @@ class Doctrine_Migration_TestCase extends Doctrine_UnitTestCase
// migrate to version 3
$migration->migrate(2);
// Make sure the column was added
$this->assertTrue(Doctrine_Manager::getInstance()->getTable('User')->hasColumn('field2'));
// now migrate back to original version
$migration->migrate(0);
// Make sure the current version is 0
$this->assertEqual($migration->getCurrentVersion(), 0);
}
}
}

View File

@ -3,11 +3,11 @@ class ChangeColumn extends Doctrine_Migration
{
public function up()
{
$this->changeColumn('migration_test', 'field1', 'integer');
}
public function down()
{
$this->changeColumn('migration_test', 'field1', 'string');
}
}
}