Merge branch 'release/1.3'

* release/1.3:
  Bump version to v1.3
  Document order in which files and groups are rendered, and the consequences for satisfying JS deps.
  Remove declaration of 'global' group.
  Document render() function in readme
  Create render() function, which calls render_css() then render_js().
  Some functions weren't declared static. PHP man claims E_STICT should be thrown, but that didn't happen. Fixed anyway!
  Add instrunctions on how to load casset to the readme.
  Document the ability to pass any non-x (bool, array) value for some default function arguments.
  Allow the user to enter any value for some function argument defaults, rather than remember that eg 'false' must be used.
  Add "Comparison to Assetic" section to the readme.
  Remove extra forward slash from file path when rending a minified file inline.
  Remove '?$mtime' from filename when rending the file inline.

classes/casset.php

@@ -4,7 +4,7 @@
  * Casset: Convenient asset library for FuelPHP.
  *
  * @package    Casset
- * @version    v1.2
+ * @version    v1.3
  * @author     Antony Male
  * @license    MIT License
  * @copyright  2011 Antony Male
@@ -45,8 +45,8 @@ class Casset {
 	 * @var array Holds groups of assets. Is documenented fully in the config file.
 	 */
 	protected static $groups = array(
-		'css' => array('global' => array('files' => array(), 'enabled' => true)),
-		'js' => array('global' => array('files' => array(), 'enabled' => true)),
+		'css' => array(),
+		'js' => array(),
 	);
 
 	/**
@@ -182,7 +182,7 @@ public static function add_group($group_type, $group_name, $files, $enabled = tr
 	 * @param string $asset_type 'css', 'js' or 'img'
 	 * @return string The path to the asset, relative to $asset_url
 	 */
-	public function find_file($file, $asset_type)
+	public static function find_file($file, $asset_type)
 	{
 		if (strpos($file, '//') === false)
 		{
@@ -323,6 +323,10 @@ public static function css($sheet, $sheet_min = false, $group = 'global')
 	 */
 	private static function add_asset($type, $script, $script_min, $group)
 	{
+		// Don't force the user to remember that 'false' is used when not supplying
+		// a pre-minified file.
+		if (!is_string($script_min))
+			$script_min = false;
 		if (!array_key_exists($group, static::$groups[$type]))
 		{
 			// Assume they want the group enabled
@@ -367,6 +371,23 @@ private static function add_asset_inline($type, $content)
 		array_push(static::$inline_assets[$type], $content);
 	}
 
+	/**
+	 * Shortcut to render_js() and render_css().
+	 *
+	 * @param string $group Which group to render. If omitted renders all groups
+	 * @param bool $inline If true, the result is printed inline. If false, is
+	 *        written to a file and linked to. In fact, $inline = true also causes
+	 *        a cache file to be written for speed purposes
+	 * @param bool $min True to minify the javascript files. null to use the config value
+	 * @return string The javascript tags to be written to the page
+	 */
+	public static function render($group = false, $inline = false, $attr = array(), $min = null)
+	{
+		$r = static::render_css($group, $inline, $attr, $min);
+		$r.= static::render_js($group, $inline, $attr, $min);
+		return $r;
+	}
+
 	/**
 	 * Renders the specific javascript group, or all groups if no group specified.
 	 *
@@ -377,8 +398,13 @@ private static function add_asset_inline($type, $content)
 	 * @param bool $min True to minify the javascript files. null to use the config value
 	 * @return string The javascript tags to be written to the page
 	 */
-	public function render_js($group = false, $inline = false, $attr = array(), $min = null)
+	public static function render_js($group = false, $inline = false, $attr = array(), $min = null)
 	{
+		// Don't force the user to remember that false is used for ommitted non-bool arguments
+		if (!is_string($group))
+			$group = false;
+		if (!is_array($attr))
+			$attr = array();
 		if ($min === null)
 			$min = static::$min;
 
@@ -390,15 +416,15 @@ public function render_js($group = false, $inline = false, $attr = array(), $min
 		{
 			if ($min)
 			{
-				$filename = static::combine_and_minify('js', $file_group);
+				$filename = static::combine_and_minify('js', $file_group, $inline);
 				if (!$inline && static::$show_files)
 				{
 					$ret .= '<!--'.PHP_EOL.'Group: '.$group_name.PHP_EOL.implode('', array_map(function($a){
 						return "\t".$a['file'].PHP_EOL;
 					}, $file_group)).'-->'.PHP_EOL;
 				}
 				if ($inline)
-					$ret .= html_tag('script', array('type' => 'text/javascript')+$attr, PHP_EOL.file_get_contents(DOCROOT.static::$cache_path.'/'.$filename).PHP_EOL).PHP_EOL;
+					$ret .= html_tag('script', array('type' => 'text/javascript')+$attr, PHP_EOL.file_get_contents(DOCROOT.static::$cache_path.$filename).PHP_EOL).PHP_EOL;
 				else
 					$ret .= html_tag('script', array(
 						'type' => 'text/javascript',
@@ -433,8 +459,13 @@ public function render_js($group = false, $inline = false, $attr = array(), $min
 	 * @param bool $min True to minify the css files. null to use the config value
 	 * @return string The css tags to be written to the page
 	 */
-	public function render_css($group = false, $inline = false, $attr = array(), $min = null)
+	public static function render_css($group = false, $inline = false, $attr = array(), $min = null)
 	{
+		// Don't force the user to remember that false is used for ommitted non-bool arguments
+		if (!is_string($group))
+			$group = false;
+		if (!is_array($attr))
+			$attr = array();
 		if ($min === null)
 			$min = static::$min;
 
@@ -446,15 +477,15 @@ public function render_css($group = false, $inline = false, $attr = array(), $mi
 		{
 			if ($min)
 			{
-				$filename = static::combine_and_minify('css', $file_group);
+				$filename = static::combine_and_minify('css', $file_group, $inline);
 				if (!$inline && static::$show_files)
 				{
 					$ret .= '<!--'.PHP_EOL.'Group: '.$group_name.PHP_EOL.implode('', array_map(function($a){
 						return "\t".$a['file'].PHP_EOL;
 					}, $file_group)).'-->'.PHP_EOL;
 				}
 				if ($inline)
-					$ret .= html_tag('style', array('type' => 'text/css')+$attr, PHP_EOL.file_get_contents(DOCROOT.static::$cache_path.'/'.$filename).PHP_EOL).PHP_EOL;
+					$ret .= html_tag('style', array('type' => 'text/css')+$attr, PHP_EOL.file_get_contents(DOCROOT.static::$cache_path.$filename).PHP_EOL).PHP_EOL;
 				else
 					$ret .= html_tag('link', array(
 						'rel' => 'stylesheet',
@@ -552,7 +583,7 @@ private static function files_to_render($type, $group, $min)
 	 *        to combine and minify.
 	 * @return string The path to the cache file which was written.
 	 */
-	private static function combine_and_minify($type, $file_group)
+	private static function combine_and_minify($type, $file_group, $inline)
 	{
 		$filename = md5(implode('', array_map(function($a) {
 			return $a['file'];
@@ -594,7 +625,9 @@ private static function combine_and_minify($type, $file_group)
 			file_put_contents($filepath, $content);
 			$mtime = time();
 		}
-		return $filename.'?'.$mtime;
+		if (!$inline)
+			$filename .= '?'.$mtime;
+		return $filename;
 	}
 
 	/**

classes/casset/csscompressor.php

@@ -17,7 +17,7 @@
  * This library is used as part of Casset.
  *
  * @package    Casset
- * @version    v1.2
+ * @version    v1.3
  * @author     Antony Male
  * @license    MIT License
  * @link       http://github.com/canton7/fuelphp-casset

classes/casset/cssurirewriter.php

@@ -10,7 +10,7 @@
  * This library is used as part of Casset.
  *
  * @package    Casset
- * @version    v1.2
+ * @version    v1.3
  * @author     Antony Male
  * @license    MIT License
  * @link       http://github.com/canton7/fuelphp-casset

classes/casset/jsmin.php

@@ -52,7 +52,7 @@
 /**
  * This library is used as part of Casset.
  * @package    Casset
- * @version    v1.2
+ * @version    v1.3
  * @author     Antony Male
  * @license    MIT License
  * @link       http://github.com/canton7/fuelphp-casset

config/casset.php

@@ -4,7 +4,7 @@
  * Casset: Convenient asset library for FuelPHP.
  *
  * @package    Casset
- * @version    v1.2
+ * @version    v1.3
  * @author     Antony Male
  * @license    MIT License
  * @copyright  2011 Antony Male

readme.md

@@ -15,7 +15,8 @@ Installation
 2. Stick in fuel/packages/
 3. Optionally edit fuel/packages/casset/config/casset.php (the defaults are sensible)
 4. Create public/assets/cache
-5. Enjoy
+5. Add 'casset' to the 'always_load/packages' array in app/config/config.php (or call `Fuel::add_package('casset')` whenever you want to use it).
+6. Enjoy :)
 
 Basic usage
 -----------
@@ -55,6 +56,8 @@ can pass this as the second argument, eg:
 Casset::js('myfile.js', 'myfile.min.js');
 ```
 
+Some folks like css and js tags to be together. `Casset::render()` is a shortcut which calls `Casset::render_css()` then `Casset::render_js()`.
+
 Images
 ------
 
@@ -128,13 +131,20 @@ Casset::js('myfile.js', 'myfile.min.js', 'group_name');
 Casset::css('myfile.css', false, 'group_name');
 ```
 
+(As an aside, you can pass any non-string value instead of 'false' in the second example, and Casset will behave the same: generate your minified file for you.)
+
 Groups can also be declared on the fly, by specifying a group name which doesn't yet exist. The group is assumed to be enabled.  
 You can also use a slightly more involved syntax for creating groups, which allows you to specify multiple files and whether the group is enabled, as shown below:
 
 ```php
 Casset::add_group('js', 'group_name', array('file1.js', array('file2.js', 'file2.min.js')), $enabled);
 ```
 
+When you call `Casset::render()` (or the js- and css-specific varients), the order that groups are rendered is determined by the order in which they were created, with groups present in the config file appearing first.
+Similarly (for JS files only), the order in which files appear is determined by the order in which they were added.
+This allows you a degree of control over what order your files are included in your page, which may be necessary when satisfying dependancies.
+If this isn't working for you, or you want something a bit more explicit, try this: If file A depends on B, add B to its own group and explicitely render it first.
+
 NOTE: Calling ``Casset::js('file.js')`` will add that file to the "global" group. Use / abuse as you need!
 
 
@@ -213,9 +223,11 @@ Similarly, you can choose to put comments inside each minified file, saying whic
 The following will minify the 'group_name' group, even if minification is turned off in the config file.
 
 ```php
-echo Casset::render_js('group_name', false, array(), true);
+echo Casset::render_js(false, false, array(), true);
 ```
 
+(Again, you can pass any non-string value for the first argument, and any non-array value for the third, and Casset will treat them the same as if the default argument (false and array() respectively) had been passed.)
+
 When minifying CSS files, urls are rewritten to take account of the fact that your css file has effectively moved into `public/assets/cache`.
 
 With JS files, changing the order in which files were added to the group will re-generate the cache file, with the files in their new positions. However with CSS, it will not.
@@ -242,6 +254,17 @@ Casset::clear_cache('yesterday');
 // Removes all cache files last modified yesterday
 ```
 
+Comparison to Assetic
+---------------------
+
+A frequent question is how Casset differs from kriswallsmith's [Assetic](https://github.com/fuel-packages/fuel-assetic). InCasset and Assetic have completely different goals.
+
+* Assetic is a very powerful asset mangement framework. It allows you to perform minification, compression and compilation on your assets, although learning it will take time.
+* Casset is designed to make assets very easy to handle. You call `Casset::js()` then `Casset::render_js()`, and everything is taken care of.
+
+If you're a developer tasked with fully optimising your site's page load time, for example, go with Assetic. If you want a very easy way to manage your assets, with some minification
+thrown in for free, (and have no need for Assetic's complex features), go with Casset.
+
 Examples
 --------