Huge docs overhaul for 3.x

2025-08-30 00:59:48 +02:00 · 2015-09-28 20:30:46 -04:00
parent 0bc3769802
commit 61ba5a47a5
14 changed files with 315 additions and 477 deletions
--- a/docs/CustomSource.wiki.md
+++ b/docs/CustomSource.wiki.md
@@ -1,11 +1,12 @@
 In `groupsConfig.php`, usually you specify source file paths using strings like `/path/to/file.js` or `//js/file1.js` (Minify expands this to `"{$_SERVER['DOCUMENT_ROOT']}/js/file1.js"` ).

-Instead of a string, you may substitute a "source object" (an instance of class [Minify\_Source](http://code.google.com/p/minify/source/browse/tags/release_2.1.3/min/lib/Minify/Source.php)). This allows you to customize how minification is applied, and/or pull content from a non-file location (e.g. a URL).
+Instead of a string, you may substitute an instance of class `Minify_Source`. This allows you to customize how minification is applied, and/or pull content from a non-file location (e.g. a URL).

 ### Example: filepath

 In the `$spec` array, set the key `filepath` to produce a source based on a file path:
-```
+
+```php
 $src1 = new Minify_Source(array(
    'filepath' => '//js/file1.js',
 ));
@@ -13,15 +14,16 @@ $src2 = new Minify_Source(array(
    'filepath' => '//js/file2.js',
 ));

-return array(
-    'js' => array($src1, $src2)
-);
+return [
+    'js' => [$src1, $src2]
+];
 ```
+
 Note the above is functionally identical to:
-```
-return array(
-    'js' => array('//js/file1.js', '//js/file2.js')
-);
+```php
+return [
+    'js' => ['//js/file1.js', '//js/file2.js'],
+];
 ```

 ### Example: Specify a different minifier or none at all
@@ -30,26 +32,19 @@ To change minifier, set `minifier` to a [callback](http://php.net/manual/en/lang

 **`*`Prepare for `groupsConfig.php` to be executed more than once.** (This is likely if you're using the functions in `/min/utils.php`.) In practice this just means making sure functions are conditionally defined if they don't already exist, etc.

-```
-if (! function_exists('myMin')) {
-    function myMin($js) {
-        require_once 'JSMinPlus.php';
-        return JSMinPlus::minify($js);
-    }
-}
-
+```php
 $src1 = new Minify_Source(array(
    'filepath' => '//js/file1.js',
-    'minifier' => 'myMin',
+    'minifier' => ['JSMinPlus', 'minify'],
 ));
 $src2 = new Minify_Source(array(
    'filepath' => '//js/file2.js',
    'minifier' => '', // don't compress
 ));
 ```
-In the above, `myMin()` is only called when rebuilding the cache. This way `JSMinPlus.php` is only loaded when needed.
+In the above, `JSMinPlus.php` is only loaded when the contents of `$src1` is needed.

-**`*`Do _not_ use [create\_function](http://php.net/manual/en/function.create-function.php) or anonymous functions for the minifier.** The internal names of these function tend to vary, causing Minify to create lots of [duplicate cache files](http://code.google.com/p/minify/issues/detail?id=138) (and perform poorly).
+**`*`Do _not_ use `create_function()` or anonymous functions for the minifier.** The internal names of these function tend to vary, causing endless cache misses, killing performance and filling cache storage up.

 ## Non-File Sources

@@ -63,24 +58,23 @@ You're not limited to flat js/css files, but without `filepath`, the `$spec` arr
 ### Example: Content from a URL

 Here we want to fetch javascript from a URL. We don't know when it will change, so we use a stepping expression to re-fetch it every midnight:
-```
+```php
 if (! function_exists('src1_fetch')) {
    function src1_fetch() {
        return file_get_contents('http://example.org/javascript.php');
    }
 }
-$src1 = new Minify_Source(array(
+$src1 = new Minify_Source([
    'id' => 'source1',
    'getContentFunc' => 'src1_fetch',
    'contentType' => Minify::TYPE_JS,    
    'lastModified' => ($_SERVER['REQUEST_TIME'] - $_SERVER['REQUEST_TIME'] % 86400),
-));
+]);
 ```

 If you know that the URL content only depends on a few local files, you can use the maximum of their `mtime`s as the `lastModified` key:
-```
-...
-$src1 = new Minify_Source(array(
+```php
+$src1 = new Minify_Source([
    'id' => 'source1',
    'getContentFunc' => 'src1_fetch',
    'contentType' => Minify::TYPE_JS,
@@ -88,51 +82,55 @@ $src1 = new Minify_Source(array(
        filemtime('/path/to/javascript.php')
        ,filemtime('/path/to/javascript_input.css')
    ),
-));
+]);
 ```

 ## Performance Considerations

-Be aware that all the code you put in groupsConfig.php will be evaluated upon every request like `/min/g=...`, so make it as light as possible.
+Be aware that all the code you put in `groupsConfig.php` will be evaluated upon every request like `/min/g=...`, so make it as light as possible.

-If you wish to keep groupsConfig.php "clean", you can alternately create a separate PHP script that manually sets up sources, caching, options, and calls Minify::serve().
-```
-<?php // myServer.php
+If you wish to keep `groupsConfig.php` "clean", you can alternately create a separate PHP script that manually sets up sources, caching, options, and calls Minify::serve().
+
+```php
+// myServer.php
 /**
 * This script implements a Minify server for a single set of sources.
 * If you don't want '.php' in the URL, use mod_rewrite...
 */

+require __DIR__ . '/vendor/autoload.php';
+
 // setup Minify
-set_include_path('path/to/min/lib' . PATH_SEPARATOR . get_include_path());
-require 'Minify.php';
-require 'Minify/Cache/File.php';
-Minify::setCache(new Minify_Cache_File()); // guesses a temp directory
+$cache = new Minify_Cache_File();
+$minify = new Minify($cache);
+$env = new Minify_Env();
+$sourceFactory = new Minify_Source_Factory($env, [], $cache);
+$controller = new Minify_Controller_Files($env, $sourceFactory);

 function src1_fetch() {
    return file_get_contents('http://example.org/javascript.php');
 }

 // setup sources
-$sources = array();
-$sources[] = new Minify_Source(array(
-    'id' => 'source1'
-    ,'getContentFunc' => 'src1_fetch'
-    ,'contentType' => Minify::TYPE_JS    
-    ,'lastModified' => max(
-        filemtime('/path/to/javascript.php')
-        ,filemtime('/path/to/javascript_input.js')
-    )
-));
+$sources = [];
+$sources[] = new Minify_Source([
+    'id' => 'source1',
+    'getContentFunc' => 'src1_fetch',
+    'contentType' => Minify::TYPE_JS,
+    'lastModified' => max(
+        filemtime('/path/to/javascript.php'),
+        filemtime('/path/to/javascript_input.js')
+    ),
+]);
 $sources[] = '//file2.js';
 $sources[] = '//file3.js';

-// setup serve options
-$options = array(
+// setup serve and controller options
+$options = [
    'files' => $sources,
    'maxAge' => 86400,
-);
+];

 // handle request
-Minify::serve('Files', $options);
-```
+$minify->serve($controller, $options);
+```