Configuration Properties Reference

    Here is a list of properties that can be set to affect Propel behavior: how it builds your model, how it performs migrations or runs.

    Where and how to Specify Properties

    You can specify configuration properties in a file, in the main directory of your project, named propel.ext, where .ext means: one of the supported extensions. See Configuration chapter for further information.

    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.

    Property List

    The following configuration properties are written in yaml but you can use your favorite format among the supported ones.

    A valid configuration file must start with a propel key, which is the parent of all other properties. If you omit this, Propel can't process and validate the configuration tree.

    propel:
    

    General Settings

      general:
          # The name of your project.
          project: /Your-Project-Name/
          version: /propel version/
    

    Directories and Filenames

      ### Directories and Filenames ###
      paths:
          # Directory where the project files (`schema.xml`, etc.) are located.
          # Default value is current path #
          projectDir:  {current_path}|string
    
          # The directory where Propel expects to find your `schema.xml` file.
          schemaDir: {current_path}|string
    
          # The directory where Propel should output classes, sql, config, etc.
          # Default value is current path #
          outputDir: {current_path}|string
    
          # The directory where Propel should output generated object model classes.
          phpDir: {current-path/generated-classes}|string
    
          # The directory where Propel should output the compiled runtime configuration.
          phpConfDir: {current-path/generated-conf}|string
    
          # The directory where Propel should output the generated DDL (or data insert statements, etc.)
          sqlDir: {current-path/generated-sql}|string
    
          # Directory in which your composer.json resides
          composerDir: {empty}|string
    

    Database settings

    In this section you can define all configured connections and other databases properties. Propel expects you to define one connection at least.

    Tip
    If you come from Propel 1.x: this section replaces the old runtime-conf.xml file. This section is also used by config:convert command, to write down the bootstrap Propel file.

      ## All Database settings ##
      #
      database:
          # All database sources
          connections:
              /the name of the connection/:
    

    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).

                  adapter: {empty}|string
    

    Classname

    A ConnectionInterface class (ConnectionWrapper or DebugPDO etc.) that you would like to use for the connection.

    This can be used to specify the alternative DebugPDO class bundled with Propel, or your own subclass. Your class must inherit from ConnectionWrapper, because Propel requires the ability to nest transactions (without having exceptions being thrown by PDO).

                  # Connection class. One of the Propel\Runtime\Connection classes
                  classname: {Propel\Runtime\Connection\ConnectionWrapper}|string
    

    dsn

    The PDO DSN that Propel will use to connect to the database.

    See the PHP documentation for specific format:

    Note that some databases (e.g. PostgreSQL) specify username and password as part of the DSN while the others specify user and password separately.

                  # The PDO dsn
                  dsn: /your dsn/
    

    Username and Password

    Specifies credentials for databases that specify username and password separately (e.g. MySQL, Oracle).

                  user: /Your username/
                  password: /Your password/
    

    options

    This property contains any options which must be specified when the ConnectionInterface connection is created. For example, the ATTR_PERSISTENT option must be specified at the object creation time.

    See the PDO documentation for more details.

                  # Driver options. See http://www.php.net/manual/en/pdo.construct.php
                  # options must be passed to the contructor of the connection object
                  options: {empty}|array
    

    attributes

    attributes are similar to options; the difference is that options specified in attributes are set after the ConnectionInterface object has been created. These are set using the ConnectionInterface::setAttribute() method.

    In addition to the standard attributes that can be set on the ConnectionInterface object, there are also the following Propel-specific attributes that change the behavior of the Propel 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 configuration file can be specified with or without the PDO:: (or PropelPDO::) constant prefix.

                  # See http://www.php.net/manual/en/pdo.getattribute.php
                  # Attributes are set via `setAttribute()` method, after the connection object is created
                  attributes: {empty}|array
    

    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
                  #Propel specific settings
                  settings: {empty}|array
    
    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.

                    charset: {utf8}|string
    

    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 each time Propel get initialized (e.g. each time a PHP script is loaded).

                    #Array of queries to run when the database connection is initialized
                    queries: {empty}|array
    

    Master/Slaves

    The slaves properties groups lists slave connection elements which provide support for configuring slave db servers -- when using Propel in a master-slave replication environment. See the Master-Slave documentation for more information.

                  slaves:
                      - dsn: mysql:host=slave-host-1;dbname=bookstore
                      - ......
    

    Specific adapter settings

    In this section you can define some settings for specific DBMS.

          ## Specific adapter settings
          adapters:
              ## Mysql ##
              mysql:
    

    Default table type.

    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 Schema AddingVendorInfo).

                  # Default table type
                  tableType: {InnoDB}|MyIsam
    
                  # Keyword used to specify the table engine in the CREATE SQL statement.
                  # Defaults to 'ENGINE', users of MYSQL < 5 should use 'TYPE' instead.
                  tableEngineKeyword: {ENGINE}|TYPE
    
              ## Sqlite ##
              sqlite:
                  foreigKey: {empty}|string
                  tableAlteringWorkaround: {empty}|boolean
    
              ## Oracle ##
              oracle:
                  autoincrementSequencePattern: ${table}_SEQ
    

    Migrations settings

      ## Migration settings ##
      migrations:
          # Whether to specify PHP names that are the same as the column names.
          samePhpName: {false}|true
    
          # Whether to add the vendor info. It does provide additional information (such as full-text indexes) which can
          # affect the generation of the DDL from the schema.
          addVendorInfo: {false}|true
    
          # The name of migrations table
          tableName: {propel_migration}|string
    
          # The name of the parser class
          # If you leave this property blank, Propel looks for an appropriate parserClass, based on platform: e.g.
          # if the platform is `MysqlPlatform` then parser is `\Propel\Generator\Reverse\MysqlSchemaParser` 
          parserClass: {empty}|string
    

    Reverse engeneering

    This section configures the reverse engineering, to create an xml schema from an existing database.

      ## Reverse settings
      reverse:
        # The connection to use to reverse the database
        connection: /One of the connections defined in database section/
    
        # Reverse parser class can be different from migration one
        # If you leave this property blank, Propel looks for an appropriate parser class, based on platform: i.e.
        # if the platform is `MysqlPlatform` then parser is `\Propel\Generator\Reverse\MysqlSchemaParser` 
        parserClass: {empty}|string
    

    Runtime settings

      ## Runtime settings ##
      runtime:
          defaultConnection: /One of the connections defined in database section/
          # Datasources as defined in database.connections
          # This section affects config:convert command
          connections:
             - default
    
          ## Log and loggers definitions ##
          # For `type` and `level` options see Monolog documentation https://github.com/Seldaek/monolog
          log:
            defaultLogger:
              type: {empty}|string
              path: {empty}|string
              level: {empty}|integer
    
          ## Profiler configuration ##
          # To enable the profiler for a connection, set the `classname` option to \Propel\Runtime\Connection\ProfilerConnectionWrapper
          # see: http://propelorm.org/documentation/07-logging.html
          profiler:
            classname: {\Propel\Runtime\Util\Profiler}|string
            slowTreshold: 0.1
            time:
              precision: {3}|integer
              pad: {8}|integer
            memory:
              precision: {3}|integer
              pad: {8}|integer
            innerGlue: {":"}|integer
            outerGlue: {"|"}|integer
    

    Generator settings

      ## Generator settings ##
      generator:
          defaultConnection: /One of the connections defined in database section/
          # Datasources as defined in database.connections
          connections:
              - default
    
          # 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.
          tablePrefix: {empty}|string
    
          # Platform class name
          platformClass: {Propel\Generator\Platform\MysqlPlatform}|string
    
          # 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.
          targetPackage: {empty}|string
    
          # 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.
          packageObjectModel: {true}|false
    
          # If you use namespaces in your schemas, this setting tells Propel to use the
          # namespace attribute for the package. Consequently, the namespace attribute
          # will also stipulate the subdirectory in which model classes get generated.
          namespaceAutoPackage: {true}|false
    
          schema:
              # The schema base name
              basename: {schema}|string
              # If your XML schema specifies SQL schemas for each table, you can copy the
              # value of the `schema` attribute to other attributes.
              # To copy the schema attribute to the package attribute, set this to true
              autoPackage: {false}|true
              # To copy the schema attribute to the namespace attribute, set this to true
              autoNamespace: {false}|true
              # To use the schema attribute as a prefix to all model phpNames, set this to true
              autoPrefix: {false}|true
    
              # Whether to transform the XML schema using the XSL file.
              # It is disabled by default.
              # The default XSL file is located under `resources/xsl/database.xsl`
              # and you can use a custom XSL file by changing the `propel.schema.xsl.file`
              # property.
              transform: {false}|true
    

    Date/Time settings

          ## Date/Time settings ##
          dateTime:
    
              # Enable full use of the DateTime class.
              # Setting this to true means that getter methods for date/time/timestamp
              # columns will return a DateTime object when the default format is empty.
              useDateTimeClass: {true}|false
    
              # Specify a custom DateTime subclass that you wish to have Propel use
              # for temporal values.
              dateTimeClass: {DateTime}|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
              defaultTimeStampFormat: {Y-m-d H:i:s}
              defaultTimeFormat: { %X }|string
              defaultDateFormat: { %x }|string
    

    Customizing generated object model

          objectModel:
              # Whether to add generic getter/setter methods.
              # Generic accessors are `getByName()`, `getByPosition(), ` and `toArray()`.
              addGenericAccessors: {true}|false
              # Generic mutators are `setByName()`, `setByPosition()`, and `fromArray()`.
              addGenericMutators: {true}|false
              emulateForeignKeyConstraints: {false}|true
              addClassLevelComment: {true}|false
              defaultKeyType: {phpName}|string
              addSaveMethod: {true}|false
              namespaceMap: {Map}|string
    
              # Whether to add a timestamp to the phpdoc header of generated OM classes.
              # If you use a versioning system, don't set this to true, or the classes
              # will be committed too often with just a date change.
              addTimeStamp: {false}|true
    
              # 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.
              addHooks: {true}|false
    
              # Some sort of "namespacing": All Propel classes will get the Prefix
              # "My_ORM_Prefix_" just like "My_ORM_Prefix_BookTableMap".
              classPrefix: {empty}|string
    
              # Identifier quoting may result in undesired behavior (especially in Postgres),
              # it can be disabled in DDL by setting this property to true.
              disableIdentifierQuoting: {false}|true
    
              # Whether the generated `doSelectJoin*()` methods use LEFT JOIN or INNER JOIN.
              useLeftJoinsInDoJoinMethods: {true}|false
    
              # Pluralizer class (used to generate plural forms)
              # Use StandardEnglishPluralizer instead of DefaultEnglishPluralizer for better pluralization
              # (Handles uncountable and irregular nouns)
              pluralizerClass: \Propel\Common\Pluralizer\StandardEnglishPluralizer
    
              # Builder classes
              builders:
                  object: \Propel\Generator\Builder\Om\ObjectBuilder
                  objectstub: \Propel\Generator\Builder\Om\ExtensionObjectBuilder
                  objectmultiextend: \Propel\Generator\Builder\Om\MultiExtendObjectBuilder
                  tablemap: \Propel\Generator\Builder\Om\TableMapBuilder
                  query: \Propel\Generator\Builder\Om\QueryBuilder
                  querystub: \Propel\Generator\Builder\Om\ExtensionQueryBuilder
                  queryinheritance: \Propel\Generator\Builder\Om\QueryInheritanceBuilder
                  queryinheritancestub: \Propel\Generator\Builder\Om\ExtensionQueryInheritanceBuilder
                  interface: \Propel\Generator\Builder\Om\InterfaceBuilder
                  # SQL builders
                  datasql: \Propel\Generator\Builder\Sql\PgsqlDataSQLBuilder
    

    Complete file

    Here it is the complete file, without interruptions.

    propel:
      general:
          # The name of your project.
          project: /Your-Project-Name/
          version: /propel version/
    
      ### Directories and Filenames ###
      paths:
          # Directory where the project files (`schema.xml`, etc.) are located.
          # Default value is current path #
          projectDir:  {current_path}|string
    
          # The directory where Propel expects to find your `schema.xml` file.
          schemaDir: {current_path}|string
    
          # The directory where Propel should output classes, sql, config, etc.
          # Default value is current path #
          outputDir: {current_path}|string
    
          # The directory where Propel should output generated object model classes.
          phpDir: {current-path/generated-classes}|string
    
          # The directory where Propel should output the compiled runtime configuration.
          phpConfDir: {current-path/generated-conf}|string
    
          # The directory where Propel should output the generated DDL (or data insert statements, etc.)
          sqlDir: {current-path/generated-sql}|string
    
          # Directory in which your composer.json resides
          composerDir: {empty}|string
    
      ## All Database settings ##
      database:
          # All database sources
          connections:
              /the name of the connection/:
                  adapter: {mysql}|string
                  # Connection class. One of the Propel\Runtime\Connection classes
                  classname: {Propel\Runtime\Connection\ConnectionWrapper}|string
                  # The PDO dsn
                  dsn: /your dsn/
                  user: /Your username/
                  password: /Your password/
                  # Driver options. See http://www.php.net/manual/en/pdo.construct.php
                  # options must be passed to the contructor of the connection object
                  options: {empty}|array
                  # See http://www.php.net/manual/en/pdo.getattribute.php
                  # Attributes are set via `setAttribute()` method, after the connection object is created
                  attributes: {empty}|array
                  #Propel specific settings
                  settings: {empty}|array
                  charset: {utf8}|string
                  #Array of queries to run when the database connection is initialized
                  query: {empty}|array
                  slaves:
                      - dsn: mysql:host=slave-host-1;dbname=bookstore
                      - ......
    
          ## Specific adapter settings
          adapters:
              ## Mysql ##
              mysql:
                  # Default table type
                  tableType: {InnoDB}|MyIsam
    
                  # Keyword used to specify the table engine in the CREATE SQL statement.
                  # Defaults to 'ENGINE', users of MYSQL < 5 should use 'TYPE' instead.
                  tableEngineKeyword: {ENGINE}|TYPE
    
              ## Sqlite ##
              sqlite:
                  foreigKey: {empty}|string
                  tableAlteringWorkaround: {empty}|boolean
    
              ## Oracle ##
              oracle:
                  autoincrementSequencePattern: ${table}_SEQ
    
      ## Migration settings ##
      migrations:
          # Whether to specify PHP names that are the same as the column names.
          samePhpName: {false}|true
    
          # Whether to add the vendor info. It does provide additional information (such as full-text indexes) which can
          # affect the generation of the DDL from the schema.
          addVendorInfo: {false}|true
    
          # The name of migrations table
          tableName: {propel_migration}|string
    
          # The name of the parser class
          # If you leave this property blank, Propel looks for an appropriate parser class, based on platform: i.e.
          # if the platform is `MysqlPlatform` then parser is `\Propel\Generator\Reverse\MysqlSchemaParser` 
          parserClass: {empty}|string
    
      ## Reverse settings
      reverse:
        # The connection to use to reverse the database
        connection: /One of the connections defined in database section/
    
        # Reverse parser class can be different from migration one
        # If you leave this property blank, Propel looks for an appropriate parser class, based on platform: i.e.
        # if the platform is `MysqlPlatform` then parser is `\Propel\Generator\Reverse\MysqlSchemaParser` 
        parserClass: {empty}|string
    
      ## Runtime settings ##
      runtime:
          defaultConnection: /One of the connections defined in database section/
          # Datasources as defined in database.connections
          # This section affects config:convert command
          connections:
             - default
    
          ## Log and loggers definitions ##
          # For `type` and `level` options see Monolog documentation https://github.com/Seldaek/monolog
          log:
            defaultLogger:
              type: {empty}|string
              path: {empty}|string
              level: {empty}|integer
    
          ## Profiler configuration ##
          # To enable the profiler for a connection, set the `classname` option to \Propel\Runtime\Connection\ProfilerConnectionWrapper
          # see: http://propelorm.org/documentation/07-logging.html
          profiler:
            classname: {\Propel\Runtime\Util\Profiler}|string
            slowTreshold: 0.1
            time:
              precision: {3}|integer
              pad: {8}|integer
            memory:
              precision: {3}|integer
              pad: {8}|integer
            innerGlue: {":"}|integer
            outerGlue: {"|"}|integer
    
      ## Generator settings ##
      generator:
          defaultConnection: /One of the connections defined in database section/
          # Datasources as defined in database.connections
          connections:
              - default
    
          # 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.
          tablePrefix: {empty}|string
    
          # Platform class name
          platformClass: {Propel\Generator\Platform\MysqlPlatform}|string
    
          # 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.
          targetPackage: {empty}|string
    
          # 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.
          packageObjectModel: {true}|false
    
          # If you use namespaces in your schemas, this setting tells Propel to use the
          # namespace attribute for the package. Consequently, the namespace attribute
          # will also stipulate the subdirectory in which model classes get generated.
          namespaceAutoPackage: {true}|false
    
          schema:
              # The schema base name
              basename: {schema}|string
              # If your XML schema specifies SQL schemas for each table, you can copy the
              # value of the `schema` attribute to other attributes.
              # To copy the schema attribute to the package attribute, set this to true
              autoPackage: {false}|true
              # To copy the schema attribute to the namespace attribute, set this to true
              autoNamespace: {false}|true
              # To use the schema attribute as a prefix to all model phpNames, set this to true
              autoPrefix: {false}|true
    
              # Whether to transform the XML 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 `resources/xsl/database.xsl`
              # and you can use a custom XSL file by changing the `propel.schema.xsl.file`
              # property.
              transform: {false}|true
    
          ## Date/Time settings ##
          dateTime:
    
              # Enable full use of the DateTime class.
              # Setting this to true means that getter methods for date/time/timestamp
              # columns will return a DateTime object when the default format is empty.
              useDateTimeClass: {true}|false
    
              # Specify a custom DateTime subclass that you wish to have Propel use
              # for temporal values.
              dateTimeClass: {DateTime}|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
              defaultTimeStampFormat: {Y-m-d H:i:s}
              defaultTimeFormat: { %X }|string
              defaultDateFormat: { %x }|string
    
          objectModel:
              # Whether to add generic getter/setter methods.
              # Generic accessors are `getByName()`, `getByPosition(), ` and `toArray()`.
              addGenericAccessors: {true}|false
              # Generic mutators are `setByName()`, `setByPosition()`, and `fromArray()`.
              addGenericMutators: {true}|false
              emulateForeignKeyConstraints: {false}|true
              addClassLevelComment: {true}|false
              defaultKeyType: {phpName}|string
              addSaveMethod: {true}|false
              namespaceMap: {Map}|string
    
              # Whether to add a timestamp to the phpdoc header of generated OM classes.
              # If you use a versioning system, don't set this to true, or the classes
              # will be committed too often with just a date change.
              addTimeStamp: {false}|true
    
              # 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.
              addHooks: {true}|false
    
              # Some sort of "namespacing": All Propel classes with get the Prefix
              # "My_ORM_Prefix_" just like "My_ORM_Prefix_BookTableMap".
              classPrefix: {empty}|string
    
              # Identifier quoting may result in undesired behavior (especially in Postgres),
              # it can be disabled in DDL by setting this property to true.
              disableIdentifierQuoting: {false}|true
    
              # Whether the generated `doSelectJoin*()` methods use LEFT JOIN or INNER JOIN
              # (see ticket:491 and ticket:588 to understand more about why this might be
              # important).
              useLeftJoinsInDoJoinMethods: {true}|false
    
              # Pluralizer class (used to generate plural forms)
              # Use StandardEnglishPluralizer instead of DefaultEnglishPluralizer for better pluralization
              # (Handles uncountable and irregular nouns)
              pluralizerClass: \Propel\Common\Pluralizer\StandardEnglishPluralizer
    
              # Builder classes
              builders:
                  object: \Propel\Generator\Builder\Om\ObjectBuilder
                  objectstub: \Propel\Generator\Builder\Om\ExtensionObjectBuilder
                  objectmultiextend: \Propel\Generator\Builder\Om\MultiExtendObjectBuilder
                  tablemap: \Propel\Generator\Builder\Om\TableMapBuilder
                  query: \Propel\Generator\Builder\Om\QueryBuilder
                  querystub: \Propel\Generator\Builder\Om\ExtensionQueryBuilder
                  queryinheritance: \Propel\Generator\Builder\Om\QueryInheritanceBuilder
                  queryinheritancestub: \Propel\Generator\Builder\Om\ExtensionQueryInheritanceBuilder
                  interface: \Propel\Generator\Builder\Om\InterfaceBuilder
                  # SQL builders
                  datasql: