Skip to content
Browse files

Updated phpdoc comments for all files

  • Loading branch information...
1 parent f49c510 commit c13580fb6c4b5a9ece30a8c11ac2904c810d62a8 @dstockto dstockto committed Oct 16, 2011
View
2 zf1/Akrabat/Db/Adapter/Pdo/Sqlsrv.php
@@ -134,7 +134,7 @@ protected function _connect()
$this->_connection->exec('SET QUOTED_IDENTIFIER ON');
}
-/**
+ /**
* Set the transaction isoltion level.
*
* @param integer|null $level A fetch mode from SQLSRV_TXN_*.
View
12 zf1/Akrabat/Db/Schema/AbstractChange.php
@@ -12,19 +12,29 @@
*/
protected $_tablePrefix;
- function __construct(Zend_Db_Adapter_Abstract $db, $tablePrefix = '')
+ /**
+ * Build and initialize the object
+ *
+ * @param Zend_Db_Adapter_Abstract $db Database adabpter to use
+ * @param string $tablePrefix Prefix for any table names
+ */
+ public function __construct(Zend_Db_Adapter_Abstract $db, $tablePrefix = '')
{
$this->_db = $db;
$this->_tablePrefix = $tablePrefix;
}
/**
* Changes to be applied in this change
+ *
+ * @return null
*/
abstract function up();
/**
* Rollback changes made in up()
+ *
+ * @return null
*/
abstract function down();
View
136 zf1/Akrabat/Db/Schema/Manager.php
@@ -1,13 +1,15 @@
<?php
class Akrabat_Db_Schema_Manager
{
- const RESULT_OK = 'RESULT_OK';
- const RESULT_AT_CURRENT_VERSION = 'RESULT_AT_CURRENT_VERSION';
+ const RESULT_OK = 'RESULT_OK';
+ const RESULT_AT_CURRENT_VERSION = 'RESULT_AT_CURRENT_VERSION';
const RESULT_NO_MIGRATIONS_FOUND = 'RESULT_NO_MIGRATIONS_FOUND';
- const RESULT_AT_MAXIMUM_VERSION = 'RESULT_AT_MAXIMUM_VERSION';
- const RESULT_AT_MINIMUM_VERSION = 'RESULT_AT_MINIMUM_VERSION';
-
+ const RESULT_AT_MAXIMUM_VERSION = 'RESULT_AT_MAXIMUM_VERSION';
+ const RESULT_AT_MINIMUM_VERSION = 'RESULT_AT_MINIMUM_VERSION';
+ /**
+ * @var string
+ */
protected $_schemaVersionTableName = 'schema_version';
/**
@@ -36,19 +38,26 @@ class Akrabat_Db_Schema_Manager
* 'schema_version_table_name' => name of table to use for holding the schema version number
*
*
- * @param $dir Directory where migrations files are stored
- * @param $db Database adapter
- * @param $tablePrefix Table prefix to be used by change files
- * @param $options Options
+ * @param string $dir Directory where migrations files are stored
+ * @param Zend_Db_Adapter_Abstract $db Database adapter
+ * @param string $tablePrefix Table prefix to be used by change files
*/
- function __construct($dir, Zend_Db_Adapter_Abstract $db, $tablePrefix='')
+ public function __construct($dir, Zend_Db_Adapter_Abstract $db, $tablePrefix='')
{
$this->_dir = $dir;
$this->_db = $db;
$this->_tablePrefix = $tablePrefix;
}
- function getCurrentSchemaVersion()
+ /**
+ * Retrieves the current database schema version from the database
+ *
+ * If the table does not exist, it will be created and the version will
+ * be set to 0.
+ *
+ * @return int
+ */
+ public function getCurrentSchemaVersion()
{
// Ensure we have valid connection to the database
if (!$this->_db->isConnected()) {
@@ -74,7 +83,26 @@ function getCurrentSchemaVersion()
return $version;
}
- function updateTo($version = null)
+ /**
+ * Updates the database schema to a specified version. If upgrading (increasing
+ * version number) the schema version will be the largest available version
+ * that is less than or equal to the specified version. ie, if the highest version
+ * is 050 and 7000 is specified for $version, the resulting version will be
+ * 050. If downgrading (decreasing version number) the ending version will be
+ * the highest version that is less than or equal to the specified version
+ * number. i.e, if versions 10, 15 and 20 exist and the version is updated
+ * to 19, the resulting version will be 15 since version 20 will be downgraded.
+ *
+ * The method automatcally determines the direction of the migration by comparing
+ * the current version (from the database) and the desired version. If they
+ * are the same, no migration will be performed and the version will remain
+ * the same.
+ *
+ * @param string $version
+ *
+ * @return string
+ */
+ public function updateTo($version = null)
{
if (is_null($version)) {
$version = PHP_INT_MAX;
@@ -102,6 +130,8 @@ function updateTo($version = null)
}
// figure out what the real version we're going to is if going down
+ // TODO: make this more efficient by caching file information instead
+ // of fetching it again.
if ($direction == 'down') {
$files = $this->_getMigrationFiles($version, 0);
$versionFile = array_shift($files);
@@ -117,6 +147,22 @@ function updateTo($version = null)
return self::RESULT_OK;
}
+ /**
+ * Increments the database version a specified number of upgrades. For instance,
+ * if $versions is 1, it will update to the next highest version of the database.
+ *
+ * If $versions is provided and less than 1, it will assume 1 and update
+ * a single version. If a number higher than the available upgradable versions
+ * is specified, it will update to the highest version number.
+ *
+ * If the database is already at the highest version number available, it will
+ * not do anything and indicate it is at the maximum version number via
+ * the return value.
+ *
+ * @param int $versions Number of versions to increment. Must be 1 or greater
+ *
+ * @return string
+ */
public function incrementVersion($versions)
{
$versions = (int)$versions;
@@ -138,6 +184,16 @@ public function incrementVersion($versions)
return $this->updateTo($nextVersion);
}
+ /**
+ * Decrements the version of the database by the specified number of versions.
+ *
+ * If the database is already at the lowest version number, it will indicate
+ * this through the return value.
+ *
+ * @param int $versions Number of versions to decrement.
+ *
+ * @return string
+ */
public function decrementVersion($versions)
{
$versions = (int)$versions;
@@ -158,6 +214,17 @@ public function decrementVersion($versions)
return $this->updateTo($nextVersion);
}
+ /**
+ * Retrieves the migration files that are needed to take the database from
+ * its a specified version (current version) to the desired version. It
+ * will also determine the direction of the migration and sort the files
+ * accordingly.
+ *
+ * @param string $currentVersion Version to migrate database from
+ * @param string $stopVersion Version to migrate database to
+ *
+ * @return array of file name, version and class name
+ */
protected function _getMigrationFiles($currentVersion, $stopVersion)
{
$direction = 'up';
@@ -198,7 +265,34 @@ protected function _getMigrationFiles($currentVersion, $stopVersion)
return $files;
}
-
+ /**
+ * Runs a migration file according to the information provided. The
+ * migration parameter is an array or object allowing ArrayAccess with the
+ * following fields:
+ *
+ * version - The version of the migration this file represents
+ * filename - The name of the file containing the code to upgrade or downgrade the database
+ * classname - The name of the class contained in the file
+ *
+ * The direction parameter should be one of either "up" or "down" and indicates
+ * which of the migration class methods should be executed. The up method is
+ * assumed to move the database schema to the next version while down is
+ * assumed to undo whatever up did.
+ *
+ * @param array|ArrayAccess $migration Information about the migration file
+ * @param string $direction "up" or "down"
+ *
+ * @throws Akrabat_Db_Schema_Exception
+ *
+ * @return null
+ *
+ * @todo I think there may be a problem with different migration files using
+ * the same class name. -- Confirmed. If you migrate single versions at a time,
+ * i.e. using increment or decrement then you will have no problems. If you
+ * try to migrate through files where there are more than one file with a
+ * particular class name, it will fail because it tries to redeclare a class
+ * that already exists.
+ */
protected function _processFile($migration, $direction)
{
$version = $migration['version'];
@@ -218,16 +312,28 @@ protected function _processFile($migration, $direction)
$this->_updateSchemaVersion($version);
}
+ /**
+ * Updates the schema version in the database.
+ *
+ * @param int $version Version to update into database
+ *
+ * @return null
+ */
protected function _updateSchemaVersion($version)
{
$schemaVersionTableName = $this->getPrefixedSchemaVersionTableName();
$sql = "UPDATE $schemaVersionTableName SET version = " . (int)$version;
$this->_db->query($sql);
}
+ /**
+ * Retrieves the prefixed version of the schema version table.
+ *
+ * @return string
+ */
public function getPrefixedSchemaVersionTableName()
{
return $this->_tablePrefix . $this->_schemaVersionTableName;
}
-
-}
+}
+
View
61 zf1/Akrabat/Tool/DatabaseSchemaProvider.php
@@ -27,6 +27,18 @@ public function update($env='development', $dir='./scripts/migrations')
return $this->updateTo(null, $env, $dir);
}
+ /**
+ * Allows you to change the database schema version by specifying the desired version. If you are
+ * upgrading (choosing a higher version), it will update to the highest version that is available.
+ * If you are downgrading, it will go to the highest version that is equal to or lower than the
+ * version you specified.
+ *
+ * @param string $version Version to change to
+ * @param string $env Environment to retrieve database credentials from, default is development
+ * @param string $dir Directory containing migration files, default is ./scripts/migrations
+ *
+ * @return boolean
+ */
public function updateTo($version, $env='development', $dir='./scripts/migrations')
{
$this->_init($env);
@@ -61,6 +73,16 @@ public function updateTo($version, $env='development', $dir='./scripts/migration
}
}
+ /**
+ * Decrements the database schema version to the next version or if specified
+ * down a specified number of versions.
+ *
+ * @param int $versions Number of versions to decrement. Default is 1
+ * @param string $env Environment to read database credentials from
+ * @param string $dir Directory containing migration files
+ *
+ * @return boolean
+ */
public function decrement($versions=1, $env='development', $dir='./scripts/migrations')
{
$this->_init($env);
@@ -88,6 +110,16 @@ public function decrement($versions=1, $env='development', $dir='./scripts/migra
}
}
+ /**
+ * Increments the datbase schema version to the next version or up a specified
+ * number of versions
+ *
+ * @param int $versions Number of versions to increment. Default is 1
+ * @param string $env Environment to read database conguration from
+ * @param string $dir Directory containing migration scripts
+ *
+ * @return booolean
+ */
public function increment($versions=1,$env='development', $dir='./scripts/migrations')
{
$this->_init($env);
@@ -117,6 +149,8 @@ public function increment($versions=1,$env='development', $dir='./scripts/migrat
/**
* Provide the current schema version number
+ *
+ * @return boolean
*/
public function current($env='development', $dir='./migrations')
{
@@ -136,12 +170,28 @@ public function current($env='development', $dir='./migrations')
}
}
+ /**
+ * Retrieves the realpath for ./scripts/migrations. Does not appear to be
+ * used anywhere. Possible candidate for removal.
+ *
+ * @return string
+ * @deprecated
+ */
protected function _getDirectory()
{
$dir = './scripts/migrations';
return realpath($dir);
}
+ /**
+ * Initializes the Akrabat functionality and adds it to Zend_Tool (zf)
+ *
+ * @param string $env Environment to initialize for
+ *
+ * @return null
+ *
+ * @throws Zend_Tool_Project_Exception
+ */
protected function _init($env)
{
$profile = $this->_loadProfile(self::NO_PROFILE_THROW_EXCEPTION);
@@ -191,7 +241,9 @@ protected function _getUserConfig()
* @param string $section If not null, pull this sestion of the config
* file only. Doesn't apply to .php and .inc file
* @param string $allowModifications Should the object be mutable or not
+ *
* @throws Akrabat_Db_Schema_Exception
+ *
* @return Zend_Config
*/
protected function _createConfig($filename, $section = null, $allowModifications = false) {
@@ -246,8 +298,8 @@ protected function _createConfig($filename, $section = null, $allowModifications
/**
* Will pull a list of file paths to application config overrides
*
- * There is a deliberate attempt to be very forgiving. If a file doesnt exist,
- * it won't be included in the list. If a the file doesnt have a section that
+ * There is a deliberate attempt to be very forgiving. If a file doesn't exist,
+ * it won't be included in the list. If a the file doesn't have a section that
* corresponds the current target environment it don't be merged.
*
* The config files should be standalone, they will not be able to extend
@@ -294,10 +346,11 @@ protected function _createConfig($filename, $section = null, $allowModifications
*
* Where the last part of the config key is the order to merge the files.
*
- * If a path is added that's order clashes with another file then the path will
- * be added the end of the queue
+ * If a path is added with an order that clashes with another file then the
+ * path will be added the end of the queue
*
* @param string $appConfigFilePath
+ *
* @return array
*/
protected function _getAppConfigOverridePathList($appConfigFilePath)

0 comments on commit c13580f

Please sign in to comment.
Something went wrong with that request. Please try again.