commit f96694b18fdaa9bd6310debca71427068fe24046 Author: Deon George Date: Mon Apr 22 14:09:50 2013 +1000 Kohana v3.3.0 diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..ba7adb4 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,24 @@ +language: php + +php: + - 5.3 + +before_install: + - "git submodule update --init --recursive" + +before_script: + - "pear channel-discover pear.phing.info" + - "pear install phing/phing" + - "phpenv rehash" + - "composer install" + +script: "phing test" + +notifications: + irc: + channels: + - "irc.freenode.org#kohana" + template: + - "%{repository}/%{branch} (%{commit}) - %{author}: %{message}" + - "Build details: %{build_url}" + email: false diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..a36fb76 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,14 @@ +# Kohana License Agreement + +This license is a legal agreement between you and the Kohana Team for the use of Kohana Framework (the "Software"). By obtaining the Software you agree to comply with the terms and conditions of this license. + +Copyright (c) 2007-2011 Kohana Team +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. +* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. +* Neither the name of the Kohana nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..220a934 --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +# Kohana PHP Framework + +[Kohana](http://kohanaframework.org/) is an elegant, open source, and object oriented HMVC framework built using PHP5, by a team of volunteers. It aims to be swift, secure, and small. + +Released under a [BSD license](http://kohanaframework.org/license), Kohana can be used legally for any open source, commercial, or personal project. + +## Documentation +Kohana's documentation can be found at which also contains an API browser. + +The `userguide` module included in all Kohana releases also allows you to view the documentation locally. Once the `userguide` module is enabled in the bootstrap, it is accessible from your site via `/index.php/guide` (or just `/guide` if you are rewriting your URLs). + +## Reporting bugs +If you've stumbled across a bug, please help us out by [reporting the bug](http://dev.kohanaframework.org/projects/kohana3/) you have found. Simply log in or register and submit a new issue, leaving as much information about the bug as possible, e.g. + +* Steps to reproduce +* Expected result +* Actual result + +This will help us to fix the bug as quickly as possible, and if you'd like to fix it yourself feel free to [fork us on GitHub](https://github.com/kohana) and submit a pull request! diff --git a/application/bootstrap.php b/application/bootstrap.php new file mode 100644 index 0000000..96b8b19 --- /dev/null +++ b/application/bootstrap.php @@ -0,0 +1,129 @@ +" + */ +if (isset($_SERVER['KOHANA_ENV'])) +{ + Kohana::$environment = constant('Kohana::'.strtoupper($_SERVER['KOHANA_ENV'])); +} + +/** + * Initialize Kohana, setting the default options. + * + * The following options are available: + * + * - string base_url path, and optionally domain, of your application NULL + * - string index_file name of your index file, usually "index.php" index.php + * - string charset internal character set used for input and output utf-8 + * - string cache_dir set the internal cache directory APPPATH/cache + * - integer cache_life lifetime, in seconds, of items cached 60 + * - boolean errors enable or disable error handling TRUE + * - boolean profile enable or disable internal profiling TRUE + * - boolean caching enable or disable internal caching FALSE + * - boolean expose set the X-Powered-By header FALSE + */ +Kohana::init(array( + 'base_url' => '/kohana/', +)); + +/** + * Attach the file write to logging. Multiple writers are supported. + */ +Kohana::$log->attach(new Log_File(APPPATH.'logs')); + +/** + * Attach a file reader to config. Multiple readers are supported. + */ +Kohana::$config->attach(new Config_File); + +/** + * Enable modules. Modules are referenced by a relative or absolute path. + */ +Kohana::modules(array( + // 'auth' => MODPATH.'auth', // Basic authentication + // 'cache' => MODPATH.'cache', // Caching with multiple backends + // 'codebench' => MODPATH.'codebench', // Benchmarking tool + // 'database' => MODPATH.'database', // Database access + // 'image' => MODPATH.'image', // Image manipulation + // 'minion' => MODPATH.'minion', // CLI Tasks + // 'orm' => MODPATH.'orm', // Object Relationship Mapping + // 'unittest' => MODPATH.'unittest', // Unit testing + // 'userguide' => MODPATH.'userguide', // User guide and API documentation + )); + +/** + * Set the routes. Each route must have a minimum of a name, a URI and a set of + * defaults for the URI. + */ +Route::set('default', '((/(/)))') + ->defaults(array( + 'controller' => 'welcome', + 'action' => 'index', + )); diff --git a/application/classes/Controller/Welcome.php b/application/classes/Controller/Welcome.php new file mode 100644 index 0000000..0984eff --- /dev/null +++ b/application/classes/Controller/Welcome.php @@ -0,0 +1,10 @@ +response->body('hello, world!'); + } + +} // End Welcome diff --git a/composer.json b/composer.json new file mode 100644 index 0000000..a473df1 --- /dev/null +++ b/composer.json @@ -0,0 +1,5 @@ +{ + "require": { + "phpunit/phpunit": "3.7.*" + } +} diff --git a/composer.lock b/composer.lock new file mode 100644 index 0000000..3fe1de8 --- /dev/null +++ b/composer.lock @@ -0,0 +1,413 @@ +{ + "hash": "11774bed2716724738d66bb56a8a1508", + "packages": [ + { + "name": "phpunit/php-code-coverage", + "version": "1.2.6", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/php-code-coverage.git", + "reference": "1.2.6" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/php-code-coverage/zipball/1.2.6", + "reference": "1.2.6", + "shasum": "" + }, + "require": { + "php": ">=5.3.3", + "phpunit/php-file-iterator": ">=1.3.0@stable", + "phpunit/php-token-stream": ">=1.1.3@stable", + "phpunit/php-text-template": ">=1.1.1@stable" + }, + "suggest": { + "ext-dom": "*", + "ext-xdebug": ">=2.0.5" + }, + "time": "2012-10-16 22:34:13", + "type": "library", + "installation-source": "dist", + "autoload": { + "classmap": [ + "PHP/" + ] + }, + "include-path": [ + "" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sb@sebastian-bergmann.de", + "role": "lead" + } + ], + "description": "Library that provides collection, processing, and rendering functionality for PHP code coverage information.", + "homepage": "https://github.com/sebastianbergmann/php-code-coverage", + "keywords": [ + "testing", + "coverage", + "xunit" + ] + }, + { + "name": "phpunit/php-file-iterator", + "version": "1.3.3", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/php-file-iterator.git", + "reference": "1.3.3" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/php-file-iterator/zipball/1.3.3", + "reference": "1.3.3", + "shasum": "" + }, + "require": { + "php": ">=5.3.3" + }, + "time": "2012-10-11 04:44:38", + "type": "library", + "installation-source": "dist", + "autoload": { + "classmap": [ + "File/" + ] + }, + "include-path": [ + "" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sb@sebastian-bergmann.de", + "role": "lead" + } + ], + "description": "FilterIterator implementation that filters files based on a list of suffixes.", + "homepage": "http://www.phpunit.de/", + "keywords": [ + "filesystem", + "iterator" + ] + }, + { + "name": "phpunit/php-text-template", + "version": "1.1.3", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/php-text-template.git", + "reference": "1.1.3" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/php-text-template/zipball/1.1.3", + "reference": "1.1.3", + "shasum": "" + }, + "require": { + "php": ">=5.3.3" + }, + "time": "2012-10-11 04:48:39", + "type": "library", + "installation-source": "dist", + "autoload": { + "classmap": [ + "Text/" + ] + }, + "include-path": [ + "" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sb@sebastian-bergmann.de", + "role": "lead" + } + ], + "description": "Simple template engine.", + "homepage": "http://www.phpunit.de/", + "keywords": [ + "template" + ] + }, + { + "name": "phpunit/php-timer", + "version": "1.0.4", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/php-timer.git", + "reference": "1.0.4" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/php-timer/zipball/1.0.4", + "reference": "1.0.4", + "shasum": "" + }, + "require": { + "php": ">=5.3.3" + }, + "time": "2012-10-11 04:45:58", + "type": "library", + "installation-source": "dist", + "autoload": { + "classmap": [ + "PHP/" + ] + }, + "include-path": [ + "" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sb@sebastian-bergmann.de", + "role": "lead" + } + ], + "description": "Utility class for timing", + "homepage": "http://www.phpunit.de/", + "keywords": [ + "timer" + ] + }, + { + "name": "phpunit/php-token-stream", + "version": "1.1.5", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/php-token-stream.git", + "reference": "1.1.5" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/php-token-stream/zipball/1.1.5", + "reference": "1.1.5", + "shasum": "" + }, + "require": { + "ext-tokenizer": "*", + "php": ">=5.3.3" + }, + "time": "2012-10-11 04:47:14", + "type": "library", + "installation-source": "dist", + "autoload": { + "classmap": [ + "PHP/" + ] + }, + "include-path": [ + "" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sb@sebastian-bergmann.de", + "role": "lead" + } + ], + "description": "Wrapper around PHP's tokenizer extension.", + "homepage": "http://www.phpunit.de/", + "keywords": [ + "tokenizer" + ] + }, + { + "name": "phpunit/phpunit", + "version": "3.7.8", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/phpunit.git", + "reference": "3.7.8" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/phpunit/zipball/3.7.8", + "reference": "3.7.8", + "shasum": "" + }, + "require": { + "php": ">=5.3.3", + "phpunit/php-file-iterator": ">=1.3.1", + "phpunit/php-text-template": ">=1.1.1", + "phpunit/php-code-coverage": ">=1.2.1", + "phpunit/php-timer": ">=1.0.2", + "phpunit/phpunit-mock-objects": ">=1.2.0", + "symfony/yaml": ">=2.1.0", + "ext-dom": "*", + "ext-pcre": "*", + "ext-reflection": "*", + "ext-spl": "*" + }, + "suggest": { + "phpunit/php-invoker": ">=1.1.0", + "ext-json": "*", + "ext-simplexml": "*", + "ext-tokenizer": "*" + }, + "time": "2012-10-16 22:37:08", + "bin": [ + "composer/bin/phpunit" + ], + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "3.7.x-dev" + } + }, + "installation-source": "dist", + "autoload": { + "classmap": [ + "PHPUnit/" + ] + }, + "include-path": [ + "", + "../../symfony/yaml/" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sebastian@phpunit.de", + "role": "lead" + } + ], + "description": "The PHP Unit Testing framework.", + "homepage": "http://www.phpunit.de/", + "keywords": [ + "testing", + "phpunit", + "xunit" + ] + }, + { + "name": "phpunit/phpunit-mock-objects", + "version": "1.2.1", + "source": { + "type": "git", + "url": "git://github.com/sebastianbergmann/phpunit-mock-objects.git", + "reference": "1.2.1" + }, + "dist": { + "type": "zip", + "url": "https://github.com/sebastianbergmann/phpunit-mock-objects/zipball/1.2.1", + "reference": "1.2.1", + "shasum": "" + }, + "require": { + "php": ">=5.3.3", + "phpunit/php-text-template": ">=1.1.1@stable", + "ext-reflection": "*", + "ext-spl": "*" + }, + "suggest": { + "ext-soap": "*" + }, + "time": "2012-10-05 00:00:00", + "type": "library", + "installation-source": "dist", + "autoload": { + "classmap": [ + "PHPUnit/" + ] + }, + "include-path": [ + "" + ], + "license": [ + "BSD-3-Clause" + ], + "authors": [ + { + "name": "Sebastian Bergmann", + "email": "sb@sebastian-bergmann.de", + "role": "lead" + } + ], + "description": "Mock Object library for PHPUnit", + "homepage": "http://www.phpunit.de/", + "keywords": [ + "mock", + "xunit" + ] + }, + { + "name": "symfony/yaml", + "version": "v2.1.2", + "target-dir": "Symfony/Component/Yaml", + "source": { + "type": "git", + "url": "https://github.com/symfony/Yaml", + "reference": "v2.1.0-RC2" + }, + "dist": { + "type": "zip", + "url": "https://github.com/symfony/Yaml/zipball/v2.1.0-RC2", + "reference": "v2.1.0-RC2", + "shasum": "" + }, + "require": { + "php": ">=5.3.3" + }, + "time": "2012-08-22 06:48:41", + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "2.1-dev" + } + }, + "installation-source": "dist", + "autoload": { + "psr-0": { + "Symfony\\Component\\Yaml": "" + } + }, + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Fabien Potencier", + "email": "fabien@symfony.com" + }, + { + "name": "Symfony Community", + "homepage": "http://symfony.com/contributors" + } + ], + "description": "Symfony Yaml Component", + "homepage": "http://symfony.com" + } + ], + "packages-dev": null, + "aliases": [ + + ], + "minimum-stability": "stable", + "stability-flags": [ + + ] +} diff --git a/composer.phar b/composer.phar new file mode 100644 index 0000000..7c83809 Binary files /dev/null and b/composer.phar differ diff --git a/example.htaccess b/example.htaccess new file mode 100644 index 0000000..53b8ccb --- /dev/null +++ b/example.htaccess @@ -0,0 +1,21 @@ +# Turn on URL rewriting +RewriteEngine On + +# Installation directory +RewriteBase / + +# Protect hidden files from being viewed + + Order Deny,Allow + Deny From All + + +# Protect application and system files from being viewed +RewriteRule ^(?:application|modules|system)\b.* index.php/$0 [L] + +# Allow any files or directories that exist to be displayed directly +RewriteCond %{REQUEST_FILENAME} !-f +RewriteCond %{REQUEST_FILENAME} !-d + +# Rewrite all other URLs to index.php/URL +RewriteRule .* index.php/$0 [PT] diff --git a/index.php b/index.php new file mode 100644 index 0000000..6c352aa --- /dev/null +++ b/index.php @@ -0,0 +1,121 @@ += 5.3, it is recommended to disable + * deprecated notices. Disable with: E_ALL & ~E_DEPRECATED + */ +error_reporting(E_ALL | E_STRICT); + +/** + * End of standard configuration! Changing any of the code below should only be + * attempted by those with a working knowledge of Kohana internals. + * + * @link http://kohanaframework.org/guide/using.configuration + */ + +// Set the full path to the docroot +define('DOCROOT', realpath(dirname(__FILE__)).DIRECTORY_SEPARATOR); + +// Make the application relative to the docroot, for symlink'd index.php +if ( ! is_dir($application) AND is_dir(DOCROOT.$application)) + $application = DOCROOT.$application; + +// Make the modules relative to the docroot, for symlink'd index.php +if ( ! is_dir($modules) AND is_dir(DOCROOT.$modules)) + $modules = DOCROOT.$modules; + +// Make the system relative to the docroot, for symlink'd index.php +if ( ! is_dir($system) AND is_dir(DOCROOT.$system)) + $system = DOCROOT.$system; + +// Define the absolute paths for configured directories +define('APPPATH', realpath($application).DIRECTORY_SEPARATOR); +define('MODPATH', realpath($modules).DIRECTORY_SEPARATOR); +define('SYSPATH', realpath($system).DIRECTORY_SEPARATOR); + +// Clean up the configuration vars +unset($application, $modules, $system); + +if (file_exists('install'.EXT)) +{ + // Load the installation check + return include 'install'.EXT; +} + +/** + * Define the start time of the application, used for profiling. + */ +if ( ! defined('KOHANA_START_TIME')) +{ + define('KOHANA_START_TIME', microtime(TRUE)); +} + +/** + * Define the memory usage at the start of the application, used for profiling. + */ +if ( ! defined('KOHANA_START_MEMORY')) +{ + define('KOHANA_START_MEMORY', memory_get_usage()); +} + +// Bootstrap the application +require APPPATH.'bootstrap'.EXT; + +if (PHP_SAPI == 'cli') // Try and load minion +{ + class_exists('Minion_Task') OR die('Please enable the Minion module for CLI support.'); + set_exception_handler(array('Minion_Exception', 'handler')); + + Minion_Task::factory(Minion_CLI::options())->execute(); +} +else +{ + /** + * Execute the main request. A source of the URI can be passed, eg: $_SERVER['PATH_INFO']. + * If no source is specified, the URI will be automatically detected. + */ + echo Request::factory(TRUE, array(), FALSE) + ->execute() + ->send_headers(TRUE) + ->body(); +} diff --git a/install.php b/install.php new file mode 100644 index 0000000..f654177 --- /dev/null +++ b/install.php @@ -0,0 +1,233 @@ + + + + + + + + Kohana Installation + + + + + + +

Environment Tests

+ +

+ The following tests have been run to determine if Kohana will work in your environment. + If any of the tests have failed, consult the documentation + for more information on how to correct the problem. +

+ + + + + + + =')): ?> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PHP VersionKohana requires PHP 5.3.3 or newer, this version is .
System DirectoryThe configured system directory does not exist or does not contain required files.
Application DirectoryThe configured application directory does not exist or does not contain required files.
Cache DirectoryThe directory is not writable.
Logs DirectoryThe directory is not writable.
PCRE UTF-8PCRE has not been compiled with UTF-8 support.PCRE has not been compiled with Unicode property support.Pass
SPL EnabledPassPHP SPL is either not loaded or not compiled in.
Reflection EnabledPassPHP reflection is either not loaded or not compiled in.
Filters EnabledPassThe filter extension is either not loaded or not compiled in.
Iconv Extension LoadedPassThe iconv extension is not loaded.
Mbstring Not OverloadedThe mbstring extension is overloading PHP's native string functions.Pass
Character Type (CTYPE) ExtensionThe ctype extension is not enabled.Pass
URI DeterminationPassNeither $_SERVER['REQUEST_URI'], $_SERVER['PHP_SELF'], or $_SERVER['PATH_INFO'] is available.
+ + +

✘ Kohana may not work correctly with your environment.

+ +

✔ Your environment passed all requirements.
+ Remove or rename the install file now.

+ + +

Optional Tests

+ +

+ The following extensions are not required to run the Kohana core, but if enabled can provide access to additional classes. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PECL HTTP EnabledPassKohana can use the http extension for the Request_Client_External class.
cURL EnabledPassKohana can use the cURL extension for the Request_Client_External class.
mcrypt EnabledPassKohana requires mcrypt for the Encrypt class.
GD EnabledPassKohana requires GD v2 for the Image class.
MySQL EnabledPassKohana can use the MySQL extension to support MySQL databases.
PDO EnabledPassKohana can use PDO to support additional databases.
+ + + diff --git a/modules/auth/README.md b/modules/auth/README.md new file mode 100644 index 0000000..27ac9cd --- /dev/null +++ b/modules/auth/README.md @@ -0,0 +1,13 @@ +New Age Auth +--- + +I've forked the main Auth module because there were some fundamental flaws with it: + + 1. It's trivial to [bruteforce](http://dev.kohanaframework.org/issues/3163) publicly hidden salt hashes. + - I've fixed this by switching the password hashing algorithm to the more secure secret-key based hash_hmac method. + 2. ORM drivers were included. + - I've fixed this by simply removing them. They cause confusion with new users because they think that Auth requires ORM. The only driver currently provided by default is the file driver. + 3. Auth::get_user()'s api is inconsistent because it returns different data types. + - I've fixed this by returning an empty user model by default. You can override what gets returned (if you've changed your user model class name for instance) by overloading the get_user() method in your application. + +These changes should be merged into the mainline branch eventually, but they completely break the API, so likely won't be done until 3.1. \ No newline at end of file diff --git a/modules/auth/classes/Auth.php b/modules/auth/classes/Auth.php new file mode 100644 index 0000000..8d31fad --- /dev/null +++ b/modules/auth/classes/Auth.php @@ -0,0 +1,3 @@ +load('auth'); + + if ( ! $type = $config->get('driver')) + { + $type = 'file'; + } + + // Set the session class name + $class = 'Auth_'.ucfirst($type); + + // Create a new session instance + Auth::$_instance = new $class($config); + } + + return Auth::$_instance; + } + + protected $_session; + + protected $_config; + + /** + * Loads Session and configuration options. + * + * @param array $config Config Options + * @return void + */ + public function __construct($config = array()) + { + // Save the config in the object + $this->_config = $config; + + $this->_session = Session::instance($this->_config['session_type']); + } + + abstract protected function _login($username, $password, $remember); + + abstract public function password($username); + + abstract public function check_password($password); + + /** + * Gets the currently logged in user from the session. + * Returns NULL if no user is currently logged in. + * + * @param mixed $default Default value to return if the user is currently not logged in. + * @return mixed + */ + public function get_user($default = NULL) + { + return $this->_session->get($this->_config['session_key'], $default); + } + + /** + * Attempt to log in a user by using an ORM object and plain-text password. + * + * @param string $username Username to log in + * @param string $password Password to check against + * @param boolean $remember Enable autologin + * @return boolean + */ + public function login($username, $password, $remember = FALSE) + { + if (empty($password)) + return FALSE; + + return $this->_login($username, $password, $remember); + } + + /** + * Log out a user by removing the related session variables. + * + * @param boolean $destroy Completely destroy the session + * @param boolean $logout_all Remove all tokens for user + * @return boolean + */ + public function logout($destroy = FALSE, $logout_all = FALSE) + { + if ($destroy === TRUE) + { + // Destroy the session completely + $this->_session->destroy(); + } + else + { + // Remove the user from the session + $this->_session->delete($this->_config['session_key']); + + // Regenerate session_id + $this->_session->regenerate(); + } + + // Double check + return ! $this->logged_in(); + } + + /** + * Check if there is an active session. Optionally allows checking for a + * specific role. + * + * @param string $role role name + * @return mixed + */ + public function logged_in($role = NULL) + { + return ($this->get_user() !== NULL); + } + + /** + * Creates a hashed hmac password from a plaintext password. This + * method is deprecated, [Auth::hash] should be used instead. + * + * @deprecated + * @param string $password Plaintext password + */ + public function hash_password($password) + { + return $this->hash($password); + } + + /** + * Perform a hmac hash, using the configured method. + * + * @param string $str string to hash + * @return string + */ + public function hash($str) + { + if ( ! $this->_config['hash_key']) + throw new Kohana_Exception('A valid hash key must be set in your auth config.'); + + return hash_hmac($this->_config['hash_method'], $str, $this->_config['hash_key']); + } + + protected function complete_login($user) + { + // Regenerate session_id + $this->_session->regenerate(); + + // Store username in session + $this->_session->set($this->_config['session_key'], $user); + + return TRUE; + } + +} // End Auth diff --git a/modules/auth/classes/Kohana/Auth/File.php b/modules/auth/classes/Kohana/Auth/File.php new file mode 100644 index 0000000..8640fde --- /dev/null +++ b/modules/auth/classes/Kohana/Auth/File.php @@ -0,0 +1,94 @@ +_users = Arr::get($config, 'users', array()); + } + + /** + * Logs a user in. + * + * @param string $username Username + * @param string $password Password + * @param boolean $remember Enable autologin (not supported) + * @return boolean + */ + protected function _login($username, $password, $remember) + { + if (is_string($password)) + { + // Create a hashed password + $password = $this->hash($password); + } + + if (isset($this->_users[$username]) AND $this->_users[$username] === $password) + { + // Complete the login + return $this->complete_login($username); + } + + // Login failed + return FALSE; + } + + /** + * Forces a user to be logged in, without specifying a password. + * + * @param mixed $username Username + * @return boolean + */ + public function force_login($username) + { + // Complete the login + return $this->complete_login($username); + } + + /** + * Get the stored password for a username. + * + * @param mixed $username Username + * @return string + */ + public function password($username) + { + return Arr::get($this->_users, $username, FALSE); + } + + /** + * Compare password with original (plain text). Works for current (logged in) user + * + * @param string $password Password + * @return boolean + */ + public function check_password($password) + { + $username = $this->get_user(); + + if ($username === FALSE) + { + return FALSE; + } + + return ($password === $this->password($username)); + } + +} // End Auth File diff --git a/modules/auth/config/auth.php b/modules/auth/config/auth.php new file mode 100644 index 0000000..837930d --- /dev/null +++ b/modules/auth/config/auth.php @@ -0,0 +1,17 @@ + 'File', + 'hash_method' => 'sha256', + 'hash_key' => NULL, + 'lifetime' => 1209600, + 'session_type' => Session::$default, + 'session_key' => 'auth_user', + + // Username/password combinations for the Auth File driver + 'users' => array( + // 'admin' => 'b3154acf3a344170077d11bdb5fff31532f679a1919e716a02', + ), + +); diff --git a/modules/auth/config/userguide.php b/modules/auth/config/userguide.php new file mode 100644 index 0000000..425e27c --- /dev/null +++ b/modules/auth/config/userguide.php @@ -0,0 +1,23 @@ + array( + + // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + 'auth' => array( + + // Whether this modules userguide pages should be shown + 'enabled' => TRUE, + + // The name that should show up on the userguide index page + 'name' => 'Auth', + + // A short description of this module, shown on the index page + 'description' => 'User authentication and authorization.', + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2008–2012 Kohana Team', + ) + ) +); \ No newline at end of file diff --git a/modules/auth/guide/auth/config.md b/modules/auth/guide/auth/config.md new file mode 100644 index 0000000..e411fa0 --- /dev/null +++ b/modules/auth/guide/auth/config.md @@ -0,0 +1,13 @@ +# Configuration + +The default configuration file is located in `MODPATH/auth/config/auth.php`. You should copy this file to `APPPATH/config/auth.php` and make changes there, in keeping with the [cascading filesystem](../kohana/files). + +[Config merging](../kohana/config#config-merging) allows these default configuration settings to apply if you don't overwrite them in your application configuration file. + +Name | Type | Default | Description +-----|------|---------|------------ +driver | `string` | file | The name of the auth driver to use. +hash_method | `string` | sha256 | The hashing function to use on the passwords. +hash_key | `string` | NULL | The key to use when hashing the password. +session_type | `string` | [Session::$default] | The type of session to use when storing the auth user. +session_key | `string` | auth_user | The name of the session variable used to save the user. diff --git a/modules/auth/guide/auth/driver/develop.md b/modules/auth/guide/auth/driver/develop.md new file mode 100644 index 0000000..a69a08c --- /dev/null +++ b/modules/auth/guide/auth/driver/develop.md @@ -0,0 +1,79 @@ +# Developing Drivers + +## Real World Example + +Sometimes the best way to learn is to jump right in and read the code from another module. The [ORM](https://github.com/kohana/orm/blob/3.2/develop/classes/kohana/auth/orm.php) module comes with an auth driver you can learn from. + +[!!] We will be developing an `example` driver. In your own driver you will substitute `example` with your driver name. + +This example file would be saved at `APPPATH/classes/auth/example.php` (or `MODPATH` if you are creating a module). + +--- + +## Quick Example + +First we will show you a quick example and then break down what is going on. + +~~~ +class Auth_Example extends Auth +{ + protected function _login($username, $password, $remember) + { + // Do username/password check here + } + + public function password($username) + { + // Return the password for the username + } + + public function check_password($password) + { + // Check to see if the logged in user has the given password + } + + public function logged_in($role = NULL) + { + // Check to see if the user is logged in, and if $role is set, has all roles + } + + public function get_user($default = NULL) + { + // Get the logged in user, or return the $default if a user is not found + } +} +~~~ + +## Extending Auth + +All drivers must extend the [Auth] class. + + class Auth_Example extends Auth + +## Abstract Methods + +The `Auth` class has 3 abstract methods that must be defined in your new driver. + +~~~ +abstract protected function _login($username, $password, $remember); + +abstract public function password($username); + +abstract public function check_password($user); +~~~ + +## Extending Functionality + +Given that every auth system is going to check if users exist and if they have roles or not you will more than likely have to change some default functionality. + +Here are a few functions that you should pay attention to. + +~~~ +public function logged_in($role = NULL) + +public function get_user($default = NULL) +~~~ + +## Activating the Driver + +After you create your driver you will want to use it. It is a easy as setting the `driver` [configuration](config) option to the name of your driver (in our case `example`). diff --git a/modules/auth/guide/auth/driver/file.md b/modules/auth/guide/auth/driver/file.md new file mode 100644 index 0000000..7a6fa09 --- /dev/null +++ b/modules/auth/guide/auth/driver/file.md @@ -0,0 +1,19 @@ +# File Driver + +The [Auth::File] driver is included with the auth module. + +Below are additional configuration options that can be set for this driver. + +Name | Type | Default | Description +-----|------|---------|------------- +users | `array` | array() | A user => password (_hashed_) array of all the users in your application + +## Forcing Login + +[Auth_File::force_login] allows you to force a user login without a password. + +~~~ +// Force the user with a username of admin to be logged into your application +Auth::instance()->force_login('admin'); +$user = Auth::instance()->get_user(); +~~~ diff --git a/modules/auth/guide/auth/index.md b/modules/auth/guide/auth/index.md new file mode 100644 index 0000000..18127e6 --- /dev/null +++ b/modules/auth/guide/auth/index.md @@ -0,0 +1,19 @@ +# Auth + +User authentication and authorization is provided by the auth module. + +The auth module is included with Kohana, but needs to be enabled before you can use it. To enable, open your `application/bootstrap.php` file and modify the call to [Kohana::modules] by including the auth module like so: + +~~~ +Kohana::modules(array( + ... + 'auth' => MODPATH.'auth', + ... +)); +~~~ + +Next, you will then need to [configure](config) the auth module. + +The auth module provides the [Auth::File] driver for you. There is also an auth driver included with the ORM module. + +As your application needs change you may need to find another driver or [develop](driver/develop) your own. diff --git a/modules/auth/guide/auth/login.md b/modules/auth/guide/auth/login.md new file mode 100644 index 0000000..1207b5d --- /dev/null +++ b/modules/auth/guide/auth/login.md @@ -0,0 +1,62 @@ +# Log in and out + +The auth module provides methods to help you log users in and out of your application. + +## Log in + +The [Auth::login] method handles the login. + +~~~ +// Handled from a form with inputs with names email / password +$post = $this->request->post(); +$success = Auth::instance()->login($post['email'], $post['password']); + +if ($success) +{ + // Login successful, send to app +} +else +{ + // Login failed, send back to form with error message +} +~~~ + +## Logged in User + +There are two ways to check if a user is logged in. If you just need to check if the user is logged in use [Auth::logged_in]. + +~~~ +if (Auth::instance()->logged_in()) +{ + // User is logged in, continue on +} +else +{ + // User isn't logged in, redirect to the login form. +} +~~~ + +You can also get the logged in user object by using [Auth::get_user]. If the user is null, then no user was found. + +~~~ +$user = Auth::instance()->get_user(); + +// Check for a user (NULL if not user is found) +if ($user !== null) +{ + // User is found, continue on +} +else +{ + // User was not found, redirect to the login form +} +~~~ + +## Log out + +The [Auth::logout] method will take care of logging out a user. + +~~~ +Auth::instance()->logout(); +// Redirect the user back to login page +~~~ diff --git a/modules/auth/guide/auth/menu.md b/modules/auth/guide/auth/menu.md new file mode 100644 index 0000000..23fc0ee --- /dev/null +++ b/modules/auth/guide/auth/menu.md @@ -0,0 +1,6 @@ +## [Auth]() +- [Configuration](config) +- [Log in and out](login) +- Drivers + - [File](driver/file) + - [Developing](driver/develop) diff --git a/modules/cache/README.md b/modules/cache/README.md new file mode 100644 index 0000000..7acff9c --- /dev/null +++ b/modules/cache/README.md @@ -0,0 +1,59 @@ +Kohana Cache library +==================== + +The cache library for Kohana 3 provides a simple interface to the most common cache solutions. Developers are free to add their own caching solutions that follow the cache design pattern defined within this module. + +Supported cache solutions +------------------------- + +Currently this module supports the following cache methods. + +1. APC +2. Memcache +3. Memcached-tags (Supports tags) +4. SQLite (Supports tags) +5. File +6. Wincache + +Planned support +--------------- + +In the near future, additional support for the following methods will be included. + +1. Memcached + +Introduction to caching +----------------------- + +To use caching to the maximum potential, your application should be designed with caching in mind from the outset. In general, the most effective caches contain lots of small collections of data that are the result of expensive computational operations, such as searching through a large data set. + +There are many different caching methods available for PHP, from the very basic file based caching to opcode caching in eAccelerator and APC. Caching engines that use physical memory over disk based storage are always faster, however many do not support more advanced features such as tagging. + +Using Cache +----------- + +To use Kohana Cache, download and extract the latest stable release of Kohana Cache from [Github](http://github.com/samsoir/kohana-cache). Place the module into your Kohana instances modules folder. Finally enable the module within the application bootstrap within the section entitled _modules_. + +Quick example +------------- + +The following is a quick example of how to use Kohana Cache. The example is using the SQLite driver. + + 'bar', 'apples' => 'pear', 'BDFL' => 'Shadowhand'); + + // Save the data to cache, with an id of test_id and a lifetime of 10 minutes + $mycache->set('test_id', $data, 600); + + // Retrieve the data from cache + $retrieved_data = $mycache->get('test_id'); + + // Remove the cache item + $mycache->delete('test_id'); + + // Clear the cache of all stored items + $mycache->delete_all(); diff --git a/modules/cache/classes/Cache.php b/modules/cache/classes/Cache.php new file mode 100644 index 0000000..2b43c93 --- /dev/null +++ b/modules/cache/classes/Cache.php @@ -0,0 +1,3 @@ + array( // Default group + * 'driver' => 'memcache', // using Memcache driver + * 'servers' => array( // Available server definitions + * array( + * 'host' => 'localhost', + * 'port' => 11211, + * 'persistent' => FALSE + * ) + * ), + * 'compression' => FALSE, // Use compression? + * ), + * ) + * + * In cases where only one cache group is required, if the group is named `default` there is + * no need to pass the group name when instantiating a cache instance. + * + * #### General cache group configuration settings + * + * Below are the settings available to all types of cache driver. + * + * Name | Required | Description + * -------------- | -------- | --------------------------------------------------------------- + * driver | __YES__ | (_string_) The driver type to use + * + * Details of the settings specific to each driver are available within the drivers documentation. + * + * ### System requirements + * + * * Kohana 3.0.x + * * PHP 5.2.4 or greater + * + * @package Kohana/Cache + * @category Base + * @version 2.0 + * @author Kohana Team + * @copyright (c) 2009-2012 Kohana Team + * @license http://kohanaphp.com/license + */ +abstract class Kohana_Cache { + + const DEFAULT_EXPIRE = 3600; + + /** + * @var string default driver to use + */ + public static $default = 'file'; + + /** + * @var Kohana_Cache instances + */ + public static $instances = array(); + + /** + * Creates a singleton of a Kohana Cache group. If no group is supplied + * the __default__ cache group is used. + * + * // Create an instance of the default group + * $default_group = Cache::instance(); + * + * // Create an instance of a group + * $foo_group = Cache::instance('foo'); + * + * // Access an instantiated group directly + * $foo_group = Cache::$instances['default']; + * + * @param string $group the name of the cache group to use [Optional] + * @return Cache + * @throws Cache_Exception + */ + public static function instance($group = NULL) + { + // If there is no group supplied + if ($group === NULL) + { + // Use the default setting + $group = Cache::$default; + } + + if (isset(Cache::$instances[$group])) + { + // Return the current group if initiated already + return Cache::$instances[$group]; + } + + $config = Kohana::$config->load('cache'); + + if ( ! $config->offsetExists($group)) + { + throw new Cache_Exception( + 'Failed to load Kohana Cache group: :group', + array(':group' => $group) + ); + } + + $config = $config->get($group); + + // Create a new cache type instance + $cache_class = 'Cache_'.ucfirst($config['driver']); + Cache::$instances[$group] = new $cache_class($config); + + // Return the instance + return Cache::$instances[$group]; + } + + /** + * @var Config + */ + protected $_config = array(); + + /** + * Ensures singleton pattern is observed, loads the default expiry + * + * @param array $config configuration + */ + protected function __construct(array $config) + { + $this->config($config); + } + + /** + * Getter and setter for the configuration. If no argument provided, the + * current configuration is returned. Otherwise the configuration is set + * to this class. + * + * // Overwrite all configuration + * $cache->config(array('driver' => 'memcache', '...')); + * + * // Set a new configuration setting + * $cache->config('servers', array( + * 'foo' => 'bar', + * '...' + * )); + * + * // Get a configuration setting + * $servers = $cache->config('servers); + * + * @param mixed key to set to array, either array or config path + * @param mixed value to associate with key + * @return mixed + */ + public function config($key = NULL, $value = NULL) + { + if ($key === NULL) + return $this->_config; + + if (is_array($key)) + { + $this->_config = $key; + } + else + { + if ($value === NULL) + return Arr::get($this->_config, $key); + + $this->_config[$key] = $value; + } + + return $this; + } + + /** + * Overload the __clone() method to prevent cloning + * + * @return void + * @throws Cache_Exception + */ + final public function __clone() + { + throw new Cache_Exception('Cloning of Kohana_Cache objects is forbidden'); + } + + /** + * Retrieve a cached value entry by id. + * + * // Retrieve cache entry from default group + * $data = Cache::instance()->get('foo'); + * + * // Retrieve cache entry from default group and return 'bar' if miss + * $data = Cache::instance()->get('foo', 'bar'); + * + * // Retrieve cache entry from memcache group + * $data = Cache::instance('memcache')->get('foo'); + * + * @param string $id id of cache to entry + * @param string $default default value to return if cache miss + * @return mixed + * @throws Cache_Exception + */ + abstract public function get($id, $default = NULL); + + /** + * Set a value to cache with id and lifetime + * + * $data = 'bar'; + * + * // Set 'bar' to 'foo' in default group, using default expiry + * Cache::instance()->set('foo', $data); + * + * // Set 'bar' to 'foo' in default group for 30 seconds + * Cache::instance()->set('foo', $data, 30); + * + * // Set 'bar' to 'foo' in memcache group for 10 minutes + * if (Cache::instance('memcache')->set('foo', $data, 600)) + * { + * // Cache was set successfully + * return + * } + * + * @param string $id id of cache entry + * @param string $data data to set to cache + * @param integer $lifetime lifetime in seconds + * @return boolean + */ + abstract public function set($id, $data, $lifetime = 3600); + + /** + * Delete a cache entry based on id + * + * // Delete 'foo' entry from the default group + * Cache::instance()->delete('foo'); + * + * // Delete 'foo' entry from the memcache group + * Cache::instance('memcache')->delete('foo') + * + * @param string $id id to remove from cache + * @return boolean + */ + abstract public function delete($id); + + /** + * Delete all cache entries. + * + * Beware of using this method when + * using shared memory cache systems, as it will wipe every + * entry within the system for all clients. + * + * // Delete all cache entries in the default group + * Cache::instance()->delete_all(); + * + * // Delete all cache entries in the memcache group + * Cache::instance('memcache')->delete_all(); + * + * @return boolean + */ + abstract public function delete_all(); + + /** + * Replaces troublesome characters with underscores. + * + * // Sanitize a cache id + * $id = $this->_sanitize_id($id); + * + * @param string $id id of cache to sanitize + * @return string + */ + protected function _sanitize_id($id) + { + // Change slashes and spaces to underscores + return str_replace(array('/', '\\', ' '), '_', $id); + } +} +// End Kohana_Cache diff --git a/modules/cache/classes/Kohana/Cache/Apc.php b/modules/cache/classes/Kohana/Cache/Apc.php new file mode 100644 index 0000000..acefcc8 --- /dev/null +++ b/modules/cache/classes/Kohana/Cache/Apc.php @@ -0,0 +1,166 @@ + array( // Driver group + * 'driver' => 'apc', // using APC driver + * ), + * ) + * + * In cases where only one cache group is required, if the group is named `default` there is + * no need to pass the group name when instantiating a cache instance. + * + * #### General cache group configuration settings + * + * Below are the settings available to all types of cache driver. + * + * Name | Required | Description + * -------------- | -------- | --------------------------------------------------------------- + * driver | __YES__ | (_string_) The driver type to use + * + * ### System requirements + * + * * Kohana 3.0.x + * * PHP 5.2.4 or greater + * * APC PHP extension + * + * @package Kohana/Cache + * @category Base + * @author Kohana Team + * @copyright (c) 2009-2012 Kohana Team + * @license http://kohanaphp.com/license + */ +class Kohana_Cache_Apc extends Cache implements Cache_Arithmetic { + + /** + * Check for existence of the APC extension This method cannot be invoked externally. The driver must + * be instantiated using the `Cache::instance()` method. + * + * @param array $config configuration + * @throws Cache_Exception + */ + protected function __construct(array $config) + { + if ( ! extension_loaded('apc')) + { + throw new Cache_Exception('PHP APC extension is not available.'); + } + + parent::__construct($config); + } + + /** + * Retrieve a cached value entry by id. + * + * // Retrieve cache entry from apc group + * $data = Cache::instance('apc')->get('foo'); + * + * // Retrieve cache entry from apc group and return 'bar' if miss + * $data = Cache::instance('apc')->get('foo', 'bar'); + * + * @param string $id id of cache to entry + * @param string $default default value to return if cache miss + * @return mixed + * @throws Cache_Exception + */ + public function get($id, $default = NULL) + { + $data = apc_fetch($this->_sanitize_id($id), $success); + + return $success ? $data : $default; + } + + /** + * Set a value to cache with id and lifetime + * + * $data = 'bar'; + * + * // Set 'bar' to 'foo' in apc group, using default expiry + * Cache::instance('apc')->set('foo', $data); + * + * // Set 'bar' to 'foo' in apc group for 30 seconds + * Cache::instance('apc')->set('foo', $data, 30); + * + * @param string $id id of cache entry + * @param string $data data to set to cache + * @param integer $lifetime lifetime in seconds + * @return boolean + */ + public function set($id, $data, $lifetime = NULL) + { + if ($lifetime === NULL) + { + $lifetime = Arr::get($this->_config, 'default_expire', Cache::DEFAULT_EXPIRE); + } + + return apc_store($this->_sanitize_id($id), $data, $lifetime); + } + + /** + * Delete a cache entry based on id + * + * // Delete 'foo' entry from the apc group + * Cache::instance('apc')->delete('foo'); + * + * @param string $id id to remove from cache + * @return boolean + */ + public function delete($id) + { + return apc_delete($this->_sanitize_id($id)); + } + + /** + * Delete all cache entries. + * + * Beware of using this method when + * using shared memory cache systems, as it will wipe every + * entry within the system for all clients. + * + * // Delete all cache entries in the apc group + * Cache::instance('apc')->delete_all(); + * + * @return boolean + */ + public function delete_all() + { + return apc_clear_cache('user'); + } + + /** + * Increments a given value by the step value supplied. + * Useful for shared counters and other persistent integer based + * tracking. + * + * @param string id of cache entry to increment + * @param int step value to increment by + * @return integer + * @return boolean + */ + public function increment($id, $step = 1) + { + return apc_inc($id, $step); + } + + /** + * Decrements a given value by the step value supplied. + * Useful for shared counters and other persistent integer based + * tracking. + * + * @param string id of cache entry to decrement + * @param int step value to decrement by + * @return integer + * @return boolean + */ + public function decrement($id, $step = 1) + { + return apc_dec($id, $step); + } + +} // End Kohana_Cache_Apc diff --git a/modules/cache/classes/Kohana/Cache/Arithmetic.php b/modules/cache/classes/Kohana/Cache/Arithmetic.php new file mode 100644 index 0000000..1bdfb31 --- /dev/null +++ b/modules/cache/classes/Kohana/Cache/Arithmetic.php @@ -0,0 +1,39 @@ + array( // File driver group + * 'driver' => 'file', // using File driver + * 'cache_dir' => APPPATH.'cache/.kohana_cache', // Cache location + * ), + * ) + * + * In cases where only one cache group is required, if the group is named `default` there is + * no need to pass the group name when instantiating a cache instance. + * + * #### General cache group configuration settings + * + * Below are the settings available to all types of cache driver. + * + * Name | Required | Description + * -------------- | -------- | --------------------------------------------------------------- + * driver | __YES__ | (_string_) The driver type to use + * cache_dir | __NO__ | (_string_) The cache directory to use for this cache instance + * + * ### System requirements + * + * * Kohana 3.0.x + * * PHP 5.2.4 or greater + * + * @package Kohana/Cache + * @category Base + * @author Kohana Team + * @copyright (c) 2009-2012 Kohana Team + * @license http://kohanaphp.com/license + */ +class Kohana_Cache_File extends Cache implements Cache_GarbageCollect { + + /** + * Creates a hashed filename based on the string. This is used + * to create shorter unique IDs for each cache filename. + * + * // Create the cache filename + * $filename = Cache_File::filename($this->_sanitize_id($id)); + * + * @param string $string string to hash into filename + * @return string + */ + protected static function filename($string) + { + return sha1($string).'.cache'; + } + + /** + * @var string the caching directory + */ + protected $_cache_dir; + + /** + * Constructs the file cache driver. This method cannot be invoked externally. The file cache driver must + * be instantiated using the `Cache::instance()` method. + * + * @param array $config config + * @throws Cache_Exception + */ + protected function __construct(array $config) + { + // Setup parent + parent::__construct($config); + + try + { + $directory = Arr::get($this->_config, 'cache_dir', Kohana::$cache_dir); + $this->_cache_dir = new SplFileInfo($directory); + } + // PHP < 5.3 exception handle + catch (ErrorException $e) + { + $this->_cache_dir = $this->_make_directory($directory, 0777, TRUE); + } + // PHP >= 5.3 exception handle + catch (UnexpectedValueException $e) + { + $this->_cache_dir = $this->_make_directory($directory, 0777, TRUE); + } + + // If the defined directory is a file, get outta here + if ($this->_cache_dir->isFile()) + { + throw new Cache_Exception('Unable to create cache directory as a file already exists : :resource', array(':resource' => $this->_cache_dir->getRealPath())); + } + + // Check the read status of the directory + if ( ! $this->_cache_dir->isReadable()) + { + throw new Cache_Exception('Unable to read from the cache directory :resource', array(':resource' => $this->_cache_dir->getRealPath())); + } + + // Check the write status of the directory + if ( ! $this->_cache_dir->isWritable()) + { + throw new Cache_Exception('Unable to write to the cache directory :resource', array(':resource' => $this->_cache_dir->getRealPath())); + } + } + + /** + * Retrieve a cached value entry by id. + * + * // Retrieve cache entry from file group + * $data = Cache::instance('file')->get('foo'); + * + * // Retrieve cache entry from file group and return 'bar' if miss + * $data = Cache::instance('file')->get('foo', 'bar'); + * + * @param string $id id of cache to entry + * @param string $default default value to return if cache miss + * @return mixed + * @throws Cache_Exception + */ + public function get($id, $default = NULL) + { + $filename = Cache_File::filename($this->_sanitize_id($id)); + $directory = $this->_resolve_directory($filename); + + // Wrap operations in try/catch to handle notices + try + { + // Open file + $file = new SplFileInfo($directory.$filename); + + // If file does not exist + if ( ! $file->isFile()) + { + // Return default value + return $default; + } + else + { + // Open the file and parse data + $created = $file->getMTime(); + $data = $file->openFile(); + $lifetime = $data->fgets(); + + // If we're at the EOF at this point, corrupted! + if ($data->eof()) + { + throw new Cache_Exception(__METHOD__.' corrupted cache file!'); + } + + $cache = ''; + + while ($data->eof() === FALSE) + { + $cache .= $data->fgets(); + } + + // Test the expiry + if (($created + (int) $lifetime) < time()) + { + // Delete the file + $this->_delete_file($file, NULL, TRUE); + return $default; + } + else + { + return unserialize($cache); + } + } + + } + catch (ErrorException $e) + { + // Handle ErrorException caused by failed unserialization + if ($e->getCode() === E_NOTICE) + { + throw new Cache_Exception(__METHOD__.' failed to unserialize cached object with message : '.$e->getMessage()); + } + + // Otherwise throw the exception + throw $e; + } + } + + /** + * Set a value to cache with id and lifetime + * + * $data = 'bar'; + * + * // Set 'bar' to 'foo' in file group, using default expiry + * Cache::instance('file')->set('foo', $data); + * + * // Set 'bar' to 'foo' in file group for 30 seconds + * Cache::instance('file')->set('foo', $data, 30); + * + * @param string $id id of cache entry + * @param string $data data to set to cache + * @param integer $lifetime lifetime in seconds + * @return boolean + */ + public function set($id, $data, $lifetime = NULL) + { + $filename = Cache_File::filename($this->_sanitize_id($id)); + $directory = $this->_resolve_directory($filename); + + // If lifetime is NULL + if ($lifetime === NULL) + { + // Set to the default expiry + $lifetime = Arr::get($this->_config, 'default_expire', Cache::DEFAULT_EXPIRE); + } + + // Open directory + $dir = new SplFileInfo($directory); + + // If the directory path is not a directory + if ( ! $dir->isDir()) + { + // Create the directory + if ( ! mkdir($directory, 0777, TRUE)) + { + throw new Cache_Exception(__METHOD__.' unable to create directory : :directory', array(':directory' => $directory)); + } + + // chmod to solve potential umask issues + chmod($directory, 0777); + } + + // Open file to inspect + $resouce = new SplFileInfo($directory.$filename); + $file = $resouce->openFile('w'); + + try + { + $data = $lifetime."\n".serialize($data); + $file->fwrite($data, strlen($data)); + return (bool) $file->fflush(); + } + catch (ErrorException $e) + { + // If serialize through an error exception + if ($e->getCode() === E_NOTICE) + { + // Throw a caching error + throw new Cache_Exception(__METHOD__.' failed to serialize data for caching with message : '.$e->getMessage()); + } + + // Else rethrow the error exception + throw $e; + } + } + + /** + * Delete a cache entry based on id + * + * // Delete 'foo' entry from the file group + * Cache::instance('file')->delete('foo'); + * + * @param string $id id to remove from cache + * @return boolean + */ + public function delete($id) + { + $filename = Cache_File::filename($this->_sanitize_id($id)); + $directory = $this->_resolve_directory($filename); + + return $this->_delete_file(new SplFileInfo($directory.$filename), NULL, TRUE); + } + + /** + * Delete all cache entries. + * + * Beware of using this method when + * using shared memory cache systems, as it will wipe every + * entry within the system for all clients. + * + * // Delete all cache entries in the file group + * Cache::instance('file')->delete_all(); + * + * @return boolean + */ + public function delete_all() + { + return $this->_delete_file($this->_cache_dir, TRUE); + } + + /** + * Garbage collection method that cleans any expired + * cache entries from the cache. + * + * @return void + */ + public function garbage_collect() + { + $this->_delete_file($this->_cache_dir, TRUE, FALSE, TRUE); + return; + } + + /** + * Deletes files recursively and returns FALSE on any errors + * + * // Delete a file or folder whilst retaining parent directory and ignore all errors + * $this->_delete_file($folder, TRUE, TRUE); + * + * @param SplFileInfo $file file + * @param boolean $retain_parent_directory retain the parent directory + * @param boolean $ignore_errors ignore_errors to prevent all exceptions interrupting exec + * @param boolean $only_expired only expired files + * @return boolean + * @throws Cache_Exception + */ + protected function _delete_file(SplFileInfo $file, $retain_parent_directory = FALSE, $ignore_errors = FALSE, $only_expired = FALSE) + { + // Allow graceful error handling + try + { + // If is file + if ($file->isFile()) + { + try + { + // Handle ignore files + if (in_array($file->getFilename(), $this->config('ignore_on_delete'))) + { + $delete = FALSE; + } + // If only expired is not set + elseif ($only_expired === FALSE) + { + // We want to delete the file + $delete = TRUE; + } + // Otherwise... + else + { + // Assess the file expiry to flag it for deletion + $json = $file->openFile('r')->current(); + $data = json_decode($json); + $delete = $data->expiry < time(); + } + + // If the delete flag is set delete file + if ($delete === TRUE) + return unlink($file->getRealPath()); + else + return FALSE; + } + catch (ErrorException $e) + { + // Catch any delete file warnings + if ($e->getCode() === E_WARNING) + { + throw new Cache_Exception(__METHOD__.' failed to delete file : :file', array(':file' => $file->getRealPath())); + } + } + } + // Else, is directory + elseif ($file->isDir()) + { + // Create new DirectoryIterator + $files = new DirectoryIterator($file->getPathname()); + + // Iterate over each entry + while ($files->valid()) + { + // Extract the entry name + $name = $files->getFilename(); + + // If the name is not a dot + if ($name != '.' AND $name != '..') + { + // Create new file resource + $fp = new SplFileInfo($files->getRealPath()); + // Delete the file + $this->_delete_file($fp); + } + + // Move the file pointer on + $files->next(); + } + + // If set to retain parent directory, return now + if ($retain_parent_directory) + { + return TRUE; + } + + try + { + // Remove the files iterator + // (fixes Windows PHP which has permission issues with open iterators) + unset($files); + + // Try to remove the parent directory + return rmdir($file->getRealPath()); + } + catch (ErrorException $e) + { + // Catch any delete directory warnings + if ($e->getCode() === E_WARNING) + { + throw new Cache_Exception(__METHOD__.' failed to delete directory : :directory', array(':directory' => $file->getRealPath())); + } + throw $e; + } + } + else + { + // We get here if a file has already been deleted + return FALSE; + } + } + // Catch all exceptions + catch (Exception $e) + { + // If ignore_errors is on + if ($ignore_errors === TRUE) + { + // Return + return FALSE; + } + // Throw exception + throw $e; + } + } + + /** + * Resolves the cache directory real path from the filename + * + * // Get the realpath of the cache folder + * $realpath = $this->_resolve_directory($filename); + * + * @param string $filename filename to resolve + * @return string + */ + protected function _resolve_directory($filename) + { + return $this->_cache_dir->getRealPath().DIRECTORY_SEPARATOR.$filename[0].$filename[1].DIRECTORY_SEPARATOR; + } + + /** + * Makes the cache directory if it doesn't exist. Simply a wrapper for + * `mkdir` to ensure DRY principles + * + * @link http://php.net/manual/en/function.mkdir.php + * @param string $directory + * @param integer $mode + * @param boolean $recursive + * @param resource $context + * @return SplFileInfo + * @throws Cache_Exception + */ + protected function _make_directory($directory, $mode = 0777, $recursive = FALSE, $context = NULL) + { + if ( ! mkdir($directory, $mode, $recursive, $context)) + { + throw new Cache_Exception('Failed to create the defined cache directory : :directory', array(':directory' => $directory)); + } + chmod($directory, $mode); + + return new SplFileInfo($directory); + } +} diff --git a/modules/cache/classes/Kohana/Cache/GarbageCollect.php b/modules/cache/classes/Kohana/Cache/GarbageCollect.php new file mode 100644 index 0000000..c0bc519 --- /dev/null +++ b/modules/cache/classes/Kohana/Cache/GarbageCollect.php @@ -0,0 +1,23 @@ + array( // Default group + * 'driver' => 'memcache', // using Memcache driver + * 'servers' => array( // Available server definitions + * // First memcache server server + * array( + * 'host' => 'localhost', + * 'port' => 11211, + * 'persistent' => FALSE + * 'weight' => 1, + * 'timeout' => 1, + * 'retry_interval' => 15, + * 'status' => TRUE, + * 'instant_death' => TRUE, + * 'failure_callback' => array('className', 'classMethod') + * ), + * // Second memcache server + * array( + * 'host' => '192.168.1.5', + * 'port' => 22122, + * 'persistent' => TRUE + * ) + * ), + * 'compression' => FALSE, // Use compression? + * ), + * ) + * + * In cases where only one cache group is required, if the group is named `default` there is + * no need to pass the group name when instantiating a cache instance. + * + * #### General cache group configuration settings + * + * Below are the settings available to all types of cache driver. + * + * Name | Required | Description + * -------------- | -------- | --------------------------------------------------------------- + * driver | __YES__ | (_string_) The driver type to use + * servers | __YES__ | (_array_) Associative array of server details, must include a __host__ key. (see _Memcache server configuration_ below) + * compression | __NO__ | (_boolean_) Use data compression when caching + * + * #### Memcache server configuration + * + * The following settings should be used when defining each memcache server + * + * Name | Required | Description + * ---------------- | -------- | --------------------------------------------------------------- + * host | __YES__ | (_string_) The host of the memcache server, i.e. __localhost__; or __127.0.0.1__; or __memcache.domain.tld__ + * port | __NO__ | (_integer_) Point to the port where memcached is listening for connections. Set this parameter to 0 when using UNIX domain sockets. Default __11211__ + * persistent | __NO__ | (_boolean_) Controls the use of a persistent connection. Default __TRUE__ + * weight | __NO__ | (_integer_) Number of buckets to create for this server which in turn control its probability of it being selected. The probability is relative to the total weight of all servers. Default __1__ + * timeout | __NO__ | (_integer_) Value in seconds which will be used for connecting to the daemon. Think twice before changing the default value of 1 second - you can lose all the advantages of caching if your connection is too slow. Default __1__ + * retry_interval | __NO__ | (_integer_) Controls how often a failed server will be retried, the default value is 15 seconds. Setting this parameter to -1 disables automatic retry. Default __15__ + * status | __NO__ | (_boolean_) Controls if the server should be flagged as online. Default __TRUE__ + * failure_callback | __NO__ | (_[callback](http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback)_) Allows the user to specify a callback function to run upon encountering an error. The callback is run before failover is attempted. The function takes two parameters, the hostname and port of the failed server. Default __NULL__ + * + * ### System requirements + * + * * Kohana 3.0.x + * * PHP 5.2.4 or greater + * * Memcache (plus Memcached-tags for native tagging support) + * * Zlib + * + * @package Kohana/Cache + * @category Base + * @version 2.0 + * @author Kohana Team + * @copyright (c) 2009-2012 Kohana Team + * @license http://kohanaphp.com/license + */ +class Kohana_Cache_Memcache extends Cache implements Cache_Arithmetic { + + // Memcache has a maximum cache lifetime of 30 days + const CACHE_CEILING = 2592000; + + /** + * Memcache resource + * + * @var Memcache + */ + protected $_memcache; + + /** + * Flags to use when storing values + * + * @var string + */ + protected $_flags; + + /** + * The default configuration for the memcached server + * + * @var array + */ + protected $_default_config = array(); + + /** + * Constructs the memcache Kohana_Cache object + * + * @param array $config configuration + * @throws Cache_Exception + */ + protected function __construct(array $config) + { + // Check for the memcache extention + if ( ! extension_loaded('memcache')) + { + throw new Cache_Exception('Memcache PHP extention not loaded'); + } + + parent::__construct($config); + + // Setup Memcache + $this->_memcache = new Memcache; + + // Load servers from configuration + $servers = Arr::get($this->_config, 'servers', NULL); + + if ( ! $servers) + { + // Throw an exception if no server found + throw new Cache_Exception('No Memcache servers defined in configuration'); + } + + // Setup default server configuration + $this->_default_config = array( + 'host' => 'localhost', + 'port' => 11211, + 'persistent' => FALSE, + 'weight' => 1, + 'timeout' => 1, + 'retry_interval' => 15, + 'status' => TRUE, + 'instant_death' => TRUE, + 'failure_callback' => array($this, '_failed_request'), + ); + + // Add the memcache servers to the pool + foreach ($servers as $server) + { + // Merge the defined config with defaults + $server += $this->_default_config; + + if ( ! $this->_memcache->addServer($server['host'], $server['port'], $server['persistent'], $server['weight'], $server['timeout'], $server['retry_interval'], $server['status'], $server['failure_callback'])) + { + throw new Cache_Exception('Memcache could not connect to host \':host\' using port \':port\'', array(':host' => $server['host'], ':port' => $server['port'])); + } + } + + // Setup the flags + $this->_flags = Arr::get($this->_config, 'compression', FALSE) ? MEMCACHE_COMPRESSED : FALSE; + } + + /** + * Retrieve a cached value entry by id. + * + * // Retrieve cache entry from memcache group + * $data = Cache::instance('memcache')->get('foo'); + * + * // Retrieve cache entry from memcache group and return 'bar' if miss + * $data = Cache::instance('memcache')->get('foo', 'bar'); + * + * @param string $id id of cache to entry + * @param string $default default value to return if cache miss + * @return mixed + * @throws Cache_Exception + */ + public function get($id, $default = NULL) + { + // Get the value from Memcache + $value = $this->_memcache->get($this->_sanitize_id($id)); + + // If the value wasn't found, normalise it + if ($value === FALSE) + { + $value = (NULL === $default) ? NULL : $default; + } + + // Return the value + return $value; + } + + /** + * Set a value to cache with id and lifetime + * + * $data = 'bar'; + * + * // Set 'bar' to 'foo' in memcache group for 10 minutes + * if (Cache::instance('memcache')->set('foo', $data, 600)) + * { + * // Cache was set successfully + * return + * } + * + * @param string $id id of cache entry + * @param mixed $data data to set to cache + * @param integer $lifetime lifetime in seconds, maximum value 2592000 + * @return boolean + */ + public function set($id, $data, $lifetime = 3600) + { + // If the lifetime is greater than the ceiling + if ($lifetime > Cache_Memcache::CACHE_CEILING) + { + // Set the lifetime to maximum cache time + $lifetime = Cache_Memcache::CACHE_CEILING + time(); + } + // Else if the lifetime is greater than zero + elseif ($lifetime > 0) + { + $lifetime += time(); + } + // Else + else + { + // Normalise the lifetime + $lifetime = 0; + } + + // Set the data to memcache + return $this->_memcache->set($this->_sanitize_id($id), $data, $this->_flags, $lifetime); + } + + /** + * Delete a cache entry based on id + * + * // Delete the 'foo' cache entry immediately + * Cache::instance('memcache')->delete('foo'); + * + * // Delete the 'bar' cache entry after 30 seconds + * Cache::instance('memcache')->delete('bar', 30); + * + * @param string $id id of entry to delete + * @param integer $timeout timeout of entry, if zero item is deleted immediately, otherwise the item will delete after the specified value in seconds + * @return boolean + */ + public function delete($id, $timeout = 0) + { + // Delete the id + return $this->_memcache->delete($this->_sanitize_id($id), $timeout); + } + + /** + * Delete all cache entries. + * + * Beware of using this method when + * using shared memory cache systems, as it will wipe every + * entry within the system for all clients. + * + * // Delete all cache entries in the default group + * Cache::instance('memcache')->delete_all(); + * + * @return boolean + */ + public function delete_all() + { + $result = $this->_memcache->flush(); + + // We must sleep after flushing, or overwriting will not work! + // @see http://php.net/manual/en/function.memcache-flush.php#81420 + sleep(1); + + return $result; + } + + /** + * Callback method for Memcache::failure_callback to use if any Memcache call + * on a particular server fails. This method switches off that instance of the + * server if the configuration setting `instant_death` is set to `TRUE`. + * + * @param string $hostname + * @param integer $port + * @return void|boolean + * @since 3.0.8 + */ + public function _failed_request($hostname, $port) + { + if ( ! $this->_config['instant_death']) + return; + + // Setup non-existent host + $host = FALSE; + + // Get host settings from configuration + foreach ($this->_config['servers'] as $server) + { + // Merge the defaults, since they won't always be set + $server += $this->_default_config; + // We're looking at the failed server + if ($hostname == $server['host'] and $port == $server['port']) + { + // Server to disable, since it failed + $host = $server; + continue; + } + } + + if ( ! $host) + return; + else + { + return $this->_memcache->setServerParams( + $host['host'], + $host['port'], + $host['timeout'], + $host['retry_interval'], + FALSE, // Server is offline + array($this, '_failed_request' + )); + } + } + + /** + * Increments a given value by the step value supplied. + * Useful for shared counters and other persistent integer based + * tracking. + * + * @param string id of cache entry to increment + * @param int step value to increment by + * @return integer + * @return boolean + */ + public function increment($id, $step = 1) + { + return $this->_memcache->increment($id, $step); + } + + /** + * Decrements a given value by the step value supplied. + * Useful for shared counters and other persistent integer based + * tracking. + * + * @param string id of cache entry to decrement + * @param int step value to decrement by + * @return integer + * @return boolean + */ + public function decrement($id, $step = 1) + { + return $this->_memcache->decrement($id, $step); + } +} \ No newline at end of file diff --git a/modules/cache/classes/Kohana/Cache/MemcacheTag.php b/modules/cache/classes/Kohana/Cache/MemcacheTag.php new file mode 100644 index 0000000..644e543 --- /dev/null +++ b/modules/cache/classes/Kohana/Cache/MemcacheTag.php @@ -0,0 +1,78 @@ +_memcache, 'tag_add')) + { + throw new Cache_Exception('Memcached-tags PHP plugin not present. Please see http://code.google.com/p/memcached-tags/ for more information'); + } + } + + /** + * Set a value based on an id with tags + * + * @param string $id id + * @param mixed $data data + * @param integer $lifetime lifetime [Optional] + * @param array $tags tags [Optional] + * @return boolean + */ + public function set_with_tags($id, $data, $lifetime = NULL, array $tags = NULL) + { + $id = $this->_sanitize_id($id); + + $result = $this->set($id, $data, $lifetime); + + if ($result and $tags) + { + foreach ($tags as $tag) + { + $this->_memcache->tag_add($tag, $id); + } + } + + return $result; + } + + /** + * Delete cache entries based on a tag + * + * @param string $tag tag + * @return boolean + */ + public function delete_tag($tag) + { + return $this->_memcache->tag_delete($tag); + } + + /** + * Find cache entries based on a tag + * + * @param string $tag tag + * @return void + * @throws Cache_Exception + */ + public function find($tag) + { + throw new Cache_Exception('Memcached-tags does not support finding by tag'); + } +} diff --git a/modules/cache/classes/Kohana/Cache/Sqlite.php b/modules/cache/classes/Kohana/Cache/Sqlite.php new file mode 100644 index 0000000..932704a --- /dev/null +++ b/modules/cache/classes/Kohana/Cache/Sqlite.php @@ -0,0 +1,334 @@ +_config, 'database', NULL); + + if ($database === NULL) + { + throw new Cache_Exception('Database path not available in Kohana Cache configuration'); + } + + // Load new Sqlite DB + $this->_db = new PDO('sqlite:'.$database); + + // Test for existing DB + $result = $this->_db->query("SELECT * FROM sqlite_master WHERE name = 'caches' AND type = 'table'")->fetchAll(); + + // If there is no table, create a new one + if (0 == count($result)) + { + $database_schema = Arr::get($this->_config, 'schema', NULL); + + if ($database_schema === NULL) + { + throw new Cache_Exception('Database schema not found in Kohana Cache configuration'); + } + + try + { + // Create the caches table + $this->_db->query(Arr::get($this->_config, 'schema', NULL)); + } + catch (PDOException $e) + { + throw new Cache_Exception('Failed to create new SQLite caches table with the following error : :error', array(':error' => $e->getMessage())); + } + } + } + + /** + * Retrieve a value based on an id + * + * @param string $id id + * @param string $default default [Optional] Default value to return if id not found + * @return mixed + * @throws Cache_Exception + */ + public function get($id, $default = NULL) + { + // Prepare statement + $statement = $this->_db->prepare('SELECT id, expiration, cache FROM caches WHERE id = :id LIMIT 0, 1'); + + // Try and load the cache based on id + try + { + $statement->execute(array(':id' => $this->_sanitize_id($id))); + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + if ( ! $result = $statement->fetch(PDO::FETCH_OBJ)) + { + return $default; + } + + // If the cache has expired + if ($result->expiration != 0 and $result->expiration <= time()) + { + // Delete it and return default value + $this->delete($id); + return $default; + } + // Otherwise return cached object + else + { + // Disable notices for unserializing + $ER = error_reporting(~E_NOTICE); + + // Return the valid cache data + $data = unserialize($result->cache); + + // Turn notices back on + error_reporting($ER); + + // Return the resulting data + return $data; + } + } + + /** + * Set a value based on an id. Optionally add tags. + * + * @param string $id id + * @param mixed $data data + * @param integer $lifetime lifetime [Optional] + * @return boolean + */ + public function set($id, $data, $lifetime = NULL) + { + return (bool) $this->set_with_tags($id, $data, $lifetime); + } + + /** + * Delete a cache entry based on id + * + * @param string $id id + * @return boolean + * @throws Cache_Exception + */ + public function delete($id) + { + // Prepare statement + $statement = $this->_db->prepare('DELETE FROM caches WHERE id = :id'); + + // Remove the entry + try + { + $statement->execute(array(':id' => $this->_sanitize_id($id))); + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + return (bool) $statement->rowCount(); + } + + /** + * Delete all cache entries + * + * @return boolean + */ + public function delete_all() + { + // Prepare statement + $statement = $this->_db->prepare('DELETE FROM caches'); + + // Remove the entry + try + { + $statement->execute(); + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + return (bool) $statement->rowCount(); + } + + /** + * Set a value based on an id. Optionally add tags. + * + * @param string $id id + * @param mixed $data data + * @param integer $lifetime lifetime [Optional] + * @param array $tags tags [Optional] + * @return boolean + * @throws Cache_Exception + */ + public function set_with_tags($id, $data, $lifetime = NULL, array $tags = NULL) + { + // Serialize the data + $data = serialize($data); + + // Normalise tags + $tags = (NULL === $tags) ? NULL : ('<'.implode('>,<', $tags).'>'); + + // Setup lifetime + if ($lifetime === NULL) + { + $lifetime = (0 === Arr::get($this->_config, 'default_expire', NULL)) ? 0 : (Arr::get($this->_config, 'default_expire', Cache::DEFAULT_EXPIRE) + time()); + } + else + { + $lifetime = (0 === $lifetime) ? 0 : ($lifetime + time()); + } + + // Prepare statement + // $this->exists() may throw Cache_Exception, no need to catch/rethrow + $statement = $this->exists($id) ? $this->_db->prepare('UPDATE caches SET expiration = :expiration, cache = :cache, tags = :tags WHERE id = :id') : $this->_db->prepare('INSERT INTO caches (id, cache, expiration, tags) VALUES (:id, :cache, :expiration, :tags)'); + + // Try to insert + try + { + $statement->execute(array(':id' => $this->_sanitize_id($id), ':cache' => $data, ':expiration' => $lifetime, ':tags' => $tags)); + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + return (bool) $statement->rowCount(); + } + + /** + * Delete cache entries based on a tag + * + * @param string $tag tag + * @return boolean + * @throws Cache_Exception + */ + public function delete_tag($tag) + { + // Prepare the statement + $statement = $this->_db->prepare('DELETE FROM caches WHERE tags LIKE :tag'); + + // Try to delete + try + { + $statement->execute(array(':tag' => "%<{$tag}>%")); + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + return (bool) $statement->rowCount(); + } + + /** + * Find cache entries based on a tag + * + * @param string $tag tag + * @return array + * @throws Cache_Exception + */ + public function find($tag) + { + // Prepare the statement + $statement = $this->_db->prepare('SELECT id, cache FROM caches WHERE tags LIKE :tag'); + + // Try to find + try + { + if ( ! $statement->execute(array(':tag' => "%<{$tag}>%"))) + { + return array(); + } + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + $result = array(); + + while ($row = $statement->fetchObject()) + { + // Disable notices for unserializing + $ER = error_reporting(~E_NOTICE); + + $result[$row->id] = unserialize($row->cache); + + // Turn notices back on + error_reporting($ER); + } + + return $result; + } + + /** + * Garbage collection method that cleans any expired + * cache entries from the cache. + * + * @return void + */ + public function garbage_collect() + { + // Create the sequel statement + $statement = $this->_db->prepare('DELETE FROM caches WHERE expiration < :expiration'); + + try + { + $statement->execute(array(':expiration' => time())); + } + catch (PDOException $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + } + + /** + * Tests whether an id exists or not + * + * @param string $id id + * @return boolean + * @throws Cache_Exception + */ + protected function exists($id) + { + $statement = $this->_db->prepare('SELECT id FROM caches WHERE id = :id'); + try + { + $statement->execute(array(':id' => $this->_sanitize_id($id))); + } + catch (PDOExeption $e) + { + throw new Cache_Exception('There was a problem querying the local SQLite3 cache. :error', array(':error' => $e->getMessage())); + } + + return (bool) $statement->fetchAll(); + } +} diff --git a/modules/cache/classes/Kohana/Cache/Tagging.php b/modules/cache/classes/Kohana/Cache/Tagging.php new file mode 100644 index 0000000..70d4d63 --- /dev/null +++ b/modules/cache/classes/Kohana/Cache/Tagging.php @@ -0,0 +1,41 @@ + array( // Driver group + * 'driver' => 'wincache', // using wincache driver + * ), + * ) + * + * In cases where only one cache group is required, if the group is named `default` there is + * no need to pass the group name when instantiating a cache instance. + * + * #### General cache group configuration settings + * + * Below are the settings available to all types of cache driver. + * + * Name | Required | Description + * -------------- | -------- | --------------------------------------------------------------- + * driver | __YES__ | (_string_) The driver type to use + * + * ### System requirements + * + * * Windows XP SP3 with IIS 5.1 and » FastCGI Extension + * * Windows Server 2003 with IIS 6.0 and » FastCGI Extension + * * Windows Vista SP1 with IIS 7.0 and FastCGI Module + * * Windows Server 2008 with IIS 7.0 and FastCGI Module + * * Windows 7 with IIS 7.5 and FastCGI Module + * * Windows Server 2008 R2 with IIS 7.5 and FastCGI Module + * * PHP 5.2.X, Non-thread-safe build + * * PHP 5.3 X86, Non-thread-safe VC9 build + * + * @package Kohana/Cache + * @category Base + * @author Kohana Team + * @copyright (c) 2009-2012 Kohana Team + * @license http://kohanaphp.com/license + */ +class Kohana_Cache_Wincache extends Cache { + + /** + * Check for existence of the wincache extension This method cannot be invoked externally. The driver must + * be instantiated using the `Cache::instance()` method. + * + * @param array $config configuration + * @throws Cache_Exception + */ + protected function __construct(array $config) + { + if ( ! extension_loaded('wincache')) + { + throw new Cache_Exception('PHP wincache extension is not available.'); + } + + parent::__construct($config); + } + + /** + * Retrieve a cached value entry by id. + * + * // Retrieve cache entry from wincache group + * $data = Cache::instance('wincache')->get('foo'); + * + * // Retrieve cache entry from wincache group and return 'bar' if miss + * $data = Cache::instance('wincache')->get('foo', 'bar'); + * + * @param string $id id of cache to entry + * @param string $default default value to return if cache miss + * @return mixed + * @throws Cache_Exception + */ + public function get($id, $default = NULL) + { + $data = wincache_ucache_get($this->_sanitize_id($id), $success); + + return $success ? $data : $default; + } + + /** + * Set a value to cache with id and lifetime + * + * $data = 'bar'; + * + * // Set 'bar' to 'foo' in wincache group, using default expiry + * Cache::instance('wincache')->set('foo', $data); + * + * // Set 'bar' to 'foo' in wincache group for 30 seconds + * Cache::instance('wincache')->set('foo', $data, 30); + * + * @param string $id id of cache entry + * @param string $data data to set to cache + * @param integer $lifetime lifetime in seconds + * @return boolean + */ + public function set($id, $data, $lifetime = NULL) + { + if ($lifetime === NULL) + { + $lifetime = Arr::get($this->_config, 'default_expire', Cache::DEFAULT_EXPIRE); + } + + return wincache_ucache_set($this->_sanitize_id($id), $data, $lifetime); + } + + /** + * Delete a cache entry based on id + * + * // Delete 'foo' entry from the wincache group + * Cache::instance('wincache')->delete('foo'); + * + * @param string $id id to remove from cache + * @return boolean + */ + public function delete($id) + { + return wincache_ucache_delete($this->_sanitize_id($id)); + } + + /** + * Delete all cache entries. + * + * Beware of using this method when + * using shared memory cache systems, as it will wipe every + * entry within the system for all clients. + * + * // Delete all cache entries in the wincache group + * Cache::instance('wincache')->delete_all(); + * + * @return boolean + */ + public function delete_all() + { + return wincache_ucache_clear(); + } +} diff --git a/modules/cache/classes/Kohana/HTTP/Cache.php b/modules/cache/classes/Kohana/HTTP/Cache.php new file mode 100644 index 0000000..2507f81 --- /dev/null +++ b/modules/cache/classes/Kohana/HTTP/Cache.php @@ -0,0 +1,503 @@ + FALSE + * ) + * ); + * + * // Create HTTP_Cache with supplied cache engine + * $http_cache = HTTP_Cache::factory(Cache::instance('memcache'), + * array( + * 'allow_private_cache' => FALSE + * ) + * ); + * + * @uses [Cache] + * @param mixed $cache cache engine to use + * @param array $options options to set to this class + * @return HTTP_Cache + */ + public static function factory($cache, array $options = array()) + { + if ( ! $cache instanceof Cache) + { + $cache = Cache::instance($cache); + } + + $options['cache'] = $cache; + + return new HTTP_Cache($options); + } + + /** + * Basic cache key generator that hashes the entire request and returns + * it. This is fine for static content, or dynamic content where user + * specific information is encoded into the request. + * + * // Generate cache key + * $cache_key = HTTP_Cache::basic_cache_key_generator($request); + * + * @param Request $request + * @return string + */ + public static function basic_cache_key_generator(Request $request) + { + $uri = $request->uri(); + $query = $request->query(); + $headers = $request->headers()->getArrayCopy(); + $body = $request->body(); + + return sha1($uri.'?'.http_build_query($query, NULL, '&').'~'.implode('~', $headers).'~'.$body); + } + + /** + * @var Cache cache driver to use for HTTP caching + */ + protected $_cache; + + /** + * @var callback Cache key generator callback + */ + protected $_cache_key_callback; + + /** + * @var boolean Defines whether this client should cache `private` cache directives + * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 + */ + protected $_allow_private_cache = FALSE; + + /** + * @var int The timestamp of the request + */ + protected $_request_time; + + /** + * @var int The timestamp of the response + */ + protected $_response_time; + + /** + * Constructor method for this class. Allows dependency injection of the + * required components such as `Cache` and the cache key generator. + * + * @param array $options + */ + public function __construct(array $options = array()) + { + foreach ($options as $key => $value) + { + if (method_exists($this, $key)) + { + $this->$key($value); + } + } + + if ($this->_cache_key_callback === NULL) + { + $this->cache_key_callback('HTTP_Cache::basic_cache_key_generator'); + } + } + + /** + * Executes the supplied [Request] with the supplied [Request_Client]. + * Before execution, the HTTP_Cache adapter checks the request type, + * destructive requests such as `POST`, `PUT` and `DELETE` will bypass + * cache completely and ensure the response is not cached. All other + * Request methods will allow caching, if the rules are met. + * + * @param Request_Client $client client to execute with Cache-Control + * @param Request $request request to execute with client + * @return [Response] + */ + public function execute(Request_Client $client, Request $request, Response $response) + { + if ( ! $this->_cache instanceof Cache) + return $client->execute_request($request, $response); + + // If this is a destructive request, by-pass cache completely + if (in_array($request->method(), array( + HTTP_Request::POST, + HTTP_Request::PUT, + HTTP_Request::DELETE))) + { + // Kill existing caches for this request + $this->invalidate_cache($request); + + $response = $client->execute_request($request, $response); + + $cache_control = HTTP_Header::create_cache_control(array( + 'no-cache', + 'must-revalidate' + )); + + // Ensure client respects destructive action + return $response->headers('cache-control', $cache_control); + } + + // Create the cache key + $cache_key = $this->create_cache_key($request, $this->_cache_key_callback); + + // Try and return cached version + if (($cached_response = $this->cache_response($cache_key, $request)) instanceof Response) + return $cached_response; + + // Start request time + $this->_request_time = time(); + + // Execute the request with the Request client + $response = $client->execute_request($request, $response); + + // Stop response time + $this->_response_time = (time() - $this->_request_time); + + // Cache the response + $this->cache_response($cache_key, $request, $response); + + $response->headers(HTTP_Cache::CACHE_STATUS_KEY, + HTTP_Cache::CACHE_STATUS_MISS); + + return $response; + } + + /** + * Invalidate a cached response for the [Request] supplied. + * This has the effect of deleting the response from the + * [Cache] entry. + * + * @param Request $request Response to remove from cache + * @return void + */ + public function invalidate_cache(Request $request) + { + if (($cache = $this->cache()) instanceof Cache) + { + $cache->delete($this->create_cache_key($request, $this->_cache_key_callback)); + } + + return; + } + + /** + * Getter and setter for the internal caching engine, + * used to cache responses if available and valid. + * + * @param Kohana_Cache $cache engine to use for caching + * @return Kohana_Cache + * @return Kohana_Request_Client + */ + public function cache(Cache $cache = NULL) + { + if ($cache === NULL) + return $this->_cache; + + $this->_cache = $cache; + return $this; + } + + /** + * Gets or sets the [Request_Client::allow_private_cache] setting. + * If set to `TRUE`, the client will also cache cache-control directives + * that have the `private` setting. + * + * @link http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9 + * @param boolean $setting allow caching of privately marked responses + * @return boolean + * @return [Request_Client] + */ + public function allow_private_cache($setting = NULL) + { + if ($setting === NULL) + return $this->_allow_private_cache; + + $this->_allow_private_cache = (bool) $setting; + return $this; + } + + /** + * Sets or gets the cache key generator callback for this caching + * class. The cache key generator provides a unique hash based on the + * `Request` object passed to it. + * + * The default generator is [HTTP_Cache::basic_cache_key_generator()], which + * serializes the entire `HTTP_Request` into a unique sha1 hash. This will + * provide basic caching for static and simple dynamic pages. More complex + * algorithms can be defined and then passed into `HTTP_Cache` using this + * method. + * + * // Get the cache key callback + * $callback = $http_cache->cache_key_callback(); + * + * // Set the cache key callback + * $http_cache->cache_key_callback('Foo::cache_key'); + * + * // Alternatively, in PHP 5.3 use a closure + * $http_cache->cache_key_callback(function (Request $request) { + * return sha1($request->render()); + * }); + * + * @param callback $callback + * @return mixed + * @throws HTTP_Exception + */ + public function cache_key_callback($callback = NULL) + { + if ($callback === NULL) + return $this->_cache_key_callback; + + if ( ! is_callable($callback)) + throw new Kohana_Exception('cache_key_callback must be callable!'); + + $this->_cache_key_callback = $callback; + return $this; + } + + /** + * Creates a cache key for the request to use for caching + * [Kohana_Response] returned by [Request::execute]. + * + * This is the default cache key generating logic, but can be overridden + * by setting [HTTP_Cache::cache_key_callback()]. + * + * @param Request $request request to create key for + * @param callback $callback optional callback to use instead of built-in method + * @return string + */ + public function create_cache_key(Request $request, $callback = FALSE) + { + if (is_callable($callback)) + return call_user_func($callback, $request); + else + return HTTP_Cache::basic_cache_key_generator($request); + } + + /** + * Controls whether the response can be cached. Uses HTTP + * protocol to determine whether the response can be cached. + * + * @link RFC 2616 http://www.w3.org/Protocols/rfc2616/ + * @param Response $response The Response + * @return boolean + */ + public function set_cache(Response $response) + { + $headers = $response->headers()->getArrayCopy(); + + if ($cache_control = Arr::get($headers, 'cache-control')) + { + // Parse the cache control + $cache_control = HTTP_Header::parse_cache_control($cache_control); + + // If the no-cache or no-store directive is set, return + if (array_intersect($cache_control, array('no-cache', 'no-store'))) + return FALSE; + + // Check for private cache and get out of here if invalid + if ( ! $this->_allow_private_cache AND in_array('private', $cache_control)) + { + if ( ! isset($cache_control['s-maxage'])) + return FALSE; + + // If there is a s-maxage directive we can use that + $cache_control['max-age'] = $cache_control['s-maxage']; + } + + // Check that max-age has been set and if it is valid for caching + if (isset($cache_control['max-age']) AND $cache_control['max-age'] < 1) + return FALSE; + } + + if ($expires = Arr::get($headers, 'expires') AND ! isset($cache_control['max-age'])) + { + // Can't cache things that have expired already + if (strtotime($expires) <= time()) + return FALSE; + } + + return TRUE; + } + + /** + * Caches a [Response] using the supplied [Cache] + * and the key generated by [Request_Client::_create_cache_key]. + * + * If not response is supplied, the cache will be checked for an existing + * one that is available. + * + * @param string $key the cache key to use + * @param Request $request the HTTP Request + * @param Response $response the HTTP Response + * @return mixed + */ + public function cache_response($key, Request $request, Response $response = NULL) + { + if ( ! $this->_cache instanceof Cache) + return FALSE; + + // Check for Pragma: no-cache + if ($pragma = $request->headers('pragma')) + { + if ($pragma == 'no-cache') + return FALSE; + elseif (is_array($pragma) AND in_array('no-cache', $pragma)) + return FALSE; + } + + // If there is no response, lookup an existing cached response + if ($response === NULL) + { + $response = $this->_cache->get($key); + + if ( ! $response instanceof Response) + return FALSE; + + // Do cache hit arithmetic, using fast arithmetic if available + if ($this->_cache instanceof Cache_Arithmetic) + { + $hit_count = $this->_cache->increment(HTTP_Cache::CACHE_HIT_KEY.$key); + } + else + { + $hit_count = $this->_cache->get(HTTP_Cache::CACHE_HIT_KEY.$key); + $this->_cache->set(HTTP_Cache::CACHE_HIT_KEY.$key, ++$hit_count); + } + + // Update the header to have correct HIT status and count + $response->headers(HTTP_Cache::CACHE_STATUS_KEY, + HTTP_Cache::CACHE_STATUS_HIT) + ->headers(HTTP_Cache::CACHE_HIT_KEY, $hit_count); + + return $response; + } + else + { + if (($ttl = $this->cache_lifetime($response)) === FALSE) + return FALSE; + + $response->headers(HTTP_Cache::CACHE_STATUS_KEY, + HTTP_Cache::CACHE_STATUS_SAVED); + + // Set the hit count to zero + $this->_cache->set(HTTP_Cache::CACHE_HIT_KEY.$key, 0); + + return $this->_cache->set($key, $response, $ttl); + } + } + + /** + * Calculates the total Time To Live based on the specification + * RFC 2616 cache lifetime rules. + * + * @param Response $response Response to evaluate + * @return mixed TTL value or false if the response should not be cached + */ + public function cache_lifetime(Response $response) + { + // Get out of here if this cannot be cached + if ( ! $this->set_cache($response)) + return FALSE; + + // Calculate apparent age + if ($date = $response->headers('date')) + { + $apparent_age = max(0, $this->_response_time - strtotime($date)); + } + else + { + $apparent_age = max(0, $this->_response_time); + } + + // Calculate corrected received age + if ($age = $response->headers('age')) + { + $corrected_received_age = max($apparent_age, intval($age)); + } + else + { + $corrected_received_age = $apparent_age; + } + + // Corrected initial age + $corrected_initial_age = $corrected_received_age + $this->request_execution_time(); + + // Resident time + $resident_time = time() - $this->_response_time; + + // Current age + $current_age = $corrected_initial_age + $resident_time; + + // Prepare the cache freshness lifetime + $ttl = NULL; + + // Cache control overrides + if ($cache_control = $response->headers('cache-control')) + { + // Parse the cache control header + $cache_control = HTTP_Header::parse_cache_control($cache_control); + + if (isset($cache_control['max-age'])) + { + $ttl = $cache_control['max-age']; + } + + if (isset($cache_control['s-maxage']) AND isset($cache_control['private']) AND $this->_allow_private_cache) + { + $ttl = $cache_control['s-maxage']; + } + + if (isset($cache_control['max-stale']) AND ! isset($cache_control['must-revalidate'])) + { + $ttl = $current_age + $cache_control['max-stale']; + } + } + + // If we have a TTL at this point, return + if ($ttl !== NULL) + return $ttl; + + if ($expires = $response->headers('expires')) + return strtotime($expires) - $current_age; + + return FALSE; + } + + /** + * Returns the duration of the last request execution. + * Either returns the time of completed requests or + * `FALSE` if the request hasn't finished executing, or + * is yet to be run. + * + * @return mixed + */ + public function request_execution_time() + { + if ($this->_request_time === NULL OR $this->_response_time === NULL) + return FALSE; + + return $this->_response_time - $this->_request_time; + } + +} // End Kohana_HTTP_Cache \ No newline at end of file diff --git a/modules/cache/config/cache.php b/modules/cache/config/cache.php new file mode 100644 index 0000000..acc567e --- /dev/null +++ b/modules/cache/config/cache.php @@ -0,0 +1,70 @@ + array( + 'driver' => 'memcache', + 'default_expire' => 3600, + 'compression' => FALSE, // Use Zlib compression (can cause issues with integers) + 'servers' => array( + 'local' => array( + 'host' => 'localhost', // Memcache Server + 'port' => 11211, // Memcache port number + 'persistent' => FALSE, // Persistent connection + 'weight' => 1, + 'timeout' => 1, + 'retry_interval' => 15, + 'status' => TRUE, + ), + ), + 'instant_death' => TRUE, // Take server offline immediately on first fail (no retry) + ), + 'memcachetag' => array( + 'driver' => 'memcachetag', + 'default_expire' => 3600, + 'compression' => FALSE, // Use Zlib compression (can cause issues with integers) + 'servers' => array( + 'local' => array( + 'host' => 'localhost', // Memcache Server + 'port' => 11211, // Memcache port number + 'persistent' => FALSE, // Persistent connection + 'weight' => 1, + 'timeout' => 1, + 'retry_interval' => 15, + 'status' => TRUE, + ), + ), + 'instant_death' => TRUE, + ), + 'apc' => array( + 'driver' => 'apc', + 'default_expire' => 3600, + ), + 'wincache' => array( + 'driver' => 'wincache', + 'default_expire' => 3600, + ), + 'sqlite' => array( + 'driver' => 'sqlite', + 'default_expire' => 3600, + 'database' => APPPATH.'cache/kohana-cache.sql3', + 'schema' => 'CREATE TABLE caches(id VARCHAR(127) PRIMARY KEY, tags VARCHAR(255), expiration INTEGER, cache TEXT)', + ), + 'eaccelerator' => array( + 'driver' => 'eaccelerator', + ), + 'xcache' => array( + 'driver' => 'xcache', + 'default_expire' => 3600, + ), + 'file' => array( + 'driver' => 'file', + 'cache_dir' => APPPATH.'cache', + 'default_expire' => 3600, + 'ignore_on_delete' => array( + '.gitignore', + '.git', + '.svn' + ) + ) +*/ +); diff --git a/modules/cache/config/userguide.php b/modules/cache/config/userguide.php new file mode 100644 index 0000000..0756600 --- /dev/null +++ b/modules/cache/config/userguide.php @@ -0,0 +1,23 @@ + array( + + // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + 'cache' => array( + + // Whether this modules userguide pages should be shown + 'enabled' => TRUE, + + // The name that should show up on the userguide index page + 'name' => 'Cache', + + // A short description of this module, shown on the index page + 'description' => 'Common interface for caching engines.', + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2008–2012 Kohana Team', + ) + ) +); \ No newline at end of file diff --git a/modules/cache/guide/cache.usage.md b/modules/cache/guide/cache.usage.md new file mode 100644 index 0000000..15d7c52 --- /dev/null +++ b/modules/cache/guide/cache.usage.md @@ -0,0 +1,219 @@ +# Kohana Cache usage + +[Kohana_Cache] provides a simple interface allowing getting, setting and deleting of cached values. Two interfaces included in _Kohana Cache_ additionally provide _tagging_ and _garbage collection_ where they are supported by the respective drivers. + +## Getting a new cache instance + +Creating a new _Kohana Cache_ instance is simple, however it must be done using the [Cache::instance] method, rather than the traditional `new` constructor. + + // Create a new instance of cache using the default group + $cache = Cache::instance(); + +The default group will use whatever is set to [Cache::$default] and must have a corresponding [configuration](cache.config) definition for that group. + +To create a cache instance using a group other than the _default_, simply provide the group name as an argument. + + // Create a new instance of the memcache group + $memcache = Cache::instance('memcache'); + +If there is a cache instance already instantiated then you can get it directly from the class member. + + [!!] Beware that this can cause issues if you do not test for the instance before trying to access it. + + // Check for the existance of the cache driver + if (isset(Cache::$instances['memcache'])) + { + // Get the existing cache instance directly (faster) + $memcache = Cache::$instances['memcache']; + } + else + { + // Get the cache driver instance (slower) + $memcache = Cache::instance('memcache'); + } + +## Setting and getting variables to and from cache + +The cache library supports scalar and object values, utilising object serialization where required (or not supported by the caching engine). This means that the majority or objects can be cached without any modification. + + [!!] Serialisation does not work with resource handles, such as filesystem, curl or socket resources. + +### Setting a value to cache + +Setting a value to cache using the [Cache::set] method can be done in one of two ways; either using the Cache instance interface, which is good for atomic operations; or getting an instance and using that for multiple operations. + +The first example demonstrates how to quickly load and set a value to the default cache instance. + + // Create a cachable object + $object = new stdClass; + + // Set a property + $object->foo = 'bar'; + + // Cache the object using default group (quick interface) with default time (3600 seconds) + Cache::instance()->set('foo', $object); + +If multiple cache operations are required, it is best to assign an instance of Cache to a variable and use that as below. + + // Set the object using a defined group for a defined time period (30 seconds) + $memcache = Cache::instance('memcache'); + $memcache->set('foo', $object, 30); + +#### Setting a value with tags + +Certain cache drivers support setting values with tags. To set a value to cache with tags using the following interface. + + // Get a cache instance that supports tags + $memcache = Cache::instance('memcachetag'); + + // Test for tagging interface + if ($memcache instanceof Cache_Tagging) + { + // Set a value with some tags for 30 seconds + $memcache->set('foo', $object, 30, array('snafu', 'stfu', 'fubar')); + } + // Otherwise set without tags + else + { + // Set a value for 30 seconds + $memcache->set('foo', $object, 30); + } + +It is possible to implement custom tagging solutions onto existing or new cache drivers by implementing the [Cache_Tagging] interface. Kohana_Cache only applies the interface to drivers that support tagging natively as standard. + +### Getting a value from cache + +Getting variables back from cache is achieved using the [Cache::get] method using a single key to identify the cache entry. + + // Retrieve a value from cache (quickly) + $object = Cache::instance()->get('foo'); + +In cases where the requested key is not available or the entry has expired, a default value will be returned (__NULL__ by default). It is possible to define the default value as the key is requested. + + // If the cache key is available (with default value set to FALSE) + if ($object = Cache::instance()->get('foo', FALSE)) + { + // Do something + } + else + { + // Do something else + } + +#### Getting values from cache using tags + +It is possible to retrieve values from cache grouped by tag, using the [Cache::find] method with drivers that support tagging. + + [!!] The __Memcachetag__ driver does not support the `Cache::find($tag)` interface and will throw an exception. + + // Get an instance of cache + $cache = Cache::instance('memcachetag'); + + // Wrap in a try/catch statement to gracefully handle memcachetag + try + { + // Find values based on tag + return $cache->find('snafu'); + } + catch (Cache_Exception $e) + { + // Handle gracefully + return FALSE; + } + +### Deleting values from cache + +Deleting variables is very similar to the getting and setting methods already described. Deleting operations are split into three categories: + + - __Delete value by key__. Deletes a cached value by the associated key. + - __Delete all values__. Deletes all caches values stored in the cache instance. + - __Delete values by tag__. Deletes all values that have the supplied tag. This is only supported by Memcached-Tag and Sqlite. + +#### Delete value by key + +To delete a specific value by its associated key: + + // If the cache entry for 'foo' is deleted + if (Cache::instance()->delete('foo')) + { + // Cache entry successfully deleted, do something + } + +By default a `TRUE` value will be returned. However a `FALSE` value will be returned in instances where the key did not exist in the cache. + +#### Delete all values + +To delete all values in a specific instance: + + // If all cache items where deleted successfully + if (Cache::instance()->delete_all()) + { + // Do something + } + +It is also possible to delete all cache items in every instance: + + // For each cache instance + foreach (Cache::$instances as $group => $instance) + { + if ($instance->delete_all()) + { + var_dump('instance : '.$group.' has been flushed!'); + } + } + +#### Delete values by tag + +Some of the caching drivers support deleting by tag. This will remove all the cached values that are associated with a specific tag. Below is an example of how to robustly handle deletion by tag. + + // Get cache instance + $cache = Cache::instance(); + + // Check for tagging interface + if ($cache instanceof Cache_Tagging) + { + // Delete all entries by the tag 'snafu' + $cache->delete_tag('snafu'); + } + +#### Garbage Collection + +Garbage Collection (GC) is the cleaning of expired cache entries. For the most part, caching engines will take care of garbage collection internally. However a few of the file based systems do not handle this task and in these circumstances it would be prudent to garbage collect at a predetermined frequency. If no garbage collection is executed, the resource storing the cache entries will eventually fill and become unusable. + +When not automated, garbage collection is the responsibility of the developer. It is prudent to have a GC probability value that dictates how likely the garbage collection routing will be run. An example of such a system is demonstrated below. + + // Get a cache instance + $cache_file = Cache::instance('file'); + + // Set a GC probability of 10% + $gc = 10; + + // If the GC probability is a hit + if (rand(0,99) <= $gc and $cache_file instanceof Cache_GarbageCollect) + { + // Garbage Collect + $cache_file->garbage_collect(); + } + +# Interfaces + +Kohana Cache comes with two interfaces that are implemented where the drivers support them: + + - __[Cache_Tagging] for tagging support on cache entries__ + - [Cache_MemcacheTag] + - [Cache_Sqlite] + - __[Cache_GarbageCollect] for garbage collection with drivers without native support__ + - [Cache_File] + - [Cache_Sqlite] + +When using interface specific caching features, ensure that code checks for the required interface before using the methods supplied. The following example checks whether the garbage collection interface is available before calling the `garbage_collect` method. + + // Create a cache instance + $cache = Cache::instance(); + + // Test for Garbage Collection + if ($cache instanceof Cache_GarbageCollect) + { + // Collect garbage + $cache->garbage_collect(); + } \ No newline at end of file diff --git a/modules/cache/guide/cache/config.md b/modules/cache/guide/cache/config.md new file mode 100644 index 0000000..450bea8 --- /dev/null +++ b/modules/cache/guide/cache/config.md @@ -0,0 +1,162 @@ +# Kohana Cache configuration + +Kohana Cache uses configuration groups to create cache instances. A configuration group can +use any supported driver, with successive groups using multiple instances of the same driver type. + +The default cache group is loaded based on the `Cache::$default` setting. It is set to the `file` driver as standard, however this can be changed within the `/application/boostrap.php` file. + + // Change the default cache driver to memcache + Cache::$default = 'memcache'; + + // Load the memcache cache driver using default setting + $memcache = Cache::instance(); + +## Group settings + +Below are the default cache configuration groups for each supported driver. Add to- or override these settings +within the `application/config/cache.php` file. + +Name | Required | Description +-------------- | -------- | --------------------------------------------------------------- +driver | __YES__ | (_string_) The driver type to use +default_expire | __NO__ | (_string_) The driver type to use + + + 'file' => array + ( + 'driver' => 'file', + 'cache_dir' => APPPATH.'cache/.kohana_cache', + 'default_expire' => 3600, + ), + +## Memcache & Memcached-tag settings + +Name | Required | Description +-------------- | -------- | --------------------------------------------------------------- +driver | __YES__ | (_string_) The driver type to use +servers | __YES__ | (_array_) Associative array of server details, must include a __host__ key. (see _Memcache server configuration_ below) +compression | __NO__ | (_boolean_) Use data compression when caching + +### Memcache server configuration + +Name | Required | Description +---------------- | -------- | --------------------------------------------------------------- +host | __YES__ | (_string_) The host of the memcache server, i.e. __localhost__; or __127.0.0.1__; or __memcache.domain.tld__ +port | __NO__ | (_integer_) Point to the port where memcached is listening for connections. Set this parameter to 0 when using UNIX domain sockets. Default __11211__ +persistent | __NO__ | (_boolean_) Controls the use of a persistent connection. Default __TRUE__ +weight | __NO__ | (_integer_) Number of buckets to create for this server which in turn control its probability of it being selected. The probability is relative to the total weight of all servers. Default __1__ +timeout | __NO__ | (_integer_) Value in seconds which will be used for connecting to the daemon. Think twice before changing the default value of 1 second - you can lose all the advantages of caching if your connection is too slow. Default __1__ +retry_interval | __NO__ | (_integer_) Controls how often a failed server will be retried, the default value is 15 seconds. Setting this parameter to -1 disables automatic retry. Default __15__ +status | __NO__ | (_boolean_) Controls if the server should be flagged as online. Default __TRUE__ +failure_callback | __NO__ | (_[callback](http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback)_) Allows the user to specify a callback function to run upon encountering an error. The callback is run before failover is attempted. The function takes two parameters, the hostname and port of the failed server. Default __NULL__ + + 'memcache' => array + ( + 'driver' => 'memcache', + 'default_expire' => 3600, + 'compression' => FALSE, // Use Zlib compression + (can cause issues with integers) + 'servers' => array + ( + 'local' => array + ( + 'host' => 'localhost', // Memcache Server + 'port' => 11211, // Memcache port number + 'persistent' => FALSE, // Persistent connection + ), + ), + ), + 'memcachetag' => array + ( + 'driver' => 'memcachetag', + 'default_expire' => 3600, + 'compression' => FALSE, // Use Zlib compression + (can cause issues with integers) + 'servers' => array + ( + 'local' => array + ( + 'host' => 'localhost', // Memcache Server + 'port' => 11211, // Memcache port number + 'persistent' => FALSE, // Persistent connection + ), + ), + ), + +## APC settings + + 'apc' => array + ( + 'driver' => 'apc', + 'default_expire' => 3600, + ), + +## SQLite settings + + 'sqlite' => array + ( + 'driver' => 'sqlite', + 'default_expire' => 3600, + 'database' => APPPATH.'cache/kohana-cache.sql3', + 'schema' => 'CREATE TABLE caches(id VARCHAR(127) PRIMARY KEY, + tags VARCHAR(255), expiration INTEGER, cache TEXT)', + ), + +## File settings + + 'file' => array + ( + 'driver' => 'file', + 'cache_dir' => 'cache/.kohana_cache', + 'default_expire' => 3600, + ) + +## Wincache settings + + 'wincache' => array + ( + 'driver' => 'wincache', + 'default_expire' => 3600, + ), + + +## Override existing configuration group + +The following example demonstrates how to override an existing configuration setting, using the config file in `/application/config/cache.php`. + + array + ( + 'driver' => 'memcache', // Use Memcached as the default driver + 'default_expire' => 8000, // Overide default expiry + 'servers' => array + ( + // Add a new server + array + ( + 'host' => 'cache.domain.tld', + 'port' => 11211, + 'persistent' => FALSE + ) + ), + 'compression' => FALSE + ) + ); + +## Add new configuration group + +The following example demonstrates how to add a new configuration setting, using the config file in `/application/config/cache.php`. + + array + ( + 'driver' => 'apc', // Use Memcached as the default driver + 'default_expire' => 1000, // Overide default expiry + ) + ); diff --git a/modules/cache/guide/cache/examples.md b/modules/cache/guide/cache/examples.md new file mode 100644 index 0000000..e69de29 diff --git a/modules/cache/guide/cache/index.md b/modules/cache/guide/cache/index.md new file mode 100644 index 0000000..0df10c9 --- /dev/null +++ b/modules/cache/guide/cache/index.md @@ -0,0 +1,57 @@ +# About Kohana Cache + +[Kohana_Cache] provides a common interface to a variety of caching engines. [Cache_Tagging] is +supported where available natively to the cache system. Kohana Cache supports multiple +instances of cache engines through a grouped singleton pattern. + +## Supported cache engines + + * APC ([Cache_Apc]) + * File ([Cache_File]) + * Memcached ([Cache_Memcache]) + * Memcached-tags ([Cache_Memcachetag]) + * SQLite ([Cache_Sqlite]) + * Wincache + +## Introduction to caching + +Caching should be implemented with consideration. Generally, caching the result of resources +is faster than reprocessing them. Choosing what, how and when to cache is vital. [PHP APC](http://php.net/manual/en/book.apc.php) is one of the fastest caching systems available, closely followed by [Memcached](http://memcached.org/). [SQLite](http://www.sqlite.org/) and File caching are two of the slowest cache methods, however usually faster than reprocessing +a complex set of instructions. + +Caching engines that use memory are considerably faster than file based alternatives. But +memory is limited whereas disk space is plentiful. If caching large datasets, such as large database result sets, it is best to use file caching. + + [!!] Cache drivers require the relevant PHP extensions to be installed. APC, eAccelerator, Memecached and Xcache all require non-standard PHP extensions. + +## What the Kohana Cache module does (and does not do) + +This module provides a simple abstracted interface to a wide selection of popular PHP cache engines. The caching API provides the basic caching methods implemented across all solutions, memory, network or disk based. Basic key / value storing is supported by all drivers, with additional tagging and garbage collection support where implemented or required. + +_Kohana Cache_ does not provide HTTP style caching for clients (web browsers) and/or proxies (_Varnish_, _Squid_). There are other Kohana modules that provide this functionality. + +## Choosing a cache provider + +Getting and setting values to cache is very simple when using the _Kohana Cache_ interface. The hardest choice is choosing which cache engine to use. When choosing a caching engine, the following criteria must be considered: + + 1. __Does the cache need to be distributed?__ + This is an important consideration as it will severely limit the options available to solutions such as Memcache when a distributed solution is required. + 2. __Does the cache need to be fast?__ + In almost all cases retrieving data from a cache is faster than execution. However generally memory based caching is considerably faster than disk based caching (see table below). + 3. __How much cache is required?__ + Cache is not endless, and memory based caches are subject to a considerably more limited storage resource. + +Driver | Storage | Speed | Tags | Distributed | Automatic Garbage Collection | Notes +---------------- | ------------ | --------- | -------- | ----------- | ---------------------------- | ----------------------- +APC | __Memory__ | Excellent | No | No | Yes | Widely available PHP opcode caching solution, improves php execution performance +Wincache | __Memory__ | Excellent | No | No | Yes | Windows variant of APC +File | __Disk__ | Poor | No | No | No | Marginally faster than execution +Memcache (tag) | __Memory__ | Good | No (yes) | Yes | Yes | Generally fast distributed solution, but has a speed hit due to variable network latency and serialization +Sqlite | __Disk__ | Poor | Yes | No | No | Marginally faster than execution + +It is possible to have hybrid cache solutions that use a combination of the engines above in different contexts. This is supported with _Kohana Cache_ as well + +## Minimum requirements + + * Kohana 3.0.4 + * PHP 5.2.4 or greater \ No newline at end of file diff --git a/modules/cache/guide/cache/menu.md b/modules/cache/guide/cache/menu.md new file mode 100644 index 0000000..5218558 --- /dev/null +++ b/modules/cache/guide/cache/menu.md @@ -0,0 +1,3 @@ +## [Cache]() +- [Configuration](config) +- [Usage](usage) \ No newline at end of file diff --git a/modules/cache/guide/cache/usage.md b/modules/cache/guide/cache/usage.md new file mode 100644 index 0000000..15d7c52 --- /dev/null +++ b/modules/cache/guide/cache/usage.md @@ -0,0 +1,219 @@ +# Kohana Cache usage + +[Kohana_Cache] provides a simple interface allowing getting, setting and deleting of cached values. Two interfaces included in _Kohana Cache_ additionally provide _tagging_ and _garbage collection_ where they are supported by the respective drivers. + +## Getting a new cache instance + +Creating a new _Kohana Cache_ instance is simple, however it must be done using the [Cache::instance] method, rather than the traditional `new` constructor. + + // Create a new instance of cache using the default group + $cache = Cache::instance(); + +The default group will use whatever is set to [Cache::$default] and must have a corresponding [configuration](cache.config) definition for that group. + +To create a cache instance using a group other than the _default_, simply provide the group name as an argument. + + // Create a new instance of the memcache group + $memcache = Cache::instance('memcache'); + +If there is a cache instance already instantiated then you can get it directly from the class member. + + [!!] Beware that this can cause issues if you do not test for the instance before trying to access it. + + // Check for the existance of the cache driver + if (isset(Cache::$instances['memcache'])) + { + // Get the existing cache instance directly (faster) + $memcache = Cache::$instances['memcache']; + } + else + { + // Get the cache driver instance (slower) + $memcache = Cache::instance('memcache'); + } + +## Setting and getting variables to and from cache + +The cache library supports scalar and object values, utilising object serialization where required (or not supported by the caching engine). This means that the majority or objects can be cached without any modification. + + [!!] Serialisation does not work with resource handles, such as filesystem, curl or socket resources. + +### Setting a value to cache + +Setting a value to cache using the [Cache::set] method can be done in one of two ways; either using the Cache instance interface, which is good for atomic operations; or getting an instance and using that for multiple operations. + +The first example demonstrates how to quickly load and set a value to the default cache instance. + + // Create a cachable object + $object = new stdClass; + + // Set a property + $object->foo = 'bar'; + + // Cache the object using default group (quick interface) with default time (3600 seconds) + Cache::instance()->set('foo', $object); + +If multiple cache operations are required, it is best to assign an instance of Cache to a variable and use that as below. + + // Set the object using a defined group for a defined time period (30 seconds) + $memcache = Cache::instance('memcache'); + $memcache->set('foo', $object, 30); + +#### Setting a value with tags + +Certain cache drivers support setting values with tags. To set a value to cache with tags using the following interface. + + // Get a cache instance that supports tags + $memcache = Cache::instance('memcachetag'); + + // Test for tagging interface + if ($memcache instanceof Cache_Tagging) + { + // Set a value with some tags for 30 seconds + $memcache->set('foo', $object, 30, array('snafu', 'stfu', 'fubar')); + } + // Otherwise set without tags + else + { + // Set a value for 30 seconds + $memcache->set('foo', $object, 30); + } + +It is possible to implement custom tagging solutions onto existing or new cache drivers by implementing the [Cache_Tagging] interface. Kohana_Cache only applies the interface to drivers that support tagging natively as standard. + +### Getting a value from cache + +Getting variables back from cache is achieved using the [Cache::get] method using a single key to identify the cache entry. + + // Retrieve a value from cache (quickly) + $object = Cache::instance()->get('foo'); + +In cases where the requested key is not available or the entry has expired, a default value will be returned (__NULL__ by default). It is possible to define the default value as the key is requested. + + // If the cache key is available (with default value set to FALSE) + if ($object = Cache::instance()->get('foo', FALSE)) + { + // Do something + } + else + { + // Do something else + } + +#### Getting values from cache using tags + +It is possible to retrieve values from cache grouped by tag, using the [Cache::find] method with drivers that support tagging. + + [!!] The __Memcachetag__ driver does not support the `Cache::find($tag)` interface and will throw an exception. + + // Get an instance of cache + $cache = Cache::instance('memcachetag'); + + // Wrap in a try/catch statement to gracefully handle memcachetag + try + { + // Find values based on tag + return $cache->find('snafu'); + } + catch (Cache_Exception $e) + { + // Handle gracefully + return FALSE; + } + +### Deleting values from cache + +Deleting variables is very similar to the getting and setting methods already described. Deleting operations are split into three categories: + + - __Delete value by key__. Deletes a cached value by the associated key. + - __Delete all values__. Deletes all caches values stored in the cache instance. + - __Delete values by tag__. Deletes all values that have the supplied tag. This is only supported by Memcached-Tag and Sqlite. + +#### Delete value by key + +To delete a specific value by its associated key: + + // If the cache entry for 'foo' is deleted + if (Cache::instance()->delete('foo')) + { + // Cache entry successfully deleted, do something + } + +By default a `TRUE` value will be returned. However a `FALSE` value will be returned in instances where the key did not exist in the cache. + +#### Delete all values + +To delete all values in a specific instance: + + // If all cache items where deleted successfully + if (Cache::instance()->delete_all()) + { + // Do something + } + +It is also possible to delete all cache items in every instance: + + // For each cache instance + foreach (Cache::$instances as $group => $instance) + { + if ($instance->delete_all()) + { + var_dump('instance : '.$group.' has been flushed!'); + } + } + +#### Delete values by tag + +Some of the caching drivers support deleting by tag. This will remove all the cached values that are associated with a specific tag. Below is an example of how to robustly handle deletion by tag. + + // Get cache instance + $cache = Cache::instance(); + + // Check for tagging interface + if ($cache instanceof Cache_Tagging) + { + // Delete all entries by the tag 'snafu' + $cache->delete_tag('snafu'); + } + +#### Garbage Collection + +Garbage Collection (GC) is the cleaning of expired cache entries. For the most part, caching engines will take care of garbage collection internally. However a few of the file based systems do not handle this task and in these circumstances it would be prudent to garbage collect at a predetermined frequency. If no garbage collection is executed, the resource storing the cache entries will eventually fill and become unusable. + +When not automated, garbage collection is the responsibility of the developer. It is prudent to have a GC probability value that dictates how likely the garbage collection routing will be run. An example of such a system is demonstrated below. + + // Get a cache instance + $cache_file = Cache::instance('file'); + + // Set a GC probability of 10% + $gc = 10; + + // If the GC probability is a hit + if (rand(0,99) <= $gc and $cache_file instanceof Cache_GarbageCollect) + { + // Garbage Collect + $cache_file->garbage_collect(); + } + +# Interfaces + +Kohana Cache comes with two interfaces that are implemented where the drivers support them: + + - __[Cache_Tagging] for tagging support on cache entries__ + - [Cache_MemcacheTag] + - [Cache_Sqlite] + - __[Cache_GarbageCollect] for garbage collection with drivers without native support__ + - [Cache_File] + - [Cache_Sqlite] + +When using interface specific caching features, ensure that code checks for the required interface before using the methods supplied. The following example checks whether the garbage collection interface is available before calling the `garbage_collect` method. + + // Create a cache instance + $cache = Cache::instance(); + + // Test for Garbage Collection + if ($cache instanceof Cache_GarbageCollect) + { + // Collect garbage + $cache->garbage_collect(); + } \ No newline at end of file diff --git a/modules/cache/tests/cache/CacheBasicMethodsTest.php b/modules/cache/tests/cache/CacheBasicMethodsTest.php new file mode 100644 index 0000000..5fdae60 --- /dev/null +++ b/modules/cache/tests/cache/CacheBasicMethodsTest.php @@ -0,0 +1,299 @@ +_cache_driver; + + $this->_cache_driver = $cache; + return $this; + } + + /** + * Data provider for test_set_get() + * + * @return array + */ + public function provider_set_get() + { + $object = new StdClass; + $object->foo = 'foo'; + $object->bar = 'bar'; + + $html_text = << + + + + + + +TESTTEXT; + + return array( + array( + array( + 'id' => 'string', // Key to set to cache + 'value' => 'foobar', // Value to set to key + 'ttl' => 0, // Time to live + 'wait' => FALSE, // Test wait time to let cache expire + 'type' => 'string', // Type test + 'default' => NULL // Default value get should return + ), + 'foobar' + ), + array( + array( + 'id' => 'integer', + 'value' => 101010, + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'integer', + 'default' => NULL + ), + 101010 + ), + array( + array( + 'id' => 'float', + 'value' => 10.00, + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'float', + 'default' => NULL + ), + 10.00 + ), + array( + array( + 'id' => 'array', + 'value' => array( + 'key' => 'foo', + 'value' => 'bar' + ), + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'array', + 'default' => NULL + ), + array( + 'key' => 'foo', + 'value' => 'bar' + ) + ), + array( + array( + 'id' => 'boolean', + 'value' => TRUE, + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'boolean', + 'default' => NULL + ), + TRUE + ), + array( + array( + 'id' => 'null', + 'value' => NULL, + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'null', + 'default' => NULL + ), + NULL + ), + array( + array( + 'id' => 'object', + 'value' => $object, + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'object', + 'default' => NULL + ), + $object + ), + array( + array( + 'id' => 'bar\\ with / troublesome key', + 'value' => 'foo bar snafu', + 'ttl' => 0, + 'wait' => FALSE, + 'type' => 'string', + 'default' => NULL + ), + 'foo bar snafu' + ), + array( + array( + 'id' => 'bar', + 'value' => 'foo', + 'ttl' => 3, + 'wait' => 5, + 'type' => 'null', + 'default' => NULL + ), + NULL + ), + array( + array( + 'id' => 'snafu', + 'value' => 'fubar', + 'ttl' => 3, + 'wait' => 5, + 'type' => 'string', + 'default' => 'something completely different!' + ), + 'something completely different!' + ), + array( + array( + 'id' => 'new line test with HTML', + 'value' => $html_text, + 'ttl' => 10, + 'wait' => FALSE, + 'type' => 'string', + 'default' => NULL, + ), + $html_text + ) + ); + } + + /** + * Tests the [Cache::set()] method, testing; + * + * - The value is cached + * - The lifetime is respected + * - The returned value type is as expected + * - The default not-found value is respected + * + * @dataProvider provider_set_get + * + * @param array data + * @param mixed expected + * @return void + */ + public function test_set_get(array $data, $expected) + { + $cache = $this->cache(); + extract($data); + + $this->assertTrue($cache->set($id, $value, $ttl)); + + if ($wait !== FALSE) + { + // Lets let the cache expire + sleep($wait); + } + + $result = $cache->get($id, $default); + $this->assertEquals($expected, $result); + $this->assertInternalType($type, $result); + + unset($id, $value, $ttl, $wait, $type, $default); + } + + /** + * Tests the [Cache::delete()] method, testing; + * + * - The a cached value is deleted from cache + * - The cache returns a TRUE value upon deletion + * - The cache returns a FALSE value if no value exists to delete + * + * @return void + */ + public function test_delete() + { + // Init + $cache = $this->cache(); + $cache->delete_all(); + + // Test deletion if real cached value + if ( ! $cache->set('test_delete_1', 'This should not be here!', 0)) + { + $this->fail('Unable to set cache value to delete!'); + } + + // Test delete returns TRUE and check the value is gone + $this->assertTrue($cache->delete('test_delete_1')); + $this->assertNull($cache->get('test_delete_1')); + + // Test non-existant cache value returns FALSE if no error + $this->assertFalse($cache->delete('test_delete_1')); + } + + /** + * Tests [Cache::delete_all()] works as specified + * + * @return void + * @uses Kohana_CacheBasicMethodsTest::provider_set_get() + */ + public function test_delete_all() + { + // Init + $cache = $this->cache(); + $data = $this->provider_set_get(); + + foreach ($data as $key => $values) + { + extract($values[0]); + if ( ! $cache->set($id, $value)) + { + $this->fail('Unable to set: '.$key.' => '.$value.' to cache'); + } + unset($id, $value, $ttl, $wait, $type, $default); + } + + // Test delete_all is successful + $this->assertTrue($cache->delete_all()); + + foreach ($data as $key => $values) + { + // Verify data has been purged + $this->assertSame('Cache Deleted!', $cache->get($values[0]['id'], + 'Cache Deleted!')); + } + } + +} // End Kohana_CacheBasicMethodsTest diff --git a/modules/cache/tests/cache/CacheTest.php b/modules/cache/tests/cache/CacheTest.php new file mode 100644 index 0000000..a5c7564 --- /dev/null +++ b/modules/cache/tests/cache/CacheTest.php @@ -0,0 +1,242 @@ +load('cache.file')) + { + $base = array( + // Test default group + array( + NULL, + Cache::instance('file') + ), + // Test defined group + array( + 'file', + Cache::instance('file') + ), + ); + } + + + return array( + // Test bad group definition + $base+array( + Kohana_CacheTest::BAD_GROUP_DEFINITION, + 'Failed to load Kohana Cache group: 1010' + ), + ); + } + + /** + * Tests the [Cache::factory()] method behaves as expected + * + * @dataProvider provider_instance + * + * @return void + */ + public function test_instance($group, $expected) + { + if (in_array($group, array( + Kohana_CacheTest::BAD_GROUP_DEFINITION, + ) + )) + { + $this->setExpectedException('Cache_Exception'); + } + + try + { + $cache = Cache::instance($group); + } + catch (Cache_Exception $e) + { + $this->assertSame($expected, $e->getMessage()); + throw $e; + } + + $this->assertInstanceOf(get_class($expected), $cache); + $this->assertSame($expected->config(), $cache->config()); + } + + /** + * Tests that `clone($cache)` will be prevented to maintain singleton + * + * @return void + * @expectedException Cache_Exception + */ + public function test_cloning_fails() + { + if ( ! Kohana::$config->load('cache.file')) + { + $this->markTestSkipped('Unable to load File configuration'); + } + + try + { + $cache_clone = clone(Cache::instance('file')); + } + catch (Cache_Exception $e) + { + $this->assertSame('Cloning of Kohana_Cache objects is forbidden', + $e->getMessage()); + throw $e; + } + } + + /** + * Data provider for test_config + * + * @return array + */ + public function provider_config() + { + return array( + array( + array( + 'server' => 'otherhost', + 'port' => 5555, + 'persistent' => TRUE, + ), + NULL, + Kohana_CacheTest::EXPECT_SELF, + array( + 'server' => 'otherhost', + 'port' => 5555, + 'persistent' => TRUE, + ), + ), + array( + 'foo', + 'bar', + Kohana_CacheTest::EXPECT_SELF, + array( + 'foo' => 'bar' + ) + ), + array( + 'server', + NULL, + NULL, + array() + ), + array( + NULL, + NULL, + array(), + array() + ) + ); + } + + /** + * Tests the config method behaviour + * + * @dataProvider provider_config + * + * @param mixed key value to set or get + * @param mixed value to set to key + * @param mixed expected result from [Cache::config()] + * @param array expected config within cache + * @return void + */ + public function test_config($key, $value, $expected_result, array $expected_config) + { + $cache = $this->getMock('Cache_File', NULL, array(), '', FALSE); + + if ($expected_result === Kohana_CacheTest::EXPECT_SELF) + { + $expected_result = $cache; + } + + $this->assertSame($expected_result, $cache->config($key, $value)); + $this->assertSame($expected_config, $cache->config()); + } + + /** + * Data provider for test_sanitize_id + * + * @return array + */ + public function provider_sanitize_id() + { + return array( + array( + 'foo', + 'foo' + ), + array( + 'foo+-!@', + 'foo+-!@' + ), + array( + 'foo/bar', + 'foo_bar', + ), + array( + 'foo\\bar', + 'foo_bar' + ), + array( + 'foo bar', + 'foo_bar' + ), + array( + 'foo\\bar snafu/stfu', + 'foo_bar_snafu_stfu' + ) + ); + } + + /** + * Tests the [Cache::_sanitize_id()] method works as expected. + * This uses some nasty reflection techniques to access a protected + * method. + * + * @dataProvider provider_sanitize_id + * + * @param string id + * @param string expected + * @return void + */ + public function test_sanitize_id($id, $expected) + { + $cache = $this->getMock('Cache', array( + 'get', + 'set', + 'delete', + 'delete_all' + ), array(array()), + '', FALSE + ); + + $cache_reflection = new ReflectionClass($cache); + $sanitize_id = $cache_reflection->getMethod('_sanitize_id'); + $sanitize_id->setAccessible(TRUE); + + $this->assertSame($expected, $sanitize_id->invoke($cache, $id)); + } +} // End Kohana_CacheTest diff --git a/modules/cache/tests/cache/FileTest.php b/modules/cache/tests/cache/FileTest.php new file mode 100644 index 0000000..803258f --- /dev/null +++ b/modules/cache/tests/cache/FileTest.php @@ -0,0 +1,98 @@ +load('cache.file')) + { + $this->markTestSkipped('Unable to load File configuration'); + } + + $this->cache(Cache::instance('file')); + } + + /** + * Tests that ignored files are not removed from file cache + * + * @return void + */ + public function test_ignore_delete_file() + { + $cache = $this->cache(); + $config = Kohana::$config->load('cache')->file; + $file = $config['cache_dir'].'/.gitignore'; + + // Lets pollute the cache folder + file_put_contents($file, 'foobar'); + + $this->assertTrue($cache->delete_all()); + $this->assertTrue(file_exists($file)); + $this->assertEquals('foobar', file_get_contents($file)); + + unlink($file); + } + + /** + * Provider for test_utf8 + * + * @return array + */ + public function provider_utf8() + { + return array( + array( + 'This is â ütf-8 Ӝ☃ string', + 'This is â ütf-8 Ӝ☃ string' + ), + array( + '㆓㆕㆙㆛', + '㆓㆕㆙㆛' + ), + array( + 'அஆஇஈஊ', + 'அஆஇஈஊ' + ) + ); + } + + /** + * Tests the file driver supports utf-8 strings + * + * @dataProvider provider_utf8 + * + * @return void + */ + public function test_utf8($input, $expected) + { + $cache = $this->cache(); + $cache->set('utf8', $input); + + $this->assertSame($expected, $cache->get('utf8')); + } + +} // End Kohana_SqliteTest diff --git a/modules/cache/tests/cache/SqliteTest.php b/modules/cache/tests/cache/SqliteTest.php new file mode 100644 index 0000000..4a9c2ea --- /dev/null +++ b/modules/cache/tests/cache/SqliteTest.php @@ -0,0 +1,44 @@ +markTestSkipped('SQLite PDO PHP Extension is not available'); + } + + if ( ! Kohana::$config->load('cache.sqlite')) + { + $this->markTestIncomplete('Unable to load sqlite configuration'); + } + + $this->cache(Cache::instance('sqlite')); + } + +} // End Kohana_SqliteTest diff --git a/modules/cache/tests/cache/WincacheTest.php b/modules/cache/tests/cache/WincacheTest.php new file mode 100644 index 0000000..70e6f79 --- /dev/null +++ b/modules/cache/tests/cache/WincacheTest.php @@ -0,0 +1,39 @@ +markTestSkipped('Wincache PHP Extension is not available'); + } + + $this->cache(Cache::instance('wincache')); + } + +} // End Kohana_WincacheTest diff --git a/modules/cache/tests/cache/arithmetic/ApcTest.php b/modules/cache/tests/cache/arithmetic/ApcTest.php new file mode 100644 index 0000000..e1597cd --- /dev/null +++ b/modules/cache/tests/cache/arithmetic/ApcTest.php @@ -0,0 +1,75 @@ +markTestSkipped('APC PHP Extension is not available'); + } + + if (ini_get('apc.enable_cli') != '1') + { + $this->markTestSkipped('Unable to test APC in CLI mode. To fix '. + 'place "apc.enable_cli=1" in your php.ini file'); + } + + $this->cache(Cache::instance('apc')); + } + + /** + * Tests the [Cache::set()] method, testing; + * + * - The value is cached + * - The lifetime is respected + * - The returned value type is as expected + * - The default not-found value is respected + * + * This test doesn't test the TTL as there is a known bug/feature + * in APC that prevents the same request from killing cache on timeout. + * + * @link http://pecl.php.net/bugs/bug.php?id=16814 + * + * @dataProvider provider_set_get + * + * @param array data + * @param mixed expected + * @return void + */ + public function test_set_get(array $data, $expected) + { + if ($data['wait'] !== FALSE) + { + $this->markTestSkipped('Unable to perform TTL test in CLI, see: '. + 'http://pecl.php.net/bugs/bug.php?id=16814 for more info!'); + } + + parent::test_set_get($data, $expected); + } + +} // End Kohana_ApcTest diff --git a/modules/cache/tests/cache/arithmetic/CacheArithmeticMethods.php b/modules/cache/tests/cache/arithmetic/CacheArithmeticMethods.php new file mode 100644 index 0000000..1dcc7c7 --- /dev/null +++ b/modules/cache/tests/cache/arithmetic/CacheArithmeticMethods.php @@ -0,0 +1,173 @@ +cache(); + + if ($cache instanceof Cache) + { + $cache->delete_all(); + } + } + + /** + * Provider for test_increment + * + * @return array + */ + public function provider_increment() + { + return array( + array( + 0, + array( + 'id' => 'increment_test_1', + 'step' => 1 + ), + 1 + ), + array( + 1, + array( + 'id' => 'increment_test_2', + 'step' => 1 + ), + 2 + ), + array( + 5, + array( + 'id' => 'increment_test_3', + 'step' => 5 + ), + 10 + ), + array( + NULL, + array( + 'id' => 'increment_test_4', + 'step' => 1 + ), + FALSE + ), + ); + } + + /** + * Test for [Cache_Arithmetic::increment()] + * + * @dataProvider provider_increment + * + * @param integer start state + * @param array increment arguments + * @return void + */ + public function test_increment( + $start_state = NULL, + array $inc_args, + $expected) + { + $cache = $this->cache(); + + if ($start_state !== NULL) + { + $cache->set($inc_args['id'], $start_state, 0); + } + + $this->assertSame( + $expected, + $cache->increment( + $inc_args['id'], + $inc_args['step'] + ) + ); + } + + /** + * Provider for test_decrement + * + * @return array + */ + public function provider_decrement() + { + return array( + array( + 10, + array( + 'id' => 'decrement_test_1', + 'step' => 1 + ), + 9 + ), + array( + 10, + array( + 'id' => 'decrement_test_2', + 'step' => 2 + ), + 8 + ), + array( + 50, + array( + 'id' => 'decrement_test_3', + 'step' => 5 + ), + 45 + ), + array( + NULL, + array( + 'id' => 'decrement_test_4', + 'step' => 1 + ), + FALSE + ), + ); } + + /** + * Test for [Cache_Arithmetic::decrement()] + * + * @dataProvider provider_decrement + * + * @param integer start state + * @param array decrement arguments + * @return void + */ + public function test_decrement( + $start_state = NULL, + array $dec_args, + $expected) + { + $cache = $this->cache(); + + if ($start_state !== NULL) + { + $cache->set($dec_args['id'], $start_state, 0); + } + + $this->assertSame( + $expected, + $cache->decrement( + $dec_args['id'], + $dec_args['step'] + ) + ); + } + +} // End Kohana_CacheArithmeticMethodsTest diff --git a/modules/cache/tests/cache/arithmetic/MemcacheTest.php b/modules/cache/tests/cache/arithmetic/MemcacheTest.php new file mode 100644 index 0000000..07cb9ef --- /dev/null +++ b/modules/cache/tests/cache/arithmetic/MemcacheTest.php @@ -0,0 +1,103 @@ +markTestSkipped('Memcache PHP Extension is not available'); + } + if ( ! $config = Kohana::$config->load('cache.memcache')) + { + $this->markTestSkipped('Unable to load Memcache configuration'); + } + + $memcache = new Memcache; + if ( ! $memcache->connect($config['servers']['local']['host'], + $config['servers']['local']['port'])) + { + $this->markTestSkipped('Unable to connect to memcache server @ '. + $config['servers']['local']['host'].':'. + $config['servers']['local']['port']); + } + + if ($memcache->getVersion() === FALSE) + { + $this->markTestSkipped('Memcache server @ '. + $config['servers']['local']['host'].':'. + $config['servers']['local']['port']. + ' not responding!'); + } + + unset($memcache); + + $this->cache(Cache::instance('memcache')); + } + + /** + * Tests that multiple values set with Memcache do not cause unexpected + * results. For accurate results, this should be run with a memcache + * configuration that includes multiple servers. + * + * This is to test #4110 + * + * @link http://dev.kohanaframework.org/issues/4110 + * @return void + */ + public function test_multiple_set() + { + $cache = $this->cache(); + $id_set = 'set_id'; + $ttl = 300; + + $data = array( + 'foobar', + 0, + 1.0, + new stdClass, + array('foo', 'bar' => 1), + TRUE, + NULL, + FALSE + ); + + $previous_set = $cache->get($id_set, NULL); + + foreach ($data as $value) + { + // Use Equals over Sames as Objects will not be equal + $this->assertEquals($previous_set, $cache->get($id_set, NULL)); + $cache->set($id_set, $value, $ttl); + + $previous_set = $value; + } + } + + +} // End Kohana_CacheArithmeticMemcacheTest diff --git a/modules/cache/tests/cache/request/client/CacheTest.php b/modules/cache/tests/cache/request/client/CacheTest.php new file mode 100644 index 0000000..11f9a3e --- /dev/null +++ b/modules/cache/tests/cache/request/client/CacheTest.php @@ -0,0 +1,265 @@ +defaults(array( + 'controller' => 'welcome', + 'action' => 'index' + )); + + parent::setUp(); + } + + /** + * Tests the Client does not attempt to load cache if no Cache library + * is present + * + * @return void + */ + public function test_cache_not_called_with_no_cache() + { + $request = new Request('welcome/index'); + $response = new Response; + + $client_mock = $this->getMock('Request_Client_Internal'); + + $request->client($client_mock); + $client_mock->expects($this->exactly(0)) + ->method('execute_request'); + $client_mock->expects($this->once()) + ->method('execute') + ->will($this->returnValue($response)); + + $this->assertSame($response, $request->execute()); + } + + /** + * Tests that the client attempts to load a cached response from the + * cache library, but fails. + * + * @return void + */ + public function test_cache_miss() + { + $route = new Route('welcome/index'); + $route->defaults(array( + 'controller' => 'Kohana_Request_CacheTest_Dummy', + 'action' => 'index', + )); + + $request = new Request('welcome/index', NULL, array($route)); + $cache_mock = $this->_get_cache_mock(); + + $request->client()->cache(HTTP_Cache::factory($cache_mock)); + + $cache_mock->expects($this->once()) + ->method('get') + ->with($request->client()->cache()->create_cache_key($request)) + ->will($this->returnValue(FALSE)); + + $response = $request->client()->execute($request); + + $this->assertSame(HTTP_Cache::CACHE_STATUS_MISS, + $response->headers(HTTP_Cache::CACHE_STATUS_KEY)); + } + + /** + * Tests the client saves a response if the correct headers are set + * + * @return void + */ + public function test_cache_save() + { + $lifetime = 800; + $request = new Request('welcome/index'); + $cache_mock = $this->_get_cache_mock(); + $response = Response::factory(); + + $request->client()->cache(new HTTP_Cache(array( + 'cache' => $cache_mock + ) + )); + + $response->headers('cache-control', 'max-age='.$lifetime); + + $key = $request->client()->cache()->create_cache_key($request); + + $cache_mock->expects($this->at(0)) + ->method('set') + ->with($this->stringEndsWith($key), $this->identicalTo(0)); + + $cache_mock->expects($this->at(1)) + ->method('set') + ->with($this->identicalTo($key), $this->anything(), $this->identicalTo($lifetime)) + ->will($this->returnValue(TRUE)); + + $this->assertTrue( + $request->client()->cache() + ->cache_response($key, $request, $response) + ); + + $this->assertSame(HTTP_Cache::CACHE_STATUS_SAVED, + $response->headers(HTTP_Cache::CACHE_STATUS_KEY)); + } + + /** + * Tests the client handles a cache HIT event correctly + * + * @return void + */ + public function test_cache_hit() + { + $lifetime = 800; + $request = new Request('welcome/index'); + $cache_mock = $this->_get_cache_mock(); + + $request->client()->cache(new HTTP_Cache(array( + 'cache' => $cache_mock + ) + )); + + $response = Response::factory(); + + $response->headers(array( + 'cache-control' => 'max-age='.$lifetime, + HTTP_Cache::CACHE_STATUS_KEY => + HTTP_Cache::CACHE_STATUS_HIT + )); + + $key = $request->client()->cache()->create_cache_key($request); + + $cache_mock->expects($this->exactly(2)) + ->method('get') + ->with($this->stringContains($key)) + ->will($this->returnValue($response)); + + $request->client()->cache()->cache_response($key, $request); + + $this->assertSame(HTTP_Cache::CACHE_STATUS_HIT, + $response->headers(HTTP_Cache::CACHE_STATUS_KEY)); + } + + + /** + * Data provider for test_set_cache + * + * @return array + */ + public function provider_set_cache() + { + return array( + array( + new HTTP_Header(array('cache-control' => 'no-cache')), + array('no-cache' => NULL), + FALSE, + ), + array( + new HTTP_Header(array('cache-control' => 'no-store')), + array('no-store' => NULL), + FALSE, + ), + array( + new HTTP_Header(array('cache-control' => 'max-age=100')), + array('max-age' => '100'), + TRUE + ), + array( + new HTTP_Header(array('cache-control' => 'private')), + array('private' => NULL), + FALSE + ), + array( + new HTTP_Header(array('cache-control' => 'private, max-age=100')), + array('private' => NULL, 'max-age' => '100'), + FALSE + ), + array( + new HTTP_Header(array('cache-control' => 'private, s-maxage=100')), + array('private' => NULL, 's-maxage' => '100'), + TRUE + ), + array( + new HTTP_Header(array( + 'expires' => date('m/d/Y', strtotime('-1 day')), + )), + array(), + FALSE + ), + array( + new HTTP_Header(array( + 'expires' => date('m/d/Y', strtotime('+1 day')), + )), + array(), + TRUE + ), + array( + new HTTP_Header(array()), + array(), + TRUE + ), + ); + } + + /** + * Tests the set_cache() method + * + * @test + * @dataProvider provider_set_cache + * + * @return null + */ + public function test_set_cache($headers, $cache_control, $expected) + { + /** + * Set up a mock response object to test with + */ + $response = $this->getMock('Response'); + + $response->expects($this->any()) + ->method('headers') + ->will($this->returnValue($headers)); + + $request = new Request_Client_Internal; + $request->cache(new HTTP_Cache); + $this->assertEquals($request->cache()->set_cache($response), $expected); + } + + /** + * Returns a mock object for Cache + * + * @return Cache + */ + protected function _get_cache_mock() + { + return $this->getMock('Cache_File', array(), array(), '', FALSE); + } +} // End Kohana_Request_Client_CacheTest + +class Controller_Kohana_Request_CacheTest_Dummy extends Controller +{ + public function action_index() + { + + } +} \ No newline at end of file diff --git a/modules/cache/tests/phpunit.xml b/modules/cache/tests/phpunit.xml new file mode 100644 index 0000000..c6590be --- /dev/null +++ b/modules/cache/tests/phpunit.xml @@ -0,0 +1,19 @@ + + + ./cache + + + + + cache/ + + + diff --git a/modules/codebench/classes/Bench/ArrCallback.php b/modules/codebench/classes/Bench/ArrCallback.php new file mode 100644 index 0000000..698a6b8 --- /dev/null +++ b/modules/codebench/classes/Bench/ArrCallback.php @@ -0,0 +1,57 @@ + + */ +class Bench_ArrCallback extends Codebench { + + public $description = + 'Parsing command[param,param] strings in Arr::callback(): + http://github.com/shadowhand/kohana/commit/c3aaae849164bf92a486e29e736a265b350cb4da#L0R127'; + + public $loops = 10000; + + public $subjects = array + ( + // Valid callback strings + 'foo', + 'foo::bar', + 'foo[apple,orange]', + 'foo::bar[apple,orange]', + '[apple,orange]', // no command, only params + 'foo[[apple],[orange]]', // params with brackets inside + + // Invalid callback strings + 'foo[apple,orange', // no closing bracket + ); + + public function bench_shadowhand($subject) + { + // The original regex we're trying to optimize + if (preg_match('/([^\[]*+)\[(.*)\]/', $subject, $match)) + return $match; + } + + public function bench_geert_regex_1($subject) + { + // Added ^ and $ around the whole pattern + if (preg_match('/^([^\[]*+)\[(.*)\]$/', $subject, $matches)) + return $matches; + } + + public function bench_geert_regex_2($subject) + { + // A rather experimental approach using \K which requires PCRE 7.2 ~ PHP 5.2.4 + // Note: $matches[0] = params, $matches[1] = command + if (preg_match('/^([^\[]*+)\[\K.*(?=\]$)/', $subject, $matches)) + return $matches; + } + + public function bench_geert_str($subject) + { + // A native string function approach which beats all the regexes + if (strpos($subject, '[') !== FALSE AND substr($subject, -1) === ']') + return explode('[', substr($subject, 0, -1), 2); + } +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/AutoLinkEmails.php b/modules/codebench/classes/Bench/AutoLinkEmails.php new file mode 100644 index 0000000..46e7a15 --- /dev/null +++ b/modules/codebench/classes/Bench/AutoLinkEmails.php @@ -0,0 +1,70 @@ + + */ +class Bench_AutoLinkEmails extends Codebench { + + public $description = + 'Fixing #2772, and comparing some possibilities.'; + + public $loops = 1000; + + public $subjects = array + ( + '
    +
  • voorzitter@xxxx.com
    • +
  • vicevoorzitter@xxxx.com
    • +
', + ); + + // The original function, with str_replace replaced by preg_replace. Looks clean. + public function bench_match_all_loop($subject) + { + if (preg_match_all('~\b(?|58;)(?!\.)[-+_a-z0-9.]++(?|58;)(?!\.)[-+_a-z0-9.]++(?|58;)(?!\.)[-+_a-z0-9.]++(?|58;)(?!\.)[-+_a-z0-9.]++(? + */ +class Bench_DateSpan extends Codebench { + + public $description = + 'Optimization for Date::span().'; + + public $loops = 1000; + + public $subjects = array(); + + public function __construct() + { + parent::__construct(); + + $this->subjects = array( + time(), + time() - Date::MONTH, + time() - Date::YEAR, + time() - Date::YEAR * 10, + ); + } + + // Original method + public static function bench_span_original($remote, $local = NULL, $output = 'years,months,weeks,days,hours,minutes,seconds') + { + // Array with the output formats + $output = preg_split('/[^a-z]+/', strtolower( (string) $output)); + + // Invalid output + if (empty($output)) + return FALSE; + + // Make the output values into keys + extract(array_flip($output), EXTR_SKIP); + + if ($local === NULL) + { + // Calculate the span from the current time + $local = time(); + } + + // Calculate timespan (seconds) + $timespan = abs($remote - $local); + + if (isset($years)) + { + $timespan -= Date::YEAR * ($years = (int) floor($timespan / Date::YEAR)); + } + + if (isset($months)) + { + $timespan -= Date::MONTH * ($months = (int) floor($timespan / Date::MONTH)); + } + + if (isset($weeks)) + { + $timespan -= Date::WEEK * ($weeks = (int) floor($timespan / Date::WEEK)); + } + + if (isset($days)) + { + $timespan -= Date::DAY * ($days = (int) floor($timespan / Date::DAY)); + } + + if (isset($hours)) + { + $timespan -= Date::HOUR * ($hours = (int) floor($timespan / Date::HOUR)); + } + + if (isset($minutes)) + { + $timespan -= Date::MINUTE * ($minutes = (int) floor($timespan / Date::MINUTE)); + } + + // Seconds ago, 1 + if (isset($seconds)) + { + $seconds = $timespan; + } + + // Remove the variables that cannot be accessed + unset($timespan, $remote, $local); + + // Deny access to these variables + $deny = array_flip(array('deny', 'key', 'difference', 'output')); + + // Return the difference + $difference = array(); + foreach ($output as $key) + { + if (isset($$key) AND ! isset($deny[$key])) + { + // Add requested key to the output + $difference[$key] = $$key; + } + } + + // Invalid output formats string + if (empty($difference)) + return FALSE; + + // If only one output format was asked, don't put it in an array + if (count($difference) === 1) + return current($difference); + + // Return array + return $difference; + } + + // Using an array for the output + public static function bench_span_use_array($remote, $local = NULL, $output = 'years,months,weeks,days,hours,minutes,seconds') + { + // Array with the output formats + $output = preg_split('/[^a-z]+/', strtolower( (string) $output)); + + // Invalid output + if (empty($output)) + return FALSE; + + // Convert the list of outputs to an associative array + $output = array_combine($output, array_fill(0, count($output), 0)); + + // Make the output values into keys + extract(array_flip($output), EXTR_SKIP); + + if ($local === NULL) + { + // Calculate the span from the current time + $local = time(); + } + + // Calculate timespan (seconds) + $timespan = abs($remote - $local); + + if (isset($output['years'])) + { + $timespan -= Date::YEAR * ($output['years'] = (int) floor($timespan / Date::YEAR)); + } + + if (isset($output['months'])) + { + $timespan -= Date::MONTH * ($output['months'] = (int) floor($timespan / Date::MONTH)); + } + + if (isset($output['weeks'])) + { + $timespan -= Date::WEEK * ($output['weeks'] = (int) floor($timespan / Date::WEEK)); + } + + if (isset($output['days'])) + { + $timespan -= Date::DAY * ($output['days'] = (int) floor($timespan / Date::DAY)); + } + + if (isset($output['hours'])) + { + $timespan -= Date::HOUR * ($output['hours'] = (int) floor($timespan / Date::HOUR)); + } + + if (isset($output['minutes'])) + { + $timespan -= Date::MINUTE * ($output['minutes'] = (int) floor($timespan / Date::MINUTE)); + } + + // Seconds ago, 1 + if (isset($output['seconds'])) + { + $output['seconds'] = $timespan; + } + + if (count($output) === 1) + { + // Only a single output was requested, return it + return array_pop($output); + } + + // Return array + return $output; + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/ExplodeLimit.php b/modules/codebench/classes/Bench/ExplodeLimit.php new file mode 100644 index 0000000..4bf2acc --- /dev/null +++ b/modules/codebench/classes/Bench/ExplodeLimit.php @@ -0,0 +1,34 @@ + + */ +class Bench_ExplodeLimit extends Codebench { + + public $description = + 'Having a look at the effect of adding a limit to the explode function.
+ http://stackoverflow.com/questions/1308149/how-to-get-a-part-of-url-between-4th-and-5th-slashes'; + + public $loops = 10000; + + public $subjects = array + ( + 'http://example.com/articles/123a/view', + 'http://example.com/articles/123a/view/x/x/x/x/x', + 'http://example.com/articles/123a/view/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x/x', + ); + + public function bench_explode_without_limit($subject) + { + $parts = explode('/', $subject); + return $parts[4]; + } + + public function bench_explode_with_limit($subject) + { + $parts = explode('/', $subject, 6); + return $parts[4]; + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/GruberURL.php b/modules/codebench/classes/Bench/GruberURL.php new file mode 100644 index 0000000..af23975 --- /dev/null +++ b/modules/codebench/classes/Bench/GruberURL.php @@ -0,0 +1,61 @@ + + */ +class Bench_GruberURL extends Codebench { + + public $description = + 'Optimization for http://daringfireball.net/2009/11/liberal_regex_for_matching_urls'; + + public $loops = 10000; + + public $subjects = array + ( + 'http://foo.com/blah_blah', + 'http://foo.com/blah_blah/', + '(Something like http://foo.com/blah_blah)', + 'http://foo.com/blah_blah_(wikipedia)', + '(Something like http://foo.com/blah_blah_(wikipedia))', + 'http://foo.com/blah_blah.', + 'http://foo.com/blah_blah/.', + '', + '', + 'http://foo.com/blah_blah,', + 'http://www.example.com/wpstyle/?p=364.', + 'http://✪df.ws/e7l', + 'rdar://1234', + 'rdar:/1234', + 'x-yojimbo-item://6303E4C1-xxxx-45A6-AB9D-3A908F59AE0E', + 'message://%3c330e7f8409726r6a4ba78dkf1fd71420c1bf6ff@mail.gmail.com%3e', + 'http://➡.ws/䨹', + 'www.➡.ws/䨹', + 'http://example.com', + 'Just a www.example.com link.', + // To test the use of possessive quatifiers: + 'httpppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppp', + ); + + public function bench_daringfireball($subject) + { + // Original regex by John Gruber + preg_match('~\b(([\w-]+://?|www[.])[^\s()<>]+(?:\([\w\d]+\)|([^[:punct:]\s]|/)))~', $subject, $matches); + return (empty($matches)) ? FALSE : $matches[0]; + } + + public function bench_daringfireball_v2($subject) + { + // Removed outer capturing parentheses, made another pair non-capturing + preg_match('~\b(?:[\w-]+://?|www[.])[^\s()<>]+(?:\([\w\d]+\)|(?:[^[:punct:]\s]|/))~', $subject, $matches); + return (empty($matches)) ? FALSE : $matches[0]; + } + + public function bench_daringfireball_v3($subject) + { + // Made quantifiers possessive where possible + preg_match('~\b(?:[\w-]++://?+|www[.])[^\s()<>]+(?:\([\w\d]++\)|(?:[^[:punct:]\s]|/))~', $subject, $matches); + return (empty($matches)) ? FALSE : $matches[0]; + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/LtrimDigits.php b/modules/codebench/classes/Bench/LtrimDigits.php new file mode 100644 index 0000000..71ead49 --- /dev/null +++ b/modules/codebench/classes/Bench/LtrimDigits.php @@ -0,0 +1,28 @@ + + */ +class Bench_LtrimDigits extends Codebench { + + public $description = 'Chopping off leading digits: regex vs ltrim.'; + + public $loops = 100000; + + public $subjects = array + ( + '123digits', + 'no-digits', + ); + + public function bench_regex($subject) + { + return preg_replace('/^\d+/', '', $subject); + } + + public function bench_ltrim($subject) + { + return ltrim($subject, '0..9'); + } +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/MDDoBaseURL.php b/modules/codebench/classes/Bench/MDDoBaseURL.php new file mode 100644 index 0000000..1ad2a1b --- /dev/null +++ b/modules/codebench/classes/Bench/MDDoBaseURL.php @@ -0,0 +1,66 @@ + + */ +class Bench_MDDoBaseURL extends Codebench { + + public $description = + 'Optimization for the doBaseURL() method of Kohana_Kodoc_Markdown + for the Kohana Userguide.'; + + public $loops = 10000; + + public $subjects = array + ( + // Valid matches + '[filesystem](about.filesystem)', + '[filesystem](about.filesystem "Optional title")', + '[same page link](#id)', + '[object oriented](http://wikipedia.org/wiki/Object-Oriented_Programming)', + + // Invalid matches + '![this is image syntax](about.filesystem)', + '[filesystem](about.filesystem', + ); + + public function bench_original($subject) + { + // The original regex contained a bug, which is fixed here for benchmarking purposes. + // At the very start of the regex, (?!!) has been replace by (? + */ +class Bench_MDDoImageURL extends Codebench { + + public $description = + 'Optimization for the doImageURL() method of Kohana_Kodoc_Markdown + for the Kohana Userguide.'; + + public $loops = 10000; + + public $subjects = array + ( + // Valid matches + '![Alt text](http://img.skitch.com/20091019-rud5mmqbf776jwua6hx9nm1n.png)', + '![Alt text](https://img.skitch.com/20091019-rud5mmqbf776jwua6hx9nm1n.png)', + '![Alt text](otherprotocol://image.png "Optional title")', + '![Alt text](img/install.png "Optional title")', + '![Alt text containing [square] brackets](img/install.png)', + '![Empty src]()', + + // Invalid matches + '![Alt text](img/install.png "No closing parenthesis"', + ); + + public function bench_original($subject) + { + return preg_replace_callback('~!\[(.+?)\]\((\S*(?:\s*".+?")?)\)~', array($this, '_add_image_url_original'), $subject); + } + protected function _add_image_url_original($matches) + { + if ($matches[2] AND strpos($matches[2], '://') === FALSE) + { + // Add the base url to the link URL + $matches[2] = 'http://BASE/'.$matches[2]; + } + + // Recreate the link + return "![{$matches[1]}]({$matches[2]})"; + } + + public function bench_optimized_callback($subject) + { + // Moved the check for "://" to the regex, simplifying the callback function + return preg_replace_callback('~!\[(.+?)\]\((?!\w++://)(\S*(?:\s*+".+?")?)\)~', array($this, '_add_image_url_optimized'), $subject); + } + protected function _add_image_url_optimized($matches) + { + // Add the base url to the link URL + $matches[2] = 'http://BASE/'.$matches[2]; + + // Recreate the link + return "![{$matches[1]}]({$matches[2]})"; + } + + public function bench_callback_gone($subject) + { + // All the optimized callback was doing now, is prepend some text to the URL. + // We don't need a callback for that, and that should be clearly faster. + return preg_replace('~(!\[.+?\]\()(?!\w++://)(\S*(?:\s*+".+?")?\))~', '$1http://BASE/$2', $subject); + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/MDDoIncludeViews.php b/modules/codebench/classes/Bench/MDDoIncludeViews.php new file mode 100644 index 0000000..9cac3d6 --- /dev/null +++ b/modules/codebench/classes/Bench/MDDoIncludeViews.php @@ -0,0 +1,50 @@ + + */ +class Bench_MDDoIncludeViews extends Codebench { + + public $description = + 'Optimization for the doIncludeViews() method of Kohana_Kodoc_Markdown + for the Kohana Userguide.'; + + public $loops = 10000; + + public $subjects = array + ( + // Valid matches + '{{one}} two {{three}}', + '{{userguide/examples/hello_world_error}}', + + // Invalid matches + '{}', + '{{}}', + '{{userguide/examples/hello_world_error}', + '{{userguide/examples/hello_world_error }}', + '{{userguide/examples/{{hello_world_error }}', + ); + + public function bench_original($subject) + { + preg_match_all('/{{(\S+?)}}/m', $subject, $matches, PREG_SET_ORDER); + return $matches; + } + + public function bench_possessive($subject) + { + // Using a possessive character class + // Removed useless /m modifier + preg_match_all('/{{([^\s{}]++)}}/', $subject, $matches, PREG_SET_ORDER); + return $matches; + } + + public function bench_lookaround($subject) + { + // Using lookaround to move $mathes[1] into $matches[0] + preg_match_all('/(?<={{)[^\s{}]++(?=}})/', $subject, $matches, PREG_SET_ORDER); + return $matches; + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/StripNullBytes.php b/modules/codebench/classes/Bench/StripNullBytes.php new file mode 100644 index 0000000..4d28853 --- /dev/null +++ b/modules/codebench/classes/Bench/StripNullBytes.php @@ -0,0 +1,37 @@ + + */ +class Bench_StripNullBytes extends Codebench { + + public $description = + 'String replacement comparisons related to #2676.'; + + public $loops = 1000; + + public $subjects = array + ( + "\0", + "\0\0\0\0\0\0\0\0\0\0", + "bla\0bla\0bla\0bla\0bla\0bla\0bla\0bla\0bla\0bla", + "blablablablablablablablablablablablablablablabla", + ); + + public function bench_str_replace($subject) + { + return str_replace("\0", '', $subject); + } + + public function bench_strtr($subject) + { + return strtr($subject, array("\0" => '')); + } + + public function bench_preg_replace($subject) + { + return preg_replace('~\0+~', '', $subject); + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/Transliterate.php b/modules/codebench/classes/Bench/Transliterate.php new file mode 100644 index 0000000..aff8693 --- /dev/null +++ b/modules/codebench/classes/Bench/Transliterate.php @@ -0,0 +1,65 @@ + + */ +class Bench_Transliterate extends Codebench { + + public $description = + 'Inspired by: + http://forum.kohanaframework.org/comments.php?DiscussionID=6113'; + + public $loops = 10; + + public $subjects = array + ( + // ASCII + 'a', 'b', 'c', 'd', '1', '2', '3', + + // Non-ASCII + 'à', 'ô', 'ď', 'ḟ', 'ë', 'š', 'ơ', + 'ß', 'ă', 'ř', 'ț', 'ň', 'ā', 'ķ', + 'ŝ', 'ỳ', 'ņ', 'ĺ', 'ħ', 'ṗ', 'ó', + 'ú', 'ě', 'é', 'ç', 'ẁ', 'ċ', 'õ', + 'ṡ', 'ø', 'ģ', 'ŧ', 'ș', 'ė', 'ĉ', + 'ś', 'î', 'ű', 'ć', 'ę', 'ŵ', 'ṫ', + 'ū', 'č', 'ö', 'è', 'ŷ', 'ą', 'ł', + 'ų', 'ů', 'ş', 'ğ', 'ļ', 'ƒ', 'ž', + 'ẃ', 'ḃ', 'å', 'ì', 'ï', 'ḋ', 'ť', + 'ŗ', 'ä', 'í', 'ŕ', 'ê', 'ü', 'ò', + 'ē', 'ñ', 'ń', 'ĥ', 'ĝ', 'đ', 'ĵ', + 'ÿ', 'ũ', 'ŭ', 'ư', 'ţ', 'ý', 'ő', + 'â', 'ľ', 'ẅ', 'ż', 'ī', 'ã', 'ġ', + 'ṁ', 'ō', 'ĩ', 'ù', 'į', 'ź', 'á', + 'û', 'þ', 'ð', 'æ', 'µ', 'ĕ', 'ı', + 'À', 'Ô', 'Ď', 'Ḟ', 'Ë', 'Š', 'Ơ', + 'Ă', 'Ř', 'Ț', 'Ň', 'Ā', 'Ķ', 'Ĕ', + 'Ŝ', 'Ỳ', 'Ņ', 'Ĺ', 'Ħ', 'Ṗ', 'Ó', + 'Ú', 'Ě', 'É', 'Ç', 'Ẁ', 'Ċ', 'Õ', + 'Ṡ', 'Ø', 'Ģ', 'Ŧ', 'Ș', 'Ė', 'Ĉ', + 'Ś', 'Î', 'Ű', 'Ć', 'Ę', 'Ŵ', 'Ṫ', + 'Ū', 'Č', 'Ö', 'È', 'Ŷ', 'Ą', 'Ł', + 'Ų', 'Ů', 'Ş', 'Ğ', 'Ļ', 'Ƒ', 'Ž', + 'Ẃ', 'Ḃ', 'Å', 'Ì', 'Ï', 'Ḋ', 'Ť', + 'Ŗ', 'Ä', 'Í', 'Ŕ', 'Ê', 'Ü', 'Ò', + 'Ē', 'Ñ', 'Ń', 'Ĥ', 'Ĝ', 'Đ', 'Ĵ', + 'Ÿ', 'Ũ', 'Ŭ', 'Ư', 'Ţ', 'Ý', 'Ő', + 'Â', 'Ľ', 'Ẅ', 'Ż', 'Ī', 'Ã', 'Ġ', + 'Ṁ', 'Ō', 'Ĩ', 'Ù', 'Į', 'Ź', 'Á', + 'Û', 'Þ', 'Ð', 'Æ', 'İ', + ); + + public function bench_utf8($subject) + { + return UTF8::transliterate_to_ascii($subject); + } + + public function bench_iconv($subject) + { + // Note: need to suppress errors on iconv because some chars trigger the following notice: + // "Detected an illegal character in input string" + return preg_replace('~[^-a-z0-9]+~i', '', @iconv('UTF-8', 'ASCII//TRANSLIT', $subject)); + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/URLSite.php b/modules/codebench/classes/Bench/URLSite.php new file mode 100644 index 0000000..0db347d --- /dev/null +++ b/modules/codebench/classes/Bench/URLSite.php @@ -0,0 +1,123 @@ + + */ +class Bench_URLSite extends Codebench { + + public $description = 'http://dev.kohanaframework.org/issues/3110'; + + public $loops = 1000; + + public $subjects = array + ( + '', + 'news', + 'news/', + '/news/', + 'news/page/5', + 'news/page:5', + 'http://example.com/', + 'http://example.com/hello', + 'http://example.com:80/', + 'http://user:pass@example.com/', + ); + + public function __construct() + { + foreach ($this->subjects as $subject) + { + // Automatically create URIs with query string and/or fragment part appended + $this->subjects[] = $subject.'?query=string'; + $this->subjects[] = $subject.'#fragment'; + $this->subjects[] = $subject.'?query=string#fragment'; + } + + parent::__construct(); + } + + public function bench_original($uri) + { + // Get the path from the URI + $path = trim(parse_url($uri, PHP_URL_PATH), '/'); + + if ($query = parse_url($uri, PHP_URL_QUERY)) + { + $query = '?'.$query; + } + + if ($fragment = parse_url($uri, PHP_URL_FRAGMENT)) + { + $fragment = '#'.$fragment; + } + + return $path.$query.$fragment; + } + + public function bench_explode($uri) + { + // Chop off possible scheme, host, port, user and pass parts + $path = preg_replace('~^[-a-z0-9+.]++://[^/]++/?~', '', trim($uri, '/')); + + $fragment = ''; + $explode = explode('#', $path, 2); + if (isset($explode[1])) + { + $path = $explode[0]; + $fragment = '#'.$explode[1]; + } + + $query = ''; + $explode = explode('?', $path, 2); + if (isset($explode[1])) + { + $path = $explode[0]; + $query = '?'.$explode[1]; + } + + return $path.$query.$fragment; + } + + public function bench_regex($uri) + { + preg_match('~^(?:[-a-z0-9+.]++://[^/]++/?)?([^?#]++)?(\?[^#]*+)?(#.*)?~', trim($uri, '/'), $matches); + $path = Arr::get($matches, 1, ''); + $query = Arr::get($matches, 2, ''); + $fragment = Arr::get($matches, 3, ''); + + return $path.$query.$fragment; + } + + public function bench_regex_without_arrget($uri) + { + preg_match('~^(?:[-a-z0-9+.]++://[^/]++/?)?([^?#]++)?(\?[^#]*+)?(#.*)?~', trim($uri, '/'), $matches); + $path = isset($matches[1]) ? $matches[1] : ''; + $query = isset($matches[2]) ? $matches[2] : ''; + $fragment = isset($matches[3]) ? $matches[3] : ''; + + return $path.$query.$fragment; + } + + // And then I thought, why do all the work of extracting the query and fragment parts and then reappending them? + // Just leaving them alone should be fine, right? As a bonus we get a very nice speed boost. + public function bench_less_is_more($uri) + { + // Chop off possible scheme, host, port, user and pass parts + $path = preg_replace('~^[-a-z0-9+.]++://[^/]++/?~', '', trim($uri, '/')); + + return $path; + } + + public function bench_less_is_more_with_strpos_optimization($uri) + { + if (strpos($uri, '://') !== FALSE) + { + // Chop off possible scheme, host, port, user and pass parts + $uri = preg_replace('~^[-a-z0-9+.]++://[^/]++/?~', '', trim($uri, '/')); + } + + return $uri; + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/UserFuncArray.php b/modules/codebench/classes/Bench/UserFuncArray.php new file mode 100644 index 0000000..f53d0c6 --- /dev/null +++ b/modules/codebench/classes/Bench/UserFuncArray.php @@ -0,0 +1,58 @@ + + */ +class Bench_UserFuncArray extends Codebench { + + public $description = + 'Testing the speed difference of using call_user_func_array + compared to counting args and doing manual calls.'; + + public $loops = 100000; + + public $subjects = array + ( + // Argument sets + array(), + array('one'), + array('one', 'two'), + array('one', 'two', 'three'), + ); + + public function bench_count_args($args) + { + $name = 'callme'; + switch (count($args)) + { + case 1: + $this->$name($args[0]); + break; + case 2: + $this->$name($args[0], $args[1]); + break; + case 3: + $this->$name($args[0], $args[1], $args[2]); + break; + case 4: + $this->$name($args[0], $args[1], $args[2], $args[3]); + break; + default: + call_user_func_array(array($this, $name), $args); + break; + } + } + + public function bench_direct_call($args) + { + $name = 'callme'; + call_user_func_array(array($this, $name), $args); + } + + protected function callme() + { + return count(func_get_args()); + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/ValidColor.php b/modules/codebench/classes/Bench/ValidColor.php new file mode 100644 index 0000000..8d04608 --- /dev/null +++ b/modules/codebench/classes/Bench/ValidColor.php @@ -0,0 +1,116 @@ + + */ +class Bench_ValidColor extends Codebench { + + public $description = + 'Optimization for Validate::color(). + See: http://forum.kohanaphp.com/comments.php?DiscussionID=2192. + + Note that the methods with an _invalid suffix contain flawed regexes and should be + completely discarded. I left them in here for educational purposes, and to remind myself + to think harder and test more thoroughly. It can\'t be that I only found out so late in + the game. For the regex explanation have a look at the forum topic mentioned earlier.'; + + public $loops = 10000; + + public $subjects = array + ( + // Valid colors + 'aaA', + '123', + '000000', + '#123456', + '#abcdef', + + // Invalid colors + 'ggg', + '1234', + '#1234567', + "#000\n", + '}§è!çà%$z', + ); + + // Note that I added the D modifier to corey's regexes. We need to match exactly + // the same if we want the benchmarks to be of any value. + public function bench_corey_regex_1_invalid($subject) + { + return (bool) preg_match('/^#?([0-9a-f]{1,2}){3}$/iD', $subject); + } + + public function bench_corey_regex_2($subject) + { + return (bool) preg_match('/^#?([0-9a-f]){3}(([0-9a-f]){3})?$/iD', $subject); + } + + // Optimized corey_regex_1 + // Using non-capturing parentheses and a possessive interval + public function bench_geert_regex_1a_invalid($subject) + { + return (bool) preg_match('/^#?(?:[0-9a-f]{1,2}+){3}$/iD', $subject); + } + + // Optimized corey_regex_2 + // Removed useless parentheses, made the remaining ones non-capturing + public function bench_geert_regex_2a($subject) + { + return (bool) preg_match('/^#?[0-9a-f]{3}(?:[0-9a-f]{3})?$/iD', $subject); + } + + // Optimized geert_regex_1a + // Possessive "#" + public function bench_geert_regex_1b_invalid($subject) + { + return (bool) preg_match('/^#?+(?:[0-9a-f]{1,2}+){3}$/iD', $subject); + } + + // Optimized geert_regex_2a + // Possessive "#" + public function bench_geert_regex_2b($subject) + { + return (bool) preg_match('/^#?+[0-9a-f]{3}(?:[0-9a-f]{3})?$/iD', $subject); + } + + // Using \z instead of $ + public function bench_salathe_regex_1($subject) + { + return (bool) preg_match('/^#?+[0-9a-f]{3}(?:[0-9a-f]{3})?\z/i', $subject); + } + + // Using \A instead of ^ + public function bench_salathe_regex_2($subject) + { + return (bool) preg_match('/\A#?+[0-9a-f]{3}(?:[0-9a-f]{3})?\z/i', $subject); + } + + // A solution without regex + public function bench_geert_str($subject) + { + if ($subject[0] === '#') + { + $subject = substr($subject, 1); + } + + $strlen = strlen($subject); + return (($strlen === 3 OR $strlen === 6) AND ctype_xdigit($subject)); + } + + // An ugly, but fast, solution without regex + public function bench_salathe_str($subject) + { + if ($subject[0] === '#') + { + $subject = substr($subject, 1); + } + + // TRUE if: + // 1. $subject is 6 or 3 chars long + // 2. $subject contains only hexadecimal digits + return (((isset($subject[5]) AND ! isset($subject[6])) OR + (isset($subject[2]) AND ! isset($subject[3]))) + AND ctype_xdigit($subject)); + } +} \ No newline at end of file diff --git a/modules/codebench/classes/Bench/ValidURL.php b/modules/codebench/classes/Bench/ValidURL.php new file mode 100644 index 0000000..3c88675 --- /dev/null +++ b/modules/codebench/classes/Bench/ValidURL.php @@ -0,0 +1,105 @@ + + */ +class Bench_ValidURL extends Codebench { + + public $description = + 'filter_var vs regex: + http://dev.kohanaframework.org/issues/2847'; + + public $loops = 1000; + + public $subjects = array + ( + // Valid + 'http://google.com', + 'http://google.com/', + 'http://google.com/?q=abc', + 'http://google.com/#hash', + 'http://localhost', + 'http://hello-world.pl', + 'http://hello--world.pl', + 'http://h.e.l.l.0.pl', + 'http://server.tld/get/info', + 'http://127.0.0.1', + 'http://127.0.0.1:80', + 'http://user@127.0.0.1', + 'http://user:pass@127.0.0.1', + 'ftp://my.server.com', + 'rss+xml://rss.example.com', + + // Invalid + 'http://google.2com', + 'http://google.com?q=abc', + 'http://google.com#hash', + 'http://hello-.pl', + 'http://hel.-lo.world.pl', + 'http://ww£.google.com', + 'http://127.0.0.1234', + 'http://127.0.0.1.1', + 'http://user:@127.0.0.1', + "http://finalnewline.com\n", + ); + + public function bench_filter_var($url) + { + return (bool) filter_var($url, FILTER_VALIDATE_URL, FILTER_FLAG_HOST_REQUIRED); + } + + public function bench_regex($url) + { + // Based on http://www.apps.ietf.org/rfc/rfc1738.html#sec-5 + if ( ! preg_match( + '~^ + + # scheme + [-a-z0-9+.]++:// + + # username:password (optional) + (?: + [-a-z0-9$_.+!*\'(),;?&=%]++ # username + (?::[-a-z0-9$_.+!*\'(),;?&=%]++)? # password (optional) + @ + )? + + (?: + # ip address + \d{1,3}+(?:\.\d{1,3}+){3}+ + + | # or + + # hostname (captured) + ( + (?!-)[-a-z0-9]{1,63}+(? 253) + return FALSE; + + // An extra check for the top level domain + // It must start with a letter + $tld = ltrim(substr($matches[1], (int) strrpos($matches[1], '.')), '.'); + return ctype_alpha($tld[0]); + } + +} \ No newline at end of file diff --git a/modules/codebench/classes/Codebench.php b/modules/codebench/classes/Codebench.php new file mode 100644 index 0000000..0f4c55c --- /dev/null +++ b/modules/codebench/classes/Codebench.php @@ -0,0 +1,3 @@ +request->param('class'); + + // Convert submitted class name to URI segment + if (isset($_POST['class'])) + { + throw HTTP_Exception::factory(302)->location('codebench/'.trim($_POST['class'])); + } + + // Pass the class name on to the view + $this->template->class = (string) $class; + + // Try to load the class, then run it + if (Kohana::auto_load($class) === TRUE) + { + $codebench = new $class; + $this->template->codebench = $codebench->run(); + } + } +} diff --git a/modules/codebench/classes/Kohana/Codebench.php b/modules/codebench/classes/Kohana/Codebench.php new file mode 100644 index 0000000..0acfa5c --- /dev/null +++ b/modules/codebench/classes/Kohana/Codebench.php @@ -0,0 +1,217 @@ + 'A', + 150 => 'B', + 200 => 'C', + 300 => 'D', + 500 => 'E', + 'default' => 'F', + ); + + /** + * Constructor. + * + * @return void + */ + public function __construct() + { + // Set the maximum execution time + set_time_limit(Kohana::$config->load('codebench')->max_execution_time); + } + + /** + * Runs Codebench on the extending class. + * + * @return array benchmark output + */ + public function run() + { + // Array of all methods to loop over + $methods = array_filter(get_class_methods($this), array($this, '_method_filter')); + + // Make sure the benchmark runs at least once, + // also if no subject data has been provided. + if (empty($this->subjects)) + { + $this->subjects = array('NULL' => NULL); + } + + // Initialize benchmark output + $codebench = array + ( + 'class' => get_class($this), + 'description' => $this->description, + 'loops' => array + ( + 'base' => (int) $this->loops, + 'total' => (int) $this->loops * count($this->subjects) * count($methods), + ), + 'subjects' => $this->subjects, + 'benchmarks' => array(), + ); + + // Benchmark each method + foreach ($methods as $method) + { + // Initialize benchmark output for this method + $codebench['benchmarks'][$method] = array('time' => 0, 'memory' => 0); + + // Using Reflection because simply calling $this->$method($subject) in the loop below + // results in buggy benchmark times correlating to the length of the method name. + $reflection = new ReflectionMethod(get_class($this), $method); + + // Benchmark each subject on each method + foreach ($this->subjects as $subject_key => $subject) + { + // Prerun each method/subject combo before the actual benchmark loop. + // This way relatively expensive initial processes won't be benchmarked, e.g. autoloading. + // At the same time we capture the return here so we don't have to do that in the loop anymore. + $return = $reflection->invoke($this, $subject); + + // Start the timer for one subject + $token = Profiler::start('codebench', $method.$subject_key); + + // The heavy work + for ($i = 0; $i < $this->loops; ++$i) + { + $reflection->invoke($this, $subject); + } + + // Stop and read the timer + $benchmark = Profiler::total($token); + + // Benchmark output specific to the current method and subject + $codebench['benchmarks'][$method]['subjects'][$subject_key] = array + ( + 'return' => $return, + 'time' => $benchmark[0], + 'memory' => $benchmark[1], + ); + + // Update method totals + $codebench['benchmarks'][$method]['time'] += $benchmark[0]; + $codebench['benchmarks'][$method]['memory'] += $benchmark[1]; + } + } + + // Initialize the fastest and slowest benchmarks for both methods and subjects, time and memory, + // these values will be overwritten using min() and max() later on. + // The 999999999 values look like a hack, I know, but they work, + // unless your method runs for more than 31 years or consumes over 1GB of memory. + $fastest_method = $fastest_subject = array('time' => 999999999, 'memory' => 999999999); + $slowest_method = $slowest_subject = array('time' => 0, 'memory' => 0); + + // Find the fastest and slowest benchmarks, needed for the percentage calculations + foreach ($methods as $method) + { + // Update the fastest and slowest method benchmarks + $fastest_method['time'] = min($fastest_method['time'], $codebench['benchmarks'][$method]['time']); + $fastest_method['memory'] = min($fastest_method['memory'], $codebench['benchmarks'][$method]['memory']); + $slowest_method['time'] = max($slowest_method['time'], $codebench['benchmarks'][$method]['time']); + $slowest_method['memory'] = max($slowest_method['memory'], $codebench['benchmarks'][$method]['memory']); + + foreach ($this->subjects as $subject_key => $subject) + { + // Update the fastest and slowest subject benchmarks + $fastest_subject['time'] = min($fastest_subject['time'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['time']); + $fastest_subject['memory'] = min($fastest_subject['memory'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['memory']); + $slowest_subject['time'] = max($slowest_subject['time'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['time']); + $slowest_subject['memory'] = max($slowest_subject['memory'], $codebench['benchmarks'][$method]['subjects'][$subject_key]['memory']); + } + } + + // Percentage calculations for methods + foreach ($codebench['benchmarks'] as & $method) + { + // Calculate percentage difference relative to fastest and slowest methods + $method['percent']['fastest']['time'] = (empty($fastest_method['time'])) ? 0 : ($method['time'] / $fastest_method['time'] * 100); + $method['percent']['fastest']['memory'] = (empty($fastest_method['memory'])) ? 0 : ($method['memory'] / $fastest_method['memory'] * 100); + $method['percent']['slowest']['time'] = (empty($slowest_method['time'])) ? 0 : ($method['time'] / $slowest_method['time'] * 100); + $method['percent']['slowest']['memory'] = (empty($slowest_method['memory'])) ? 0 : ($method['memory'] / $slowest_method['memory'] * 100); + + // Assign a grade for time and memory to each method + $method['grade']['time'] = $this->_grade($method['percent']['fastest']['time']); + $method['grade']['memory'] = $this->_grade($method['percent']['fastest']['memory']); + + // Percentage calculations for subjects + foreach ($method['subjects'] as & $subject) + { + // Calculate percentage difference relative to fastest and slowest subjects for this method + $subject['percent']['fastest']['time'] = (empty($fastest_subject['time'])) ? 0 : ($subject['time'] / $fastest_subject['time'] * 100); + $subject['percent']['fastest']['memory'] = (empty($fastest_subject['memory'])) ? 0 : ($subject['memory'] / $fastest_subject['memory'] * 100); + $subject['percent']['slowest']['time'] = (empty($slowest_subject['time'])) ? 0 : ($subject['time'] / $slowest_subject['time'] * 100); + $subject['percent']['slowest']['memory'] = (empty($slowest_subject['memory'])) ? 0 : ($subject['memory'] / $slowest_subject['memory'] * 100); + + // Assign a grade letter for time and memory to each subject + $subject['grade']['time'] = $this->_grade($subject['percent']['fastest']['time']); + $subject['grade']['memory'] = $this->_grade($subject['percent']['fastest']['memory']); + } + } + + return $codebench; + } + + /** + * Callback for array_filter(). + * Filters out all methods not to benchmark. + * + * @param string method name + * @return boolean + */ + protected function _method_filter($method) + { + // Only benchmark methods with the "bench" prefix + return (substr($method, 0, 5) === 'bench'); + } + + /** + * Returns the applicable grade letter for a score. + * + * @param integer|double score + * @return string grade letter + */ + protected function _grade($score) + { + foreach ($this->grades as $max => $grade) + { + if ($max === 'default') + continue; + + if ($score <= $max) + return $grade; + } + + return $this->grades['default']; + } +} diff --git a/modules/codebench/config/codebench.php b/modules/codebench/config/codebench.php new file mode 100644 index 0000000..590186d --- /dev/null +++ b/modules/codebench/config/codebench.php @@ -0,0 +1,16 @@ + 0, + + /** + * Expand all benchmark details by default. + */ + 'expand_all' => FALSE, + +); diff --git a/modules/codebench/config/userguide.php b/modules/codebench/config/userguide.php new file mode 100644 index 0000000..e6943ac --- /dev/null +++ b/modules/codebench/config/userguide.php @@ -0,0 +1,23 @@ + array( + + // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + 'codebench' => array( + + // Whether this modules userguide pages should be shown + 'enabled' => TRUE, + + // The name that should show up on the userguide index page + 'name' => 'Codebench', + + // A short description of this module, shown on the index page + 'description' => 'Code benchmarking tool.', + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2008–2012 Kohana Team', + ) + ) +); \ No newline at end of file diff --git a/modules/codebench/guide/codebench/index.md b/modules/codebench/guide/codebench/index.md new file mode 100644 index 0000000..78b6f21 --- /dev/null +++ b/modules/codebench/guide/codebench/index.md @@ -0,0 +1,76 @@ +# Using Codebench + +[!!] The contents of this page are taken (with some minor changes) from and are copyright Geert De Deckere. + +For a long time I have been using a quick-and-dirty `benchmark.php` file to optimize bits of PHP code, many times regex-related stuff. The file contained not much more than a [gettimeofday](http://php.net/gettimeofday) function wrapped around a `for` loop. It worked, albeit not very efficiently. Something more solid was needed. I set out to create a far more usable piece of software to aid in the everlasting quest to squeeze every millisecond out of those regular expressions. + +## Codebench Goals + +### Benchmark multiple regular expressions at once + +Being able to compare the speed of an arbitrary amount of regular expressions would be tremendously useful. In case you are wondering—yes, I had been writing down benchmark times for each regex, uncommenting them one by one. You get the idea. Those days should be gone forever now. + +### Benchmark multiple subjects at once + +What gets overlooked too often when testing and optimizing regular expressions is the fact that speed can vastly differ depending on the subjects, also known as input or target strings. Just because your regular expression matches, say, a valid email address quickly, does not necessarily mean it will quickly realize when an invalid email is provided. I plan to write a follow-up article with hands-on regex examples to demonstrate this point. Anyway, Codebench allows you to create an array of subjects which will be passed to each benchmark. + +### Make it flexible enough to work for all PCRE functions + +Initially I named the module “Regexbench”. I quickly realized, though, it would be flexible enough to benchmark all kinds of PHP code, hence the change to “Codebench”. While tools specifically built to help profiling PCRE functions, like [preg_match](http://php.net/preg_match) or [preg_replace](http://php.net/preg_replace), definitely have their use, more flexibility was needed here. You should be able to compare all kinds of constructions like combinations of PCRE functions and native PHP string functions. + +### Create clean and portable benchmark cases + +Throwing valuable benchmark data away every time I needed to optimize another regular expression had to stop. A clean file containing the complete set of all regex variations to compare, together with the set of subjects to test them against, would be more than welcome. Moreover, it would be easy to exchange benchmark cases with others. + +### Visualize the benchmarks + +Obviously providing a visual representation of the benchmark results, via simple graphs, would make interpreting them easier. Having not to think about Internet Explorer for once, made writing CSS a whole lot more easy and fun. It resulted in some fine graphs which are fully resizable. + +Below are two screenshots of Codebench in action. `Valid_Color` is a class made for benchmarking different ways to validate hexadecimal HTML color values, e.g. `#FFF`. If you are interested in the story behind the actual regular expressions, take a look at [this topic in the Kohana forums](http://forum.kohanaphp.com/comments.php?DiscussionID=2192). + +![Benchmarking several ways to validate HTML color values](codebench_screenshot1.png) +**Benchmarking seven ways to validate HTML color values** + +![Collapsable results per subject for each method](codebench_screenshot2.png) +**Collapsable results per subject for each method** + +## Working with Codebench + +Codebench is included in Kohana 3, but if you need you [can download it](http://github.com/kohana/codebench/) from GitHub. Be sure Codebench is activated in your `application/bootstrap.php`. + +Creating your own benchmarks is just a matter of creating a class that extends the Codebench class. The class should go in `classes/bench` and the class name should have the `Bench_` prefix. Put the code parts you want to compare into separate methods. Be sure to prefix those methods with `bench_`, other methods will not be benchmarked. Glance at the files in `modules/codebench/classes/bench/` for more examples. + +Here is another short example with some extra explanations. + + // classes/bench/ltrimdigits.php + class Bench_LtrimDigits extends Codebench { + + // Some optional explanatory comments about the benchmark file. + // HTML allowed. URLs will be converted to links automatically. + public $description = 'Chopping off leading digits: regex vs ltrim.'; + + // How many times to execute each method per subject. + // Total loops = loops * number of methods * number of subjects + public $loops = 100000; + + // The subjects to supply iteratively to your benchmark methods. + public $subjects = array + ( + '123digits', + 'no-digits', + ); + + public function bench_regex($subject) + { + return preg_replace('/^\d+/', '', $subject); + } + + public function bench_ltrim($subject) + { + return ltrim($subject, '0..9'); + } + } + + + +And the winner is… [ltrim](http://php.net/ltrim). Happy benchmarking! \ No newline at end of file diff --git a/modules/codebench/guide/codebench/menu.md b/modules/codebench/guide/codebench/menu.md new file mode 100644 index 0000000..c73a19a --- /dev/null +++ b/modules/codebench/guide/codebench/menu.md @@ -0,0 +1 @@ +## [Codebench]() \ No newline at end of file diff --git a/modules/codebench/init.php b/modules/codebench/init.php new file mode 100644 index 0000000..f238cb0 --- /dev/null +++ b/modules/codebench/init.php @@ -0,0 +1,8 @@ +)') + ->defaults(array( + 'controller' => 'Codebench', + 'action' => 'index', + 'class' => NULL)); diff --git a/modules/codebench/media/guide/codebench/codebench_screenshot1.png b/modules/codebench/media/guide/codebench/codebench_screenshot1.png new file mode 100644 index 0000000..d1cfcfb Binary files /dev/null and b/modules/codebench/media/guide/codebench/codebench_screenshot1.png differ diff --git a/modules/codebench/media/guide/codebench/codebench_screenshot2.png b/modules/codebench/media/guide/codebench/codebench_screenshot2.png new file mode 100644 index 0000000..85bf560 Binary files /dev/null and b/modules/codebench/media/guide/codebench/codebench_screenshot2.png differ diff --git a/modules/codebench/views/codebench.php b/modules/codebench/views/codebench.php new file mode 100644 index 0000000..6482340 --- /dev/null +++ b/modules/codebench/views/codebench.php @@ -0,0 +1,260 @@ + + + + + + + + <?php if ($class !== ''): ?> + <?php echo $class, ' · ' ?> + <?php endif; ?>Codebench + + + + + + + + + + + +
+

+ + + + + Library not found + + No methods found to benchmark + + +

+
+ + + + + +

+ + Remember to prefix the methods you want to benchmark with “bench”.
+ You might also want to overwrite Codebench->method_filter(). + +

+ + + +
    + $benchmark) { ?> +
  • + +

    + + + +% + +

    + +
    + + + + + + + + + + + + $subject) { ?> + + + + + + + + +
    Benchmarks per subject for
    subject → returns
    + + [] → + + () + + + + + + + + + + + s + + +
    +
    + +
    • + +
+ + + + + + + + Raw output:', Debug::vars($codebench) ?> + + + + + + + diff --git a/modules/database/classes/Config/Database.php b/modules/database/classes/Config/Database.php new file mode 100644 index 0000000..7acb31b --- /dev/null +++ b/modules/database/classes/Config/Database.php @@ -0,0 +1,12 @@ +_db_instance = $config['instance']; + } + elseif ($this->_db_instance === NULL) + { + $this->_db_instance = Database::$default; + } + + if (isset($config['table_name'])) + { + $this->_table_name = $config['table_name']; + } + } + + /** + * Tries to load the specificed configuration group + * + * Returns FALSE if group does not exist or an array if it does + * + * @param string $group Configuration group + * @return boolean|array + */ + public function load($group) + { + /** + * Prevents the catch-22 scenario where the database config reader attempts to load the + * database connections details from the database. + * + * @link http://dev.kohanaframework.org/issues/4316 + */ + if ($group === 'database') + return FALSE; + + $query = DB::select('config_key', 'config_value') + ->from($this->_table_name) + ->where('group_name', '=', $group) + ->execute($this->_db_instance); + + return count($query) ? array_map('unserialize', $query->as_array('config_key', 'config_value')) : FALSE; + } +} diff --git a/modules/database/classes/Kohana/Config/Database/Writer.php b/modules/database/classes/Kohana/Config/Database/Writer.php new file mode 100644 index 0000000..f6b6738 --- /dev/null +++ b/modules/database/classes/Kohana/Config/Database/Writer.php @@ -0,0 +1,110 @@ +_loaded_keys[$group] = array_combine(array_keys($config), array_keys($config)); + } + + return $config; + } + + /** + * Writes the passed config for $group + * + * Returns chainable instance on success or throws + * Kohana_Config_Exception on failure + * + * @param string $group The config group + * @param string $key The config key to write to + * @param array $config The configuration to write + * @return boolean + */ + public function write($group, $key, $config) + { + $config = serialize($config); + + // Check to see if we've loaded the config from the table already + if (isset($this->_loaded_keys[$group][$key])) + { + $this->_update($group, $key, $config); + } + else + { + // Attempt to run an insert query + // This may fail if the config key already exists in the table + // and we don't know about it + try + { + $this->_insert($group, $key, $config); + } + catch (Database_Exception $e) + { + // Attempt to run an update instead + $this->_update($group, $key, $config); + } + } + + return TRUE; + } + + /** + * Insert the config values into the table + * + * @param string $group The config group + * @param string $key The config key to write to + * @param array $config The serialized configuration to write + * @return boolean + */ + protected function _insert($group, $key, $config) + { + DB::insert($this->_table_name, array('group_name', 'config_key', 'config_value')) + ->values(array($group, $key, $config)) + ->execute($this->_db_instance); + + return $this; + } + + /** + * Update the config values in the table + * + * @param string $group The config group + * @param string $key The config key to write to + * @param array $config The serialized configuration to write + * @return boolean + */ + protected function _update($group, $key, $config) + { + DB::update($this->_table_name) + ->set(array('config_value' => $config)) + ->where('group_name', '=', $group) + ->where('config_key', '=', $key) + ->execute($this->_db_instance); + + return $this; + } +} diff --git a/modules/database/classes/Kohana/DB.php b/modules/database/classes/Kohana/DB.php new file mode 100644 index 0000000..77388a9 --- /dev/null +++ b/modules/database/classes/Kohana/DB.php @@ -0,0 +1,139 @@ +[`DB::select_array()`](#select_array) | [Database_Query_Builder_Select] + * [`DB::update()`](#update) | [Database_Query_Builder_Update] + * [`DB::delete()`](#delete) | [Database_Query_Builder_Delete] + * [`DB::expr()`](#expr) | [Database_Expression] + * + * You pass the same parameters to these functions as you pass to the objects they return. + * + * @package Kohana/Database + * @category Base + * @author Kohana Team + * @copyright (c) 2009 Kohana Team + * @license http://kohanaphp.com/license + */ +class Kohana_DB { + + /** + * Create a new [Database_Query] of the given type. + * + * // Create a new SELECT query + * $query = DB::query(Database::SELECT, 'SELECT * FROM users'); + * + * // Create a new DELETE query + * $query = DB::query(Database::DELETE, 'DELETE FROM users WHERE id = 5'); + * + * Specifying the type changes the returned result. When using + * `Database::SELECT`, a [Database_Query_Result] will be returned. + * `Database::INSERT` queries will return the insert id and number of rows. + * For all other queries, the number of affected rows is returned. + * + * @param integer $type type: Database::SELECT, Database::UPDATE, etc + * @param string $sql SQL statement + * @return Database_Query + */ + public static function query($type, $sql) + { + return new Database_Query($type, $sql); + } + + /** + * Create a new [Database_Query_Builder_Select]. Each argument will be + * treated as a column. To generate a `foo AS bar` alias, use an array. + * + * // SELECT id, username + * $query = DB::select('id', 'username'); + * + * // SELECT id AS user_id + * $query = DB::select(array('id', 'user_id')); + * + * @param mixed $columns column name or array($column, $alias) or object + * @return Database_Query_Builder_Select + */ + public static function select($columns = NULL) + { + return new Database_Query_Builder_Select(func_get_args()); + } + + /** + * Create a new [Database_Query_Builder_Select] from an array of columns. + * + * // SELECT id, username + * $query = DB::select_array(array('id', 'username')); + * + * @param array $columns columns to select + * @return Database_Query_Builder_Select + */ + public static function select_array(array $columns = NULL) + { + return new Database_Query_Builder_Select($columns); + } + + /** + * Create a new [Database_Query_Builder_Insert]. + * + * // INSERT INTO users (id, username) + * $query = DB::insert('users', array('id', 'username')); + * + * @param string $table table to insert into + * @param array $columns list of column names or array($column, $alias) or object + * @return Database_Query_Builder_Insert + */ + public static function insert($table = NULL, array $columns = NULL) + { + return new Database_Query_Builder_Insert($table, $columns); + } + + /** + * Create a new [Database_Query_Builder_Update]. + * + * // UPDATE users + * $query = DB::update('users'); + * + * @param string $table table to update + * @return Database_Query_Builder_Update + */ + public static function update($table = NULL) + { + return new Database_Query_Builder_Update($table); + } + + /** + * Create a new [Database_Query_Builder_Delete]. + * + * // DELETE FROM users + * $query = DB::delete('users'); + * + * @param string $table table to delete from + * @return Database_Query_Builder_Delete + */ + public static function delete($table = NULL) + { + return new Database_Query_Builder_Delete($table); + } + + /** + * Create a new [Database_Expression] which is not escaped. An expression + * is the only way to use SQL functions within query builders. + * + * $expression = DB::expr('COUNT(users.id)'); + * $query = DB::update('users')->set(array('login_count' => DB::expr('login_count + 1')))->where('id', '=', $id); + * $users = ORM::factory('user')->where(DB::expr("BINARY `hash`"), '=', $hash)->find(); + * + * @param string $string expression + * @param array parameters + * @return Database_Expression + */ + public static function expr($string, $parameters = array()) + { + return new Database_Expression($string, $parameters); + } + +} // End DB diff --git a/modules/database/classes/Kohana/Database.php b/modules/database/classes/Kohana/Database.php new file mode 100644 index 0000000..267d938 --- /dev/null +++ b/modules/database/classes/Kohana/Database.php @@ -0,0 +1,726 @@ +load('database')->$name; + } + + if ( ! isset($config['type'])) + { + throw new Kohana_Exception('Database type not defined in :name configuration', + array(':name' => $name)); + } + + // Set the driver class name + $driver = 'Database_'.ucfirst($config['type']); + + // Create the database connection instance + $driver = new $driver($name, $config); + + // Store the database instance + Database::$instances[$name] = $driver; + } + + return Database::$instances[$name]; + } + + /** + * @var string the last query executed + */ + public $last_query; + + // Character that is used to quote identifiers + protected $_identifier = '"'; + + // Instance name + protected $_instance; + + // Raw server connection + protected $_connection; + + // Configuration array + protected $_config; + + /** + * Stores the database configuration locally and name the instance. + * + * [!!] This method cannot be accessed directly, you must use [Database::instance]. + * + * @return void + */ + public function __construct($name, array $config) + { + // Set the instance name + $this->_instance = $name; + + // Store the config locally + $this->_config = $config; + + if (empty($this->_config['table_prefix'])) + { + $this->_config['table_prefix'] = ''; + } + } + + /** + * Disconnect from the database when the object is destroyed. + * + * // Destroy the database instance + * unset(Database::instances[(string) $db], $db); + * + * [!!] Calling `unset($db)` is not enough to destroy the database, as it + * will still be stored in `Database::$instances`. + * + * @return void + */ + public function __destruct() + { + $this->disconnect(); + } + + /** + * Returns the database instance name. + * + * echo (string) $db; + * + * @return string + */ + public function __toString() + { + return $this->_instance; + } + + /** + * Connect to the database. This is called automatically when the first + * query is executed. + * + * $db->connect(); + * + * @throws Database_Exception + * @return void + */ + abstract public function connect(); + + /** + * Disconnect from the database. This is called automatically by [Database::__destruct]. + * Clears the database instance from [Database::$instances]. + * + * $db->disconnect(); + * + * @return boolean + */ + public function disconnect() + { + unset(Database::$instances[$this->_instance]); + + return TRUE; + } + + /** + * Set the connection character set. This is called automatically by [Database::connect]. + * + * $db->set_charset('utf8'); + * + * @throws Database_Exception + * @param string $charset character set name + * @return void + */ + abstract public function set_charset($charset); + + /** + * Perform an SQL query of the given type. + * + * // Make a SELECT query and use objects for results + * $db->query(Database::SELECT, 'SELECT * FROM groups', TRUE); + * + * // Make a SELECT query and use "Model_User" for the results + * $db->query(Database::SELECT, 'SELECT * FROM users LIMIT 1', 'Model_User'); + * + * @param integer $type Database::SELECT, Database::INSERT, etc + * @param string $sql SQL query + * @param mixed $as_object result object class string, TRUE for stdClass, FALSE for assoc array + * @param array $params object construct parameters for result class + * @return object Database_Result for SELECT queries + * @return array list (insert id, row count) for INSERT queries + * @return integer number of affected rows for all other queries + */ + abstract public function query($type, $sql, $as_object = FALSE, array $params = NULL); + + /** + * Start a SQL transaction + * + * // Start the transactions + * $db->begin(); + * + * try { + * DB::insert('users')->values($user1)... + * DB::insert('users')->values($user2)... + * // Insert successful commit the changes + * $db->commit(); + * } + * catch (Database_Exception $e) + * { + * // Insert failed. Rolling back changes... + * $db->rollback(); + * } + * + * @param string $mode transaction mode + * @return boolean + */ + abstract public function begin($mode = NULL); + + /** + * Commit the current transaction + * + * // Commit the database changes + * $db->commit(); + * + * @return boolean + */ + abstract public function commit(); + + /** + * Abort the current transaction + * + * // Undo the changes + * $db->rollback(); + * + * @return boolean + */ + abstract public function rollback(); + + /** + * Count the number of records in a table. + * + * // Get the total number of records in the "users" table + * $count = $db->count_records('users'); + * + * @param mixed $table table name string or array(query, alias) + * @return integer + */ + public function count_records($table) + { + // Quote the table name + $table = $this->quote_table($table); + + return $this->query(Database::SELECT, 'SELECT COUNT(*) AS total_row_count FROM '.$table, FALSE) + ->get('total_row_count'); + } + + /** + * Returns a normalized array describing the SQL data type + * + * $db->datatype('char'); + * + * @param string $type SQL data type + * @return array + */ + public function datatype($type) + { + static $types = array + ( + // SQL-92 + 'bit' => array('type' => 'string', 'exact' => TRUE), + 'bit varying' => array('type' => 'string'), + 'char' => array('type' => 'string', 'exact' => TRUE), + 'char varying' => array('type' => 'string'), + 'character' => array('type' => 'string', 'exact' => TRUE), + 'character varying' => array('type' => 'string'), + 'date' => array('type' => 'string'), + 'dec' => array('type' => 'float', 'exact' => TRUE), + 'decimal' => array('type' => 'float', 'exact' => TRUE), + 'double precision' => array('type' => 'float'), + 'float' => array('type' => 'float'), + 'int' => array('type' => 'int', 'min' => '-2147483648', 'max' => '2147483647'), + 'integer' => array('type' => 'int', 'min' => '-2147483648', 'max' => '2147483647'), + 'interval' => array('type' => 'string'), + 'national char' => array('type' => 'string', 'exact' => TRUE), + 'national char varying' => array('type' => 'string'), + 'national character' => array('type' => 'string', 'exact' => TRUE), + 'national character varying' => array('type' => 'string'), + 'nchar' => array('type' => 'string', 'exact' => TRUE), + 'nchar varying' => array('type' => 'string'), + 'numeric' => array('type' => 'float', 'exact' => TRUE), + 'real' => array('type' => 'float'), + 'smallint' => array('type' => 'int', 'min' => '-32768', 'max' => '32767'), + 'time' => array('type' => 'string'), + 'time with time zone' => array('type' => 'string'), + 'timestamp' => array('type' => 'string'), + 'timestamp with time zone' => array('type' => 'string'), + 'varchar' => array('type' => 'string'), + + // SQL:1999 + 'binary large object' => array('type' => 'string', 'binary' => TRUE), + 'blob' => array('type' => 'string', 'binary' => TRUE), + 'boolean' => array('type' => 'bool'), + 'char large object' => array('type' => 'string'), + 'character large object' => array('type' => 'string'), + 'clob' => array('type' => 'string'), + 'national character large object' => array('type' => 'string'), + 'nchar large object' => array('type' => 'string'), + 'nclob' => array('type' => 'string'), + 'time without time zone' => array('type' => 'string'), + 'timestamp without time zone' => array('type' => 'string'), + + // SQL:2003 + 'bigint' => array('type' => 'int', 'min' => '-9223372036854775808', 'max' => '9223372036854775807'), + + // SQL:2008 + 'binary' => array('type' => 'string', 'binary' => TRUE, 'exact' => TRUE), + 'binary varying' => array('type' => 'string', 'binary' => TRUE), + 'varbinary' => array('type' => 'string', 'binary' => TRUE), + ); + + if (isset($types[$type])) + return $types[$type]; + + return array(); + } + + /** + * List all of the tables in the database. Optionally, a LIKE string can + * be used to search for specific tables. + * + * // Get all tables in the current database + * $tables = $db->list_tables(); + * + * // Get all user-related tables + * $tables = $db->list_tables('user%'); + * + * @param string $like table to search for + * @return array + */ + abstract public function list_tables($like = NULL); + + /** + * Lists all of the columns in a table. Optionally, a LIKE string can be + * used to search for specific fields. + * + * // Get all columns from the "users" table + * $columns = $db->list_columns('users'); + * + * // Get all name-related columns + * $columns = $db->list_columns('users', '%name%'); + * + * // Get the columns from a table that doesn't use the table prefix + * $columns = $db->list_columns('users', NULL, FALSE); + * + * @param string $table table to get columns from + * @param string $like column to search for + * @param boolean $add_prefix whether to add the table prefix automatically or not + * @return array + */ + abstract public function list_columns($table, $like = NULL, $add_prefix = TRUE); + + /** + * Extracts the text between parentheses, if any. + * + * // Returns: array('CHAR', '6') + * list($type, $length) = $db->_parse_type('CHAR(6)'); + * + * @param string $type + * @return array list containing the type and length, if any + */ + protected function _parse_type($type) + { + if (($open = strpos($type, '(')) === FALSE) + { + // No length specified + return array($type, NULL); + } + + // Closing parenthesis + $close = strrpos($type, ')', $open); + + // Length without parentheses + $length = substr($type, $open + 1, $close - 1 - $open); + + // Type without the length + $type = substr($type, 0, $open).substr($type, $close + 1); + + return array($type, $length); + } + + /** + * Return the table prefix defined in the current configuration. + * + * $prefix = $db->table_prefix(); + * + * @return string + */ + public function table_prefix() + { + return $this->_config['table_prefix']; + } + + /** + * Quote a value for an SQL query. + * + * $db->quote(NULL); // 'NULL' + * $db->quote(10); // 10 + * $db->quote('fred'); // 'fred' + * + * Objects passed to this function will be converted to strings. + * [Database_Expression] objects will be compiled. + * [Database_Query] objects will be compiled and converted to a sub-query. + * All other objects will be converted using the `__toString` method. + * + * @param mixed $value any value to quote + * @return string + * @uses Database::escape + */ + public function quote($value) + { + if ($value === NULL) + { + return 'NULL'; + } + elseif ($value === TRUE) + { + return "'1'"; + } + elseif ($value === FALSE) + { + return "'0'"; + } + elseif (is_object($value)) + { + if ($value instanceof Database_Query) + { + // Create a sub-query + return '('.$value->compile($this).')'; + } + elseif ($value instanceof Database_Expression) + { + // Compile the expression + return $value->compile($this); + } + else + { + // Convert the object to a string + return $this->quote( (string) $value); + } + } + elseif (is_array($value)) + { + return '('.implode(', ', array_map(array($this, __FUNCTION__), $value)).')'; + } + elseif (is_int($value)) + { + return (int) $value; + } + elseif (is_float($value)) + { + // Convert to non-locale aware float to prevent possible commas + return sprintf('%F', $value); + } + + return $this->escape($value); + } + + /** + * Quote a database column name and add the table prefix if needed. + * + * $column = $db->quote_column($column); + * + * You can also use SQL methods within identifiers. + * + * $column = $db->quote_column(DB::expr('COUNT(`column`)')); + * + * Objects passed to this function will be converted to strings. + * [Database_Expression] objects will be compiled. + * [Database_Query] objects will be compiled and converted to a sub-query. + * All other objects will be converted using the `__toString` method. + * + * @param mixed $column column name or array(column, alias) + * @return string + * @uses Database::quote_identifier + * @uses Database::table_prefix + */ + public function quote_column($column) + { + // Identifiers are escaped by repeating them + $escaped_identifier = $this->_identifier.$this->_identifier; + + if (is_array($column)) + { + list($column, $alias) = $column; + $alias = str_replace($this->_identifier, $escaped_identifier, $alias); + } + + if ($column instanceof Database_Query) + { + // Create a sub-query + $column = '('.$column->compile($this).')'; + } + elseif ($column instanceof Database_Expression) + { + // Compile the expression + $column = $column->compile($this); + } + else + { + // Convert to a string + $column = (string) $column; + + $column = str_replace($this->_identifier, $escaped_identifier, $column); + + if ($column === '*') + { + return $column; + } + elseif (strpos($column, '.') !== FALSE) + { + $parts = explode('.', $column); + + if ($prefix = $this->table_prefix()) + { + // Get the offset of the table name, 2nd-to-last part + $offset = count($parts) - 2; + + // Add the table prefix to the table name + $parts[$offset] = $prefix.$parts[$offset]; + } + + foreach ($parts as & $part) + { + if ($part !== '*') + { + // Quote each of the parts + $part = $this->_identifier.$part.$this->_identifier; + } + } + + $column = implode('.', $parts); + } + else + { + $column = $this->_identifier.$column.$this->_identifier; + } + } + + if (isset($alias)) + { + $column .= ' AS '.$this->_identifier.$alias.$this->_identifier; + } + + return $column; + } + + /** + * Quote a database table name and adds the table prefix if needed. + * + * $table = $db->quote_table($table); + * + * Objects passed to this function will be converted to strings. + * [Database_Expression] objects will be compiled. + * [Database_Query] objects will be compiled and converted to a sub-query. + * All other objects will be converted using the `__toString` method. + * + * @param mixed $table table name or array(table, alias) + * @return string + * @uses Database::quote_identifier + * @uses Database::table_prefix + */ + public function quote_table($table) + { + // Identifiers are escaped by repeating them + $escaped_identifier = $this->_identifier.$this->_identifier; + + if (is_array($table)) + { + list($table, $alias) = $table; + $alias = str_replace($this->_identifier, $escaped_identifier, $alias); + } + + if ($table instanceof Database_Query) + { + // Create a sub-query + $table = '('.$table->compile($this).')'; + } + elseif ($table instanceof Database_Expression) + { + // Compile the expression + $table = $table->compile($this); + } + else + { + // Convert to a string + $table = (string) $table; + + $table = str_replace($this->_identifier, $escaped_identifier, $table); + + if (strpos($table, '.') !== FALSE) + { + $parts = explode('.', $table); + + if ($prefix = $this->table_prefix()) + { + // Get the offset of the table name, last part + $offset = count($parts) - 1; + + // Add the table prefix to the table name + $parts[$offset] = $prefix.$parts[$offset]; + } + + foreach ($parts as & $part) + { + // Quote each of the parts + $part = $this->_identifier.$part.$this->_identifier; + } + + $table = implode('.', $parts); + } + else + { + // Add the table prefix + $table = $this->_identifier.$this->table_prefix().$table.$this->_identifier; + } + } + + if (isset($alias)) + { + // Attach table prefix to alias + $table .= ' AS '.$this->_identifier.$this->table_prefix().$alias.$this->_identifier; + } + + return $table; + } + + /** + * Quote a database identifier + * + * Objects passed to this function will be converted to strings. + * [Database_Expression] objects will be compiled. + * [Database_Query] objects will be compiled and converted to a sub-query. + * All other objects will be converted using the `__toString` method. + * + * @param mixed $value any identifier + * @return string + */ + public function quote_identifier($value) + { + // Identifiers are escaped by repeating them + $escaped_identifier = $this->_identifier.$this->_identifier; + + if (is_array($value)) + { + list($value, $alias) = $value; + $alias = str_replace($this->_identifier, $escaped_identifier, $alias); + } + + if ($value instanceof Database_Query) + { + // Create a sub-query + $value = '('.$value->compile($this).')'; + } + elseif ($value instanceof Database_Expression) + { + // Compile the expression + $value = $value->compile($this); + } + else + { + // Convert to a string + $value = (string) $value; + + $value = str_replace($this->_identifier, $escaped_identifier, $value); + + if (strpos($value, '.') !== FALSE) + { + $parts = explode('.', $value); + + foreach ($parts as & $part) + { + // Quote each of the parts + $part = $this->_identifier.$part.$this->_identifier; + } + + $value = implode('.', $parts); + } + else + { + $value = $this->_identifier.$value.$this->_identifier; + } + } + + if (isset($alias)) + { + $value .= ' AS '.$this->_identifier.$alias.$this->_identifier; + } + + return $value; + } + + /** + * Sanitize a string by escaping characters that could cause an SQL + * injection attack. + * + * $value = $db->escape('any string'); + * + * @param string $value value to quote + * @return string + */ + abstract public function escape($value); + +} // End Database_Connection diff --git a/modules/database/classes/Kohana/Database/Exception.php b/modules/database/classes/Kohana/Database/Exception.php new file mode 100644 index 0000000..68f709e --- /dev/null +++ b/modules/database/classes/Kohana/Database/Exception.php @@ -0,0 +1,11 @@ +_value = $value; + $this->_parameters = $parameters; + } + + /** + * Bind a variable to a parameter. + * + * @param string $param parameter key to replace + * @param mixed $var variable to use + * @return $this + */ + public function bind($param, & $var) + { + $this->_parameters[$param] =& $var; + + return $this; + } + + /** + * Set the value of a parameter. + * + * @param string $param parameter key to replace + * @param mixed $value value to use + * @return $this + */ + public function param($param, $value) + { + $this->_parameters[$param] = $value; + + return $this; + } + + /** + * Add multiple parameter values. + * + * @param array $params list of parameter values + * @return $this + */ + public function parameters(array $params) + { + $this->_parameters = $params + $this->_parameters; + + return $this; + } + + /** + * Get the expression value as a string. + * + * $sql = $expression->value(); + * + * @return string + */ + public function value() + { + return (string) $this->_value; + } + + /** + * Return the value of the expression as a string. + * + * echo $expression; + * + * @return string + * @uses Database_Expression::value + */ + public function __toString() + { + return $this->value(); + } + + /** + * Compile the SQL expression and return it. Replaces any parameters with + * their given values. + * + * @param mixed Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + $value = $this->value(); + + if ( ! empty($this->_parameters)) + { + // Quote all of the parameter values + $params = array_map(array($db, 'quote'), $this->_parameters); + + // Replace the values in the expression + $value = strtr($value, $params); + } + + return $value; + } + +} // End Database_Expression diff --git a/modules/database/classes/Kohana/Database/MySQL.php b/modules/database/classes/Kohana/Database/MySQL.php new file mode 100644 index 0000000..8700904 --- /dev/null +++ b/modules/database/classes/Kohana/Database/MySQL.php @@ -0,0 +1,443 @@ +_connection) + return; + + if (Database_MySQL::$_set_names === NULL) + { + // Determine if we can use mysql_set_charset(), which is only + // available on PHP 5.2.3+ when compiled against MySQL 5.0+ + Database_MySQL::$_set_names = ! function_exists('mysql_set_charset'); + } + + // Extract the connection parameters, adding required variabels + extract($this->_config['connection'] + array( + 'database' => '', + 'hostname' => '', + 'username' => '', + 'password' => '', + 'persistent' => FALSE, + )); + + // Prevent this information from showing up in traces + unset($this->_config['connection']['username'], $this->_config['connection']['password']); + + try + { + if ($persistent) + { + // Create a persistent connection + $this->_connection = mysql_pconnect($hostname, $username, $password); + } + else + { + // Create a connection and force it to be a new link + $this->_connection = mysql_connect($hostname, $username, $password, TRUE); + } + } + catch (Exception $e) + { + // No connection exists + $this->_connection = NULL; + + throw new Database_Exception(':error', + array(':error' => $e->getMessage()), + $e->getCode()); + } + + // \xFF is a better delimiter, but the PHP driver uses underscore + $this->_connection_id = sha1($hostname.'_'.$username.'_'.$password); + + $this->_select_db($database); + + if ( ! empty($this->_config['charset'])) + { + // Set the character set + $this->set_charset($this->_config['charset']); + } + + if ( ! empty($this->_config['connection']['variables'])) + { + // Set session variables + $variables = array(); + + foreach ($this->_config['connection']['variables'] as $var => $val) + { + $variables[] = 'SESSION '.$var.' = '.$this->quote($val); + } + + mysql_query('SET '.implode(', ', $variables), $this->_connection); + } + } + + /** + * Select the database + * + * @param string $database Database + * @return void + */ + protected function _select_db($database) + { + if ( ! mysql_select_db($database, $this->_connection)) + { + // Unable to select database + throw new Database_Exception(':error', + array(':error' => mysql_error($this->_connection)), + mysql_errno($this->_connection)); + } + + Database_MySQL::$_current_databases[$this->_connection_id] = $database; + } + + public function disconnect() + { + try + { + // Database is assumed disconnected + $status = TRUE; + + if (is_resource($this->_connection)) + { + if ($status = mysql_close($this->_connection)) + { + // Clear the connection + $this->_connection = NULL; + + // Clear the instance + parent::disconnect(); + } + } + } + catch (Exception $e) + { + // Database is probably not disconnected + $status = ! is_resource($this->_connection); + } + + return $status; + } + + public function set_charset($charset) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + if (Database_MySQL::$_set_names === TRUE) + { + // PHP is compiled against MySQL 4.x + $status = (bool) mysql_query('SET NAMES '.$this->quote($charset), $this->_connection); + } + else + { + // PHP is compiled against MySQL 5.x + $status = mysql_set_charset($charset, $this->_connection); + } + + if ($status === FALSE) + { + throw new Database_Exception(':error', + array(':error' => mysql_error($this->_connection)), + mysql_errno($this->_connection)); + } + } + + public function query($type, $sql, $as_object = FALSE, array $params = NULL) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + if (Kohana::$profiling) + { + // Benchmark this query for the current instance + $benchmark = Profiler::start("Database ({$this->_instance})", $sql); + } + + if ( ! empty($this->_config['connection']['persistent']) AND $this->_config['connection']['database'] !== Database_MySQL::$_current_databases[$this->_connection_id]) + { + // Select database on persistent connections + $this->_select_db($this->_config['connection']['database']); + } + + // Execute the query + if (($result = mysql_query($sql, $this->_connection)) === FALSE) + { + if (isset($benchmark)) + { + // This benchmark is worthless + Profiler::delete($benchmark); + } + + throw new Database_Exception(':error [ :query ]', + array(':error' => mysql_error($this->_connection), ':query' => $sql), + mysql_errno($this->_connection)); + } + + if (isset($benchmark)) + { + Profiler::stop($benchmark); + } + + // Set the last query + $this->last_query = $sql; + + if ($type === Database::SELECT) + { + // Return an iterator of results + return new Database_MySQL_Result($result, $sql, $as_object, $params); + } + elseif ($type === Database::INSERT) + { + // Return a list of insert id and rows created + return array( + mysql_insert_id($this->_connection), + mysql_affected_rows($this->_connection), + ); + } + else + { + // Return the number of rows affected + return mysql_affected_rows($this->_connection); + } + } + + public function datatype($type) + { + static $types = array + ( + 'blob' => array('type' => 'string', 'binary' => TRUE, 'character_maximum_length' => '65535'), + 'bool' => array('type' => 'bool'), + 'bigint unsigned' => array('type' => 'int', 'min' => '0', 'max' => '18446744073709551615'), + 'datetime' => array('type' => 'string'), + 'decimal unsigned' => array('type' => 'float', 'exact' => TRUE, 'min' => '0'), + 'double' => array('type' => 'float'), + 'double precision unsigned' => array('type' => 'float', 'min' => '0'), + 'double unsigned' => array('type' => 'float', 'min' => '0'), + 'enum' => array('type' => 'string'), + 'fixed' => array('type' => 'float', 'exact' => TRUE), + 'fixed unsigned' => array('type' => 'float', 'exact' => TRUE, 'min' => '0'), + 'float unsigned' => array('type' => 'float', 'min' => '0'), + 'int unsigned' => array('type' => 'int', 'min' => '0', 'max' => '4294967295'), + 'integer unsigned' => array('type' => 'int', 'min' => '0', 'max' => '4294967295'), + 'longblob' => array('type' => 'string', 'binary' => TRUE, 'character_maximum_length' => '4294967295'), + 'longtext' => array('type' => 'string', 'character_maximum_length' => '4294967295'), + 'mediumblob' => array('type' => 'string', 'binary' => TRUE, 'character_maximum_length' => '16777215'), + 'mediumint' => array('type' => 'int', 'min' => '-8388608', 'max' => '8388607'), + 'mediumint unsigned' => array('type' => 'int', 'min' => '0', 'max' => '16777215'), + 'mediumtext' => array('type' => 'string', 'character_maximum_length' => '16777215'), + 'national varchar' => array('type' => 'string'), + 'numeric unsigned' => array('type' => 'float', 'exact' => TRUE, 'min' => '0'), + 'nvarchar' => array('type' => 'string'), + 'point' => array('type' => 'string', 'binary' => TRUE), + 'real unsigned' => array('type' => 'float', 'min' => '0'), + 'set' => array('type' => 'string'), + 'smallint unsigned' => array('type' => 'int', 'min' => '0', 'max' => '65535'), + 'text' => array('type' => 'string', 'character_maximum_length' => '65535'), + 'tinyblob' => array('type' => 'string', 'binary' => TRUE, 'character_maximum_length' => '255'), + 'tinyint' => array('type' => 'int', 'min' => '-128', 'max' => '127'), + 'tinyint unsigned' => array('type' => 'int', 'min' => '0', 'max' => '255'), + 'tinytext' => array('type' => 'string', 'character_maximum_length' => '255'), + 'year' => array('type' => 'string'), + ); + + $type = str_replace(' zerofill', '', $type); + + if (isset($types[$type])) + return $types[$type]; + + return parent::datatype($type); + } + + /** + * Start a SQL transaction + * + * @link http://dev.mysql.com/doc/refman/5.0/en/set-transaction.html + * + * @param string $mode Isolation level + * @return boolean + */ + public function begin($mode = NULL) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + if ($mode AND ! mysql_query("SET TRANSACTION ISOLATION LEVEL $mode", $this->_connection)) + { + throw new Database_Exception(':error', + array(':error' => mysql_error($this->_connection)), + mysql_errno($this->_connection)); + } + + return (bool) mysql_query('START TRANSACTION', $this->_connection); + } + + /** + * Commit a SQL transaction + * + * @return boolean + */ + public function commit() + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + return (bool) mysql_query('COMMIT', $this->_connection); + } + + /** + * Rollback a SQL transaction + * + * @return boolean + */ + public function rollback() + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + return (bool) mysql_query('ROLLBACK', $this->_connection); + } + + public function list_tables($like = NULL) + { + if (is_string($like)) + { + // Search for table names + $result = $this->query(Database::SELECT, 'SHOW TABLES LIKE '.$this->quote($like), FALSE); + } + else + { + // Find all table names + $result = $this->query(Database::SELECT, 'SHOW TABLES', FALSE); + } + + $tables = array(); + foreach ($result as $row) + { + $tables[] = reset($row); + } + + return $tables; + } + + public function list_columns($table, $like = NULL, $add_prefix = TRUE) + { + // Quote the table name + $table = ($add_prefix === TRUE) ? $this->quote_table($table) : $table; + + if (is_string($like)) + { + // Search for column names + $result = $this->query(Database::SELECT, 'SHOW FULL COLUMNS FROM '.$table.' LIKE '.$this->quote($like), FALSE); + } + else + { + // Find all column names + $result = $this->query(Database::SELECT, 'SHOW FULL COLUMNS FROM '.$table, FALSE); + } + + $count = 0; + $columns = array(); + foreach ($result as $row) + { + list($type, $length) = $this->_parse_type($row['Type']); + + $column = $this->datatype($type); + + $column['column_name'] = $row['Field']; + $column['column_default'] = $row['Default']; + $column['data_type'] = $type; + $column['is_nullable'] = ($row['Null'] == 'YES'); + $column['ordinal_position'] = ++$count; + + switch ($column['type']) + { + case 'float': + if (isset($length)) + { + list($column['numeric_precision'], $column['numeric_scale']) = explode(',', $length); + } + break; + case 'int': + if (isset($length)) + { + // MySQL attribute + $column['display'] = $length; + } + break; + case 'string': + switch ($column['data_type']) + { + case 'binary': + case 'varbinary': + $column['character_maximum_length'] = $length; + break; + case 'char': + case 'varchar': + $column['character_maximum_length'] = $length; + case 'text': + case 'tinytext': + case 'mediumtext': + case 'longtext': + $column['collation_name'] = $row['Collation']; + break; + case 'enum': + case 'set': + $column['collation_name'] = $row['Collation']; + $column['options'] = explode('\',\'', substr($length, 1, -1)); + break; + } + break; + } + + // MySQL attributes + $column['comment'] = $row['Comment']; + $column['extra'] = $row['Extra']; + $column['key'] = $row['Key']; + $column['privileges'] = $row['Privileges']; + + $columns[$row['Field']] = $column; + } + + return $columns; + } + + public function escape($value) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + if (($value = mysql_real_escape_string( (string) $value, $this->_connection)) === FALSE) + { + throw new Database_Exception(':error', + array(':error' => mysql_error($this->_connection)), + mysql_errno($this->_connection)); + } + + // SQL standard is to use single-quotes for all values + return "'$value'"; + } + +} // End Database_MySQL diff --git a/modules/database/classes/Kohana/Database/MySQL/Result.php b/modules/database/classes/Kohana/Database/MySQL/Result.php new file mode 100644 index 0000000..22a5d14 --- /dev/null +++ b/modules/database/classes/Kohana/Database/MySQL/Result.php @@ -0,0 +1,71 @@ +_total_rows = mysql_num_rows($result); + } + + public function __destruct() + { + if (is_resource($this->_result)) + { + mysql_free_result($this->_result); + } + } + + public function seek($offset) + { + if ($this->offsetExists($offset) AND mysql_data_seek($this->_result, $offset)) + { + // Set the current row to the offset + $this->_current_row = $this->_internal_row = $offset; + + return TRUE; + } + else + { + return FALSE; + } + } + + public function current() + { + if ($this->_current_row !== $this->_internal_row AND ! $this->seek($this->_current_row)) + return NULL; + + // Increment internal row for optimization assuming rows are fetched in order + $this->_internal_row++; + + if ($this->_as_object === TRUE) + { + // Return an stdClass + return mysql_fetch_object($this->_result); + } + elseif (is_string($this->_as_object)) + { + // Return an object of given class name + return mysql_fetch_object($this->_result, $this->_as_object, $this->_object_params); + } + else + { + // Return an array of the row + return mysql_fetch_assoc($this->_result); + } + } + +} // End Database_MySQL_Result_Select diff --git a/modules/database/classes/Kohana/Database/PDO.php b/modules/database/classes/Kohana/Database/PDO.php new file mode 100644 index 0000000..573f8d3 --- /dev/null +++ b/modules/database/classes/Kohana/Database/PDO.php @@ -0,0 +1,247 @@ +_config['identifier'])) + { + // Allow the identifier to be overloaded per-connection + $this->_identifier = (string) $this->_config['identifier']; + } + } + + public function connect() + { + if ($this->_connection) + return; + + // Extract the connection parameters, adding required variabels + extract($this->_config['connection'] + array( + 'dsn' => '', + 'username' => NULL, + 'password' => NULL, + 'persistent' => FALSE, + )); + + // Clear the connection parameters for security + unset($this->_config['connection']); + + // Force PDO to use exceptions for all errors + $options[PDO::ATTR_ERRMODE] = PDO::ERRMODE_EXCEPTION; + + if ( ! empty($persistent)) + { + // Make the connection persistent + $options[PDO::ATTR_PERSISTENT] = TRUE; + } + + try + { + // Create a new PDO connection + $this->_connection = new PDO($dsn, $username, $password, $options); + } + catch (PDOException $e) + { + throw new Database_Exception(':error', + array(':error' => $e->getMessage()), + $e->getCode()); + } + } + + /** + * Create or redefine a SQL aggregate function. + * + * [!!] Works only with SQLite + * + * @link http://php.net/manual/function.pdo-sqlitecreateaggregate + * + * @param string $name Name of the SQL function to be created or redefined + * @param callback $step Called for each row of a result set + * @param callback $final Called after all rows of a result set have been processed + * @param integer $arguments Number of arguments that the SQL function takes + * + * @return boolean + */ + public function create_aggregate($name, $step, $final, $arguments = -1) + { + $this->_connection or $this->connect(); + + return $this->_connection->sqliteCreateAggregate( + $name, $step, $final, $arguments + ); + } + + /** + * Create or redefine a SQL function. + * + * [!!] Works only with SQLite + * + * @link http://php.net/manual/function.pdo-sqlitecreatefunction + * + * @param string $name Name of the SQL function to be created or redefined + * @param callback $callback Callback which implements the SQL function + * @param integer $arguments Number of arguments that the SQL function takes + * + * @return boolean + */ + public function create_function($name, $callback, $arguments = -1) + { + $this->_connection or $this->connect(); + + return $this->_connection->sqliteCreateFunction( + $name, $callback, $arguments + ); + } + + public function disconnect() + { + // Destroy the PDO object + $this->_connection = NULL; + + return parent::disconnect(); + } + + public function set_charset($charset) + { + // Make sure the database is connected + $this->_connection OR $this->connect(); + + // This SQL-92 syntax is not supported by all drivers + $this->_connection->exec('SET NAMES '.$this->quote($charset)); + } + + public function query($type, $sql, $as_object = FALSE, array $params = NULL) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + if (Kohana::$profiling) + { + // Benchmark this query for the current instance + $benchmark = Profiler::start("Database ({$this->_instance})", $sql); + } + + try + { + $result = $this->_connection->query($sql); + } + catch (Exception $e) + { + if (isset($benchmark)) + { + // This benchmark is worthless + Profiler::delete($benchmark); + } + + // Convert the exception in a database exception + throw new Database_Exception(':error [ :query ]', + array( + ':error' => $e->getMessage(), + ':query' => $sql + ), + $e->getCode()); + } + + if (isset($benchmark)) + { + Profiler::stop($benchmark); + } + + // Set the last query + $this->last_query = $sql; + + if ($type === Database::SELECT) + { + // Convert the result into an array, as PDOStatement::rowCount is not reliable + if ($as_object === FALSE) + { + $result->setFetchMode(PDO::FETCH_ASSOC); + } + elseif (is_string($as_object)) + { + $result->setFetchMode(PDO::FETCH_CLASS, $as_object, $params); + } + else + { + $result->setFetchMode(PDO::FETCH_CLASS, 'stdClass'); + } + + $result = $result->fetchAll(); + + // Return an iterator of results + return new Database_Result_Cached($result, $sql, $as_object, $params); + } + elseif ($type === Database::INSERT) + { + // Return a list of insert id and rows created + return array( + $this->_connection->lastInsertId(), + $result->rowCount(), + ); + } + else + { + // Return the number of rows affected + return $result->rowCount(); + } + } + + public function begin($mode = NULL) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + return $this->_connection->beginTransaction(); + } + + public function commit() + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + return $this->_connection->commit(); + } + + public function rollback() + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + return $this->_connection->rollBack(); + } + + public function list_tables($like = NULL) + { + throw new Kohana_Exception('Database method :method is not supported by :class', + array(':method' => __FUNCTION__, ':class' => __CLASS__)); + } + + public function list_columns($table, $like = NULL, $add_prefix = TRUE) + { + throw new Kohana_Exception('Database method :method is not supported by :class', + array(':method' => __FUNCTION__, ':class' => __CLASS__)); + } + + public function escape($value) + { + // Make sure the database is connected + $this->_connection or $this->connect(); + + return $this->_connection->quote($value); + } + +} // End Database_PDO diff --git a/modules/database/classes/Kohana/Database/Query.php b/modules/database/classes/Kohana/Database/Query.php new file mode 100644 index 0000000..480e41b --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query.php @@ -0,0 +1,262 @@ +_type = $type; + $this->_sql = $sql; + } + + /** + * Return the SQL query string. + * + * @return string + */ + public function __toString() + { + try + { + // Return the SQL string + return $this->compile(Database::instance()); + } + catch (Exception $e) + { + return Kohana_Exception::text($e); + } + } + + /** + * Get the type of the query. + * + * @return integer + */ + public function type() + { + return $this->_type; + } + + /** + * Enables the query to be cached for a specified amount of time. + * + * @param integer $lifetime number of seconds to cache, 0 deletes it from the cache + * @param boolean whether or not to execute the query during a cache hit + * @return $this + * @uses Kohana::$cache_life + */ + public function cached($lifetime = NULL, $force = FALSE) + { + if ($lifetime === NULL) + { + // Use the global setting + $lifetime = Kohana::$cache_life; + } + + $this->_force_execute = $force; + $this->_lifetime = $lifetime; + + return $this; + } + + /** + * Returns results as associative arrays + * + * @return $this + */ + public function as_assoc() + { + $this->_as_object = FALSE; + + $this->_object_params = array(); + + return $this; + } + + /** + * Returns results as objects + * + * @param string $class classname or TRUE for stdClass + * @param array $params + * @return $this + */ + public function as_object($class = TRUE, array $params = NULL) + { + $this->_as_object = $class; + + if ($params) + { + // Add object parameters + $this->_object_params = $params; + } + + return $this; + } + + /** + * Set the value of a parameter in the query. + * + * @param string $param parameter key to replace + * @param mixed $value value to use + * @return $this + */ + public function param($param, $value) + { + // Add or overload a new parameter + $this->_parameters[$param] = $value; + + return $this; + } + + /** + * Bind a variable to a parameter in the query. + * + * @param string $param parameter key to replace + * @param mixed $var variable to use + * @return $this + */ + public function bind($param, & $var) + { + // Bind a value to a variable + $this->_parameters[$param] =& $var; + + return $this; + } + + /** + * Add multiple parameters to the query. + * + * @param array $params list of parameters + * @return $this + */ + public function parameters(array $params) + { + // Merge the new parameters in + $this->_parameters = $params + $this->_parameters; + + return $this; + } + + /** + * Compile the SQL query and return it. Replaces any parameters with their + * given values. + * + * @param mixed $db Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + // Import the SQL locally + $sql = $this->_sql; + + if ( ! empty($this->_parameters)) + { + // Quote all of the values + $values = array_map(array($db, 'quote'), $this->_parameters); + + // Replace the values in the SQL + $sql = strtr($sql, $values); + } + + return $sql; + } + + /** + * Execute the current query on the given database. + * + * @param mixed $db Database instance or name of instance + * @param string result object classname, TRUE for stdClass or FALSE for array + * @param array result object constructor arguments + * @return object Database_Result for SELECT queries + * @return mixed the insert id for INSERT queries + * @return integer number of affected rows for all other queries + */ + public function execute($db = NULL, $as_object = NULL, $object_params = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + if ($as_object === NULL) + { + $as_object = $this->_as_object; + } + + if ($object_params === NULL) + { + $object_params = $this->_object_params; + } + + // Compile the SQL query + $sql = $this->compile($db); + + if ($this->_lifetime !== NULL AND $this->_type === Database::SELECT) + { + // Set the cache key based on the database instance name and SQL + $cache_key = 'Database::query("'.$db.'", "'.$sql.'")'; + + // Read the cache first to delete a possible hit with lifetime <= 0 + if (($result = Kohana::cache($cache_key, NULL, $this->_lifetime)) !== NULL + AND ! $this->_force_execute) + { + // Return a cached result + return new Database_Result_Cached($result, $sql, $as_object, $object_params); + } + } + + // Execute the query + $result = $db->query($this->_type, $sql, $as_object, $object_params); + + if (isset($cache_key) AND $this->_lifetime > 0) + { + // Cache the result array + Kohana::cache($cache_key, $result->as_array(), $this->_lifetime); + } + + return $result; + } + +} // End Database_Query diff --git a/modules/database/classes/Kohana/Database/Query/Builder.php b/modules/database/classes/Kohana/Database/Query/Builder.php new file mode 100644 index 0000000..3e1bdb5 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder.php @@ -0,0 +1,248 @@ +compile($db); + } + + return implode(' ', $statements); + } + + /** + * Compiles an array of conditions into an SQL partial. Used for WHERE + * and HAVING. + * + * @param object $db Database instance + * @param array $conditions condition statements + * @return string + */ + protected function _compile_conditions(Database $db, array $conditions) + { + $last_condition = NULL; + + $sql = ''; + foreach ($conditions as $group) + { + // Process groups of conditions + foreach ($group as $logic => $condition) + { + if ($condition === '(') + { + if ( ! empty($sql) AND $last_condition !== '(') + { + // Include logic operator + $sql .= ' '.$logic.' '; + } + + $sql .= '('; + } + elseif ($condition === ')') + { + $sql .= ')'; + } + else + { + if ( ! empty($sql) AND $last_condition !== '(') + { + // Add the logic operator + $sql .= ' '.$logic.' '; + } + + // Split the condition + list($column, $op, $value) = $condition; + + if ($value === NULL) + { + if ($op === '=') + { + // Convert "val = NULL" to "val IS NULL" + $op = 'IS'; + } + elseif ($op === '!=') + { + // Convert "val != NULL" to "valu IS NOT NULL" + $op = 'IS NOT'; + } + } + + // Database operators are always uppercase + $op = strtoupper($op); + + if ($op === 'BETWEEN' AND is_array($value)) + { + // BETWEEN always has exactly two arguments + list($min, $max) = $value; + + if ((is_string($min) AND array_key_exists($min, $this->_parameters)) === FALSE) + { + // Quote the value, it is not a parameter + $min = $db->quote($min); + } + + if ((is_string($max) AND array_key_exists($max, $this->_parameters)) === FALSE) + { + // Quote the value, it is not a parameter + $max = $db->quote($max); + } + + // Quote the min and max value + $value = $min.' AND '.$max; + } + elseif ((is_string($value) AND array_key_exists($value, $this->_parameters)) === FALSE) + { + // Quote the value, it is not a parameter + $value = $db->quote($value); + } + + if ($column) + { + if (is_array($column)) + { + // Use the column name + $column = $db->quote_identifier(reset($column)); + } + else + { + // Apply proper quoting to the column + $column = $db->quote_column($column); + } + } + + // Append the statement to the query + $sql .= trim($column.' '.$op.' '.$value); + } + + $last_condition = $condition; + } + } + + return $sql; + } + + /** + * Compiles an array of set values into an SQL partial. Used for UPDATE. + * + * @param object $db Database instance + * @param array $values updated values + * @return string + */ + protected function _compile_set(Database $db, array $values) + { + $set = array(); + foreach ($values as $group) + { + // Split the set + list ($column, $value) = $group; + + // Quote the column name + $column = $db->quote_column($column); + + if ((is_string($value) AND array_key_exists($value, $this->_parameters)) === FALSE) + { + // Quote the value, it is not a parameter + $value = $db->quote($value); + } + + $set[$column] = $column.' = '.$value; + } + + return implode(', ', $set); + } + + /** + * Compiles an array of GROUP BY columns into an SQL partial. + * + * @param object $db Database instance + * @param array $columns + * @return string + */ + protected function _compile_group_by(Database $db, array $columns) + { + $group = array(); + + foreach ($columns as $column) + { + if (is_array($column)) + { + // Use the column alias + $column = $db->quote_identifier(end($column)); + } + else + { + // Apply proper quoting to the column + $column = $db->quote_column($column); + } + + $group[] = $column; + } + + return 'GROUP BY '.implode(', ', $group); + } + + /** + * Compiles an array of ORDER BY statements into an SQL partial. + * + * @param object $db Database instance + * @param array $columns sorting columns + * @return string + */ + protected function _compile_order_by(Database $db, array $columns) + { + $sort = array(); + foreach ($columns as $group) + { + list ($column, $direction) = $group; + + if (is_array($column)) + { + // Use the column alias + $column = $db->quote_identifier(end($column)); + } + else + { + // Apply proper quoting to the column + $column = $db->quote_column($column); + } + + if ($direction) + { + // Make the direction uppercase + $direction = ' '.strtoupper($direction); + } + + $sort[] = $column.$direction; + } + + return 'ORDER BY '.implode(', ', $sort); + } + + /** + * Reset the current builder status. + * + * @return $this + */ + abstract public function reset(); + +} // End Database_Query_Builder diff --git a/modules/database/classes/Kohana/Database/Query/Builder/Delete.php b/modules/database/classes/Kohana/Database/Query/Builder/Delete.php new file mode 100644 index 0000000..0bc4761 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder/Delete.php @@ -0,0 +1,99 @@ +_table = $table; + } + + // Start the query with no SQL + return parent::__construct(Database::DELETE, ''); + } + + /** + * Sets the table to delete from. + * + * @param mixed $table table name or array($table, $alias) or object + * @return $this + */ + public function table($table) + { + $this->_table = $table; + + return $this; + } + + /** + * Compile the SQL query and return it. + * + * @param mixed $db Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + // Start a deletion query + $query = 'DELETE FROM '.$db->quote_table($this->_table); + + if ( ! empty($this->_where)) + { + // Add deletion conditions + $query .= ' WHERE '.$this->_compile_conditions($db, $this->_where); + } + + if ( ! empty($this->_order_by)) + { + // Add sorting + $query .= ' '.$this->_compile_order_by($db, $this->_order_by); + } + + if ($this->_limit !== NULL) + { + // Add limiting + $query .= ' LIMIT '.$this->_limit; + } + + $this->_sql = $query; + + return parent::compile($db); + } + + public function reset() + { + $this->_table = NULL; + $this->_where = array(); + + $this->_parameters = array(); + + $this->_sql = NULL; + + return $this; + } + +} // End Database_Query_Builder_Delete diff --git a/modules/database/classes/Kohana/Database/Query/Builder/Insert.php b/modules/database/classes/Kohana/Database/Query/Builder/Insert.php new file mode 100644 index 0000000..aa3c807 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder/Insert.php @@ -0,0 +1,181 @@ +_table = $table; + } + + if ($columns) + { + // Set the column names + $this->_columns = $columns; + } + + // Start the query with no SQL + return parent::__construct(Database::INSERT, ''); + } + + /** + * Sets the table to insert into. + * + * @param mixed $table table name or array($table, $alias) or object + * @return $this + */ + public function table($table) + { + $this->_table = $table; + + return $this; + } + + /** + * Set the columns that will be inserted. + * + * @param array $columns column names + * @return $this + */ + public function columns(array $columns) + { + $this->_columns = $columns; + + return $this; + } + + /** + * Adds or overwrites values. Multiple value sets can be added. + * + * @param array $values values list + * @param ... + * @return $this + */ + public function values(array $values) + { + if ( ! is_array($this->_values)) + { + throw new Kohana_Exception('INSERT INTO ... SELECT statements cannot be combined with INSERT INTO ... VALUES'); + } + + // Get all of the passed values + $values = func_get_args(); + + $this->_values = array_merge($this->_values, $values); + + return $this; + } + + /** + * Use a sub-query to for the inserted values. + * + * @param object $query Database_Query of SELECT type + * @return $this + */ + public function select(Database_Query $query) + { + if ($query->type() !== Database::SELECT) + { + throw new Kohana_Exception('Only SELECT queries can be combined with INSERT queries'); + } + + $this->_values = $query; + + return $this; + } + + /** + * Compile the SQL query and return it. + * + * @param mixed $db Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + // Start an insertion query + $query = 'INSERT INTO '.$db->quote_table($this->_table); + + // Add the column names + $query .= ' ('.implode(', ', array_map(array($db, 'quote_column'), $this->_columns)).') '; + + if (is_array($this->_values)) + { + // Callback for quoting values + $quote = array($db, 'quote'); + + $groups = array(); + foreach ($this->_values as $group) + { + foreach ($group as $offset => $value) + { + if ((is_string($value) AND array_key_exists($value, $this->_parameters)) === FALSE) + { + // Quote the value, it is not a parameter + $group[$offset] = $db->quote($value); + } + } + + $groups[] = '('.implode(', ', $group).')'; + } + + // Add the values + $query .= 'VALUES '.implode(', ', $groups); + } + else + { + // Add the sub-query + $query .= (string) $this->_values; + } + + $this->_sql = $query; + + return parent::compile($db);; + } + + public function reset() + { + $this->_table = NULL; + + $this->_columns = + $this->_values = array(); + + $this->_parameters = array(); + + $this->_sql = NULL; + + return $this; + } + +} // End Database_Query_Builder_Insert diff --git a/modules/database/classes/Kohana/Database/Query/Builder/Join.php b/modules/database/classes/Kohana/Database/Query/Builder/Join.php new file mode 100644 index 0000000..10402f6 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder/Join.php @@ -0,0 +1,149 @@ +_table = $table; + + if ($type !== NULL) + { + // Set the JOIN type + $this->_type = (string) $type; + } + } + + /** + * Adds a new condition for joining. + * + * @param mixed $c1 column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $c2 column name or array($column, $alias) or object + * @return $this + */ + public function on($c1, $op, $c2) + { + if ( ! empty($this->_using)) + { + throw new Kohana_Exception('JOIN ... ON ... cannot be combined with JOIN ... USING ...'); + } + + $this->_on[] = array($c1, $op, $c2); + + return $this; + } + + /** + * Adds a new condition for joining. + * + * @param string $columns column name + * @return $this + */ + public function using($columns) + { + if ( ! empty($this->_on)) + { + throw new Kohana_Exception('JOIN ... ON ... cannot be combined with JOIN ... USING ...'); + } + + $columns = func_get_args(); + + $this->_using = array_merge($this->_using, $columns); + + return $this; + } + + /** + * Compile the SQL partial for a JOIN statement and return it. + * + * @param mixed $db Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + if ($this->_type) + { + $sql = strtoupper($this->_type).' JOIN'; + } + else + { + $sql = 'JOIN'; + } + + // Quote the table name that is being joined + $sql .= ' '.$db->quote_table($this->_table); + + if ( ! empty($this->_using)) + { + // Quote and concat the columns + $sql .= ' USING ('.implode(', ', array_map(array($db, 'quote_column'), $this->_using)).')'; + } + else + { + $conditions = array(); + foreach ($this->_on as $condition) + { + // Split the condition + list($c1, $op, $c2) = $condition; + + if ($op) + { + // Make the operator uppercase and spaced + $op = ' '.strtoupper($op); + } + + // Quote each of the columns used for the condition + $conditions[] = $db->quote_column($c1).$op.' '.$db->quote_column($c2); + } + + // Concat the conditions "... AND ..." + $sql .= ' ON ('.implode(' AND ', $conditions).')'; + } + + return $sql; + } + + public function reset() + { + $this->_type = + $this->_table = NULL; + + $this->_on = array(); + } + +} // End Database_Query_Builder_Join diff --git a/modules/database/classes/Kohana/Database/Query/Builder/Select.php b/modules/database/classes/Kohana/Database/Query/Builder/Select.php new file mode 100644 index 0000000..3492a71 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder/Select.php @@ -0,0 +1,446 @@ +_select = $columns; + } + + // Start the query with no actual SQL statement + parent::__construct(Database::SELECT, ''); + } + + /** + * Enables or disables selecting only unique columns using "SELECT DISTINCT" + * + * @param boolean $value enable or disable distinct columns + * @return $this + */ + public function distinct($value) + { + $this->_distinct = (bool) $value; + + return $this; + } + + /** + * Choose the columns to select from. + * + * @param mixed $columns column name or array($column, $alias) or object + * @return $this + */ + public function select($columns = NULL) + { + $columns = func_get_args(); + + $this->_select = array_merge($this->_select, $columns); + + return $this; + } + + /** + * Choose the columns to select from, using an array. + * + * @param array $columns list of column names or aliases + * @return $this + */ + public function select_array(array $columns) + { + $this->_select = array_merge($this->_select, $columns); + + return $this; + } + + /** + * Choose the tables to select "FROM ..." + * + * @param mixed $table table name or array($table, $alias) or object + * @return $this + */ + public function from($tables) + { + $tables = func_get_args(); + + $this->_from = array_merge($this->_from, $tables); + + return $this; + } + + /** + * Adds addition tables to "JOIN ...". + * + * @param mixed $table column name or array($column, $alias) or object + * @param string $type join type (LEFT, RIGHT, INNER, etc) + * @return $this + */ + public function join($table, $type = NULL) + { + $this->_join[] = $this->_last_join = new Database_Query_Builder_Join($table, $type); + + return $this; + } + + /** + * Adds "ON ..." conditions for the last created JOIN statement. + * + * @param mixed $c1 column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $c2 column name or array($column, $alias) or object + * @return $this + */ + public function on($c1, $op, $c2) + { + $this->_last_join->on($c1, $op, $c2); + + return $this; + } + + /** + * Adds "USING ..." conditions for the last created JOIN statement. + * + * @param string $columns column name + * @return $this + */ + public function using($columns) + { + $columns = func_get_args(); + + call_user_func_array(array($this->_last_join, 'using'), $columns); + + return $this; + } + + /** + * Creates a "GROUP BY ..." filter. + * + * @param mixed $columns column name or array($column, $alias) or object + * @return $this + */ + public function group_by($columns) + { + $columns = func_get_args(); + + $this->_group_by = array_merge($this->_group_by, $columns); + + return $this; + } + + /** + * Alias of and_having() + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function having($column, $op, $value = NULL) + { + return $this->and_having($column, $op, $value); + } + + /** + * Creates a new "AND HAVING" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function and_having($column, $op, $value = NULL) + { + $this->_having[] = array('AND' => array($column, $op, $value)); + + return $this; + } + + /** + * Creates a new "OR HAVING" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function or_having($column, $op, $value = NULL) + { + $this->_having[] = array('OR' => array($column, $op, $value)); + + return $this; + } + + /** + * Alias of and_having_open() + * + * @return $this + */ + public function having_open() + { + return $this->and_having_open(); + } + + /** + * Opens a new "AND HAVING (...)" grouping. + * + * @return $this + */ + public function and_having_open() + { + $this->_having[] = array('AND' => '('); + + return $this; + } + + /** + * Opens a new "OR HAVING (...)" grouping. + * + * @return $this + */ + public function or_having_open() + { + $this->_having[] = array('OR' => '('); + + return $this; + } + + /** + * Closes an open "AND HAVING (...)" grouping. + * + * @return $this + */ + public function having_close() + { + return $this->and_having_close(); + } + + /** + * Closes an open "AND HAVING (...)" grouping. + * + * @return $this + */ + public function and_having_close() + { + $this->_having[] = array('AND' => ')'); + + return $this; + } + + /** + * Closes an open "OR HAVING (...)" grouping. + * + * @return $this + */ + public function or_having_close() + { + $this->_having[] = array('OR' => ')'); + + return $this; + } + + /** + * Adds an other UNION clause. + * + * @param mixed $select if string, it must be the name of a table. Else + * must be an instance of Database_Query_Builder_Select + * @param boolean $all decides if it's an UNION or UNION ALL clause + * @return $this + */ + public function union($select, $all = TRUE) + { + if (is_string($select)) + { + $select = DB::select()->from($select); + } + if ( ! $select instanceof Database_Query_Builder_Select) + throw new Kohana_Exception('first parameter must be a string or an instance of Database_Query_Builder_Select'); + $this->_union []= array('select' => $select, 'all' => $all); + return $this; + } + + /** + * Start returning results after "OFFSET ..." + * + * @param integer $number starting result number or NULL to reset + * @return $this + */ + public function offset($number) + { + $this->_offset = $number; + + return $this; + } + + /** + * Compile the SQL query and return it. + * + * @param mixed $db Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + // Callback to quote columns + $quote_column = array($db, 'quote_column'); + + // Callback to quote tables + $quote_table = array($db, 'quote_table'); + + // Start a selection query + $query = 'SELECT '; + + if ($this->_distinct === TRUE) + { + // Select only unique results + $query .= 'DISTINCT '; + } + + if (empty($this->_select)) + { + // Select all columns + $query .= '*'; + } + else + { + // Select all columns + $query .= implode(', ', array_unique(array_map($quote_column, $this->_select))); + } + + if ( ! empty($this->_from)) + { + // Set tables to select from + $query .= ' FROM '.implode(', ', array_unique(array_map($quote_table, $this->_from))); + } + + if ( ! empty($this->_join)) + { + // Add tables to join + $query .= ' '.$this->_compile_join($db, $this->_join); + } + + if ( ! empty($this->_where)) + { + // Add selection conditions + $query .= ' WHERE '.$this->_compile_conditions($db, $this->_where); + } + + if ( ! empty($this->_group_by)) + { + // Add grouping + $query .= ' '.$this->_compile_group_by($db, $this->_group_by); + } + + if ( ! empty($this->_having)) + { + // Add filtering conditions + $query .= ' HAVING '.$this->_compile_conditions($db, $this->_having); + } + + if ( ! empty($this->_order_by)) + { + // Add sorting + $query .= ' '.$this->_compile_order_by($db, $this->_order_by); + } + + if ($this->_limit !== NULL) + { + // Add limiting + $query .= ' LIMIT '.$this->_limit; + } + + if ($this->_offset !== NULL) + { + // Add offsets + $query .= ' OFFSET '.$this->_offset; + } + + if ( ! empty($this->_union)) + { + foreach ($this->_union as $u) { + $query .= ' UNION '; + if ($u['all'] === TRUE) + { + $query .= 'ALL '; + } + $query .= $u['select']->compile($db); + } + } + + $this->_sql = $query; + + return parent::compile($db); + } + + public function reset() + { + $this->_select = + $this->_from = + $this->_join = + $this->_where = + $this->_group_by = + $this->_having = + $this->_order_by = + $this->_union = array(); + + $this->_distinct = FALSE; + + $this->_limit = + $this->_offset = + $this->_last_join = NULL; + + $this->_parameters = array(); + + $this->_sql = NULL; + + return $this; + } + +} // End Database_Query_Select diff --git a/modules/database/classes/Kohana/Database/Query/Builder/Update.php b/modules/database/classes/Kohana/Database/Query/Builder/Update.php new file mode 100644 index 0000000..e6e3da5 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder/Update.php @@ -0,0 +1,140 @@ +_table = $table; + } + + // Start the query with no SQL + return parent::__construct(Database::UPDATE, ''); + } + + /** + * Sets the table to update. + * + * @param mixed $table table name or array($table, $alias) or object + * @return $this + */ + public function table($table) + { + $this->_table = $table; + + return $this; + } + + /** + * Set the values to update with an associative array. + * + * @param array $pairs associative (column => value) list + * @return $this + */ + public function set(array $pairs) + { + foreach ($pairs as $column => $value) + { + $this->_set[] = array($column, $value); + } + + return $this; + } + + /** + * Set the value of a single column. + * + * @param mixed $column table name or array($table, $alias) or object + * @param mixed $value column value + * @return $this + */ + public function value($column, $value) + { + $this->_set[] = array($column, $value); + + return $this; + } + + /** + * Compile the SQL query and return it. + * + * @param mixed $db Database instance or name of instance + * @return string + */ + public function compile($db = NULL) + { + if ( ! is_object($db)) + { + // Get the database instance + $db = Database::instance($db); + } + + // Start an update query + $query = 'UPDATE '.$db->quote_table($this->_table); + + // Add the columns to update + $query .= ' SET '.$this->_compile_set($db, $this->_set); + + if ( ! empty($this->_where)) + { + // Add selection conditions + $query .= ' WHERE '.$this->_compile_conditions($db, $this->_where); + } + + if ( ! empty($this->_order_by)) + { + // Add sorting + $query .= ' '.$this->_compile_order_by($db, $this->_order_by); + } + + if ($this->_limit !== NULL) + { + // Add limiting + $query .= ' LIMIT '.$this->_limit; + } + + $this->_sql = $query; + + return parent::compile($db); + } + + public function reset() + { + $this->_table = NULL; + + $this->_set = + $this->_where = array(); + + $this->_limit = NULL; + + $this->_parameters = array(); + + $this->_sql = NULL; + + return $this; + } + + +} // End Database_Query_Builder_Update diff --git a/modules/database/classes/Kohana/Database/Query/Builder/Where.php b/modules/database/classes/Kohana/Database/Query/Builder/Where.php new file mode 100644 index 0000000..58f6b5d --- /dev/null +++ b/modules/database/classes/Kohana/Database/Query/Builder/Where.php @@ -0,0 +1,180 @@ +and_where($column, $op, $value); + } + + /** + * Creates a new "AND WHERE" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function and_where($column, $op, $value) + { + $this->_where[] = array('AND' => array($column, $op, $value)); + + return $this; + } + + /** + * Creates a new "OR WHERE" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function or_where($column, $op, $value) + { + $this->_where[] = array('OR' => array($column, $op, $value)); + + return $this; + } + + /** + * Alias of and_where_open() + * + * @return $this + */ + public function where_open() + { + return $this->and_where_open(); + } + + /** + * Opens a new "AND WHERE (...)" grouping. + * + * @return $this + */ + public function and_where_open() + { + $this->_where[] = array('AND' => '('); + + return $this; + } + + /** + * Opens a new "OR WHERE (...)" grouping. + * + * @return $this + */ + public function or_where_open() + { + $this->_where[] = array('OR' => '('); + + return $this; + } + + /** + * Closes an open "WHERE (...)" grouping. + * + * @return $this + */ + public function where_close() + { + return $this->and_where_close(); + } + + /** + * Closes an open "WHERE (...)" grouping or removes the grouping when it is + * empty. + * + * @return $this + */ + public function where_close_empty() + { + $group = end($this->_where); + + if ($group AND reset($group) === '(') + { + array_pop($this->_where); + + return $this; + } + + return $this->where_close(); + } + + /** + * Closes an open "WHERE (...)" grouping. + * + * @return $this + */ + public function and_where_close() + { + $this->_where[] = array('AND' => ')'); + + return $this; + } + + /** + * Closes an open "WHERE (...)" grouping. + * + * @return $this + */ + public function or_where_close() + { + $this->_where[] = array('OR' => ')'); + + return $this; + } + + /** + * Applies sorting with "ORDER BY ..." + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $direction direction of sorting + * @return $this + */ + public function order_by($column, $direction = NULL) + { + $this->_order_by[] = array($column, $direction); + + return $this; + } + + /** + * Return up to "LIMIT ..." results + * + * @param integer $number maximum results to return or NULL to reset + * @return $this + */ + public function limit($number) + { + $this->_limit = $number; + + return $this; + } + +} // End Database_Query_Builder_Where diff --git a/modules/database/classes/Kohana/Database/Result.php b/modules/database/classes/Kohana/Database/Result.php new file mode 100644 index 0000000..3c3284f --- /dev/null +++ b/modules/database/classes/Kohana/Database/Result.php @@ -0,0 +1,338 @@ +_result = $result; + + // Store the SQL locally + $this->_query = $sql; + + if (is_object($as_object)) + { + // Get the object class name + $as_object = get_class($as_object); + } + + // Results as objects or associative arrays + $this->_as_object = $as_object; + + if ($params) + { + // Object constructor params + $this->_object_params = $params; + } + } + + /** + * Result destruction cleans up all open result sets. + * + * @return void + */ + abstract public function __destruct(); + + /** + * Get a cached database result from the current result iterator. + * + * $cachable = serialize($result->cached()); + * + * @return Database_Result_Cached + * @since 3.0.5 + */ + public function cached() + { + return new Database_Result_Cached($this->as_array(), $this->_query, $this->_as_object); + } + + /** + * Return all of the rows in the result as an array. + * + * // Indexed array of all rows + * $rows = $result->as_array(); + * + * // Associative array of rows by "id" + * $rows = $result->as_array('id'); + * + * // Associative array of rows, "id" => "name" + * $rows = $result->as_array('id', 'name'); + * + * @param string $key column for associative keys + * @param string $value column for values + * @return array + */ + public function as_array($key = NULL, $value = NULL) + { + $results = array(); + + if ($key === NULL AND $value === NULL) + { + // Indexed rows + + foreach ($this as $row) + { + $results[] = $row; + } + } + elseif ($key === NULL) + { + // Indexed columns + + if ($this->_as_object) + { + foreach ($this as $row) + { + $results[] = $row->$value; + } + } + else + { + foreach ($this as $row) + { + $results[] = $row[$value]; + } + } + } + elseif ($value === NULL) + { + // Associative rows + + if ($this->_as_object) + { + foreach ($this as $row) + { + $results[$row->$key] = $row; + } + } + else + { + foreach ($this as $row) + { + $results[$row[$key]] = $row; + } + } + } + else + { + // Associative columns + + if ($this->_as_object) + { + foreach ($this as $row) + { + $results[$row->$key] = $row->$value; + } + } + else + { + foreach ($this as $row) + { + $results[$row[$key]] = $row[$value]; + } + } + } + + $this->rewind(); + + return $results; + } + + /** + * Return the named column from the current row. + * + * // Get the "id" value + * $id = $result->get('id'); + * + * @param string $name column to get + * @param mixed $default default value if the column does not exist + * @return mixed + */ + public function get($name, $default = NULL) + { + $row = $this->current(); + + if ($this->_as_object) + { + if (isset($row->$name)) + return $row->$name; + } + else + { + if (isset($row[$name])) + return $row[$name]; + } + + return $default; + } + + /** + * Implements [Countable::count], returns the total number of rows. + * + * echo count($result); + * + * @return integer + */ + public function count() + { + return $this->_total_rows; + } + + /** + * Implements [ArrayAccess::offsetExists], determines if row exists. + * + * if (isset($result[10])) + * { + * // Row 10 exists + * } + * + * @param int $offset + * @return boolean + */ + public function offsetExists($offset) + { + return ($offset >= 0 AND $offset < $this->_total_rows); + } + + /** + * Implements [ArrayAccess::offsetGet], gets a given row. + * + * $row = $result[10]; + * + * @param int $offset + * @return mixed + */ + public function offsetGet($offset) + { + if ( ! $this->seek($offset)) + return NULL; + + return $this->current(); + } + + /** + * Implements [ArrayAccess::offsetSet], throws an error. + * + * [!!] You cannot modify a database result. + * + * @param int $offset + * @param mixed $value + * @return void + * @throws Kohana_Exception + */ + final public function offsetSet($offset, $value) + { + throw new Kohana_Exception('Database results are read-only'); + } + + /** + * Implements [ArrayAccess::offsetUnset], throws an error. + * + * [!!] You cannot modify a database result. + * + * @param int $offset + * @return void + * @throws Kohana_Exception + */ + final public function offsetUnset($offset) + { + throw new Kohana_Exception('Database results are read-only'); + } + + /** + * Implements [Iterator::key], returns the current row number. + * + * echo key($result); + * + * @return integer + */ + public function key() + { + return $this->_current_row; + } + + /** + * Implements [Iterator::next], moves to the next row. + * + * next($result); + * + * @return $this + */ + public function next() + { + ++$this->_current_row; + return $this; + } + + /** + * Implements [Iterator::prev], moves to the previous row. + * + * prev($result); + * + * @return $this + */ + public function prev() + { + --$this->_current_row; + return $this; + } + + /** + * Implements [Iterator::rewind], sets the current row to zero. + * + * rewind($result); + * + * @return $this + */ + public function rewind() + { + $this->_current_row = 0; + return $this; + } + + /** + * Implements [Iterator::valid], checks if the current row exists. + * + * [!!] This method is only used internally. + * + * @return boolean + */ + public function valid() + { + return $this->offsetExists($this->_current_row); + } + +} // End Database_Result diff --git a/modules/database/classes/Kohana/Database/Result/Cached.php b/modules/database/classes/Kohana/Database/Result/Cached.php new file mode 100644 index 0000000..8af0854 --- /dev/null +++ b/modules/database/classes/Kohana/Database/Result/Cached.php @@ -0,0 +1,51 @@ +_total_rows = count($result); + } + + public function __destruct() + { + // Cached results do not use resources + } + + public function cached() + { + return $this; + } + + public function seek($offset) + { + if ($this->offsetExists($offset)) + { + $this->_current_row = $offset; + + return TRUE; + } + else + { + return FALSE; + } + } + + public function current() + { + // Return an array of the row + return $this->valid() ? $this->_result[$this->_current_row] : NULL; + } + +} // End Database_Result_Cached diff --git a/modules/database/classes/Kohana/Model/Database.php b/modules/database/classes/Kohana/Model/Database.php new file mode 100644 index 0000000..790e8f0 --- /dev/null +++ b/modules/database/classes/Kohana/Model/Database.php @@ -0,0 +1,63 @@ +_db = $db; + } + elseif ( ! $this->_db) + { + // Use the default name + $this->_db = Database::$default; + } + + if (is_string($this->_db)) + { + // Load the database + $this->_db = Database::instance($this->_db); + } + } + +} // End Model diff --git a/modules/database/classes/Kohana/Session/Database.php b/modules/database/classes/Kohana/Session/Database.php new file mode 100644 index 0000000..34abbbd --- /dev/null +++ b/modules/database/classes/Kohana/Session/Database.php @@ -0,0 +1,239 @@ + 'session_id', + 'last_active' => 'last_active', + 'contents' => 'contents' + ); + + // Garbage collection requests + protected $_gc = 500; + + // The current session id + protected $_session_id; + + // The old session id + protected $_update_id; + + public function __construct(array $config = NULL, $id = NULL) + { + if ( ! isset($config['group'])) + { + // Use the default group + $config['group'] = Database::$default; + } + + // Load the database + $this->_db = Database::instance($config['group']); + + if (isset($config['table'])) + { + // Set the table name + $this->_table = (string) $config['table']; + } + + if (isset($config['gc'])) + { + // Set the gc chance + $this->_gc = (int) $config['gc']; + } + + if (isset($config['columns'])) + { + // Overload column names + $this->_columns = $config['columns']; + } + + parent::__construct($config, $id); + + if (mt_rand(0, $this->_gc) === $this->_gc) + { + // Run garbage collection + // This will average out to run once every X requests + $this->_gc(); + } + } + + public function id() + { + return $this->_session_id; + } + + protected function _read($id = NULL) + { + if ($id OR $id = Cookie::get($this->_name)) + { + $result = DB::select(array($this->_columns['contents'], 'contents')) + ->from($this->_table) + ->where($this->_columns['session_id'], '=', ':id') + ->limit(1) + ->param(':id', $id) + ->execute($this->_db); + + if ($result->count()) + { + // Set the current session id + $this->_session_id = $this->_update_id = $id; + + // Return the contents + return $result->get('contents'); + } + } + + // Create a new session id + $this->_regenerate(); + + return NULL; + } + + protected function _regenerate() + { + // Create the query to find an ID + $query = DB::select($this->_columns['session_id']) + ->from($this->_table) + ->where($this->_columns['session_id'], '=', ':id') + ->limit(1) + ->bind(':id', $id); + + do + { + // Create a new session id + $id = str_replace('.', '-', uniqid(NULL, TRUE)); + + // Get the the id from the database + $result = $query->execute($this->_db); + } + while ($result->count()); + + return $this->_session_id = $id; + } + + protected function _write() + { + if ($this->_update_id === NULL) + { + // Insert a new row + $query = DB::insert($this->_table, $this->_columns) + ->values(array(':new_id', ':active', ':contents')); + } + else + { + // Update the row + $query = DB::update($this->_table) + ->value($this->_columns['last_active'], ':active') + ->value($this->_columns['contents'], ':contents') + ->where($this->_columns['session_id'], '=', ':old_id'); + + if ($this->_update_id !== $this->_session_id) + { + // Also update the session id + $query->value($this->_columns['session_id'], ':new_id'); + } + } + + $query + ->param(':new_id', $this->_session_id) + ->param(':old_id', $this->_update_id) + ->param(':active', $this->_data['last_active']) + ->param(':contents', $this->__toString()); + + // Execute the query + $query->execute($this->_db); + + // The update and the session id are now the same + $this->_update_id = $this->_session_id; + + // Update the cookie with the new session id + Cookie::set($this->_name, $this->_session_id, $this->_lifetime); + + return TRUE; + } + + /** + * @return bool + */ + protected function _restart() + { + $this->_regenerate(); + + return TRUE; + } + + protected function _destroy() + { + if ($this->_update_id === NULL) + { + // Session has not been created yet + return TRUE; + } + + // Delete the current session + $query = DB::delete($this->_table) + ->where($this->_columns['session_id'], '=', ':id') + ->param(':id', $this->_update_id); + + try + { + // Execute the query + $query->execute($this->_db); + + // Delete the cookie + Cookie::delete($this->_name); + } + catch (Exception $e) + { + // An error occurred, the session has not been deleted + return FALSE; + } + + return TRUE; + } + + protected function _gc() + { + if ($this->_lifetime) + { + // Expire sessions when their lifetime is up + $expires = $this->_lifetime; + } + else + { + // Expire sessions after one month + $expires = Date::MONTH; + } + + // Delete all sessions that have expired + DB::delete($this->_table) + ->where($this->_columns['last_active'], '<', ':time') + ->param(':time', time() - $expires) + ->execute($this->_db); + } + +} // End Session_Database diff --git a/modules/database/classes/Model/Database.php b/modules/database/classes/Model/Database.php new file mode 100644 index 0000000..3b6e609 --- /dev/null +++ b/modules/database/classes/Model/Database.php @@ -0,0 +1,3 @@ + array + ( + 'type' => 'MySQL', + 'connection' => array( + /** + * The following options are available for MySQL: + * + * string hostname server hostname, or socket + * string database database name + * string username database username + * string password database password + * boolean persistent use persistent connections? + * array variables system variables as "key => value" pairs + * + * Ports and sockets may be appended to the hostname. + */ + 'hostname' => 'localhost', + 'database' => 'kohana', + 'username' => FALSE, + 'password' => FALSE, + 'persistent' => FALSE, + ), + 'table_prefix' => '', + 'charset' => 'utf8', + 'caching' => FALSE, + ), + 'alternate' => array( + 'type' => 'PDO', + 'connection' => array( + /** + * The following options are available for PDO: + * + * string dsn Data Source Name + * string username database username + * string password database password + * boolean persistent use persistent connections? + */ + 'dsn' => 'mysql:host=localhost;dbname=kohana', + 'username' => 'root', + 'password' => 'r00tdb', + 'persistent' => FALSE, + ), + /** + * The following extra options are available for PDO: + * + * string identifier set the escaping identifier + */ + 'table_prefix' => '', + 'charset' => 'utf8', + 'caching' => FALSE, + ), +); diff --git a/modules/database/config/session.php b/modules/database/config/session.php new file mode 100644 index 0000000..58263ae --- /dev/null +++ b/modules/database/config/session.php @@ -0,0 +1,27 @@ + array( + /** + * Database settings for session storage. + * + * string group configuation group name + * string table session table name + * integer gc number of requests before gc is invoked + * columns array custom column names + */ + 'group' => 'default', + 'table' => 'sessions', + 'gc' => 500, + 'columns' => array( + /** + * session_id: session identifier + * last_active: timestamp of the last activity + * contents: serialized session data + */ + 'session_id' => 'session_id', + 'last_active' => 'last_active', + 'contents' => 'contents' + ), + ), +); diff --git a/modules/database/config/userguide.php b/modules/database/config/userguide.php new file mode 100644 index 0000000..88ff2a3 --- /dev/null +++ b/modules/database/config/userguide.php @@ -0,0 +1,23 @@ + array( + + // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + 'database' => array( + + // Whether this modules userguide pages should be shown + 'enabled' => TRUE, + + // The name that should show up on the userguide index page + 'name' => 'Database', + + // A short description of this module, shown on the index page + 'description' => 'Database agnostic querying and result management.', + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2008–2012 Kohana Team', + ) + ) +); \ No newline at end of file diff --git a/modules/database/guide/database/config.md b/modules/database/guide/database/config.md new file mode 100644 index 0000000..240a6bb --- /dev/null +++ b/modules/database/guide/database/config.md @@ -0,0 +1,116 @@ +# Configuration + +The default config file is located in `MODPATH/database/config/database.php`. You should copy this file to `APPPATH/config/database.php` and make changes there, in keeping with the [cascading filesystem](../kohana/files). + +The database configuration file contains an array of configuration groups. The structure of each database configuration group, called an "instance", looks like this: + + string INSTANCE_NAME => array( + 'type' => string DATABASE_TYPE, + 'connection' => array CONNECTION_ARRAY, + 'table_prefix' => string TABLE_PREFIX, + 'charset' => string CHARACTER_SET, + ), + +Understanding each of these settings is important. + +INSTANCE_NAME +: Connections can be named anything you want, but you should always have at least one connection called "default". + +DATABASE_TYPE +: One of the installed database drivers. Kohana comes with "mysql" and "pdo" drivers. Drivers must extend the Database class. + +CONNECTION_ARRAY +: Specific driver options for connecting to your database. (Driver options are explained [below](#connection-settings).) + +TABLE_PREFIX +: Prefix that will be added to all table names by the [query builder](#query_building). + + +## Example + +The example file below shows 2 MySQL connections, one local and one remote. + + return array + ( + 'default' => array + ( + 'type' => 'mysql', + 'connection' => array( + 'hostname' => 'localhost', + 'username' => 'dbuser', + 'password' => 'mypassword', + 'persistent' => FALSE, + 'database' => 'my_db_name', + ), + 'table_prefix' => '', + 'charset' => 'utf8', + ), + 'remote' => array( + 'type' => 'mysql', + 'connection' => array( + 'hostname' => '55.55.55.55', + 'username' => 'remote_user', + 'password' => 'mypassword', + 'persistent' => FALSE, + 'database' => 'my_remote_db_name', + ), + 'table_prefix' => '', + 'charset' => 'utf8', + ), + ); + +## Connections and Instances + +Each configuration group is referred to as a database instance. Each instance can be accessed by calling [Database::instance]. If you don't provide a parameter, the default instance is used. + + // This would connect to the database defined as 'default' + $default = Database::instance(); + + // This would connect to the database defined as 'remote' + $remote = Database::instance('remote'); + +To disconnect the database, simply destroy the object: + + unset($default) + + // Or + + unset(Database::$instances['default']); + +If you want to disconnect all of the database instances at once: + + Database::$instances = array(); + +## Connection Settings + +Every database driver has different connection settings. + +### MySQL + +A [MySQL database](http://www.php.net/manual/en/book.mysql.php) can accept the following options in the `connection` array: + +Type | Option | Description | Default value +----------|------------|----------------------------| ------------------------- +`string` | hostname | Hostname of the database | `localhost` +`integer` | port | Port number | `NULL` +`string` | socket | UNIX socket | `NULL` +`string` | username | Database username | `NULL` +`string` | password | Database password | `NULL` +`boolean` | persistent | Persistent connections | `FALSE` +`string` | database | Database name | `kohana` + +### PDO + +A [PDO database](http://php.net/manual/en/book.pdo.php) can accept these options in the `connection` array: + +Type | Option | Description | Default value +----------|------------|----------------------------| ------------------------- +`string` | dsn | PDO data source identifier | `localhost` +`array` | options | Driver-specific options | none +`string` | username | Database username | `NULL` +`string` | password | Database password | `NULL` +`boolean` | persistent | Persistent connections | `FALSE` + +The connection character set should be configured using the DSN string or `options` array. + +[!!] If you are using PDO and are not sure what to use for the `dsn` option, review [PDO::__construct](http://php.net/pdo.construct). \ No newline at end of file diff --git a/modules/database/guide/database/examples.md b/modules/database/guide/database/examples.md new file mode 100644 index 0000000..6a9d1b5 --- /dev/null +++ b/modules/database/guide/database/examples.md @@ -0,0 +1,52 @@ +# Examples + +Here are some "real world" examples of using the database library to construct your queries and use the results. + +## Examples of Parameterized Statements + +TODO: 4-6 examples of parameterized statements of varying complexity, including a good bind() example. + +## Pagination and search/filter + +In this example, we loop through an array of whitelisted input fields and for each allowed non-empty value we add it to the search query. We make a clone of the query and then execute that query to count the total number of results. The count is then passed to the [Pagination](../pagination) class to determine the search offset. The last few lines search with Pagination's items_per_page and offset values to return a page of results based on the current page the user is on. + + $query = DB::select()->from('users'); + + //only search for these fields + $form_inputs = array('first_name', 'last_name', 'email'); + foreach ($form_inputs as $name) + { + $value = Arr::get($_GET, $name, FALSE); + if ($value !== FALSE AND $value != '') + { + $query->where($name, 'like', '%'.$value.'%'); + } + } + + //copy the query & execute it + $pagination_query = clone $query; + $count = $pagination_query->select(DB::expr('COUNT(*)) AS mycount')->execute()->get('mycount'); + + //pass the total item count to Pagination + $config = Kohana::$config->load('pagination'); + $pagination = Pagination::factory(array( + 'total_items' => $count, + 'current_page' => array('source' => 'route', 'key' => 'page'), + 'items_per_page' => 20, + 'view' => 'pagination/pretty', + 'auto_hide' => TRUE, + )); + $page_links = $pagination->render(); + + //search for results starting at the offset calculated by the Pagination class + $query->order_by('last_name', 'asc') + ->order_by('first_name', 'asc') + ->limit($pagination->items_per_page) + ->offset($pagination->offset); + $results = $query->execute()->as_array(); + +## Having + +TODO: example goes here + +[!!] We could use more examples on this page. \ No newline at end of file diff --git a/modules/database/guide/database/index.md b/modules/database/guide/database/index.md new file mode 100644 index 0000000..162651d --- /dev/null +++ b/modules/database/guide/database/index.md @@ -0,0 +1,17 @@ +# Database + +Kohana 3.0 comes with a robust module for working with databases. By default, the database module supports drivers for [MySQL](http://php.net/mysql) and [PDO](http://php.net/pdo), but new drivers can be made for other database servers. + +The database module is included with the Kohana 3.0 install, but needs to be enabled before you can use it. To enable, open your `application/bootstrap.php` file and modify the call to [Kohana::modules] by including the database module like so: + + Kohana::modules(array( + ... + 'database' => MODPATH.'database', + ... + )); + +Next, you will then need to [configure](config) the database module to connect to your database. + +Once that is done then you can make [queries](query) and use the [results](results). + +The database module also provides a [config driver](../api/Kohana_Config_Database) (for storing [configuration](../kohana/files/config) in the database) and a [session driver](Session_Database). diff --git a/modules/database/guide/database/menu.md b/modules/database/guide/database/menu.md new file mode 100644 index 0000000..e1c06a8 --- /dev/null +++ b/modules/database/guide/database/menu.md @@ -0,0 +1,7 @@ +## [Database]() +- [Configuration](config) +- [Querying](query) + - [Parameterized Statements](query/parameterized) + - [Query Builder](query/builder) +- [Results](results) +- [Examples](examples) \ No newline at end of file diff --git a/modules/database/guide/database/query.md b/modules/database/guide/database/query.md new file mode 100644 index 0000000..0a15bf5 --- /dev/null +++ b/modules/database/guide/database/query.md @@ -0,0 +1,5 @@ +# Making Queries + +There are two different ways to make queries. The simplest way to make a query is to use [Database_Query], via [DB::query], to manually create queries. These queries are called [parameterized statements](query/parameterized) and allow you to set query parameters which are automatically escaped. The second way to make a query is by building the query using method calls. This is done using the [query builder](query/builder). + +[!!] All queries are run using the `execute` method, which accepts a [Database] object or instance name. See [Database_Query::execute] for more information. \ No newline at end of file diff --git a/modules/database/guide/database/query/builder.md b/modules/database/guide/database/query/builder.md new file mode 100644 index 0000000..d2fd893 --- /dev/null +++ b/modules/database/guide/database/query/builder.md @@ -0,0 +1,251 @@ +# Query Builder + +Creating queries dynamically using objects and methods allows queries to be written very quickly in an agnostic way. Query building also adds identifier (table and column name) quoting, as well as value quoting. + +## Select + +Each type of database query is represented by a different class, each with their own methods. For instance, to create a SELECT query, we use [DB::select] which is a shortcut to return a new [Database_Query_Builder_Select] object: + + $query = DB::select(); + +Query Builder methods return a reference to itself so that method chaining may be used. Select queries ussually require a table and they are referenced using the `from()` method. The `from()` method takes one parameter which can be the table name (string), an array of two strings (table name and alias), or an object (See Subqueries in the Advanced Queries section below). + + $query = DB::select()->from('users'); + +Limiting the results of queries is done using the `where()`, `and_where()` and `or_where()` methods. These methods take three parameters: a column, an operator, and a value. + + $query = DB::select()->from('users')->where('username', '=', 'john'); + +Multiple `where()` methods may be used to string together multiple clauses connected by the boolean operator in the method's prefix. The `where()` method is a wrapper that just calls `and_where()`. + + $query = DB::select()->from('users')->where('username', '=', 'john')->or_where('username', '=', 'jane'); + +You can use any operator you want. Examples include `IN`, `BETWEEN`, `>`, `=<`, `!=`, etc. Use an array for operators that require more than one value. + + $query = DB::select()->from('users')->where('logins', '<=', 1); + + $query = DB::select()->from('users')->where('logins', '>', 50); + + $query = DB::select()->from('users')->where('username', 'IN', array('john','mark','matt')); + + $query = DB::select()->from('users')->where('joindate', 'BETWEEN', array($then, $now)); + +By default, [DB::select] will select all columns (`SELECT * ...`), but you can also specify which columns you want returned by passing parameters to [DB::select]: + + $query = DB::select('username', 'password')->from('users')->where('username', '=', 'john'); + +Now take a minute to look at what this method chain is doing. First, we create a new selection object using the [DB::select] method. Next, we set table(s) using the `from()` method. Last, we search for a specific records using the `where()` method. We can display the SQL that will be executed by casting the query to a string: + + echo Debug::vars((string) $query); + // Should display: + // SELECT `username`, `password` FROM `users` WHERE `username` = 'john' + +Notice how the column and table names are automatically escaped, as well as the values? This is one of the key benefits of using the query builder. + +### Select - AS (column aliases) + +It is also possible to create `AS` aliases when selecting, by passing an array as each parameter to [DB::select]: + + $query = DB::select(array('username', 'u'), array('password', 'p'))->from('users'); + +This query would generate the following SQL: + + SELECT `username` AS `u`, `password` AS `p` FROM `users` + +### Select - DISTINCT + +Unique column values may be turned on or off (default) by passing TRUE or FALSE, respectively, to the `distinct()` method. + + $query = DB::select('username')->distinct(TRUE)->from('posts'); + +This query would generate the following SQL: + + SELECT DISTINCT `username` FROM `posts` + +### Select - LIMIT & OFFSET + +When querying large sets of data, it is often better to limit the results and page through the data one chunk at a time. This is done using the `limit()` and `offset()` methods. + + $query = DB::select()->from(`posts`)->limit(10)->offset(30); + +This query would generate the following SQL: + + SELECT * FROM `posts` LIMIT 10 OFFSET 30 + +### Select - ORDER BY + +Often you will want the results in a particular order and rather than sorting the results, it's better to have the results returned to you in the correct order. You can do this by using the order_by() method. It takes the column name and an optional direction string as the parameters. Multiple `order_by()` methods can be used to add additional sorting capability. + + $query = DB::select()->from(`posts`)->order_by(`published`, `DESC`); + +This query would generate the following SQL: + + SELECT * FROM `posts` ORDER BY `published` DESC + +[!!] For a complete list of methods available while building a select query see [Database_Query_Builder_Select]. + +## Insert + +To create records into the database, use [DB::insert] to create an INSERT query, using `values()` to pass in the data: + + $query = DB::insert('users', array('username', 'password'))->values(array('fred', 'p@5sW0Rd')); + +This query would generate the following SQL: + + INSERT INTO `users` (`username`, `password`) VALUES ('fred', 'p@5sW0Rd') + +[!!] For a complete list of methods available while building an insert query see [Database_Query_Builder_Insert]. + +## Update + +To modify an existing record, use [DB::update] to create an UPDATE query: + + $query = DB::update('users')->set(array('username' => 'jane'))->where('username', '=', 'john'); + +This query would generate the following SQL: + + UPDATE `users` SET `username` = 'jane' WHERE `username` = 'john' + +[!!] For a complete list of methods available while building an update query see [Database_Query_Builder_Update]. + +## Delete + +To remove an existing record, use [DB::delete] to create a DELETE query: + + $query = DB::delete('users')->where('username', 'IN', array('john', 'jane')); + +This query would generate the following SQL: + + DELETE FROM `users` WHERE `username` IN ('john', 'jane') + +[!!] For a complete list of methods available while building a delete query see [Database_Query_Builder_Delete]. + +## Advanced Queries + +### Joins + +Multiple tables can be joined using the `join()` and `on()` methods. The `join()` method takes two parameters. The first is either a table name, an array containing the table and alias, or an object (subquery or expression). The second parameter is the join type: LEFT, RIGHT, INNER, etc. + +The `on()` method sets the conditions for the previous `join()` method and is very similar to the `where()` method in that it takes three parameters; left column (name or object), an operator, and the right column (name or object). Multiple `on()` methods may be used to supply multiple conditions and they will be appended with an 'AND' operator. + + // This query will find all the posts related to "smith" with JOIN + $query = DB::select('authors.name', 'posts.content')->from('authors')->join('posts')->on('authors.id', '=', 'posts.author_id')->where('authors.name', '=', 'smith'); + +This query would generate the following SQL: + + SELECT `authors`.`name`, `posts`.`content` FROM `authors` JOIN `posts` ON (`authors`.`id` = `posts`.`author_id`) WHERE `authors`.`name` = 'smith' + +If you want to do a LEFT, RIGHT or INNER JOIN you would do it like this `join('colum_name', 'type_of_join')`: + + // This query will find all the posts related to "smith" with LEFT JOIN + $query = DB::select()->from('authors')->join('posts', 'LEFT')->on('authors.id', '=', 'posts.author_id')->where('authors.name', '=', 'smith'); + +This query would generate the following SQL: + + SELECT `authors`.`name`, `posts`.`content` FROM `authors` LEFT JOIN `posts` ON (`authors`.`id` = `posts`.`author_id`) WHERE `authors`.`name` = 'smith' + +[!!] When joining multiple tables with similar column names, it's best to prefix the columns with the table name or table alias to avoid errors. Ambiguous column names should also be aliased so that they can be referenced easier. + +### Database Functions + +Eventually you will probably run into a situation where you need to call `COUNT` or some other database function within your query. The query builder supports these functions using the `Database_Expression` class: + + $query = DB::select(array(DB::expr('COUNT(`username`)'), 'total_users'))->from('users'); + +This looks almost exactly the same as a standard `AS` alias, but note how the column name is put in a call to `DB::expr()`. Any time `DB::expr()` is used, the column name will **not** be escaped. This query would generate the following SQL: + + SELECT COUNT(`username`) AS `total_users` FROM `users` + +[!!] When building complex queries and you need to get a count of the total rows that will be returned, build the expression with an empty column list first. Then clone the query and add the COUNT function to one copy and the columns list to the other. This will cut down on the total lines of code and make updating the query easier. + + $query = DB::select()->from('users') + ->join('posts')->on('posts.username', '=', 'users.username') + ->where('users.active', '=', TRUE) + ->where('posts.created', '>=', $yesterday); + + $total = clone $query; + $total->select(array(DB::expr('COUNT( DISTINCT `username`)'), 'unique_users')); + $query->select('posts.username')->distinct(); + +### Aggregate Functions + +Aggregate functions like `COUNT()`, `SUM()`, `AVG()`, etc. will most likely be used with the `group_by()` and possibly the `having()` methods in order to group and filter the results on a set of columns. + + $query = DB::select('username', array(DB::expr('COUNT(`id`)'), 'total_posts') + ->from('posts')->group_by('username')->having('total_posts', '>=', 10); + +This will generate the following query: + + SELECT `username`, COUNT(`id`) AS `total_posts` FROM `posts` GROUP BY `username` HAVING `total_posts` >= 10 + +### Subqueries + +Query Builder objects can be passed as parameters to many of the methods to create subqueries. Let's take the previous example query and pass it to a new query. + + $sub = DB::select('username', array(DB::expr('COUNT(`id`)'), 'total_posts') + ->from('posts')->group_by('username')->having('total_posts', '>=', 10); + + $query = DB::select('profiles.*', 'posts.total_posts')->from('profiles') + ->join(array($sub, 'posts'), 'INNER')->on('profiles.username', '=', 'posts.username'); + +This will generate the following query: + + SELECT `profiles`.*, `posts`.`total_posts` FROM `profiles` INNER JOIN + ( SELECT `username`, COUNT(`id`) AS `total_posts` FROM `posts` GROUP BY `username` HAVING `total_posts` >= 10 ) AS posts + ON `profiles`.`username` = `posts`.`username` + +Insert queries can also use a select query for the input values + + $sub = DB::select('username', array(DB::expr('COUNT(`id`)'), 'total_posts') + ->from('posts')->group_by('username')->having('total_posts', '>=', 10); + + $query = DB::insert('post_totals', array('username', 'posts'))->select($sub); + +This will generate the following query: + + INSERT INTO `post_totals` (`username`, `posts`) + SELECT `username`, COUNT(`id`) AS `total_posts` FROM `posts` GROUP BY `username` HAVING `total_posts` >= 10 + +### Boolean Operators and Nested Clauses + +Multiple Where and Having clauses are added to the query with Boolean operators connecting each expression. The default operator for both methods is AND which is the same as the and_ prefixed method. The OR operator can be specified by prefixing the methods with or_. Where and Having clauses can be nested or grouped by post fixing either method with _open and then followed by a method with a _close. + + $query = DB::select()->from('users') + ->where_open() + ->or_where('id', 'IN', $expired) + ->and_where_open() + ->where('last_login', '<=', $last_month) + ->or_where('last_login', 'IS', NULL) + ->and_where_close() + ->where_close() + ->and_where('removed','IS', NULL); + +This will generate the following query: + + SELECT * FROM `users` WHERE ( `id` IN (1, 2, 3, 5) OR ( `last_login` <= 1276020805 OR `last_login` IS NULL ) ) AND `removed` IS NULL + +### Database Expressions + +There are cases were you need a complex expression or other database functions, which you don't want the Query Builder to try and escape. In these cases, you will need to use a database expression created with [DB::expr]. **A database expression is taken as direct input and no escaping is performed.** + + $query = DB::update('users')->set(array('login_count' => DB::expr('login_count + 1')))->where('id', '=', $id); + +This will generate the following query, assuming `$id = 45`: + + UPDATE `users` SET `login_count` = `login_count` + 1 WHERE `id` = 45 + +Another example to calculate the distance of two geographical points: + + $query = DB::select(array(DB::expr('degrees(acos(sin(radians('.$lat.')) * sin(radians(`latitude`)) + cos(radians('.$lat.')) * cos(radians(`latitude`)) * cos(radians(abs('.$lng.' - `longitude`))))) * 69.172'), 'distance'))->from('locations'); + +[!!] You must validate or escape any user input inside of DB::expr as it will obviously not be escaped it for you. + +## Executing + +Once you are done building, you can execute the query using `execute()` and use [the results](results). + + $result = $query->execute(); + +To use a different database [config group](config) pass either the name or the config object to `execute()`. + + $result = $query->execute('config_name') \ No newline at end of file diff --git a/modules/database/guide/database/query/parameterized.md b/modules/database/guide/database/query/parameterized.md new file mode 100644 index 0000000..5a4e537 --- /dev/null +++ b/modules/database/guide/database/query/parameterized.md @@ -0,0 +1,67 @@ +# Parameterized Statements + +Using parameterized statements allows you to write SQL queries manually while still escaping the query values automatically to prevent [SQL injection](http://wikipedia.org/wiki/SQL_Injection). Creating a query is simple: + + $query = DB::query(Database::SELECT, 'SELECT * FROM users WHERE username = :user'); + +The [DB::query] method is just a shortcut that creates a new [Database_Query] class for us, to allow method chaining. The query contains a `:user` parameter, which we will get to in a second. + +The first parameter of [DB::query] is the type of query. It should be `Database::SELECT`, `Database::INSERT`, `Database::UPDATE`, or `Database::DELETE`. This is done for compatibility reasons for drivers, and to easily determine what `execute()` should return. + +The second parameter is the query itself. Rather than trying to concatenate your query and variables together, you should make use of [Database_Query::param]. This will make your queries much easier to mantain, and will escape the values to prevent [SQL injection](http://wikipedia.org/wiki/SQL_Injection). + +## Parameters + +Our example query earlier contains a `:user` parameter, which we can assign to a value using [Database_Query::param] like so: + + $query->param(':user', 'john'); + +[!!] Parameter names can be any unique string, as they are replaced using [strtr](http://php.net/strtr). It is highly recommended to **not** use dollars signs as parameter names to prevent confusion. Colons are commonly used. + +You can also update the `:user` parameter by calling [Database_Query::param] again: + + $query->param(':user', $_GET['search']); + +If you want to set multiple parameters at once, you can use [Database_Query::parameters]. + + $query = DB::query(Database::SELECT, 'SELECT * FROM users WHERE username = :user AND status = :status'); + + $query->parameters(array( + ':user' => 'john', + ':status' => 'active', + )); + +It is also possible to bind a parameter to a variable, using a [variable reference]((http://php.net/language.references.whatdo)). This can be extremely useful when running the same query many times: + + $query = DB::query(Database::INSERT, 'INSERT INTO users (username, password) VALUES (:user, :pass)') + ->bind(':user', $username) + ->bind(':pass', $password); + + foreach ($new_users as $username => $password) + { + $query->execute(); + } + +In the above example, the variables `$username` and `$password` are changed for every loop of the `foreach` statement. When the parameter changes, it effectively changes the `:user` and `:pass` query parameters. Careful parameter binding can save a lot of code when it is used properly. + +The only difference between `param()` and `bind()` is that `bind()` passes the variable by reference rather than by assignment (copied), so future changes to the variable can be "seen" by the query. + +[!!] Although all parameters are escaped to prevent SQL injection, it is still a good idea to validate/sanitize your input. + +## Display the raw query + +If you want to display the SQL that will be executed, you can simply echo the query: + + echo $query; + // Should display: + // SELECT * FROM users WHERE username = 'john' + +## Executing + +Once you have assigned something to each of the parameters, you can execute the query using `execute()` and use [the results](results). + + $result = $query->execute(); + +To use a different database [config group](config) pass either the name or the config object to `execute()`. + + $result = $query->execute('config_name') \ No newline at end of file diff --git a/modules/database/guide/database/results.md b/modules/database/guide/database/results.md new file mode 100644 index 0000000..e13dfa1 --- /dev/null +++ b/modules/database/guide/database/results.md @@ -0,0 +1,105 @@ +# Results + +## Execute + +Once you have a query object built, either through a parameterized statement or through the builder, you must then `execute()` the query and retrieve the results. Depending on the query type used, the results returned will vary. + +## Select + +[DB::select] will return a [Database_Result] object which you can then iterate over. This example shows how you can iterate through the [Database_Result] using a foreach. + + $results = DB::select()->from('users')->where('verified', '=', 0)->execute(); + foreach($results as $user) + { + // Send reminder email to $user['email'] + echo $user['email']." needs to verify his/her account\n"; + } + +### Select - `as_object()` and `as_assoc()` + +When iterating over a result set, the default type will be an associative array with the column names or aliases as the keys. As an option, before calling `execute()`, you can specify to return the result rows as an object by using the `as_object()` method. The `as_object()` method takes one parameter, the name of the class of your choice, but will default to TRUE which uses the `stdClass`. Here is the example again using `stdClass`. + + $results = DB::select()->from('users')->where('verified', '=', 0)->as_object()->execute(); + foreach($results as $user) + { + // Send reminder email to $user->email + echo $user->email." needs to verify his/her account\n"; + } + +[!!] The method `as_assoc()` will remove the object name and return the results set back to an associative array. Since this is the default, this method is seldom required. + +### Select - `as_array()` + +Sometimes you will require the results as a pure array rather than as an object. The `Database_Result` method `as_array()` will return an array of all rows. + + $results = DB::select('id', 'email')->from('users')->execute(); + $users = $results->as_array(); + foreach($users as $user) + { + echo 'User ID: '.$user['id']; + echo 'User Email: '.$user['email']; + } + +It also accepts two parameters that can be very helpful: `$key` and `$value`. When passing a value to `$key` you will index the resulting array by the column specified. + + $results = DB::select('id', 'email')->from('users')->execute(); + $users = $results->as_array('id'); + foreach($users as $id => $user) + { + echo 'User ID: '.$id; + echo 'User Email: '.$user['email']; + } + +The second parameter, `$value`, will reference the column specified and return that value rather than the whole row. This is particularly useful when making `

+

+ + + +~~~ + +View for `crop/do` action goes to `views/crop/do.php`. + +~~~ + + + Upload Profile Image Result + + + +

Upload success

+

+ Here is your uploaded and cropped avatar: + " alt="Uploaded avatar" /> +

+ +

Something went wrong with the upload

+

+ + + +~~~ + +## Screenshots + +Below are screenshots for this example. + +![Original image](crop_orig.jpg) + +_Original image to upload_ + +![Upload image form](crop_form.jpg) + +_Upload image form_ + +![Upload result page](crop_result.jpg) + +_Upload result form_ \ No newline at end of file diff --git a/modules/image/guide/image/examples/dynamic.md b/modules/image/guide/image/examples/dynamic.md new file mode 100644 index 0000000..2d70260 --- /dev/null +++ b/modules/image/guide/image/examples/dynamic.md @@ -0,0 +1,108 @@ +# Dynamic Image Controller + +In this example, we have images under `/uploads` under the webroot directory. We allow the user to render any image with dynamic dimension and is resized on the fly. It also caches the response for 1 hour to show basic caching mechanism. + +## Route + +First, we need a [Route]. This [Route] is based on this URL pattern: + +`/imagefly/filename/width/height` - where filename is the name of the image without the extension. This assumes that all images are in `jpg` and all filenames uses numbers, letters, dash and underscores only. + +This is our [Route] definition: + +~~~ +/** + * Set route for image fly + */ +Route::set('imagefly', 'imagefly///', array('image' => '[-09a-zA-Z_]+', 'width' => '[0-9]+', 'height' => '[0-9]+')) + ->defaults(array( + 'controller' => 'imagefly', + 'action' => 'index' + )); +~~~ + +We ensure that the filename is only composed of letters, numbers and underscores, width and height must be numeric. + +## Controller + +Our controller simply accepts the request and capture the following parameters as defined by the [Route]: + +* `filename` - without the filename extension (and without dot) +* `width` +* `height` + +Then it finds the image file and when found, render it on the browser. Additional features added are browser caching. + +~~~ +request->param('image'); + $width = (int) $this->request->param('width'); + $height = (int) $this->request->param('height'); + + $rendered = FALSE; + if ($file AND $width AND $height) + { + $filename = DOCROOT.'uploads/'.$file.'.jpg'; + + if (is_file($filename)) + { + $this->_render_image($filename, $width, $height); + $rendered = TRUE; + } + } + + if ( ! $rendered) + { + $this->response->status(404); + } + } + + protected function _render_image($filename, $width, $height) + { + // Calculate ETag from original file padded with the dimension specs + $etag_sum = md5(base64_encode(file_get_contents($filename)).$width.','.$height); + + // Render as image and cache for 1 hour + $this->response->headers('Content-Type', 'image/jpeg') + ->headers('Cache-Control', 'max-age='.Date::HOUR.', public, must-revalidate') + ->headers('Expires', gmdate('D, d M Y H:i:s', time() + Date::HOUR).' GMT') + ->headers('Last-Modified', date('r', filemtime($filename))) + ->headers('ETag', $etag_sum); + + if ( + $this->request->headers('if-none-match') AND + (string) $this->request->headers('if-none-match') === $etag_sum) + { + $this->response->status(304) + ->headers('Content-Length', '0'); + } + else + { + $result = Image::factory($filename) + ->resize($width, $height) + ->render('jpg'); + + $this->response->body($result); + } + } +} +~~~ + +When the parameters are invalid or the filename does not exists, it simply returns 404 not found error. + +The rendering of image uses some caching mechanism. One by setting the max age and expire headers and second by using etags. + +## Screenshots + +Visiting [http://localhost/kohana/imagefly/kitteh/400/400](http://localhost/kohana/imagefly/kitteh/400/400) yields: + +![Kitten 400x400](dynamic-400.jpg) + +Visiting [http://localhost/kohana/imagefly/kitteh/600/500](http://localhost/kohana/imagefly/kitteh/600/500) yields: + +![Kitten 400x400](dynamic-600.jpg) \ No newline at end of file diff --git a/modules/image/guide/image/examples/upload.md b/modules/image/guide/image/examples/upload.md new file mode 100644 index 0000000..e08b780 --- /dev/null +++ b/modules/image/guide/image/examples/upload.md @@ -0,0 +1,139 @@ +# Upload Image + +The following example shows how to handle uploading of an image, resize it and save it to a file. Be sure you have enabled the [Image] module as discussed in getting started guide. + +Assuming you are creating a web application that allows your members to upload their profile picture (avatar), the steps below explains it how. + +## Controller + +First we need to create a controller that handles the requests for uploading an image. We will name it `Controller_Avatar` and accessible through `/avatar` URL. Assuming that your project is located at [http://localhost/kohana](http://localhost/kohana), then our avatar controller is at [http://localhost/kohana/avatar](http://localhost/kohana/avatar). + +For simplicity, the upload form will be on `index` action and `upload` action will process the uploaded file. This is what our controller now looks like. Please note that we are not using [Controller_Template], just [Controller]. + +~~~ +response->body($view); + } + + public function action_upload() + { + $view = View::factory('avatar/upload'); + $error_message = NULL; + $filename = NULL; + + if ($this->request->method() == Request::POST) + { + if (isset($_FILES['avatar'])) + { + $filename = $this->_save_image($_FILES['avatar']); + } + } + + if ( ! $filename) + { + $error_message = 'There was a problem while uploading the image. + Make sure it is uploaded and must be JPG/PNG/GIF file.'; + } + + $view->uploaded_file = $filename; + $view->error_message = $error_message; + $this->response->body($view); + } + + protected function _save_image($image) + { + if ( + ! Upload::valid($image) OR + ! Upload::not_empty($image) OR + ! Upload::type($image, array('jpg', 'jpeg', 'png', 'gif'))) + { + return FALSE; + } + + $directory = DOCROOT.'uploads/'; + + if ($file = Upload::save($image, NULL, $directory)) + { + $filename = strtolower(Text::random('alnum', 20)).'.jpg'; + + Image::factory($file) + ->resize(200, 200, Image::AUTO) + ->save($directory.$filename); + + // Delete the temporary file + unlink($file); + + return $filename; + } + + return FALSE; + } + +} +~~~ + +We have `index` and `upload` actions. `index` action will display the upload form and `upload` action will process the uploaded image and provides feedback to the user. + +In `upload` action, it checks if the request method was `POST`, then delegates the process to `_save_image()` method which in turn performs various checks and finally resize and save the image to the `uploads` directory. + +## Views + +For the upload form (the `index` action), the view is located at `views/avatar/index.php`. + +~~~ + + + Upload Avatar + + +

Upload your avatar

+
+

Choose file:

+

+

+
+ + +~~~ + +Take note of the action attribute. It points to our `avatar/upload` action whose view code goes to `views/avatar/upload.php`. + +~~~ + + + Upload Avatar Result + + + +

Upload success

+

+ Here is your uploaded avatar: + " alt="Uploaded avatar" /> +

+ +

Something went wrong with the upload

+

+ + + +~~~ + +When the upload is successfull, a success message is displayed with the uploaded image displayed. Otherwise, when it fails, it displays an error message. + +## Screenshots + +Below are screenshots for this example. + +![Upload image form](upload_form.jpg) + +_Upload image form_ + +![Upload result page](upload_result.jpg) + +_Upload result form_ \ No newline at end of file diff --git a/modules/image/guide/image/index.md b/modules/image/guide/image/index.md new file mode 100644 index 0000000..0225c26 --- /dev/null +++ b/modules/image/guide/image/index.md @@ -0,0 +1,21 @@ +# Image + +Kohana 3.x provides a simple yet powerful image manipulation module. The [Image] module provides features that allows your application to resize images, crop, rotate, flip and many more. + +## Drivers + +[Image] module ships with [Image_GD] driver which requires `GD` extension enabled in your PHP installation. This is the default driver. Additional drivers can be created by extending the [Image] class. + +## Getting Started + +Before using the image module, we must enable it first on `APPPATH/bootstrap.php`: + +~~~ +Kohana::modules(array( + ... + 'image' => MODPATH.'image', // Image manipulation + ... +)); +~~~ + +Next: [Using the image module](using). \ No newline at end of file diff --git a/modules/image/guide/image/menu.md b/modules/image/guide/image/menu.md new file mode 100644 index 0000000..8c87743 --- /dev/null +++ b/modules/image/guide/image/menu.md @@ -0,0 +1,6 @@ +## [Image]() +- [Using](using) +- [Examples](examples) + - [Upload Image](examples/upload) + - [Crop Profile Image](examples/crop) + - [Dynamic Image Controller](examples/dynamic) \ No newline at end of file diff --git a/modules/image/guide/image/using.md b/modules/image/guide/image/using.md new file mode 100644 index 0000000..fd1859b --- /dev/null +++ b/modules/image/guide/image/using.md @@ -0,0 +1,112 @@ +# Basic Usage + +Shown here are the basic usage of this module. For full documentation about the image module usage, visit the [Image] api browser. + +## Creating Instance + +[Image::factory()] creates an instance of the image object and prepares it for manipulation. It accepts the `filename` as an arguement and an optional `driver` parameter. When `driver` is not specified, the default driver `GD` is used. + +~~~ +// Uses the image from upload directory +$img = Image::factory(DOCROOT.'uploads/sample-image.jpg'); +~~~ + +Once an instance is created, you can now manipulate the image by using the following instance methods. + +## Resize + +Resize the image to the given size. Either the width or the height can be omitted and the image will be resized proportionally. + +Using the image object above, we can resize our image to say 150x150 pixels with automatic scaling using the code below: + +~~~ +$img->resize(150, 150, Image::AUTO); +~~~ + +The parameters are `width`, `height` and `master` dimension respectively. With `AUTO` master dimension, the image is resized by either width or height depending on which is closer to the specified dimension. + +Other examples: + +~~~ +// Resize to 200 pixels on the shortest side +$img->resize(200, 200); + +// Resize to 200x200 pixels, keeping aspect ratio +$img->resize(200, 200, Image::INVERSE); + +// Resize to 500 pixel width, keeping aspect ratio +$img->resize(500, NULL); + +// Resize to 500 pixel height, keeping aspect ratio +$img->resize(NULL, 500); + +// Resize to 200x500 pixels, ignoring aspect ratio +$img->resize(200, 500, Image::NONE); +~~~ + +## Render + +You can render the image object directly to the browser using the [Image::render()] method. + +~~~ +$img = Image::factory(DOCROOT.'uploads/colorado-farm-1920x1200.jpg'); + +header('Content-Type: image/jpeg'); + +echo $img->resize(300, 300) + ->render(); +~~~ + +What it did is resize a 1920x1200 wallpaper image into 300x300 proportionally and render it to the browser. If you are trying to render the image in a controller action, you can do instead: + +~~~ +$img = Image::factory(DOCROOT.'uploads/colorado-farm-1920x1200.jpg'); + +$this->response->headers('Content-Type', 'image/jpg'); + +$this->response->body( + $img->resize(300, 300) + ->render() +); +~~~ + +[Image::render()] method also allows you to specify the type and quality of the rendered image. + +~~~ +// Render the image at 50% quality +$img->render(NULL, 50); + +// Render the image as a PNG +$img->render('png'); +~~~ + +## Save To File + +[Image::save()] let's you save the image object to a file. It has two parameters: `filename` and `quality`. If `filename` is omitted, the original file used will be overwritten instead. The `quality` parameter is an integer from 1-100 which indicates the quality of image to save which defaults to 100. + +On our example above, instead of rendering the file to the browser, you may want to save it somewhere instead. To do so, you may: + +~~~ +$img = Image::factory(DOCROOT.'uploads/colorado-farm-1920x1200.jpg'); + +$filename = DOCROOT.'uploads/img-'.uniqid().'.jpg'; + +$img->resize(300, 300) + ->save($filename, 80); +~~~ + +What we do is resize the image and save it to file reducing quality to 80% and save it to the upload directory using a unique filename. + +## Other Methods + +There are more methods available for the [Image] module which provides powerfull features that are best describe in the API documentation. Here are some of them: + +* [Image::background()] - Set the background color of an image. +* [Image::crop()] - Crop an image to the given size. +* [Image::flip()] - Flip the image along the horizontal or vertical axis. +* [Image::reflection()] - Add a reflection to an image. +* [Image::rotate()] - Rotate the image by a given amount. +* [Image::sharpen()] - Sharpen the image by a given amount. +* [Image::watermark()] - Add a watermark to an image with a specified opacity. + +Next: [Examples](examples) \ No newline at end of file diff --git a/modules/image/media/guide/image/Thumbs.db b/modules/image/media/guide/image/Thumbs.db new file mode 100644 index 0000000..a0f028f Binary files /dev/null and b/modules/image/media/guide/image/Thumbs.db differ diff --git a/modules/image/media/guide/image/crop_form.jpg b/modules/image/media/guide/image/crop_form.jpg new file mode 100644 index 0000000..7179a2e Binary files /dev/null and b/modules/image/media/guide/image/crop_form.jpg differ diff --git a/modules/image/media/guide/image/crop_orig.jpg b/modules/image/media/guide/image/crop_orig.jpg new file mode 100644 index 0000000..1389acc Binary files /dev/null and b/modules/image/media/guide/image/crop_orig.jpg differ diff --git a/modules/image/media/guide/image/crop_result.jpg b/modules/image/media/guide/image/crop_result.jpg new file mode 100644 index 0000000..7cf79b0 Binary files /dev/null and b/modules/image/media/guide/image/crop_result.jpg differ diff --git a/modules/image/media/guide/image/dynamic-400.jpg b/modules/image/media/guide/image/dynamic-400.jpg new file mode 100644 index 0000000..13b691f Binary files /dev/null and b/modules/image/media/guide/image/dynamic-400.jpg differ diff --git a/modules/image/media/guide/image/dynamic-600.jpg b/modules/image/media/guide/image/dynamic-600.jpg new file mode 100644 index 0000000..f521b49 Binary files /dev/null and b/modules/image/media/guide/image/dynamic-600.jpg differ diff --git a/modules/image/media/guide/image/upload_form.jpg b/modules/image/media/guide/image/upload_form.jpg new file mode 100644 index 0000000..101a7b3 Binary files /dev/null and b/modules/image/media/guide/image/upload_form.jpg differ diff --git a/modules/image/media/guide/image/upload_result.jpg b/modules/image/media/guide/image/upload_result.jpg new file mode 100644 index 0000000..ec88621 Binary files /dev/null and b/modules/image/media/guide/image/upload_result.jpg differ diff --git a/modules/image/tests/kohana/ImageTest.php b/modules/image/tests/kohana/ImageTest.php new file mode 100644 index 0000000..967b764 --- /dev/null +++ b/modules/image/tests/kohana/ImageTest.php @@ -0,0 +1,36 @@ +markTestSkipped('The GD extension is not available.'); + } + } + + /** + * Tests the Image::save() method for files that don't have extensions + * + * @return void + */ + public function test_save_without_extension() + { + $image = Image::factory(MODPATH.'image/tests/test_data/test_image'); + $this->assertTrue($image->save(Kohana::$cache_dir.'/test_image')); + + unlink(Kohana::$cache_dir.'/test_image'); + } + +} // End Kohana_ImageTest diff --git a/modules/image/tests/test_data/test_image b/modules/image/tests/test_data/test_image new file mode 100644 index 0000000..683a3c3 Binary files /dev/null and b/modules/image/tests/test_data/test_image differ diff --git a/modules/minion/README.md b/modules/minion/README.md new file mode 100644 index 0000000..6d317cb --- /dev/null +++ b/modules/minion/README.md @@ -0,0 +1,62 @@ +# Minion + +Minion is a framework for running tasks via the CLI. + +The system is inspired by ruckusing, which had a nice system for defining tasks but lacked the desired flexibility for kohana integration. + +## Getting Started + +First off, download and enable the module in your bootstrap + +Then copy the bash script `minion` alongside your index.php (most likely the webroot). +If you'd rather the executable be in a different location to index.php then simply modify the bash script to point to index.php. + +You can then run minion like so: + + ./minion {task} + +To view a list of minion tasks, run minion without any parameters, or with the `--help` option + + ./minion + ./minion --help + +To view help for a specific minion task run + + ./minion {task} --help + +For security reasons Minion will only run from the cli. Attempting to access it over http will cause +a `Kohana_Exception` to be thrown. + +If you're unable to use the binary file for whatever reason then simply replace `./minion {task}` in the above +examples with + + php index.php --uri=minion --task={task} + +## Writing your own tasks + +All minion tasks must be located in `classes/task/`. They can be in any module, thus allowing you to +ship custom minion tasks with your own module / product. + +Each task must extend the abstract class `Minion_Task` and implement `Minion_Task::_execute()`. + +See `Minion_Task` for more details. + +## Documentation + +Code should be commented well enough not to need documentation, and minion can extract a class' doccomment to use +as documentation on the cli. + +## Testing + +This module is unittested using the [unittest module](http://github.com/kohana/unittest). +You can use the `minion` group to only run minion tests. + +i.e. + + phpunit --group minion + +Feel free to contribute tests(!), they can be found in the `tests/minion` directory. :) + +## License + +This is licensed under the [same license as Kohana](http://kohanaframework.org/license). diff --git a/modules/minion/classes/Kohana/Minion/CLI.php b/modules/minion/classes/Kohana/Minion/CLI.php new file mode 100644 index 0000000..13c1de6 --- /dev/null +++ b/modules/minion/classes/Kohana/Minion/CLI.php @@ -0,0 +1,315 @@ + '0;30', + 'dark_gray' => '1;30', + 'blue' => '0;34', + 'light_blue' => '1;34', + 'green' => '0;32', + 'light_green' => '1;32', + 'cyan' => '0;36', + 'light_cyan' => '1;36', + 'red' => '0;31', + 'light_red' => '1;31', + 'purple' => '0;35', + 'light_purple' => '1;35', + 'brown' => '0;33', + 'yellow' => '1;33', + 'light_gray' => '0;37', + 'white' => '1;37', + ); + protected static $background_colors = array( + 'black' => '40', + 'red' => '41', + 'green' => '42', + 'yellow' => '43', + 'blue' => '44', + 'magenta' => '45', + 'cyan' => '46', + 'light_gray' => '47', + ); + + /** + * Returns one or more command-line options. Options are specified using + * standard CLI syntax: + * + * php index.php --username=john.smith --password=secret --var="some value with spaces" + * + * // Get the values of "username" and "password" + * $auth = Minion_CLI::options('username', 'password'); + * + * @param string $options,... option name + * @return array + */ + public static function options($options = NULL) + { + // Get all of the requested options + $options = func_get_args(); + + // Found option values + $values = array(); + + // Skip the first option, it is always the file executed + for ($i = 1; $i < $_SERVER['argc']; $i++) + { + if ( ! isset($_SERVER['argv'][$i])) + { + // No more args left + break; + } + + // Get the option + $opt = $_SERVER['argv'][$i]; + + if (substr($opt, 0, 2) !== '--') + { + // This is a positional argument + $values[] = $opt; + continue; + } + + // Remove the "--" prefix + $opt = substr($opt, 2); + + if (strpos($opt, '=')) + { + // Separate the name and value + list ($opt, $value) = explode('=', $opt, 2); + } + else + { + $value = NULL; + } + + $values[$opt] = $value; + } + + if ($options) + { + foreach ($values as $opt => $value) + { + if ( ! in_array($opt, $options)) + { + // Set the given value + unset($values[$opt]); + } + } + } + + return count($options) == 1 ? array_pop($values) : $values; + } + + /** + * Reads input from the user. This can have either 1 or 2 arguments. + * + * Usage: + * + * // Waits for any key press + * Minion_CLI::read(); + * + * // Takes any input + * $color = Minion_CLI::read('What is your favorite color?'); + * + * // Will only accept the options in the array + * $ready = Minion_CLI::read('Are you ready?', array('y','n')); + * + * @param string $text text to show user before waiting for input + * @param array $options array of options the user is shown + * @return string the user input + */ + public static function read($text = '', array $options = NULL) + { + // If a question has been asked with the read + $options_output = ''; + if ( ! empty($options)) + { + $options_output = ' [ '.implode(', ', $options).' ]'; + } + + fwrite(STDOUT, $text.$options_output.': '); + + // Read the input from keyboard. + $input = trim(fgets(STDIN)); + + // If options are provided and the choice is not in the array, tell them to try again + if ( ! empty($options) && ! in_array($input, $options)) + { + Minion_CLI::write('This is not a valid option. Please try again.'); + + $input = Minion_CLI::read($text, $options); + } + + // Read the input + return $input; + } + + /** + * Experimental feature. + * + * Reads hidden input from the user + * + * Usage: + * + * $password = Minion_CLI::password('Enter your password'); + * + * @author Mathew Davies. + * @return string + */ + public static function password($text = '') + { + $text .= ': '; + + if (Kohana::$is_windows) + { + $vbscript = sys_get_temp_dir().'Minion_CLI_Password.vbs'; + + // Create temporary file + file_put_contents($vbscript, 'wscript.echo(InputBox("'.addslashes($text).'"))'); + + $password = shell_exec('cscript //nologo '.escapeshellarg($command)); + + // Remove temporary file. + unlink($vbscript); + } + else + { + $password = shell_exec('/usr/bin/env bash -c \'read -s -p "'.escapeshellcmd($text).'" var && echo $var\''); + } + + Minion_CLI::write(); + + return trim($password); + } + + /** + * Outputs a string to the cli. If you send an array it will implode them + * with a line break. + * + * @param string|array $text the text to output, or array of lines + */ + public static function write($text = '') + { + if (is_array($text)) + { + foreach ($text as $line) + { + Minion_CLI::write($line); + } + } + else + { + fwrite(STDOUT, $text.PHP_EOL); + } + } + + /** + * Outputs a replacable line to the cli. You can continue replacing the + * line until `TRUE` is passed as the second parameter in order to indicate + * you are done modifying the line. + * + * // Sample progress indicator + * Minion_CLI::write_replace('0%'); + * Minion_CLI::write_replace('25%'); + * Minion_CLI::write_replace('50%'); + * Minion_CLI::write_replace('75%'); + * // Done writing this line + * Minion_CLI::write_replace('100%', TRUE); + * + * @param string $text the text to output + * @param boolean $end_line whether the line is done being replaced + */ + public static function write_replace($text = '', $end_line = FALSE) + { + // Append a newline if $end_line is TRUE + $text = $end_line ? $text.PHP_EOL : $text; + fwrite(STDOUT, "\r\033[K".$text); + } + + /** + * Waits a certain number of seconds, optionally showing a wait message and + * waiting for a key press. + * + * @author Fuel Development Team + * @license MIT License + * @copyright 2010 - 2011 Fuel Development Team + * @link http://fuelphp.com + * @param int $seconds number of seconds + * @param bool $countdown show a countdown or not + */ + public static function wait($seconds = 0, $countdown = false) + { + if ($countdown === true) + { + $time = $seconds; + + while ($time > 0) + { + fwrite(STDOUT, $time.'... '); + sleep(1); + $time--; + } + + Minion_CLI::write(); + } + else + { + if ($seconds > 0) + { + sleep($seconds); + } + else + { + Minion_CLI::write(Minion_CLI::$wait_msg); + Minion_CLI::read(); + } + } + } + + /** + * Returns the given text with the correct color codes for a foreground and + * optionally a background color. + * + * @author Fuel Development Team + * @license MIT License + * @copyright 2010 - 2011 Fuel Development Team + * @link http://fuelphp.com + * @param string $text the text to color + * @param atring $foreground the foreground color + * @param string $background the background color + * @return string the color coded string + */ + public static function color($text, $foreground, $background = null) + { + + if (Kohana::$is_windows) + { + return $text; + } + + if (!array_key_exists($foreground, Minion_CLI::$foreground_colors)) + { + throw new Kohana_Exception('Invalid CLI foreground color: '.$foreground); + } + + if ($background !== null and !array_key_exists($background, Minion_CLI::$background_colors)) + { + throw new Kohana_Exception('Invalid CLI background color: '.$background); + } + + $string = "\033[".Minion_CLI::$foreground_colors[$foreground]."m"; + + if ($background !== null) + { + $string .= "\033[".Minion_CLI::$background_colors[$background]."m"; + } + + $string .= $text."\033[0m"; + + return $string; + } + +} diff --git a/modules/minion/classes/Kohana/Minion/Exception.php b/modules/minion/classes/Kohana/Minion/Exception.php new file mode 100644 index 0000000..442e82d --- /dev/null +++ b/modules/minion/classes/Kohana/Minion/Exception.php @@ -0,0 +1,64 @@ +format_for_cli(); + } + else + { + echo Kohana_Exception::text($e); + } + + $exit_code = $e->getCode(); + + // Never exit "0" after an exception. + if ($exit_code == 0) + { + $exit_code = 1; + } + + exit($exit_code); + } + catch (Exception $e) + { + // Clean the output buffer if one exists + ob_get_level() and ob_clean(); + + // Display the exception text + echo Kohana_Exception::text($e), "\n"; + + // Exit with an error status + exit(1); + } + } + + public function format_for_cli() + { + return Kohana_Exception::text($e); + } +} diff --git a/modules/minion/classes/Kohana/Minion/Exception/InvalidTask.php b/modules/minion/classes/Kohana/Minion/Exception/InvalidTask.php new file mode 100644 index 0000000..db8ead4 --- /dev/null +++ b/modules/minion/classes/Kohana/Minion/Exception/InvalidTask.php @@ -0,0 +1,18 @@ +getMessage().PHP_EOL; + } + +} diff --git a/modules/minion/classes/Kohana/Minion/Task.php b/modules/minion/classes/Kohana/Minion/Task.php new file mode 100644 index 0000000..be4fcc0 --- /dev/null +++ b/modules/minion/classes/Kohana/Minion/Task.php @@ -0,0 +1,364 @@ + $class) + ); + } + + $class = new $class; + + if ( ! $class instanceof Minion_Task) + { + throw new Minion_Exception_InvalidTask( + "Task ':task' is not a valid minion task", + array(':task' => $class) + ); + } + + $class->set_options($options); + + // Show the help page for this task if requested + if (array_key_exists('help', $options)) + { + $class->_method = '_help'; + } + + return $class; + } + + /** + * The list of options this task accepts and their default values. + * + * protected $_options = array( + * 'limit' => 4, + * 'table' => NULL, + * ); + * + * @var array + */ + protected $_options = array(); + + /** + * Populated with the accepted options for this task. + * This array is automatically populated based on $_options. + * + * @var array + */ + protected $_accepted_options = array(); + + protected $_method = '_execute'; + + protected function __construct() + { + // Populate $_accepted_options based on keys from $_options + $this->_accepted_options = array_keys($this->_options); + } + + /** + * The file that get's passes to Validation::errors() when validation fails + * @var string|NULL + */ + protected $_errors_file = 'validation'; + + /** + * Gets the task name for the task + * + * @return string + */ + public function __toString() + { + static $task_name = NULL; + + if ($task_name === NULL) + { + $task_name = Minion_Task::convert_class_to_task($this); + } + + return $task_name; + } + + /** + * Sets options for this task + * + * $param array the array of options to set + * @return this + */ + public function set_options(array $options) + { + foreach ($options as $key => $value) + { + $this->_options[$key] = $value; + } + + return $this; + } + + /** + * Get the options that were passed into this task with their defaults + * + * @return array + */ + public function get_options() + { + return (array) $this->_options; + } + + /** + * Get a set of options that this task can accept + * + * @return array + */ + public function get_accepted_options() + { + return (array) $this->_accepted_options; + } + + /** + * Adds any validation rules/labels for validating _options + * + * public function build_validation(Validation $validation) + * { + * return parent::build_validation($validation) + * ->rule('paramname', 'not_empty'); // Require this param + * } + * + * @param Validation the validation object to add rules to + * + * @return Validation + */ + public function build_validation(Validation $validation) + { + // Add a rule to each key making sure it's in the task + foreach ($validation->as_array() as $key => $value) + { + $validation->rule($key, array($this, 'valid_option'), array(':validation', ':field')); + } + + return $validation; + } + + /** + * Returns $_errors_file + * + * @return string + */ + public function get_errors_file() + { + return $this->_errors_file; + } + + /** + * Execute the task with the specified set of options + * + * @return null + */ + public function execute() + { + $options = $this->get_options(); + + // Validate $options + $validation = Validation::factory($options); + $validation = $this->build_validation($validation); + + if ( $this->_method != '_help' AND ! $validation->check()) + { + echo View::factory('minion/error/validation') + ->set('task', Minion_Task::convert_class_to_task($this)) + ->set('errors', $validation->errors($this->get_errors_file())); + } + else + { + // Finally, run the task + $method = $this->_method; + echo $this->{$method}($options); + } + } + + abstract protected function _execute(array $params); + + /** + * Outputs help for this task + * + * @return null + */ + protected function _help(array $params) + { + $tasks = $this->_compile_task_list(Kohana::list_files('classes/task')); + + $inspector = new ReflectionClass($this); + + list($description, $tags) = $this->_parse_doccomment($inspector->getDocComment()); + + $view = View::factory('minion/help/task') + ->set('description', $description) + ->set('tags', (array) $tags) + ->set('task', Minion_Task::convert_class_to_task($this)); + + echo $view; + } + + + public function valid_option(Validation $validation, $option) + { + if ( ! in_array($option, $this->_accepted_options)) + { + $validation->error($option, 'minion_option'); + } + } + + /** + * Parses a doccomment, extracting both the comment and any tags associated + * + * Based on the code in Kodoc::parse() + * + * @param string The comment to parse + * @return array First element is the comment, second is an array of tags + */ + protected function _parse_doccomment($comment) + { + // Normalize all new lines to \n + $comment = str_replace(array("\r\n", "\n"), "\n", $comment); + + // Remove the phpdoc open/close tags and split + $comment = array_slice(explode("\n", $comment), 1, -1); + + // Tag content + $tags = array(); + + foreach ($comment as $i => $line) + { + // Remove all leading whitespace + $line = preg_replace('/^\s*\* ?/m', '', $line); + + // Search this line for a tag + if (preg_match('/^@(\S+)(?:\s*(.+))?$/', $line, $matches)) + { + // This is a tag line + unset($comment[$i]); + + $name = $matches[1]; + $text = isset($matches[2]) ? $matches[2] : ''; + + $tags[$name] = $text; + } + else + { + $comment[$i] = (string) $line; + } + } + + $comment = trim(implode("\n", $comment)); + + return array($comment, $tags); + } + + /** + * Compiles a list of available tasks from a directory structure + * + * @param array Directory structure of tasks + * @param string prefix + * @return array Compiled tasks + */ + protected function _compile_task_list(array $files, $prefix = '') + { + $output = array(); + + foreach ($files as $file => $path) + { + $file = substr($file, strrpos($file, DIRECTORY_SEPARATOR) + 1); + + if (is_array($path) AND count($path)) + { + $task = $this->_compile_task_list($path, $prefix.$file.Minion_Task::$task_separator); + + if ($task) + { + $output = array_merge($output, $task); + } + } + else + { + $output[] = strtolower($prefix.substr($file, 0, -strlen(EXT))); + } + } + + return $output; + } +} diff --git a/modules/minion/classes/Minion/CLI.php b/modules/minion/classes/Minion/CLI.php new file mode 100644 index 0000000..d998766 --- /dev/null +++ b/modules/minion/classes/Minion/CLI.php @@ -0,0 +1,3 @@ +_compile_task_list(Kohana::list_files('classes/Task')); + + $view = new View('minion/help/list'); + + $view->tasks = $tasks; + + echo $view; + } +} diff --git a/modules/minion/config/userguide.php b/modules/minion/config/userguide.php new file mode 100644 index 0000000..1bb7093 --- /dev/null +++ b/modules/minion/config/userguide.php @@ -0,0 +1,13 @@ + array( + 'minion' => array( + 'enabled' => TRUE, + 'name' => 'Minion', + 'description' => 'Minion is a simple command line task runner', + 'copyright' => '© 2009-2011 Kohana Team', + ) + ) +); \ No newline at end of file diff --git a/modules/minion/guide/minion/index.md b/modules/minion/guide/minion/index.md new file mode 100644 index 0000000..5c3be5b --- /dev/null +++ b/modules/minion/guide/minion/index.md @@ -0,0 +1,3 @@ +# Minion + +Minion is a simple command line task runner. \ No newline at end of file diff --git a/modules/minion/guide/minion/menu.md b/modules/minion/guide/minion/menu.md new file mode 100644 index 0000000..9c22809 --- /dev/null +++ b/modules/minion/guide/minion/menu.md @@ -0,0 +1,3 @@ +## [Minion]() + - [Setup](setup) + - [Writing a Task](tasks) \ No newline at end of file diff --git a/modules/minion/guide/minion/setup.md b/modules/minion/guide/minion/setup.md new file mode 100644 index 0000000..11e6256 --- /dev/null +++ b/modules/minion/guide/minion/setup.md @@ -0,0 +1,32 @@ +# Minion Setup + +To use minion, you'll need to make a small change to your index.php file: + + -/** + - * Execute the main request. A source of the URI can be passed, eg: $_SERVER['PATH_INFO']. + - * If no source is specified, the URI will be automatically detected. + - */ + -echo Request::factory() + - ->execute() + - ->send_headers(TRUE) + - ->body(); + +if (PHP_SAPI == 'cli') // Try and load minion + +{ + + class_exists('Minion_Task') OR die('minion required!'); + + set_exception_handler(array('Kohana_Minion_Exception_Handler', 'handler')); + + + + Minion_Task::factory(Minion_CLI::options())->execute(); + +} + +else + +{ + + /** + + * Execute the main request. A source of the URI can be passed, eg: $_SERVER['PATH_INFO']. + + * If no source is specified, the URI will be automatically detected. + + */ + + echo Request::factory() + + ->execute() + + ->send_headers(TRUE) + + ->body(); + +} + +This will short-circuit your index file to intercept any cli calls, and route them to the minion module. \ No newline at end of file diff --git a/modules/minion/guide/minion/tasks.md b/modules/minion/guide/minion/tasks.md new file mode 100644 index 0000000..4bda3ef --- /dev/null +++ b/modules/minion/guide/minion/tasks.md @@ -0,0 +1,71 @@ +# Writing Tasks + +Writing a task in minion is very easy. Simply create a new class called `Task_` and put it inside `classes/task/.php`. + + NULL, + ); + + /** + * This is a demo task + * + * @return null + */ + protected function _execute(array $params) + { + var_dump($params); + echo 'foobar'; + } + } + +You'll notice a few things here: + + - You need a main `_execute()` method. It should take one array parameter. + - This parameter contains any command line options passed to the task. + - For example, if you call the task above with `./minion --task=demo --foo=foobar` then `$params` will contain: `array('foo' => 'foobar', 'bar' => NULL)` + - It needs to have a `protected $_defaults` array. This is a list of parameters you want to accept for this task. Any parameters passed to the task not in this list will be rejected. + +## Namespacing Tasks + +You can "namespace" tasks by placing them all in a subdirectory: `classes/task/database/generate.php`. This task will be named `database:generate` and can be called with this task name. + +# Parameter Validations + +To add validations to your command line options, simply overload the `build_validation()` method in your task: + + public function build_validation(Validation $validation) + { + return parent::build_validation($validation) + ->rule('foo', 'not_empty') // Require this param + ->rule('bar', 'numeric'); // This param should be numeric + } + +These validations will run for every task call unless `--help` is passed to the task. + +# Task Help + +Tasks can have built-in help. Minion will read class docblocks that you specify: + + ':field is not a valid option for this task!', +); \ No newline at end of file diff --git a/modules/minion/minion b/modules/minion/minion new file mode 100644 index 0000000..dc4f755 --- /dev/null +++ b/modules/minion/minion @@ -0,0 +1,4 @@ +#!/usr/bin/env php + /dev/null 2>&1 + then + start_daemon + fi +done \ No newline at end of file diff --git a/modules/minion/tests/minion/task.php b/modules/minion/tests/minion/task.php new file mode 100644 index 0000000..e7918a0 --- /dev/null +++ b/modules/minion/tests/minion/task.php @@ -0,0 +1,70 @@ +assertSame($expected, Minion_Task::convert_task_to_class_name($task_name)); + } + + /** + * Provides test data for test_convert_class_to_task() + * + * @return array + */ + public function provider_convert_class_to_task() + { + return array( + array('db:migrate', 'Task_Db_Migrate'), + ); + } + + /** + * Tests that the task name can be found from a class name / object + * + * @test + * @covers Minion_Task::convert_class_to_task + * @dataProvider provider_convert_class_to_task + * @param string Expected task name + * @param mixed Input class + */ + public function test_convert_class_to_task($expected, $class) + { + $this->assertSame($expected, Minion_Task::convert_class_to_task($class)); + } +} diff --git a/modules/minion/views/minion/error/validation.php b/modules/minion/views/minion/error/validation.php new file mode 100644 index 0000000..a65758a --- /dev/null +++ b/modules/minion/views/minion/error/validation.php @@ -0,0 +1,10 @@ +Parameter Errors: + $error): ?> + - + + +Run + + php index.php --task= --help + +for more help \ No newline at end of file diff --git a/modules/minion/views/minion/help/error.php b/modules/minion/views/minion/help/error.php new file mode 100644 index 0000000..504115d --- /dev/null +++ b/modules/minion/views/minion/help/error.php @@ -0,0 +1,7 @@ + + +Run + + index.php --uri=minion + +for more help diff --git a/modules/minion/views/minion/help/list.php b/modules/minion/views/minion/help/list.php new file mode 100644 index 0000000..eeb06ef --- /dev/null +++ b/modules/minion/views/minion/help/list.php @@ -0,0 +1,17 @@ +Minion is a cli tool for performing tasks + +Usage + + {task} --task=[options] + +Where {task} is one of the following: + + + * + + + +For more information on what a task does and usage details execute + + --task={task} --help + diff --git a/modules/minion/views/minion/help/task.php b/modules/minion/views/minion/help/task.php new file mode 100644 index 0000000..8f2fcd7 --- /dev/null +++ b/modules/minion/views/minion/help/task.php @@ -0,0 +1,17 @@ + +Usage +======= +php minion.php --task= [--option1=value1] [--option2=value2] + +Details +======= + $tag_content): ?> +: + + + +Description +=========== + + + diff --git a/modules/orm/auth-schema-mysql.sql b/modules/orm/auth-schema-mysql.sql new file mode 100644 index 0000000..61a803a --- /dev/null +++ b/modules/orm/auth-schema-mysql.sql @@ -0,0 +1,49 @@ +CREATE TABLE IF NOT EXISTS `roles` ( + `id` int(11) UNSIGNED NOT NULL AUTO_INCREMENT, + `name` varchar(32) NOT NULL, + `description` varchar(255) NOT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `uniq_name` (`name`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +INSERT INTO `roles` (`id`, `name`, `description`) VALUES(1, 'login', 'Login privileges, granted after account confirmation'); +INSERT INTO `roles` (`id`, `name`, `description`) VALUES(2, 'admin', 'Administrative user, has access to everything.'); + +CREATE TABLE IF NOT EXISTS `roles_users` ( + `user_id` int(10) UNSIGNED NOT NULL, + `role_id` int(10) UNSIGNED NOT NULL, + PRIMARY KEY (`user_id`,`role_id`), + KEY `fk_role_id` (`role_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +CREATE TABLE IF NOT EXISTS `users` ( + `id` int(11) UNSIGNED NOT NULL AUTO_INCREMENT, + `email` varchar(254) NOT NULL, + `username` varchar(32) NOT NULL DEFAULT '', + `password` varchar(64) NOT NULL, + `logins` int(10) UNSIGNED NOT NULL DEFAULT '0', + `last_login` int(10) UNSIGNED, + PRIMARY KEY (`id`), + UNIQUE KEY `uniq_username` (`username`), + UNIQUE KEY `uniq_email` (`email`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +CREATE TABLE IF NOT EXISTS `user_tokens` ( + `id` int(11) UNSIGNED NOT NULL AUTO_INCREMENT, + `user_id` int(11) UNSIGNED NOT NULL, + `user_agent` varchar(40) NOT NULL, + `token` varchar(40) NOT NULL, + `created` int(10) UNSIGNED NOT NULL, + `expires` int(10) UNSIGNED NOT NULL, + PRIMARY KEY (`id`), + UNIQUE KEY `uniq_token` (`token`), + KEY `fk_user_id` (`user_id`), + KEY `expires` (`expires`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8; + +ALTER TABLE `roles_users` + ADD CONSTRAINT `roles_users_ibfk_1` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE, + ADD CONSTRAINT `roles_users_ibfk_2` FOREIGN KEY (`role_id`) REFERENCES `roles` (`id`) ON DELETE CASCADE; + +ALTER TABLE `user_tokens` + ADD CONSTRAINT `user_tokens_ibfk_1` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE; diff --git a/modules/orm/auth-schema-postgresql.sql b/modules/orm/auth-schema-postgresql.sql new file mode 100644 index 0000000..ce82ed1 --- /dev/null +++ b/modules/orm/auth-schema-postgresql.sql @@ -0,0 +1,53 @@ +CREATE TABLE roles +( + id serial, + "name" varchar(32) NOT NULL, + description text NOT NULL, + CONSTRAINT roles_id_pkey PRIMARY KEY (id), + CONSTRAINT roles_name_key UNIQUE (name) +); + +CREATE TABLE roles_users +( + user_id integer, + role_id integer +); + +CREATE TABLE users +( + id serial, + email varchar(254) NOT NULL, + username varchar(32) NOT NULL, + "password" varchar(64) NOT NULL, + logins integer NOT NULL DEFAULT 0, + last_login integer, + CONSTRAINT users_id_pkey PRIMARY KEY (id), + CONSTRAINT users_username_key UNIQUE (username), + CONSTRAINT users_email_key UNIQUE (email), + CONSTRAINT users_logins_check CHECK (logins >= 0) +); + +CREATE TABLE user_tokens +( + id serial, + user_id integer NOT NULL, + user_agent varchar(40) NOT NULL, + token character varying(32) NOT NULL, + created integer NOT NULL, + expires integer NOT NULL, + CONSTRAINT user_tokens_id_pkey PRIMARY KEY (id), + CONSTRAINT user_tokens_token_key UNIQUE (token) +); + +CREATE INDEX user_id_idx ON roles_users (user_id); +CREATE INDEX role_id_idx ON roles_users (role_id); + +ALTER TABLE roles_users + ADD CONSTRAINT user_id_fkey FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE, + ADD CONSTRAINT role_id_fkey FOREIGN KEY (role_id) REFERENCES roles(id) ON DELETE CASCADE; + +ALTER TABLE user_tokens + ADD CONSTRAINT user_id_fkey FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE; + +INSERT INTO roles (name, description) VALUES ('login', 'Login privileges, granted after account confirmation'); +INSERT INTO roles (name, description) VALUES ('admin', 'Administrative user, has access to everything.'); diff --git a/modules/orm/classes/Auth/ORM.php b/modules/orm/classes/Auth/ORM.php new file mode 100644 index 0000000..590bef1 --- /dev/null +++ b/modules/orm/classes/Auth/ORM.php @@ -0,0 +1,3 @@ +get_user(); + + if ( ! $user) + return FALSE; + + if ($user instanceof Model_User AND $user->loaded()) + { + // If we don't have a roll no further checking is needed + if ( ! $role) + return TRUE; + + if (is_array($role)) + { + // Get all the roles + $roles = ORM::factory('Role') + ->where('name', 'IN', $role) + ->find_all() + ->as_array(NULL, 'id'); + + // Make sure all the roles are valid ones + if (count($roles) !== count($role)) + return FALSE; + } + else + { + if ( ! is_object($role)) + { + // Load the role + $roles = ORM::factory('Role', array('name' => $role)); + + if ( ! $roles->loaded()) + return FALSE; + } + } + + return $user->has('roles', $roles); + } + } + + /** + * Logs a user in. + * + * @param string $username + * @param string $password + * @param boolean $remember enable autologin + * @return boolean + */ + protected function _login($user, $password, $remember) + { + if ( ! is_object($user)) + { + $username = $user; + + // Load the user + $user = ORM::factory('User'); + $user->where($user->unique_key($username), '=', $username)->find(); + } + + if (is_string($password)) + { + // Create a hashed password + $password = $this->hash($password); + } + + // If the passwords match, perform a login + if ($user->has('roles', ORM::factory('Role', array('name' => 'login'))) AND $user->password === $password) + { + if ($remember === TRUE) + { + // Token data + $data = array( + 'user_id' => $user->pk(), + 'expires' => time() + $this->_config['lifetime'], + 'user_agent' => sha1(Request::$user_agent), + ); + + // Create a new autologin token + $token = ORM::factory('User_Token') + ->values($data) + ->create(); + + // Set the autologin cookie + Cookie::set('authautologin', $token->token, $this->_config['lifetime']); + } + + // Finish the login + $this->complete_login($user); + + return TRUE; + } + + // Login failed + return FALSE; + } + + /** + * Forces a user to be logged in, without specifying a password. + * + * @param mixed $user username string, or user ORM object + * @param boolean $mark_session_as_forced mark the session as forced + * @return boolean + */ + public function force_login($user, $mark_session_as_forced = FALSE) + { + if ( ! is_object($user)) + { + $username = $user; + + // Load the user + $user = ORM::factory('User'); + $user->where($user->unique_key($username), '=', $username)->find(); + } + + if ($mark_session_as_forced === TRUE) + { + // Mark the session as forced, to prevent users from changing account information + $this->_session->set('auth_forced', TRUE); + } + + // Run the standard completion + $this->complete_login($user); + } + + /** + * Logs a user in, based on the authautologin cookie. + * + * @return mixed + */ + public function auto_login() + { + if ($token = Cookie::get('authautologin')) + { + // Load the token and user + $token = ORM::factory('User_Token', array('token' => $token)); + + if ($token->loaded() AND $token->user->loaded()) + { + if ($token->user_agent === sha1(Request::$user_agent)) + { + // Save the token to create a new unique token + $token->save(); + + // Set the new token + Cookie::set('authautologin', $token->token, $token->expires - time()); + + // Complete the login with the found data + $this->complete_login($token->user); + + // Automatic login was successful + return $token->user; + } + + // Token is invalid + $token->delete(); + } + } + + return FALSE; + } + + /** + * Gets the currently logged in user from the session (with auto_login check). + * Returns $default if no user is currently logged in. + * + * @param mixed $default to return in case user isn't logged in + * @return mixed + */ + public function get_user($default = NULL) + { + $user = parent::get_user($default); + + if ($user === $default) + { + // check for "remembered" login + if (($user = $this->auto_login()) === FALSE) + return $default; + } + + return $user; + } + + /** + * Log a user out and remove any autologin cookies. + * + * @param boolean $destroy completely destroy the session + * @param boolean $logout_all remove all tokens for user + * @return boolean + */ + public function logout($destroy = FALSE, $logout_all = FALSE) + { + // Set by force_login() + $this->_session->delete('auth_forced'); + + if ($token = Cookie::get('authautologin')) + { + // Delete the autologin cookie to prevent re-login + Cookie::delete('authautologin'); + + // Clear the autologin token from the database + $token = ORM::factory('User_Token', array('token' => $token)); + + if ($token->loaded() AND $logout_all) + { + // Delete all user tokens. This isn't the most elegant solution but does the job + $tokens = ORM::factory('User_Token')->where('user_id','=',$token->user_id)->find_all(); + + foreach ($tokens as $_token) + { + $_token->delete(); + } + } + elseif ($token->loaded()) + { + $token->delete(); + } + } + + return parent::logout($destroy); + } + + /** + * Get the stored password for a username. + * + * @param mixed $user username string, or user ORM object + * @return string + */ + public function password($user) + { + if ( ! is_object($user)) + { + $username = $user; + + // Load the user + $user = ORM::factory('User'); + $user->where($user->unique_key($username), '=', $username)->find(); + } + + return $user->password; + } + + /** + * Complete the login for a user by incrementing the logins and setting + * session data: user_id, username, roles. + * + * @param object $user user ORM object + * @return void + */ + protected function complete_login($user) + { + $user->complete_login(); + + return parent::complete_login($user); + } + + /** + * Compare password with original (hashed). Works for current (logged in) user + * + * @param string $password + * @return boolean + */ + public function check_password($password) + { + $user = $this->get_user(); + + if ( ! $user) + return FALSE; + + return ($this->hash($password) === $user->password); + } + +} // End Auth ORM diff --git a/modules/orm/classes/Kohana/ORM.php b/modules/orm/classes/Kohana/ORM.php new file mode 100644 index 0000000..716e51d --- /dev/null +++ b/modules/orm/classes/Kohana/ORM.php @@ -0,0 +1,2354 @@ +_initialize(); + + if ($id !== NULL) + { + if (is_array($id)) + { + foreach ($id as $column => $value) + { + // Passing an array of column => values + $this->where($column, '=', $value); + } + + $this->find(); + } + else + { + // Passing the primary key + $this->where($this->_object_name.'.'.$this->_primary_key, '=', $id)->find(); + } + } + elseif ( ! empty($this->_cast_data)) + { + // Load preloaded data from a database call cast + $this->_load_values($this->_cast_data); + + $this->_cast_data = array(); + } + } + + /** + * Prepares the model database connection, determines the table name, + * and loads column information. + * + * @return void + */ + protected function _initialize() + { + // Set the object name and plural name + $this->_object_name = strtolower(substr(get_class($this), 6)); + + // Check if this model has already been initialized + if ( ! $init = Arr::get(ORM::$_init_cache, $this->_object_name, FALSE)) + { + $init = array( + '_belongs_to' => array(), + '_has_one' => array(), + '_has_many' => array(), + ); + + // Set the object plural name if none predefined + if ( ! isset($this->_object_plural)) + { + $init['_object_plural'] = Inflector::plural($this->_object_name); + } + + if ( ! $this->_errors_filename) + { + $init['_errors_filename'] = $this->_object_name; + } + + if ( ! is_object($this->_db)) + { + // Get database instance + $init['_db'] = Database::instance($this->_db_group); + } + + if (empty($this->_table_name)) + { + // Table name is the same as the object name + $init['_table_name'] = $this->_object_name; + + if ($this->_table_names_plural === TRUE) + { + // Make the table name plural + $init['_table_name'] = Arr::get($init, '_object_plural', $this->_object_plural); + } + } + + $defaults = array(); + + foreach ($this->_belongs_to as $alias => $details) + { + if ( ! isset($details['model'])) + { + $defaults['model'] = str_replace(' ', '_', ucwords(str_replace('_', ' ', $alias))); + } + + $defaults['foreign_key'] = $alias.$this->_foreign_key_suffix; + + $init['_belongs_to'][$alias] = array_merge($defaults, $details); + } + + foreach ($this->_has_one as $alias => $details) + { + if ( ! isset($details['model'])) + { + $defaults['model'] = str_replace(' ', '_', ucwords(str_replace('_', ' ', $alias))); + } + + $defaults['foreign_key'] = $this->_object_name.$this->_foreign_key_suffix; + + $init['_has_one'][$alias] = array_merge($defaults, $details); + } + + foreach ($this->_has_many as $alias => $details) + { + if ( ! isset($details['model'])) + { + $defaults['model'] = str_replace(' ', '_', ucwords(str_replace('_', ' ', Inflector::singular($alias)))); + } + + $defaults['foreign_key'] = $this->_object_name.$this->_foreign_key_suffix; + $defaults['through'] = NULL; + + if ( ! isset($details['far_key'])) + { + $defaults['far_key'] = Inflector::singular($alias).$this->_foreign_key_suffix; + } + + $init['_has_many'][$alias] = array_merge($defaults, $details); + } + + ORM::$_init_cache[$this->_object_name] = $init; + } + + // Assign initialized properties to the current object + foreach ($init as $property => $value) + { + $this->{$property} = $value; + } + + // Load column information + $this->reload_columns(); + + // Clear initial model state + $this->clear(); + } + + /** + * Initializes validation rules, and labels + * + * @return void + */ + protected function _validation() + { + // Build the validation object with its rules + $this->_validation = Validation::factory($this->_object) + ->bind(':model', $this) + ->bind(':original_values', $this->_original_values) + ->bind(':changed', $this->_changed); + + foreach ($this->rules() as $field => $rules) + { + $this->_validation->rules($field, $rules); + } + + // Use column names by default for labels + $columns = array_keys($this->_table_columns); + + // Merge user-defined labels + $labels = array_merge(array_combine($columns, $columns), $this->labels()); + + foreach ($labels as $field => $label) + { + $this->_validation->label($field, $label); + } + } + + /** + * Reload column definitions. + * + * @chainable + * @param boolean $force Force reloading + * @return ORM + */ + public function reload_columns($force = FALSE) + { + if ($force === TRUE OR empty($this->_table_columns)) + { + if (isset(ORM::$_column_cache[$this->_object_name])) + { + // Use cached column information + $this->_table_columns = ORM::$_column_cache[$this->_object_name]; + } + else + { + // Grab column information from database + $this->_table_columns = $this->list_columns(); + + // Load column cache + ORM::$_column_cache[$this->_object_name] = $this->_table_columns; + } + } + + return $this; + } + + /** + * Unloads the current object and clears the status. + * + * @chainable + * @return ORM + */ + public function clear() + { + // Create an array with all the columns set to NULL + $values = array_combine(array_keys($this->_table_columns), array_fill(0, count($this->_table_columns), NULL)); + + // Replace the object and reset the object status + $this->_object = $this->_changed = $this->_related = $this->_original_values = array(); + + // Replace the current object with an empty one + $this->_load_values($values); + + // Reset primary key + $this->_primary_key_value = NULL; + + // Reset the loaded state + $this->_loaded = FALSE; + + $this->reset(); + + return $this; + } + + /** + * Reloads the current object from the database. + * + * @chainable + * @return ORM + */ + public function reload() + { + $primary_key = $this->pk(); + + // Replace the object and reset the object status + $this->_object = $this->_changed = $this->_related = $this->_original_values = array(); + + // Only reload the object if we have one to reload + if ($this->_loaded) + return $this->clear() + ->where($this->_object_name.'.'.$this->_primary_key, '=', $primary_key) + ->find(); + else + return $this->clear(); + } + + /** + * Checks if object data is set. + * + * @param string $column Column name + * @return boolean + */ + public function __isset($column) + { + return (isset($this->_object[$column]) OR + isset($this->_related[$column]) OR + isset($this->_has_one[$column]) OR + isset($this->_belongs_to[$column]) OR + isset($this->_has_many[$column])); + } + + /** + * Unsets object data. + * + * @param string $column Column name + * @return void + */ + public function __unset($column) + { + unset($this->_object[$column], $this->_changed[$column], $this->_related[$column]); + } + + /** + * Displays the primary key of a model when it is converted to a string. + * + * @return string + */ + public function __toString() + { + return (string) $this->pk(); + } + + /** + * Allows serialization of only the object data and state, to prevent + * "stale" objects being unserialized, which also requires less memory. + * + * @return string + */ + public function serialize() + { + // Store only information about the object + foreach (array('_primary_key_value', '_object', '_changed', '_loaded', '_saved', '_sorting', '_original_values') as $var) + { + $data[$var] = $this->{$var}; + } + + return serialize($data); + } + + /** + * Check whether the model data has been modified. + * If $field is specified, checks whether that field was modified. + * + * @param string $field field to check for changes + * @return bool Whether or not the field has changed + */ + public function changed($field = NULL) + { + return ($field === NULL) + ? $this->_changed + : Arr::get($this->_changed, $field); + } + + /** + * Prepares the database connection and reloads the object. + * + * @param string $data String for unserialization + * @return void + */ + public function unserialize($data) + { + // Initialize model + $this->_initialize(); + + foreach (unserialize($data) as $name => $var) + { + $this->{$name} = $var; + } + + if ($this->_reload_on_wakeup === TRUE) + { + // Reload the object + $this->reload(); + } + } + + /** + * Handles retrieval of all model values, relationships, and metadata. + * [!!] This should not be overridden. + * + * @param string $column Column name + * @return mixed + */ + public function __get($column) + { + return $this->get($column); + } + + /** + * Handles getting of column + * Override this method to add custom get behavior + * + * @param string $column Column name + * @throws Kohana_Exception + * @return mixed + */ + public function get($column) + { + if (array_key_exists($column, $this->_object)) + { + return (in_array($column, $this->_serialize_columns)) + ? $this->_unserialize_value($this->_object[$column]) + : $this->_object[$column]; + } + elseif (isset($this->_related[$column])) + { + // Return related model that has already been fetched + return $this->_related[$column]; + } + elseif (isset($this->_belongs_to[$column])) + { + $model = $this->_related($column); + + // Use this model's column and foreign model's primary key + $col = $model->_object_name.'.'.$model->_primary_key; + $val = $this->_object[$this->_belongs_to[$column]['foreign_key']]; + + // Make sure we don't run WHERE "AUTO_INCREMENT column" = NULL queries. This would + // return the last inserted record instead of an empty result. + // See: http://mysql.localhost.net.ar/doc/refman/5.1/en/server-session-variables.html#sysvar_sql_auto_is_null + if ($val !== NULL) + { + $model->where($col, '=', $val)->find(); + } + + return $this->_related[$column] = $model; + } + elseif (isset($this->_has_one[$column])) + { + $model = $this->_related($column); + + // Use this model's primary key value and foreign model's column + $col = $model->_object_name.'.'.$this->_has_one[$column]['foreign_key']; + $val = $this->pk(); + + $model->where($col, '=', $val)->find(); + + return $this->_related[$column] = $model; + } + elseif (isset($this->_has_many[$column])) + { + $model = ORM::factory($this->_has_many[$column]['model']); + + if (isset($this->_has_many[$column]['through'])) + { + // Grab has_many "through" relationship table + $through = $this->_has_many[$column]['through']; + + // Join on through model's target foreign key (far_key) and target model's primary key + $join_col1 = $through.'.'.$this->_has_many[$column]['far_key']; + $join_col2 = $model->_object_name.'.'.$model->_primary_key; + + $model->join($through)->on($join_col1, '=', $join_col2); + + // Through table's source foreign key (foreign_key) should be this model's primary key + $col = $through.'.'.$this->_has_many[$column]['foreign_key']; + $val = $this->pk(); + } + else + { + // Simple has_many relationship, search where target model's foreign key is this model's primary key + $col = $model->_object_name.'.'.$this->_has_many[$column]['foreign_key']; + $val = $this->pk(); + } + + return $model->where($col, '=', $val); + } + else + { + throw new Kohana_Exception('The :property property does not exist in the :class class', + array(':property' => $column, ':class' => get_class($this))); + } + } + + /** + * Base set method. + * [!!] This should not be overridden. + * + * @param string $column Column name + * @param mixed $value Column value + * @return void + */ + public function __set($column, $value) + { + $this->set($column, $value); + } + + /** + * Handles setting of columns + * Override this method to add custom set behavior + * + * @param string $column Column name + * @param mixed $value Column value + * @throws Kohana_Exception + * @return ORM + */ + public function set($column, $value) + { + if ( ! isset($this->_object_name)) + { + // Object not yet constructed, so we're loading data from a database call cast + $this->_cast_data[$column] = $value; + + return $this; + } + + if (in_array($column, $this->_serialize_columns)) + { + $value = $this->_serialize_value($value); + } + + if (array_key_exists($column, $this->_object)) + { + // Filter the data + $value = $this->run_filter($column, $value); + + // See if the data really changed + if ($value !== $this->_object[$column]) + { + $this->_object[$column] = $value; + + // Data has changed + $this->_changed[$column] = $column; + + // Object is no longer saved or valid + $this->_saved = $this->_valid = FALSE; + } + } + elseif (isset($this->_belongs_to[$column])) + { + // Update related object itself + $this->_related[$column] = $value; + + // Update the foreign key of this model + $this->_object[$this->_belongs_to[$column]['foreign_key']] = ($value instanceof ORM) + ? $value->pk() + : NULL; + + $this->_changed[$column] = $this->_belongs_to[$column]['foreign_key']; + } + else + { + throw new Kohana_Exception('The :property: property does not exist in the :class: class', + array(':property:' => $column, ':class:' => get_class($this))); + } + + return $this; + } + + /** + * Set values from an array with support for one-one relationships. This method should be used + * for loading in post data, etc. + * + * @param array $values Array of column => val + * @param array $expected Array of keys to take from $values + * @return ORM + */ + public function values(array $values, array $expected = NULL) + { + // Default to expecting everything except the primary key + if ($expected === NULL) + { + $expected = array_keys($this->_table_columns); + + // Don't set the primary key by default + unset($values[$this->_primary_key]); + } + + foreach ($expected as $key => $column) + { + if (is_string($key)) + { + // isset() fails when the value is NULL (we want it to pass) + if ( ! array_key_exists($key, $values)) + continue; + + // Try to set values to a related model + $this->{$key}->values($values[$key], $column); + } + else + { + // isset() fails when the value is NULL (we want it to pass) + if ( ! array_key_exists($column, $values)) + continue; + + // Update the column, respects __set() + $this->$column = $values[$column]; + } + } + + return $this; + } + + /** + * Returns the values of this object as an array, including any related one-one + * models that have already been loaded using with() + * + * @return array + */ + public function as_array() + { + $object = array(); + + foreach ($this->_object as $column => $value) + { + // Call __get for any user processing + $object[$column] = $this->__get($column); + } + + foreach ($this->_related as $column => $model) + { + // Include any related objects that are already loaded + $object[$column] = $model->as_array(); + } + + return $object; + } + + /** + * Binds another one-to-one object to this model. One-to-one objects + * can be nested using 'object1:object2' syntax + * + * @param string $target_path Target model to bind to + * @return ORM + */ + public function with($target_path) + { + if (isset($this->_with_applied[$target_path])) + { + // Don't join anything already joined + return $this; + } + + // Split object parts + $aliases = explode(':', $target_path); + $target = $this; + foreach ($aliases as $alias) + { + // Go down the line of objects to find the given target + $parent = $target; + $target = $parent->_related($alias); + + if ( ! $target) + { + // Can't find related object + return $this; + } + } + + // Target alias is at the end + $target_alias = $alias; + + // Pop-off top alias to get the parent path (user:photo:tag becomes user:photo - the parent table prefix) + array_pop($aliases); + $parent_path = implode(':', $aliases); + + if (empty($parent_path)) + { + // Use this table name itself for the parent path + $parent_path = $this->_object_name; + } + else + { + if ( ! isset($this->_with_applied[$parent_path])) + { + // If the parent path hasn't been joined yet, do it first (otherwise LEFT JOINs fail) + $this->with($parent_path); + } + } + + // Add to with_applied to prevent duplicate joins + $this->_with_applied[$target_path] = TRUE; + + // Use the keys of the empty object to determine the columns + foreach (array_keys($target->_object) as $column) + { + $name = $target_path.'.'.$column; + $alias = $target_path.':'.$column; + + // Add the prefix so that load_result can determine the relationship + $this->select(array($name, $alias)); + } + + if (isset($parent->_belongs_to[$target_alias])) + { + // Parent belongs_to target, use target's primary key and parent's foreign key + $join_col1 = $target_path.'.'.$target->_primary_key; + $join_col2 = $parent_path.'.'.$parent->_belongs_to[$target_alias]['foreign_key']; + } + else + { + // Parent has_one target, use parent's primary key as target's foreign key + $join_col1 = $parent_path.'.'.$parent->_primary_key; + $join_col2 = $target_path.'.'.$parent->_has_one[$target_alias]['foreign_key']; + } + + // Join the related object into the result + $this->join(array($target->_table_name, $target_path), 'LEFT')->on($join_col1, '=', $join_col2); + + return $this; + } + + /** + * Initializes the Database Builder to given query type + * + * @param integer $type Type of Database query + * @return ORM + */ + protected function _build($type) + { + // Construct new builder object based on query type + switch ($type) + { + case Database::SELECT: + $this->_db_builder = DB::select(); + break; + case Database::UPDATE: + $this->_db_builder = DB::update(array($this->_table_name, $this->_object_name)); + break; + case Database::DELETE: + // Cannot use an alias for DELETE queries + $this->_db_builder = DB::delete($this->_table_name); + } + + // Process pending database method calls + foreach ($this->_db_pending as $method) + { + $name = $method['name']; + $args = $method['args']; + + $this->_db_applied[$name] = $name; + + call_user_func_array(array($this->_db_builder, $name), $args); + } + + return $this; + } + + /** + * Finds and loads a single database row into the object. + * + * @chainable + * @throws Kohana_Exception + * @return ORM + */ + public function find() + { + if ($this->_loaded) + throw new Kohana_Exception('Method find() cannot be called on loaded objects'); + + if ( ! empty($this->_load_with)) + { + foreach ($this->_load_with as $alias) + { + // Bind auto relationships + $this->with($alias); + } + } + + $this->_build(Database::SELECT); + + return $this->_load_result(FALSE); + } + + /** + * Finds multiple database rows and returns an iterator of the rows found. + * + * @throws Kohana_Exception + * @return Database_Result + */ + public function find_all() + { + if ($this->_loaded) + throw new Kohana_Exception('Method find_all() cannot be called on loaded objects'); + + if ( ! empty($this->_load_with)) + { + foreach ($this->_load_with as $alias) + { + // Bind auto relationships + $this->with($alias); + } + } + + $this->_build(Database::SELECT); + + return $this->_load_result(TRUE); + } + + /** + * Returns an array of columns to include in the select query. This method + * can be overridden to change the default select behavior. + * + * @return array Columns to select + */ + protected function _build_select() + { + $columns = array(); + + foreach ($this->_table_columns as $column => $_) + { + $columns[] = array($this->_object_name.'.'.$column, $column); + } + + return $columns; + } + + /** + * Loads a database result, either as a new record for this model, or as + * an iterator for multiple rows. + * + * @chainable + * @param bool $multiple Return an iterator or load a single row + * @return ORM|Database_Result + */ + protected function _load_result($multiple = FALSE) + { + $this->_db_builder->from(array($this->_table_name, $this->_object_name)); + + if ($multiple === FALSE) + { + // Only fetch 1 record + $this->_db_builder->limit(1); + } + + // Select all columns by default + $this->_db_builder->select_array($this->_build_select()); + + if ( ! isset($this->_db_applied['order_by']) AND ! empty($this->_sorting)) + { + foreach ($this->_sorting as $column => $direction) + { + if (strpos($column, '.') === FALSE) + { + // Sorting column for use in JOINs + $column = $this->_object_name.'.'.$column; + } + + $this->_db_builder->order_by($column, $direction); + } + } + + if ($multiple === TRUE) + { + // Return database iterator casting to this object type + $result = $this->_db_builder->as_object(get_class($this))->execute($this->_db); + + $this->reset(); + + return $result; + } + else + { + // Load the result as an associative array + $result = $this->_db_builder->as_assoc()->execute($this->_db); + + $this->reset(); + + if ($result->count() === 1) + { + // Load object values + $this->_load_values($result->current()); + } + else + { + // Clear the object, nothing was found + $this->clear(); + } + + return $this; + } + } + + /** + * Loads an array of values into into the current object. + * + * @chainable + * @param array $values Values to load + * @return ORM + */ + protected function _load_values(array $values) + { + if (array_key_exists($this->_primary_key, $values)) + { + if ($values[$this->_primary_key] !== NULL) + { + // Flag as loaded and valid + $this->_loaded = $this->_valid = TRUE; + + // Store primary key + $this->_primary_key_value = $values[$this->_primary_key]; + } + else + { + // Not loaded or valid + $this->_loaded = $this->_valid = FALSE; + } + } + + // Related objects + $related = array(); + + foreach ($values as $column => $value) + { + if (strpos($column, ':') === FALSE) + { + // Load the value to this model + $this->_object[$column] = $value; + } + else + { + // Column belongs to a related model + list ($prefix, $column) = explode(':', $column, 2); + + $related[$prefix][$column] = $value; + } + } + + if ( ! empty($related)) + { + foreach ($related as $object => $values) + { + // Load the related objects with the values in the result + $this->_related($object)->_load_values($values); + } + } + + if ($this->_loaded) + { + // Store the object in its original state + $this->_original_values = $this->_object; + } + + return $this; + } + + /** + * Rule definitions for validation + * + * @return array + */ + public function rules() + { + return array(); + } + + /** + * Filters a value for a specific column + * + * @param string $field The column name + * @param string $value The value to filter + * @return string + */ + protected function run_filter($field, $value) + { + $filters = $this->filters(); + + // Get the filters for this column + $wildcards = empty($filters[TRUE]) ? array() : $filters[TRUE]; + + // Merge in the wildcards + $filters = empty($filters[$field]) ? $wildcards : array_merge($wildcards, $filters[$field]); + + // Bind the field name and model so they can be used in the filter method + $_bound = array + ( + ':field' => $field, + ':model' => $this, + ); + + foreach ($filters as $array) + { + // Value needs to be bound inside the loop so we are always using the + // version that was modified by the filters that already ran + $_bound[':value'] = $value; + + // Filters are defined as array($filter, $params) + $filter = $array[0]; + $params = Arr::get($array, 1, array(':value')); + + foreach ($params as $key => $param) + { + if (is_string($param) AND array_key_exists($param, $_bound)) + { + // Replace with bound value + $params[$key] = $_bound[$param]; + } + } + + if (is_array($filter) OR ! is_string($filter)) + { + // This is either a callback as an array or a lambda + $value = call_user_func_array($filter, $params); + } + elseif (strpos($filter, '::') === FALSE) + { + // Use a function call + $function = new ReflectionFunction($filter); + + // Call $function($this[$field], $param, ...) with Reflection + $value = $function->invokeArgs($params); + } + else + { + // Split the class and method of the rule + list($class, $method) = explode('::', $filter, 2); + + // Use a static method call + $method = new ReflectionMethod($class, $method); + + // Call $Class::$method($this[$field], $param, ...) with Reflection + $value = $method->invokeArgs(NULL, $params); + } + } + + return $value; + } + + /** + * Filter definitions for validation + * + * @return array + */ + public function filters() + { + return array(); + } + + /** + * Label definitions for validation + * + * @return array + */ + public function labels() + { + return array(); + } + + /** + * Validates the current model's data + * + * @param Validation $extra_validation Validation object + * @throws ORM_Validation_Exception + * @return ORM + */ + public function check(Validation $extra_validation = NULL) + { + // Determine if any external validation failed + $extra_errors = ($extra_validation AND ! $extra_validation->check()); + + // Always build a new validation object + $this->_validation(); + + $array = $this->_validation; + + if (($this->_valid = $array->check()) === FALSE OR $extra_errors) + { + $exception = new ORM_Validation_Exception($this->errors_filename(), $array); + + if ($extra_errors) + { + // Merge any possible errors from the external object + $exception->add_object('_external', $extra_validation); + } + throw $exception; + } + + return $this; + } + + /** + * Insert a new object to the database + * @param Validation $validation Validation object + * @throws Kohana_Exception + * @return ORM + */ + public function create(Validation $validation = NULL) + { + if ($this->_loaded) + throw new Kohana_Exception('Cannot create :model model because it is already loaded.', array(':model' => $this->_object_name)); + + // Require model validation before saving + if ( ! $this->_valid OR $validation) + { + $this->check($validation); + } + + $data = array(); + foreach ($this->_changed as $column) + { + // Generate list of column => values + $data[$column] = $this->_object[$column]; + } + + if (is_array($this->_created_column)) + { + // Fill the created column + $column = $this->_created_column['column']; + $format = $this->_created_column['format']; + + $data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format); + } + + $result = DB::insert($this->_table_name) + ->columns(array_keys($data)) + ->values(array_values($data)) + ->execute($this->_db); + + if ( ! array_key_exists($this->_primary_key, $data)) + { + // Load the insert id as the primary key if it was left out + $this->_object[$this->_primary_key] = $this->_primary_key_value = $result[0]; + } + else + { + $this->_primary_key_value = $this->_object[$this->_primary_key]; + } + + // Object is now loaded and saved + $this->_loaded = $this->_saved = TRUE; + + // All changes have been saved + $this->_changed = array(); + $this->_original_values = $this->_object; + + return $this; + } + + /** + * Updates a single record or multiple records + * + * @chainable + * @param Validation $validation Validation object + * @throws Kohana_Exception + * @return ORM + */ + public function update(Validation $validation = NULL) + { + if ( ! $this->_loaded) + throw new Kohana_Exception('Cannot update :model model because it is not loaded.', array(':model' => $this->_object_name)); + + // Run validation if the model isn't valid or we have additional validation rules. + if ( ! $this->_valid OR $validation) + { + $this->check($validation); + } + + if (empty($this->_changed)) + { + // Nothing to update + return $this; + } + + $data = array(); + foreach ($this->_changed as $column) + { + // Compile changed data + $data[$column] = $this->_object[$column]; + } + + if (is_array($this->_updated_column)) + { + // Fill the updated column + $column = $this->_updated_column['column']; + $format = $this->_updated_column['format']; + + $data[$column] = $this->_object[$column] = ($format === TRUE) ? time() : date($format); + } + + // Use primary key value + $id = $this->pk(); + + // Update a single record + DB::update($this->_table_name) + ->set($data) + ->where($this->_primary_key, '=', $id) + ->execute($this->_db); + + if (isset($data[$this->_primary_key])) + { + // Primary key was changed, reflect it + $this->_primary_key_value = $data[$this->_primary_key]; + } + + // Object has been saved + $this->_saved = TRUE; + + // All changes have been saved + $this->_changed = array(); + $this->_original_values = $this->_object; + + return $this; + } + + /** + * Updates or Creates the record depending on loaded() + * + * @chainable + * @param Validation $validation Validation object + * @return ORM + */ + public function save(Validation $validation = NULL) + { + return $this->loaded() ? $this->update($validation) : $this->create($validation); + } + + /** + * Deletes a single record while ignoring relationships. + * + * @chainable + * @throws Kohana_Exception + * @return ORM + */ + public function delete() + { + if ( ! $this->_loaded) + throw new Kohana_Exception('Cannot delete :model model because it is not loaded.', array(':model' => $this->_object_name)); + + // Use primary key value + $id = $this->pk(); + + // Delete the object + DB::delete($this->_table_name) + ->where($this->_primary_key, '=', $id) + ->execute($this->_db); + + return $this->clear(); + } + + /** + * Tests if this object has a relationship to a different model, + * or an array of different models. When providing far keys, the number + * of relations must equal the number of keys. + * + * + * // Check if $model has the login role + * $model->has('roles', ORM::factory('role', array('name' => 'login'))); + * // Check for the login role if you know the roles.id is 5 + * $model->has('roles', 5); + * // Check for all of the following roles + * $model->has('roles', array(1, 2, 3, 4)); + * // Check if $model has any roles + * $model->has('roles') + * + * @param string $alias Alias of the has_many "through" relationship + * @param mixed $far_keys Related model, primary key, or an array of primary keys + * @return boolean + */ + public function has($alias, $far_keys = NULL) + { + $count = $this->count_relations($alias, $far_keys); + if ($far_keys === NULL) + { + return (bool) $count; + } + else + { + return $count === count($far_keys); + } + + } + + /** + * Tests if this object has a relationship to a different model, + * or an array of different models. When providing far keys, this function + * only checks that at least one of the relationships is satisfied. + * + * // Check if $model has the login role + * $model->has('roles', ORM::factory('role', array('name' => 'login'))); + * // Check for the login role if you know the roles.id is 5 + * $model->has('roles', 5); + * // Check for any of the following roles + * $model->has('roles', array(1, 2, 3, 4)); + * // Check if $model has any roles + * $model->has('roles') + * + * @param string $alias Alias of the has_many "through" relationship + * @param mixed $far_keys Related model, primary key, or an array of primary keys + * @return boolean + */ + public function has_any($alias, $far_keys = NULL) + { + return (bool) $this->count_relations($alias, $far_keys); + } + + /** + * Returns the number of relationships + * + * // Counts the number of times the login role is attached to $model + * $model->has('roles', ORM::factory('role', array('name' => 'login'))); + * // Counts the number of times role 5 is attached to $model + * $model->has('roles', 5); + * // Counts the number of times any of roles 1, 2, 3, or 4 are attached to + * // $model + * $model->has('roles', array(1, 2, 3, 4)); + * // Counts the number roles attached to $model + * $model->has('roles') + * + * @param string $alias Alias of the has_many "through" relationship + * @param mixed $far_keys Related model, primary key, or an array of primary keys + * @return integer + */ + public function count_relations($alias, $far_keys = NULL) + { + if ($far_keys === NULL) + { + return (int) DB::select(array(DB::expr('COUNT(*)'), 'records_found')) + ->from($this->_has_many[$alias]['through']) + ->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk()) + ->execute($this->_db)->get('records_found'); + } + + $far_keys = ($far_keys instanceof ORM) ? $far_keys->pk() : $far_keys; + + // We need an array to simplify the logic + $far_keys = (array) $far_keys; + + // Nothing to check if the model isn't loaded or we don't have any far_keys + if ( ! $far_keys OR ! $this->_loaded) + return 0; + + $count = (int) DB::select(array(DB::expr('COUNT(*)'), 'records_found')) + ->from($this->_has_many[$alias]['through']) + ->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk()) + ->where($this->_has_many[$alias]['far_key'], 'IN', $far_keys) + ->execute($this->_db)->get('records_found'); + + // Rows found need to match the rows searched + return (int) $count; + } + + /** + * Adds a new relationship to between this model and another. + * + * // Add the login role using a model instance + * $model->add('roles', ORM::factory('role', array('name' => 'login'))); + * // Add the login role if you know the roles.id is 5 + * $model->add('roles', 5); + * // Add multiple roles (for example, from checkboxes on a form) + * $model->add('roles', array(1, 2, 3, 4)); + * + * @param string $alias Alias of the has_many "through" relationship + * @param mixed $far_keys Related model, primary key, or an array of primary keys + * @return ORM + */ + public function add($alias, $far_keys) + { + $far_keys = ($far_keys instanceof ORM) ? $far_keys->pk() : $far_keys; + + $columns = array($this->_has_many[$alias]['foreign_key'], $this->_has_many[$alias]['far_key']); + $foreign_key = $this->pk(); + + $query = DB::insert($this->_has_many[$alias]['through'], $columns); + + foreach ( (array) $far_keys as $key) + { + $query->values(array($foreign_key, $key)); + } + + $query->execute($this->_db); + + return $this; + } + + /** + * Removes a relationship between this model and another. + * + * // Remove a role using a model instance + * $model->remove('roles', ORM::factory('role', array('name' => 'login'))); + * // Remove the role knowing the primary key + * $model->remove('roles', 5); + * // Remove multiple roles (for example, from checkboxes on a form) + * $model->remove('roles', array(1, 2, 3, 4)); + * // Remove all related roles + * $model->remove('roles'); + * + * @param string $alias Alias of the has_many "through" relationship + * @param mixed $far_keys Related model, primary key, or an array of primary keys + * @return ORM + */ + public function remove($alias, $far_keys = NULL) + { + $far_keys = ($far_keys instanceof ORM) ? $far_keys->pk() : $far_keys; + + $query = DB::delete($this->_has_many[$alias]['through']) + ->where($this->_has_many[$alias]['foreign_key'], '=', $this->pk()); + + if ($far_keys !== NULL) + { + // Remove all the relationships in the array + $query->where($this->_has_many[$alias]['far_key'], 'IN', (array) $far_keys); + } + + $query->execute($this->_db); + + return $this; + } + + /** + * Count the number of records in the table. + * + * @return integer + */ + public function count_all() + { + $selects = array(); + + foreach ($this->_db_pending as $key => $method) + { + if ($method['name'] == 'select') + { + // Ignore any selected columns for now + $selects[] = $method; + unset($this->_db_pending[$key]); + } + } + + if ( ! empty($this->_load_with)) + { + foreach ($this->_load_with as $alias) + { + // Bind relationship + $this->with($alias); + } + } + + $this->_build(Database::SELECT); + + $records = $this->_db_builder->from(array($this->_table_name, $this->_object_name)) + ->select(array(DB::expr('COUNT(*)'), 'records_found')) + ->execute($this->_db) + ->get('records_found'); + + // Add back in selected columns + $this->_db_pending += $selects; + + $this->reset(); + + // Return the total number of records in a table + return $records; + } + + /** + * Proxy method to Database list_columns. + * + * @return array + */ + public function list_columns() + { + // Proxy to database + return $this->_db->list_columns($this->_table_name); + } + + /** + * Returns an ORM model for the given one-one related alias + * + * @param string $alias Alias name + * @return ORM + */ + protected function _related($alias) + { + if (isset($this->_related[$alias])) + { + return $this->_related[$alias]; + } + elseif (isset($this->_has_one[$alias])) + { + return $this->_related[$alias] = ORM::factory($this->_has_one[$alias]['model']); + } + elseif (isset($this->_belongs_to[$alias])) + { + return $this->_related[$alias] = ORM::factory($this->_belongs_to[$alias]['model']); + } + else + { + return FALSE; + } + } + + /** + * Returns the value of the primary key + * + * @return mixed Primary key + */ + public function pk() + { + return $this->_primary_key_value; + } + + /** + * Returns last executed query + * + * @return string + */ + public function last_query() + { + return $this->_db->last_query; + } + + /** + * Clears query builder. Passing FALSE is useful to keep the existing + * query conditions for another query. + * + * @param bool $next Pass FALSE to avoid resetting on the next call + * @return ORM + */ + public function reset($next = TRUE) + { + if ($next AND $this->_db_reset) + { + $this->_db_pending = array(); + $this->_db_applied = array(); + $this->_db_builder = NULL; + $this->_with_applied = array(); + } + + // Reset on the next call? + $this->_db_reset = $next; + + return $this; + } + + protected function _serialize_value($value) + { + return json_encode($value); + } + + protected function _unserialize_value($value) + { + return json_decode($value, TRUE); + } + + public function object_name() + { + return $this->_object_name; + } + + public function object_plural() + { + return $this->_object_plural; + } + + public function loaded() + { + return $this->_loaded; + } + + public function saved() + { + return $this->_saved; + } + + public function primary_key() + { + return $this->_primary_key; + } + + public function table_name() + { + return $this->_table_name; + } + + public function table_columns() + { + return $this->_table_columns; + } + + public function has_one() + { + return $this->_has_one; + } + + public function belongs_to() + { + return $this->_belongs_to; + } + + public function has_many() + { + return $this->_has_many; + } + + public function load_with() + { + return $this->_load_with; + } + + public function original_values() + { + return $this->_original_values; + } + + public function created_column() + { + return $this->_created_column; + } + + public function updated_column() + { + return $this->_updated_column; + } + + public function validation() + { + if ( ! isset($this->_validation)) + { + // Initialize the validation object + $this->_validation(); + } + + return $this->_validation; + } + + public function object() + { + return $this->_object; + } + + public function errors_filename() + { + return $this->_errors_filename; + } + + /** + * Alias of and_where() + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function where($column, $op, $value) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'where', + 'args' => array($column, $op, $value), + ); + + return $this; + } + + /** + * Creates a new "AND WHERE" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function and_where($column, $op, $value) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'and_where', + 'args' => array($column, $op, $value), + ); + + return $this; + } + + /** + * Creates a new "OR WHERE" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function or_where($column, $op, $value) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'or_where', + 'args' => array($column, $op, $value), + ); + + return $this; + } + + /** + * Alias of and_where_open() + * + * @return $this + */ + public function where_open() + { + return $this->and_where_open(); + } + + /** + * Opens a new "AND WHERE (...)" grouping. + * + * @return $this + */ + public function and_where_open() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'and_where_open', + 'args' => array(), + ); + + return $this; + } + + /** + * Opens a new "OR WHERE (...)" grouping. + * + * @return $this + */ + public function or_where_open() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'or_where_open', + 'args' => array(), + ); + + return $this; + } + + /** + * Closes an open "AND WHERE (...)" grouping. + * + * @return $this + */ + public function where_close() + { + return $this->and_where_close(); + } + + /** + * Closes an open "AND WHERE (...)" grouping. + * + * @return $this + */ + public function and_where_close() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'and_where_close', + 'args' => array(), + ); + + return $this; + } + + /** + * Closes an open "OR WHERE (...)" grouping. + * + * @return $this + */ + public function or_where_close() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'or_where_close', + 'args' => array(), + ); + + return $this; + } + + /** + * Applies sorting with "ORDER BY ..." + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $direction direction of sorting + * @return $this + */ + public function order_by($column, $direction = NULL) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'order_by', + 'args' => array($column, $direction), + ); + + return $this; + } + + /** + * Return up to "LIMIT ..." results + * + * @param integer $number maximum results to return + * @return $this + */ + public function limit($number) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'limit', + 'args' => array($number), + ); + + return $this; + } + + /** + * Enables or disables selecting only unique columns using "SELECT DISTINCT" + * + * @param boolean $value enable or disable distinct columns + * @return $this + */ + public function distinct($value) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'distinct', + 'args' => array($value), + ); + + return $this; + } + + /** + * Choose the columns to select from. + * + * @param mixed $columns column name or array($column, $alias) or object + * @param ... + * @return $this + */ + public function select($columns = NULL) + { + $columns = func_get_args(); + + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'select', + 'args' => $columns, + ); + + return $this; + } + + /** + * Choose the tables to select "FROM ..." + * + * @param mixed $tables table name or array($table, $alias) or object + * @param ... + * @return $this + */ + public function from($tables) + { + $tables = func_get_args(); + + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'from', + 'args' => $tables, + ); + + return $this; + } + + /** + * Adds addition tables to "JOIN ...". + * + * @param mixed $table column name or array($column, $alias) or object + * @param string $type join type (LEFT, RIGHT, INNER, etc) + * @return $this + */ + public function join($table, $type = NULL) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'join', + 'args' => array($table, $type), + ); + + return $this; + } + + /** + * Adds "ON ..." conditions for the last created JOIN statement. + * + * @param mixed $c1 column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $c2 column name or array($column, $alias) or object + * @return $this + */ + public function on($c1, $op, $c2) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'on', + 'args' => array($c1, $op, $c2), + ); + + return $this; + } + + /** + * Creates a "GROUP BY ..." filter. + * + * @param mixed $columns column name or array($column, $alias) or object + * @param ... + * @return $this + */ + public function group_by($columns) + { + $columns = func_get_args(); + + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'group_by', + 'args' => $columns, + ); + + return $this; + } + + /** + * Alias of and_having() + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function having($column, $op, $value = NULL) + { + return $this->and_having($column, $op, $value); + } + + /** + * Creates a new "AND HAVING" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function and_having($column, $op, $value = NULL) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'and_having', + 'args' => array($column, $op, $value), + ); + + return $this; + } + + /** + * Creates a new "OR HAVING" condition for the query. + * + * @param mixed $column column name or array($column, $alias) or object + * @param string $op logic operator + * @param mixed $value column value + * @return $this + */ + public function or_having($column, $op, $value = NULL) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'or_having', + 'args' => array($column, $op, $value), + ); + + return $this; + } + + /** + * Alias of and_having_open() + * + * @return $this + */ + public function having_open() + { + return $this->and_having_open(); + } + + /** + * Opens a new "AND HAVING (...)" grouping. + * + * @return $this + */ + public function and_having_open() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'and_having_open', + 'args' => array(), + ); + + return $this; + } + + /** + * Opens a new "OR HAVING (...)" grouping. + * + * @return $this + */ + public function or_having_open() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'or_having_open', + 'args' => array(), + ); + + return $this; + } + + /** + * Closes an open "AND HAVING (...)" grouping. + * + * @return $this + */ + public function having_close() + { + return $this->and_having_close(); + } + + /** + * Closes an open "AND HAVING (...)" grouping. + * + * @return $this + */ + public function and_having_close() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'and_having_close', + 'args' => array(), + ); + + return $this; + } + + /** + * Closes an open "OR HAVING (...)" grouping. + * + * @return $this + */ + public function or_having_close() + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'or_having_close', + 'args' => array(), + ); + + return $this; + } + + /** + * Start returning results after "OFFSET ..." + * + * @param integer $number starting result number + * @return $this + */ + public function offset($number) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'offset', + 'args' => array($number), + ); + + return $this; + } + + /** + * Enables the query to be cached for a specified amount of time. + * + * @param integer $lifetime number of seconds to cache + * @return $this + * @uses Kohana::$cache_life + */ + public function cached($lifetime = NULL) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'cached', + 'args' => array($lifetime), + ); + + return $this; + } + + /** + * Set the value of a parameter in the query. + * + * @param string $param parameter key to replace + * @param mixed $value value to use + * @return $this + */ + public function param($param, $value) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'param', + 'args' => array($param, $value), + ); + + return $this; + } + + /** + * Adds "USING ..." conditions for the last created JOIN statement. + * + * @param string $columns column name + * @return $this + */ + public function using($columns) + { + // Add pending database call which is executed after query type is determined + $this->_db_pending[] = array( + 'name' => 'using', + 'args' => array($columns), + ); + + return $this; + } + + /** + * Checks whether a column value is unique. + * Excludes itself if loaded. + * + * @param string $field the field to check for uniqueness + * @param mixed $value the value to check for uniqueness + * @return bool whteher the value is unique + */ + public function unique($field, $value) + { + $model = ORM::factory($this->object_name()) + ->where($field, '=', $value) + ->find(); + + if ($this->loaded()) + { + return ( ! ($model->loaded() AND $model->pk() != $this->pk())); + } + + return ( ! $model->loaded()); + } +} // End ORM diff --git a/modules/orm/classes/Kohana/ORM/Validation/Exception.php b/modules/orm/classes/Kohana/ORM/Validation/Exception.php new file mode 100644 index 0000000..d88fcd1 --- /dev/null +++ b/modules/orm/classes/Kohana/ORM/Validation/Exception.php @@ -0,0 +1,198 @@ +_alias = $alias; + $this->_objects['_object'] = $object; + $this->_objects['_has_many'] = FALSE; + + parent::__construct($message, $values, $code, $previous); + } + + /** + * Adds a Validation object to this exception + * + * // The following will add a validation object for a profile model + * // inside the exception for a user model. + * $e->add_object('profile', $validation); + * // The errors array will now look something like this + * // array + * // ( + * // 'username' => 'This field is required', + * // 'profile' => array + * // ( + * // 'first_name' => 'This field is required', + * // ), + * // ); + * + * @param string $alias The relationship alias from the model + * @param Validation $object The Validation object to merge + * @param mixed $has_many The array key to use if this exception can be merged multiple times + * @return ORM_Validation_Exception + */ + public function add_object($alias, Validation $object, $has_many = FALSE) + { + // We will need this when generating errors + $this->_objects[$alias]['_has_many'] = ($has_many !== FALSE); + + if ($has_many === TRUE) + { + // This is most likely a has_many relationship + $this->_objects[$alias][]['_object'] = $object; + } + elseif ($has_many) + { + // This is most likely a has_many relationship + $this->_objects[$alias][$has_many]['_object'] = $object; + } + else + { + $this->_objects[$alias]['_object'] = $object; + } + + return $this; + } + + /** + * Merges an ORM_Validation_Exception object into the current exception + * Useful when you want to combine errors into one array + * + * @param ORM_Validation_Exception $object The exception to merge + * @param mixed $has_many The array key to use if this exception can be merged multiple times + * @return ORM_Validation_Exception + */ + public function merge(ORM_Validation_Exception $object, $has_many = FALSE) + { + $alias = $object->alias(); + + // We will need this when generating errors + $this->_objects[$alias]['_has_many'] = ($has_many !== FALSE); + + if ($has_many === TRUE) + { + // This is most likely a has_many relationship + $this->_objects[$alias][] = $object->objects(); + } + elseif ($has_many) + { + // This is most likely a has_many relationship + $this->_objects[$alias][$has_many] = $object->objects(); + } + else + { + $this->_objects[$alias] = $object->objects(); + } + + return $this; + } + + /** + * Returns a merged array of the errors from all the Validation objects in this exception + * + * // Will load Model_User errors from messages/orm-validation/user.php + * $e->errors('orm-validation'); + * + * @param string $directory Directory to load error messages from + * @param mixed $translate Translate the message + * @return array + * @see generate_errors() + */ + public function errors($directory = NULL, $translate = TRUE) + { + return $this->generate_errors($this->_alias, $this->_objects, $directory, $translate); + } + + /** + * Recursive method to fetch all the errors in this exception + * + * @param string $alias Alias to use for messages file + * @param array $array Array of Validation objects to get errors from + * @param string $directory Directory to load error messages from + * @param mixed $translate Translate the message + * @return array + */ + protected function generate_errors($alias, array $array, $directory, $translate) + { + $errors = array(); + + foreach ($array as $key => $object) + { + if (is_array($object)) + { + $errors[$key] = ($key === '_external') + // Search for errors in $alias/_external.php + ? $this->generate_errors($alias.'/'.$key, $object, $directory, $translate) + // Regular models get their own file not nested within $alias + : $this->generate_errors($key, $object, $directory, $translate); + } + elseif ($object instanceof Validation) + { + if ($directory === NULL) + { + // Return the raw errors + $file = NULL; + } + else + { + $file = trim($directory.'/'.$alias, '/'); + } + + // Merge in this array of errors + $errors += $object->errors($file, $translate); + } + } + + return $errors; + } + + /** + * Returns the protected _objects property from this exception + * + * @return array + */ + public function objects() + { + return $this->_objects; + } + + /** + * Returns the protected _alias property from this exception + * + * @return string + */ + public function alias() + { + return $this->_alias; + } +} // End Kohana_ORM_Validation_Exception diff --git a/modules/orm/classes/Model/Auth/Role.php b/modules/orm/classes/Model/Auth/Role.php new file mode 100644 index 0000000..5a12764 --- /dev/null +++ b/modules/orm/classes/Model/Auth/Role.php @@ -0,0 +1,31 @@ + array('model' => 'User','through' => 'roles_users'), + ); + + public function rules() + { + return array( + 'name' => array( + array('not_empty'), + array('min_length', array(':value', 4)), + array('max_length', array(':value', 32)), + ), + 'description' => array( + array('max_length', array(':value', 255)), + ) + ); + } + +} // End Auth Role Model diff --git a/modules/orm/classes/Model/Auth/User.php b/modules/orm/classes/Model/Auth/User.php new file mode 100644 index 0000000..d86fae4 --- /dev/null +++ b/modules/orm/classes/Model/Auth/User.php @@ -0,0 +1,204 @@ + array('model' => 'User_Token'), + 'roles' => array('model' => 'Role', 'through' => 'roles_users'), + ); + + /** + * Rules for the user model. Because the password is _always_ a hash + * when it's set,you need to run an additional not_empty rule in your controller + * to make sure you didn't hash an empty string. The password rules + * should be enforced outside the model or with a model helper method. + * + * @return array Rules + */ + public function rules() + { + return array( + 'username' => array( + array('not_empty'), + array('max_length', array(':value', 32)), + array(array($this, 'unique'), array('username', ':value')), + ), + 'password' => array( + array('not_empty'), + ), + 'email' => array( + array('not_empty'), + array('email'), + array(array($this, 'unique'), array('email', ':value')), + ), + ); + } + + /** + * Filters to run when data is set in this model. The password filter + * automatically hashes the password when it's set in the model. + * + * @return array Filters + */ + public function filters() + { + return array( + 'password' => array( + array(array(Auth::instance(), 'hash')) + ) + ); + } + + /** + * Labels for fields in this model + * + * @return array Labels + */ + public function labels() + { + return array( + 'username' => 'username', + 'email' => 'email address', + 'password' => 'password', + ); + } + + /** + * Complete the login for a user by incrementing the logins and saving login timestamp + * + * @return void + */ + public function complete_login() + { + if ($this->_loaded) + { + // Update the number of logins + $this->logins = new Database_Expression('logins + 1'); + + // Set the last login date + $this->last_login = time(); + + // Save the user + $this->update(); + } + } + + /** + * Tests if a unique key value exists in the database. + * + * @param mixed the value to test + * @param string field name + * @return boolean + */ + public function unique_key_exists($value, $field = NULL) + { + if ($field === NULL) + { + // Automatically determine field by looking at the value + $field = $this->unique_key($value); + } + + return (bool) DB::select(array(DB::expr('COUNT(*)'), 'total_count')) + ->from($this->_table_name) + ->where($field, '=', $value) + ->where($this->_primary_key, '!=', $this->pk()) + ->execute($this->_db) + ->get('total_count'); + } + + /** + * Allows a model use both email and username as unique identifiers for login + * + * @param string unique value + * @return string field name + */ + public function unique_key($value) + { + return Valid::email($value) ? 'email' : 'username'; + } + + /** + * Password validation for plain passwords. + * + * @param array $values + * @return Validation + */ + public static function get_password_validation($values) + { + return Validation::factory($values) + ->rule('password', 'min_length', array(':value', 8)) + ->rule('password_confirm', 'matches', array(':validation', ':field', 'password')); + } + + /** + * Create a new user + * + * Example usage: + * ~~~ + * $user = ORM::factory('User')->create_user($_POST, array( + * 'username', + * 'password', + * 'email', + * ); + * ~~~ + * + * @param array $values + * @param array $expected + * @throws ORM_Validation_Exception + */ + public function create_user($values, $expected) + { + // Validation for passwords + $extra_validation = Model_User::get_password_validation($values) + ->rule('password', 'not_empty'); + + return $this->values($values, $expected)->create($extra_validation); + } + + /** + * Update an existing user + * + * [!!] We make the assumption that if a user does not supply a password, that they do not wish to update their password. + * + * Example usage: + * ~~~ + * $user = ORM::factory('User') + * ->where('username', '=', 'kiall') + * ->find() + * ->update_user($_POST, array( + * 'username', + * 'password', + * 'email', + * ); + * ~~~ + * + * @param array $values + * @param array $expected + * @throws ORM_Validation_Exception + */ + public function update_user($values, $expected = NULL) + { + if (empty($values['password'])) + { + unset($values['password'], $values['password_confirm']); + } + + // Validation for passwords + $extra_validation = Model_User::get_password_validation($values); + + return $this->values($values, $expected)->update($extra_validation); + } + +} // End Auth User Model diff --git a/modules/orm/classes/Model/Auth/User/Token.php b/modules/orm/classes/Model/Auth/User/Token.php new file mode 100644 index 0000000..3c69ead --- /dev/null +++ b/modules/orm/classes/Model/Auth/User/Token.php @@ -0,0 +1,77 @@ + array('model' => 'User'), + ); + + protected $_created_column = array( + 'column' => 'created', + 'format' => TRUE, + ); + + /** + * Handles garbage collection and deleting of expired objects. + * + * @return void + */ + public function __construct($id = NULL) + { + parent::__construct($id); + + if (mt_rand(1, 100) === 1) + { + // Do garbage collection + $this->delete_expired(); + } + + if ($this->expires < time() AND $this->_loaded) + { + // This object has expired + $this->delete(); + } + } + + /** + * Deletes all expired tokens. + * + * @return ORM + */ + public function delete_expired() + { + // Delete all expired tokens + DB::delete($this->_table_name) + ->where('expires', '<', time()) + ->execute($this->_db); + + return $this; + } + + public function create(Validation $validation = NULL) + { + $this->token = $this->create_token(); + + return parent::create($validation); + } + + protected function create_token() + { + do + { + $token = sha1(uniqid(Text::random('alnum', 32), TRUE)); + } + while (ORM::factory('User_Token', array('token' => $token))->loaded()); + + return $token; + } + +} // End Auth User Token Model diff --git a/modules/orm/classes/Model/Role.php b/modules/orm/classes/Model/Role.php new file mode 100644 index 0000000..b1ead06 --- /dev/null +++ b/modules/orm/classes/Model/Role.php @@ -0,0 +1,7 @@ + array( + + // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + 'orm' => array( + + // Whether this modules userguide pages should be shown + 'enabled' => TRUE, + + // The name that should show up on the userguide index page + 'name' => 'ORM', + + // A short description of this module, shown on the index page + 'description' => 'Official ORM module, a modeling library for object relational mapping.', + + // Copyright message, shown in the footer for this module + 'copyright' => '© 2008–2012 Kohana Team', + ) + ) +); diff --git a/modules/orm/guide/orm/examples.md b/modules/orm/guide/orm/examples.md new file mode 100644 index 0000000..5c21dd4 --- /dev/null +++ b/modules/orm/guide/orm/examples.md @@ -0,0 +1,13 @@ +# Examples + +- [Simple](examples/simple): Basic, one table model examples. +- [Validation](examples/validation): Full example of creating a user account and handling validation errors. + +## @TODO: + +The following is a sample list of examples that might be useful. Don't feel limited by this list, or consider these required. Items on the list can be combined, split up, removed or added to. All contribution are appreciated. + +- Examples of changing things like $_table_name, $_labels, with, etc. +- Example of a one to one relationship. +- Example of one to many +- Example of many to many. diff --git a/modules/orm/guide/orm/examples/simple.md b/modules/orm/guide/orm/examples/simple.md new file mode 100644 index 0000000..b8abe92 --- /dev/null +++ b/modules/orm/guide/orm/examples/simple.md @@ -0,0 +1,119 @@ +# Simple Examples + +This is a simple example of a single ORM model, that has no relationships, but uses validation on the fields. + +## SQL schema + + CREATE TABLE IF NOT EXISTS `members` ( + `id` int(10) unsigned NOT NULL AUTO_INCREMENT, + `username` varchar(32) NOT NULL, + `first_name` varchar(32) NOT NULL, + `last_name` varchar(32) NOT NULL, + `email` varchar(127) DEFAULT NULL, + PRIMARY KEY (`id`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1; + +## Model + + array( + array('not_empty'), + array('min_length', array(':value', 4)), + array('max_length', array(':value', 32)), + array('regex', array(':value', '/^[-\pL\pN_.]++$/uD')), + ), + 'first_name' => array( + array('not_empty'), + array('min_length', array(':value', 4)), + array('max_length', array(':value', 32)), + array('regex', array(':value', '/^[-\pL\pN_.]++$/uD')), + ), + 'last_name' => array( + array('not_empty'), + array('min_length', array(':value', 4)), + array('max_length', array(':value', 32)), + array('regex', array(':value', '/^[-\pL\pN_.]++$/uD')), + ), + 'email' => array( + array('not_empty'), + array('min_length', array(':value', 4)), + array('max_length', array(':value', 127)), + array('email'), + ), + ); + } + } + +[!!] The array returned by `ORM::rules()` will be passed to a [Validation] object and tested when you call `ORM::save()`. + +[!!] Please notice that defining the primary key "id" in the model is not necessary. Also the table name in the database is plural and the model name is singular. + +## Controller + + where('first_name', '=', 'Peter')->find_all(); + + // Count records in the $members object + $members->count_all(); + + /** + * Example 2 + */ + + // Create an instance of a model + $member = ORM::factory('Member'); + + // Get a member with the user name "bongo" find() means + // we only want the first record matching the query. + $member->where('username', '=', 'bongo')->find(); + + /** + * Example 3 + */ + + // Create an instance of a model + $member = ORM::factory('Member'); + + // Do an INSERT query + $member->username = 'bongo'; + $member->first_name = 'Peter'; + $member->last_name = 'Smith'; + $member->save(); + + /** + * Example 4 + */ + + // Create an instance of a model where the + // table field "id" is "1" + $member = ORM::factory('Member', 1); + + // Do an UPDATE query + $member->username = 'bongo'; + $member->first_name = 'Peter'; + $member->last_name = 'Smith'; + $member->save(); + } + } + +[!!] $member will be a PHP object where you can access the values from the query e.g. echo $member->first_name diff --git a/modules/orm/guide/orm/examples/validation.md b/modules/orm/guide/orm/examples/validation.md new file mode 100644 index 0000000..0510a45 --- /dev/null +++ b/modules/orm/guide/orm/examples/validation.md @@ -0,0 +1,137 @@ +# Validation Example + +This example will create user accounts and demonstrate how to handle model and controller validation. We will create a form, process it, and display any errors to the user. We will be assuming that the Model_User class contains a method called `hash_password` that is used to turn the plaintext passwords into some kind of hash. The implementation of the hashing methods are beyond the scope of this example and should be provided with the Authentication library you decide to use. + +## SQL schema + + CREATE TABLE IF NOT EXISTS `members` ( + `id` int(10) unsigned NOT NULL AUTO_INCREMENT, + `username` varchar(32) NOT NULL, + `password` varchar(100) NOT NULL, + PRIMARY KEY (`id`) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1; + +## Model + + array( + array('not_empty'), + array('min_length', array(':value', 4)), + array('max_length', array(':value', 32)), + array(array($this, 'username_available')), + ), + 'password' => array( + array('not_empty'), + ), + ); + } + + public function filters() + { + return array( + 'password' => array( + array(array($this, 'hash_password')), + ), + ); + } + + public function username_available($username) + { + // There are simpler ways to do this, but I will use ORM for the sake of the example + return ORM::factory('Member', array('username' => $username))->loaded(); + } + + public function hash_password($password) + { + // Do something to hash the password + } + } + +## HTML Form + +Please forgive my slightly ugly form. I am trying not to use any modules or unrelated magic. :) + +
+ + +