Congegni/sintonia
7
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

CC-2166: Packaging Improvements. Moved the Zend app into airtime_mvc. It is now installed to /var/www/airtime. Storage is now set to /srv/airtime/stor. Utils are now installed to /usr/lib/airtime/utils/. Added install/airtime-dircheck.php as a simple test to see if everything is install/uninstalled correctly.

Browse source
This commit is contained in:
Paul Baranowski 2011-04-14 18:55:04 -04:00
parent 514777e8d2
commit b11cbd8159
4546 changed files with 138 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

312
airtime_mvc/library/propel/docs/reference/Buildtime-Configuration.txt Normal file
View file

@ -0,0 +1,312 @@
= Build Properties Reference =
[[PageOutline]]
Here is a list of properties that can be set to affect how Propel builds database files. For a complete list, see the {{{default.properties}}} file that is bundled with your version of Propel generator (this will be in PEAR's data directory if you are using a PEAR-installed version of Propel).
First, some conventions:
* Text surrounded by a '''/''' is text that you would provide and is not defined in the language. (i.e. a table name is a good example of this.)
* Items where you have an alternative choice have a '''|''' character between them (i.e. true|false)
* Alternative choices may be delimited by '''{''' and '''}''' to indicate that this is the default option, if not overridden elsewhere.
== Where to Specify Properties ==
=== In the Project build.properties File ===
The most natural place to specify properties for a file are in the project's {{{build.properties}}} file. This file is expected to be found in the project directory.
=== In a global build.properties file ===
You can also create a {{{global build.properties}}} file in the same directory as Propel's {{{default.properties}}} file. For users who have installed Propel using PEAR, this will be in PEAR data directory structure.
=== On the Command Line ===
You can also specify properties on the commandline when you invoke Propel:
{{{
$ propel-gen /path/to/project -Dpropel.someOtherProperty=value
}}}
''Note that there is '''no space''' between the -D and the property name.''
== The Properties ==
=== General Build Settings ===
{{{
propel.project = Your-Project-Name
}}}
The name of your project. This affects names of generated files, etc.
{{{
propel.targetPackage = {propel.project}
}}}
The package to use for the generated classes. This affects the value of the @package phpdoc tag, and it also affects the directory that the classes are placed in. By default this will be the same as the project. Note that the target package (and thus the target directory for generated classes) can be overridden in each `<database>` and `<table>` element in the XML schema.
{{{
propel.packageObjectModel = true|{false}
}}}
Whether to join schemas using the same database name into a single schema. This allows splitting schemas in packages, and referencing tables in another schema (but in the same database) in a foreign key. Beware that database behaviors will also be joined when this parameter is set to true.
{{{
propel.schema.validate = {true}|false
}}}
Whether to validate the schema using the XSD file. The default XSD file is located under `generator/resources/xsd/database.xsd`, and you can use a custom XSD file by changing the `propel.schema.xsd.file` property.
{{{
propel.schema.transform = true|{false}
}}}
Whether to transform the schema using the XSL file. This was used in previous Propel versions to clean up the schema, but tended to hide problems in the schema. It is disabled by default since Propel 1.5. The default XSL file is located under `generator/resources/xsd/database.xsl`, and you can use a custom XSL file by changing the `propel.schema.xsl.file` property.
=== Database Settings ===
{{{
propel.database = pgsql|mysql|sqlite|mssql|oracle
}}}
The Propel platform that will be used to determine how to build the SQL DDL, etc.
{{{
propel.database.url = /PDO database connection string/
propel.database.user =
propel.database.password =
}}}
Propel will use this information as the default to connect to your database. Note that for PDO some drivers (e.g. mysql, oracle) require that you specify the username and password separately from the DSN, which is why they are available as options.
{{{
propel.database.buildUrl = /PDO database connection string, defaults to use ${propel.database.url}/
}}}
This property is used by Propel to connect to a database to reverse engineer or data dump. The default is to use the database connection defined by the ''propel.database.url'' property.
{{{
propel.database.createUrl = /PDO database connection string, defaults to use ${propel.database.url}/
}}}
This property is used by Propel for creating a database. Of course, Propel is unable to create many databases because they do not provide a SQL method for creation; therefore, it is usually recommended that you actually create your database by hand.
{{{
propel.database.schema = /schema-name/
}}}
Where supported by the RDBMS, you can specify a schema name for Propel to use.
{{{
propel.database.encoding =
}}}
The encoding to use for the database. This can affect things such as transforming charsets when exporting to XML, etc.
{{{
propel.tablePrefix = {empty}|string
}}}
Add a prefix to all the table names in the database. This does not affect the tables phpName. This setting can be overridden on a per-database basis in the schema.
=== Reverse-Engineering Settings ===
{{{
propel.samePhpName = true|{false}
}}}
Whether to specify PHP names that are the same as the column names.
{{{
propel.addVendorInfo = true|{false}
}}}
Whether to add the vendor info. This is currently only used for MySQL, but does provide additional information (such as full-text indexes) which can affect the generation of the DDL from the schema.
{{{
propel.addValidators = {none}|maxvalue|type|required|unique|all
}}}
Which Propel validators to add to the generated schema (based on the db constraints).
=== Customizing Generated Object Model ===
{{{
propel.addGenericAccessors = true|{false}
propel.addGenericMutators = true|{false}
}}}
Whether to add generic getter/setter methods -- e.g. '''getByName()''', '''setByName()'''.
{{{
propel.addTimeStamp = true|{false}
}}}
Whether to add a timestamp to the phpdoc header of generated OM classes.
{{{
propel.addValidateMethod = {true}|false
}}}
Whether to add `validate()` method to your classes. Set to false if you don't use Propel validation.
{{{
propel.addIncludes = {true}|false
}}}
Whether to add `require` statements on the generated stub classes. Set to false if you autoload every classe at runtime.
{{{
propel.addHooks = {true}|false
}}}
Whether to support pre- and post- hooks on `save()` and `delete()` methods. Set to false if you never use these hooks for a small speed boost.
{{{
propel.basePrefix = {Base}|/YourPrefix/
}}}
The prefix to use for the base (super) classes that are generated.
{{{
propel.classPrefix = {empty}|string;
}}}
Some sort of "namespacing": All Propel classes with get the Prefix "My_ORM_Prefix_" just like "My_ORM_Prefix_BookPeer".
{{{
propel.disableIdentifierQuoting = true|{false}
}}}
Identifier quoting is only implemented at the DDL layer at this point. Since this may result in undesired behavior (especially in Postgres), it can be disabled by setting this property to true.
{{{
propel.useLeftJoinsInDoJoinMethods = {true}|false
}}}
Set whether the '''doSelectJoin*()''' methods use LEFT JOIN or INNER JOIN (see ticket:491 and ticket:588 to understand more about why this might be important).
=== MySQL-specific Settings ===
{{{
propel.mysqlTableType = /DefaultTableEngine/
}}}
Default table engine - defaults to MyISAM. You can override this setting if you wish to default to another engine for all tables (for instance InnoDB, or HEAP). This setting can also be overridden on a per-table basis using the `<vendor>` element in the schema (see [wiki:Documentation/1.5/Schema#AddingVendorInfo]).
{{{
propel.mysqlTableEngineKeyword = /EngineKeyword/
}}}
Keyword used to specify the table engine in the CREATE SQL statement. Defaults to 'ENGINE', users of MYSQL < 5 should use 'TYPE' instead.
=== Date/Time Settings ===
{{{
propel.useDateTimeClass = true|{false}
}}}
This is how you enable full use of the new DateTime class in Propel. Setting this to true means that getter methods for date/time/timestamp columns will return a DateTime object ''when the default format is empty''. Note that the current default of ''false'' is only for backwards compatibility; in the future ''true'' will be the only option here.
{{{
propel.dateTimeClass = {DateTime}|string
}}}
Specify a custom DateTime subclass that you wish to have Propel use for temporal values.
{{{
propel.defaultTimeStampFormat = {Y-m-d H:i:s}|string
propel.defaultTimeFormat = {%X}|string
propel.defaultDateFormat = {%x}|string
}}}
These are the default formats that will be used when fetching values from temporal columns in Propel. You can always specify these when calling the methods directly, but for methods like getByName() it is nice to change the defaults.
To have these methods return DateTime objects instead, you should set these to empty values, for example:
{{{
propel.defaultTimeStampFormat =
}}}
=== Directories ===
{{{
propel.project.dir = default-depends-on-installation-type
}}}
''This is not necessarily a property you can change.'' The project directory is the directory where you project files (build.properties, schema.xml, runtime-conf.xml, etc.) are located. For example, if you use the {{{propel-gen}}} script, this value will get overridden to the path you pass to {{{propel-gen}}}.
{{{
propel.output.dir = ${propel.project.dir}/build
}}}
The default top-level directory for output of classes, sql, config, etc.
{{{
propel.schema.dir = ${propel.project.dir}
}}}
The directory where Propel expects to find your schema.xml file.
{{{
propel.conf.dir = ${propel.project.dir}
}}}
The directory where Propel expects to find your {{{runtime-conf.xml}}} file.
{{{
propel.php.dir = ${propel.output.dir}/classes
}}}
The directory where Propel will create generated object model classes.
{{{
propel.phpconf.dir = ${propel.output.dir}/conf
}}}
The directory where Propel will place the php-ified version of your {{{runtime-conf.xml}}}.
{{{
propel.sql.dir = ${propel.output.dir}/sql
}}}
The directory where Propel will place generated DDL (or data insert statements, etc.)
=== Overriding Builder Classes ===
{{{
# Object Model builders
propel.builder.peer.class = propel.engine.builder.om.php5.PHP5ComplexPeerBuilder
propel.builder.object.class = propel.engine.builder.om.php5.PHP5ComplexObjectBuilder
propel.builder.objectstub.class = propel.engine.builder.om.php5.PHP5ExtensionObjectBuilder
propel.builder.peerstub.class = propel.engine.builder.om.php5.PHP5ExtensionPeerBuilder
propel.builder.objectmultiextend.class = propel.engine.builder.om.php5.PHP5MultiExtendObjectBuilder
propel.builder.tablemap.class = propel.engine.builder.om.php5.PHP5TableMapBuilder
propel.builder.interface.class = propel.engine.builder.om.php5.PHP5InterfaceBuilder
propel.builder.node.class = propel.engine.builder.om.php5.PHP5NodeBuilder
propel.builder.nodepeer.class = propel.engine.builder.om.php5.PHP5NodePeerBuilder
propel.builder.nodestub.class = propel.engine.builder.om.php5.PHP5ExtensionNodeBuilder
propel.builder.nodepeerstub.class = propel.engine.builder.om.php5.PHP5ExtensionNodePeerBuilder
propel.builder.nestedset.class = propel.engine.builder.om.php5.PHP5NestedSetBuilder
propel.builder.nestedsetpeer.class = propel.engine.builder.om.php5.PHP5NestedSetPeerBuilder
# SQL builders
propel.builder.ddl.class = propel.engine.builder.sql.${propel.database}.${propel.database}DDLBuilder
propel.builder.datasql.class = propel.engine.builder.sql.${propel.database}.${propel.database}DataSQLBuilder
# Platform classes
propel.platform.class = propel.engine.platform.${propel.database}Platform
# Pluralizer class (used to generate plural forms)
propel.builder.pluralizer.class = propel.engine.builder.util.DefaultEnglishPluralizer
}}}
As you can see, you can specify your own builder and platform classes if you want to extend & override behavior in the default classes
=== Adding Behaviors ===
{{{
propel.behavior.timestampable.class = propel.engine.behavior.TimestampableBehavior
}}}
Define the path to the class to be used for the `timestampable` behavior. This behavior is bundled wit hPropel, but if you want to override it, you can specify a different path.
If you want to add more behaviors, write their path following the same model:
{{{
propel.behavior.my_behavior.class = my.custom.path.to.MyBehaviorClass
}}}
Behaviors are enabled on a per-table basis in the `schema.xml`. However, you can add behaviors for all your schemas, provided that you define them in the `propel.behavior.default` setting:
{{{
propel.behavior.default = soft_delete,my_behavior
}}}

1025
airtime_mvc/library/propel/docs/reference/ModelCriteria.txt Normal file
View file

File diff suppressed because it is too large Load diff

318
airtime_mvc/library/propel/docs/reference/Runtime-Configuration.txt Normal file
View file

@ -0,0 +1,318 @@
= Runtime Configuration File =
[[PageOutline]]
== Example {{{runtime-conf.xml}}} File ==
Here is a the sample runtime configuration file.
{{{
#!xml
<?xml version="1.0"?>
<config>
<log>
<ident>propel-bookstore</ident>
<name>console</name>
<level>7</level>
</log>
<propel>
<datasources default="bookstore">
<datasource id="bookstore">
<adapter>sqlite</adapter>
<connection>
<classname>DebugPDO</classname>
<dsn>mysql:host=localhost;dbname=bookstore</dsn>
<user>testuser</user>
<password>password</password>
<options>
<option id="ATTR_PERSISTENT">false</option>
</options>
<attributes>
<option id="ATTR_EMULATE_PREPARES">true</option>
</attributes>
<settings>
<setting id="charset">utf8</setting>
<setting id="queries">
<query>set search_path myschema, public</query><!-- automatically set postgresql's search_path -->
<query>INSERT INTO BAR ('hey', 'there')</query><!-- execute some other query -->
</setting>
</settings>
</connection>
<slaves>
<connection>
<dsn>mysql:host=slave-server1; dbname=bookstore</dsn>
</connection>
<connection>
<dsn>mysql:host=slave-server2; dbname=bookstore</dsn>
</connection>
</slaves>
</datasource>
</datasources>
<debugpdo>
<logging>
<details>
<method>
<enabled>true</enabled>
</method>
<time>
<enabled>true</enabled>
<precision>3</precision>
</time>
<mem>
<enabled>true</enabled>
<precision>1</precision>
</mem>
</details>
</logging>
</debugpdo>
</propel>
</config>
}}}
== Explanation of Configuration Sections ==
Below you will find an explanation of the primary elements in the configuration.
=== <log> ===
If the '''<log>''' element is present, Propel will use the specified information to instantiate a [http://pear.php.net/Log PEAR Log] logger.
{{{
#!xml
<config>
<log>
<type>file<type>
<name>/path/to/logger.log</name>
<ident>my-app</ident>
<level>7</level>
</log>
}}}
The nested elements correspond to the configuration options for the logger (options that would otherwise be passed to '''Log::factory()''' method).
||'''Element'''||'''Default'''||'''Description'''||
||'''<type>'''||file||The logger type.||
||'''<name>'''||./propel.log||Name of log, meaning is dependent on type specified. (For ''file'' type this is the filename).||
||'''<ident>'''||propel||The identifier tag for the log.||
||'''<level>'''||7 (PEAR_LOG_DEBUG)||The logging level.||
This log configuring API is designed to provide a simple way to get log output from Propel; however, if your application already has a logging mechanism, we recommend instead that you use your existing logger (writing a simple log adapter, if you are using an unsupported logger). See the [wiki:Documentation/1.5/07-Logging Logging documentation] for more info.
=== <datasources> ===
This is the top-level tag for Propel datasources configuration.
{{{
#!xml
<config>
<propel>
<datasources>
}}}
=== <datasource> ===
{{{
#!xml
<config>
<propel>
<datasources>
<datasource id="bookstore">
}}}
A specific datasource being configured.
* The @id must match the <database> @name attribute from your {{{schema.xml}}}.
=== <adapter> ===
The adapter to use for Propel. Currently supported adapters: sqlite, pgsql, mysql, oracle, mssql. Note that it is possible that your adapter could be different from your connection driver (e.g. if using ODBC to connect to MSSQL database, you would use an ODBC PDO driver, but MSSQL Propel adapter).
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<adapter>sqlite</adapter>
}}}
=== <connection> ===
The PDO database connection for the specified datasource.
Nested elements define the DSN, connection options, other PDO attributes, and finally some Propel-specific initialization settings.
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
}}}
==== <classname> ====
A custom PDO class (must be a PropelPDO subclass) that you would like to use for the PDO connection.
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<classname>DebugPDO</classname>
}}}
This can be used to specify the alternative '''DebugPDO''' class bundled with Propel, or your own subclass. ''Your class must extend PropelPDO, because Propel requires the ability to nest transactions (without having exceptions being thrown by PDO).''
==== <dsn> ====
The PDO DSN that Propel will use to connect to the database for this datasource.
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<dsn>mysql:host=localhost;dbname=bookstore</dsn>
}}}
See the PHP documentation for specific format:
* [http://www.php.net/manual/en/ref.pdo-mysql.connection.php MySQL DSN]
* [http://www.php.net/manual/en/ref.pdo-pgsql.connection.php PostgreSQL DSN]
* [http://www.php.net/manual/en/ref.pdo-sqlite.connection.php SQLite DSN]
* [http://www.php.net/manual/en/ref.pdo-oci.connection.php Oracle DSN]
* [http://www.php.net/manual/en/ref.pdo-dblib.connection.php MSSQL DSN]
Note that some database (e.g. PostgreSQL) specify username and password as part of the DSN while the others specify user and password separately.
==== <user> and <password> ====
Specifies credentials for databases that specify username and password separately (e.g. MySQL, Oracle).
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<dsn>mysql:host=localhost;dbname=bookstore</dsn>
<user>test</user>
<password>testpass</password>
}}}
==== <options> ====
Specify any options which ''must'' be specified when the PDO connection is created. For example, the ATTR_PERSISTENT option must be specified at object creation time.
See the [http://www.php.net/pdo PDO documentation] for more details.
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<!-- ... -->
<options>
<option id="ATTR_PERSISTENT">false</option>
</options>
}}}
==== <attributes> ====
`<attributes>` are similar to `<options>`; the difference is that options specified in `<attributes>` are set after the PDO object has been created. These are set using the [http://us.php.net/PDO-setAttribute PDO->setAttribute()] method.
In addition to the standard attributes that can be set on the PDO object, there are also the following Propel-specific attributes that change the behavior of the PropelPDO connection:
|| '''Attribute constant''' || '''Valid Values (Default)''' || '''Description''' ||
|| PropelPDO::PROPEL_ATTR_CACHE_PREPARES || true/false (false) || Whether to have the PropelPDO connection cache the PDOStatement prepared statements. This will improve performance if you are executing the same query multiple times by your script (within a single request / script run). ||
''Note that attributes in the XML can be specified with or without the PDO:: (or PropelPDO::) constant prefix.''
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<!-- ... -->
<attributes>
<option id="ATTR_ERRMODE">PDO::ERRMODE_WARNING</option>
<option id="ATTR_STATEMENT_CLASS">myPDOStatement</option>
<option id="PROPEL_ATTR_CACHE_PREPARES">true</option>
</attributes>
}}}
'''Tip''': If you are using MySQL and get the following error : "SQLSTATE[HY000]: General error: 2014 Cannot execute queries while other unbuffered queries are active", you can try adding the following attribute:
{{{
<option id="MYSQL_ATTR_USE_BUFFERED_QUERY">true</option>
}}}
==== <settings> ====
Settings are Propel-specific options used to further configure the connection -- or perform other user-defined initialization tasks.
Currently supported settings are:
* charset
* queries
===== charset =====
Specifies the character set to use. Currently you must specify the charset in the way that is understood by your RDBMS. Also note that not all database systems support specifying charset (e.g. SQLite must be compiled with specific charset support). Specifying this option will likely result in an exception if your database doesn't support the specified charset.
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<!-- ... -->
<settings>
<setting id="charset">utf8</setting>
</settings>
}}}
===== queries =====
Specifies any SQL statements to run when the database connection is initialized. This can be used for any environment setup or db initialization you would like to perform. These statements will be executed with every Propel initialization (e.g. every PHP script load).
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<connection>
<!-- ... -->
<settings>
<setting id="queries">
<query>set search_path myschema, public</query><!-- automatically set postgresql's search_path -->
<query>INSERT INTO BAR ('hey', 'there')</query>
</setting>
</settings>
}}}
=== <slaves> ===
{{{
#!xml
<config>
<propel>
<datasources>
<datasource>
<slaves>
}}}
The `<slaves>` tag groups slave `<connection>` elements which provide support for configuring slave db servers -- when using Propel in a master-slave replication environment. See the [wiki:Documentation/1.5/Master-Slave Master-Slave documentation] for more information. The nested `<connection>` elements are configured the same way as the top-level `<connection>` element is configured.
=== <debugpdo> ===
The optional `<debugpdo>` element may be provided to pass additional logging configuration options to DebugPDO. Note that these settings have no effect unless DebugPDO has been selected in [1.5/RuntimeConfiguration#debugpdo `runtime-conf.xml`] as the PDO connection class. See the [wiki:Documentation/1.5/07-Logging Logging documentation] for more information on configuring DebugPDO.

398
airtime_mvc/library/propel/docs/reference/Schema.txt Normal file
View file

@ -0,0 +1,398 @@
= Database Schema =
[[PageOutline]]
The schema for `schema.xml` contains a small number of elements with required and optional attributes. The Propel generator contains a [source:branches/1.5/generator/resources/dtd/database.dtd DTD] that can be used to validate your `schema.xml` document. Also, when you build your SQL and OM, the Propel generator will automatically validate your `schema.xml` file using a highly-detailed [source:branches/1.5/generator/resources/xsd/database.xsd XSD].
== At-a-Glance ==
The hierarchical tree relationship for the elements is:
{{{
#!xml
<database>
<external-schema />
<table>
<column>
<inheritance />
</column>
<foreign-key>
<reference />
</foreign-key>
<index>
<index-column />
</index>
<unique>
<unique-column />
</unique>
<id-method-parameter/>
</table>
</database>
}}}
**Tip**: If you use an IDE supporting autocompletion in XML documents, you can take advantage of the XSD describing the `schema.xml` syntax to suggest elements and attributes as you type. To enable it, add a `xmlns:xsi` and a `xsi:noNamespaceSchemaLocation` attribute to the leading `<database>` tag:
{{{
#!xml
<database name="my_connection_name" defaultIdMethod="native"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://svn.propelorm.org/branches/1.5/generator/resources/xsd/database.xsd" >
}}}
== Detailed Reference ==
This page provides an alternate rendering of the Appendix B - Schema Reference from the user's guide.
It spells out in specific detail, just where each attribute or element belongs.
First, some conventions:
* Text surrounded by a '''/''' is text that you would provide and is not defined in the language. (i.e. a table name is a good example of this.)
* Optional items are surrounded by '''[''' and ''']''' characters.
* Items where you have an alternative choice have a '''|''' character between them (i.e. true|false)
* Alternative choices may be delimited by '''{''' and '''}''' to indicate that this is the default option, if not overridden elsewhere.
* '''...''' means repeat the previous item.
=== <database> element ===
Starting with the {{{<database>}}} element. The ''attributes'' and ''elements'' available are:
{{{
#!xml
<database
name="/DatabaseName/"
defaultIdMethod="native|none"
[package="/ProjectName/"]
[namespace="/ClassNamespace/"]
[baseClass="/baseClassName/"]
[basePeer="/baseClassPeerName/"]
[defaultPhpNamingMethod="nochange|{underscore}|phpname|clean"
[heavyIndexing="true|false"]
[tablePrefix="/tablePrefix/"]
>
<external-schema>
<table>
...
</database>
}}}
The `package`, `baseClass`, `basePeer`, `defaultPhpNamingMethod`, and `heavyIndexing` attributes are generally optional.
A Database element may include an `<external-schema>` element, or multiple `<table>` elements.
* `defaultIdMethod` sets the default id method to use for auto-increment columns.
* `package` specifies the "package" for the generated classes. Classes are created in subdirectories according to the `package` value.
* `namespace` specifies the default namespace that generated model classes will use (PHP 5.3 only). This attribute can be completed or overridden at the table level.
* `baseClass` allows you to specify a default base class that all generated Propel objects should extend (in place of `propel.om.BaseObject`).
* `basePeer` instructs Propel to use a different SQL-generating `BasePeer` class (or sub-class of `BasePeer`) for all generated objects.
* `defaultPhpNamingMethod` the default naming method to use for tables of this database. Defaults to `underscore`, which transforms table names into CamelCase phpNames.
* `heavyIndexing` adds indexes for each component of the primary key (when using composite primary keys).
* `tablePrefix` adds a prefix to all the SQL table names.
=== <external-schema> element ===
The `<external-schema>` element is pretty simple. It just includes a schema file from somewhere on the file systems. The format is:
{{{
#!xml
<external-schema filename="/a path to a file/" />
}}}
=== <table> element ===
The `<table>` element is the most complicated of the usable elements. Its definition looks like this:
{{{
#!xml
<table
name = "/TableName/"
[idMethod = "native|{none}"]
[phpName = "/PhpObjectName/"]
[package="/PhpObjectPackage/"]
[namespace = "/PhpObjectNamespace/"]
[skipSql = "true|false"]
[abstract = "true|false"]
[phpNamingMethod = "nochange|{underscore}|phpname|clean"]
[baseClass = "/baseClassName/"]
[basePeer = "/baseClassPeerName/"]
[description="/A text description of the table/"]
[heavyIndexing = "true|false"]
[readOnly = "true|false"]
[treeMode = "NestedSet|MaterializedPath"]
[reloadOnInsert = "true|false"]
[reloadOnUpdate = "true|false"]
[allowPkInsert = "true|false"]
>
<column>
...
<foreign-key>
...
<index>
...
<unique>
...
<id-method-parameter>
...
</table>
}}}
According to the schema, `name` is the only required attribute. Also, the `idMethod`, `package`, `namespace`, `phpNamingMethod`, `baseClass`, `basePeer`, and `heavyIndexing` attributes all default to what is specified by the `<database>` element.
==== Description of Attributes ====
* `idMethod` sets the id method to use for auto-increment columns.
* `phpName` specifies object model class name. By default, Propel uses a CamelCase version of the table name as phpName.
* `package` specifies the "package" (or subdirectory) in which model classes get generated.
* `namespace` specifies the namespace that the generated model classes will use (PHP 5.3 only). If the table namespace starts with a `\`, it overrides the namespace defined in the `<database>` tag; otherwise, the actual table namespace is the concatenation of the database namespace and the table namespace.
* `skipSql` instructs Propel not to generate DDL SQL for the specified table. This can be used together with `readOnly` for supperting VIEWS in Propel.
* `abstract` Whether the generated ''stub'' class will be abstract (e.g. if you're using inheritance)
* `phpNamingMethod` the naming method to use. Defaults to `underscore`, which transforms the table name into a CamelCase phpName.
* `baseClass` allows you to specify a class that the generated Propel objects should extend ({{{in place of propel.om.BaseObject}}}).
* `basePeer` instructs Propel to use a different SQL-generating `BasePeer` class (or sub-class of `BasePeer`).
* `heavyIndexing` adds indexes for each component of the primary key (when using composite primary keys).
* `readOnly` suppresses the mutator/setter methods, save() and delete() methods.
* `treeMode` is used to indicate that this table is part of a node tree. Currently the only supported values are "!NestedSet" (see [wiki:Documentation/1.5/Behaviors/nested_set]) and "!MaterializedPath" (deprecated).
* `reloadOnInsert` is used to indicate that the object should be reloaded from the database when an INSERT is performed. This is useful if you have triggers (or other server-side functionality like column default expressions) that alters the database row on INSERT.
* `reloadOnUpdate` is used to indicate that the object should be reloaded from the database when an UPDATE is performed. This is useful if you have triggers (or other server-side functionality like column default expressions) that alters the database row on UPDATE.
* `allowPkInsert` can be used if you want to define the primary key of a new object being inserted. By default if idMethod is "native", Propel would throw an exception. However, in some cases this feature is useful, for example if you do some replication of data in an master-master environment. It defaults to false.
=== <column> element ===
{{{
#!xml
<column
name = "/ColumnName/"
[phpName = "/PHPColumnName/"]
[peerName = "/PEERNAME/"]
[primaryKey = "true|{false}"]
[required = "true|{false}"]
[type = "BOOLEAN|TINYINT|SMALLINT|INTEGER|BIGINT|DOUBLE|FLOAT|REAL|DECIMAL|CHAR|{VARCHAR}|LONGVARCHAR|DATE|TIME|TIMESTAMP|BLOB|CLOB"]
[phpType = "boolean|int|integer|double|float|string|/BuiltInClassName/|/UserDefinedClassName/"]
[sqlType = "/NativeDatabaseColumnType/"
[size = "/NumericLengthOfColumn/"]
[scale = "/DigitsAfterDecimalPlace/"]
[defaultValue = "/AnyDefaultValueMatchingType/"]
[defaultExpr = "/AnyDefaultExpressionMatchingType/"]
[autoIncrement = "true|{false}"]
[lazyLoad = "true|{false}"]
[description = "/Column Description/"]
[primaryString = "true|{false}"]
[phpNamingMethod = "nochange|underscore|phpname"]
[inheritance = "single|{false}"]
[inputValidator = "NameOfInputValidatorClass"]
>
[<inheritance key="/KeyName/" class="/ClassName/" [extends="/BaseClassName/"] />]
</column>
}}}
==== Description of Attributes ====
* {{{defaultValue}}} The default value that the object will have for this column in the PHP instance after creating a "new Object". This value is always interpreted as a string.
* {{{defaultExpr}}} The default value for this column as expressed in SQL. This value is used solely for the "sql" target which builds your database from the schema.xml file. The defaultExpr is the SQL expression used as the "default" for the column.
* {{{primaryString}}} A column defined as primary string serves as default value for a `__toString()` method in the generated Propel object.
=== <foreign-key> element ===
To link a column to another table use the following syntax:
{{{
#!xml
<foreign-key
foreignTable = "/TheOtherTableName/"
[name = "/Name for this foreign key/"]
[phpName = "/Name for the foreign object in methods generated in this class/"]
[refPhpName = "/Name for this object in methods generated in the foreign class/"]
[onDelete = "cascade|setnull|restrict|none"]
[onUpdate = "cascade|setnull|restrict|none"]
[defaultJoin= "Criteria::INNER_JOIN|Criteria::LEFT_JOIN"]
>
<reference local="/LocalColumnName/" foreign="/ForeignColumnName/" />
</foreign-key>
}}}
==== Description of Attributes ====
* {{{defaultJoin}}} This affects the default join type used in the generated `joinXXX()` methods in the model query class. Propel uses an INNER JOIN for foreign keys attached to a required column, and a LEFT JOIN for foreign keys attached to a non-required column, but you can override this in the foreign key element.
=== <index> element ===
To create an index on one or more columns, use the following syntax:
{{{
#!xml
<index>
<index-column name="/ColumnName/" [size="/LengthOfIndexColumn/"] />
...
</index>
}}}
In some cases your RDBMS may require you to specify an index size.
=== <unique> element ===
To create a unique index on one or more columns, use the following syntax:
{{{
#!xml
<unique>
<unique-column name="/ColumnName/" [size="/LengthOfIndexColumn/"] />
...
</unique>
}}}
In some cases your RDBMS may require you to specify an index size for unique indexes.
=== <id-method-parameter> element ===
If you are using a database that uses sequences for auto-increment columns (e.g. PostgreSQL or Oracle), you can customize the name of the sequence using the <id-method-paramter/> tag:
{{{
#!xml
<id-method-parameter value="my_custom_sequence_name"/>
}}}
== Column Types ==
Here are the Propel column types with some example mappings to native database and PHP types. There are also several ways to customize the mapping between these types.
=== Text Types ===
||'''Propel Type'''||'''Desc'''||'''Example Default DB Type (MySQL)'''||'''Default PHP Native Type'''||
||CHAR||Fixed-lenght character data||CHAR||string||
||VARCHAR||Variable-lenght character data||VARCHAR||string||
||LONGVARCHAR||Long variable-length character data||TEXT||string||
||CLOB||Character LOB (locator object)||LONGTEXT||string||
=== Numeric Types ===
||'''Propel Type'''||'''Desc'''||'''Example Default DB Type (MySQL)'''||'''Default PHP Native Type'''||
||NUMERIC||Numeric data||DECIMAL||string (PHP int is limited)||
||DECIMAL||Decimal data||DECIMAL||string (PHP int is limited)||
||TINYINT||Tiny integer ||TINYINT||int||
||SMALLINT||Small integer ||SMALLINT||int||
||INTEGER||Integer||INTEGER||int||
||BIGINT||Large integer||BIGINT||string (PHP int is limited)||
||REAL||Real number||REAL||double||
||FLOAT||Floating point number||FLOAT||double||
||DOUBLE||Floating point number||DOUBLE||double||
=== Binary Types ===
||'''Propel Type'''||'''Desc'''||'''Example Default DB Type (MySQL)'''||'''Default PHP Native Type'''||
||BINARY||Fixed-length binary data||BLOB||double||
||VARBINARY||Variable-length binary data||MEDIUMBLOB||double||
||LONGVARBINARY||Long variable-length binary data||LONGBLOB||double||
||BLOB||Binary LOB (locator object)||LONGBLOB||string||
=== Temporal (Date/Time) Types ===
||'''Propel Type'''||'''Desc'''||'''Example Default DB Type (MySQL)'''||'''Default PHP Native Type'''||
||DATE||Date (e.g. YYYY-MM-DD)||DATE||DateTime object||
||TIME||Time (e.g. HH:MM:SS)||TIME||DateTime object||
||TIMESTAMP||Date + time (e.g. YYYY-MM-DD HH:MM:SS)||TIMESTAMP||DateTime object||
==== Legacy Temporal Types ====
The following Propel 1.2 types are still supported, but are no longer needed with Propel 1.3.
||'''Propel Type'''||'''Desc'''||'''Example Default DB Type (MySQL)'''||'''Default PHP Native Type'''||
||BU_DATE||Pre-/post-epoch date (e.g. 1201-03-02)||DATE||DateTime object||
||BU_TIMESTAMP||Pre-/post-epoch Date + time (e.g. 1201-03-02 12:33:00)||TIMESTAMP||DateTime object||
== Customizing Mappings ==
=== Specify Column Attributes ===
You can change the way that Propel maps its own types to native SQL types or to PHP types by overriding the values for a specific column.
For example:
(Overriding PHP type)
{{{
#!xml
<column name="population_served" type="INTEGER" phpType="string"/>
}}}
(Overriding SQL type)
{{{
#!xml
<column name="ip_address" type="VARCHAR" sqlType="inet"/>
}}}
=== Adding Vendor Info ===
Propel supports database-specific elements in the schema (currently only for MySQL). This "vendor" parameters affect the generated SQL. To add vendor data, add a `<vendor>` tag with a `type` attribute specifying the target database vendor. In the `<vendor>` tag, add `<parameter>` tags with a `name` and a `value` attribue. For instance:
{{{
#!xml
<table name="book">
<vendor type="mysql">
<parameter name="Engine" value="InnoDB"/>
<parameter name="Charset" value="utf8"/>
</vendor>
</table>
}}}
This will change the generated SQL table creation to look like:
{{{
#!sql
CREATE TABLE book
()
ENGINE = InnoDB
DEFAULT CHARACTER SET utf8;
}}}
Propel supports the following vendor parameters for MySQL:
{{{
Name | Example values
-----------------|---------------
// in <table> element
Engine | MYISAM (default), BDB, HEAP, ISAM, InnoDB, MERGE, MRG_MYISAM
Charset | utf8, latin1, etc.
Collate | utf8_unicode_ci, latin1_german1_ci, etc.
Checksum | 0, 1
Pack_Keys | 0, 1, DEFAULT
Delay_key_write | 0, 1
// in <column> element
Charset | utf8, latin1, etc.
Collate | utf8_unicode_ci, latin1_german1_ci, etc.
// in <index> element
Index_type | FULLTEXT
}}}
=== Using Custom Platform ===
For overriding the mapping between Propel types and native SQL types, you can create your own Platform class and override the mapping.
For example:
{{{
#!php
<?php
require_once 'propel/engine/platform/MysqlPlatform .php';
class CustomMysqlPlatform extends MysqlPlatform {
/**
* Initializes custom domain mapping.
*/
protected function initialize()
{
parent::initialize();
$this->setSchemaDomainMapping(new Domain(PropelTypes::NUMERIC, "DECIMAL"));
$this->setSchemaDomainMapping(new Domain(PropelTypes::LONGVARCHAR, "TEXT"));
$this->setSchemaDomainMapping(new Domain(PropelTypes::BINARY, "BLOB"));
$this->setSchemaDomainMapping(new Domain(PropelTypes::VARBINARY, "MEDIUMBLOB"));
$this->setSchemaDomainMapping(new Domain(PropelTypes::LONGVARBINARY, "LONGBLOB"));
$this->setSchemaDomainMapping(new Domain(PropelTypes::BLOB, "LONGBLOB"));
$this->setSchemaDomainMapping(new Domain(PropelTypes::CLOB, "LONGTEXT"));
}
}
}}}
You must then specify that mapping in the {{{build.properties}}} for your project:
{{{
propel.platform.class = propel.engine.platform.${propel.database}Platform
}}}