Added docs and example config

doc/PHAR-PLUGINS.md

@@ -0,0 +1,98 @@
+Plugins in Phar Archives
+========================
+
+This is a short guide on how to create single-file portable plugins using
+MakePhar.
+
+
+## The workflow
+
+1.  Your application should export functions that can be called by the plugin
+    on load, such as `myapp_plugin_register` in the example below.
+2.  Locate the .phar plugins to load, and `@include` them one at a time.
+3.  Process the plugins etc that has been registered from the successfully
+    loaded .phar libraries.
+
+
+## Example files
+
+### src/plugin.php
+
+    <?php
+
+    // Prevent standalone use, as it doesn't make sense
+    if (!is_callable('myapp_plugin_register')) {
+        error_log("This is a plugin for MyApp and can't be used standalone");
+        exit(1);
+    }
+
+    // Register the plugin
+    myapp_plugin_register(new MyPlugin\MyPlugin());
+
+### composer.json
+
+    {
+        "autoload": {
+            "files": [ "src/plugin.php" ],
+            "psr-4": { "MyPlugin\\":"src/" }
+        }
+    }
+
+### makephar.sdl
+
+    phar "myplugin.phar" {
+        library;
+        include {
+            dir "src";
+            dir "vendor";
+        }
+        exclude {
+            dir ".git";
+        }
+    }
+
+
+
+## Notes and Considerations
+
+* Try not to bundle unneccesary or duplicate dependencies using composer. It is
+  possible to include multiple composer `autoload.php` files (as is done when 
+  including the phar libraries) but effectively only the first matching loader 
+  will be used. Thus, if you have required a library in the plugin that is also 
+  present in the main application, the main version will be loaded rather than 
+  the plugin version.
+
+
+
+## Problems and Solutions
+
+### Getting the directory of the running phar
+
+You can get the path of the command invoked using `$_SERVER['SCRIPT_NAME']`:
+
+    $root = dirname($_SERVER['SCRIPT_NAME']);
+
+Note that the script *can* be a symbolic link, in which case you need to call
+on `readlink` before you call `dirname`:
+
+    // Get the path of the script, eg. /usr/bin/myapp
+    $root = $_SERVER['SCRIPT_NAME'];
+    // Unwrap the links, eg. /usr/bin/myapp -> ~/myapp/myapp.phar
+    while (readlink($root)) {
+        $root = readlink($root);
+    }
+    // Finally get the directory (~/myapp)
+    $root = dirname($root);
+
+Use this to locate your plugins.
+
+### Find out if running from within a Phar
+
+You can easilly find out if running from within a .phar archive by calling
+`Phar::running()`. 
+
+    if (Phar::running()) { inside_phar(); }
+
+This doesn't make sense to use in phar plugins, as the main application can
+also be in a phar, in which case it will be true even for non-phar plugins.
+

makephar.sdl.dist

@@ -0,0 +1,25 @@
+// Define output file here
+phar "output.phar" {
+
+    // Remove this line to build an executable
+    library;
+
+    // Remove this line to minify source files (recommended9)
+    verbatim;
+
+    // Define the stub called when the phar is executed
+    stub "src/bootstrap.php";
+
+    // Select files/dirs to include
+    include {
+        dir "vendor";
+        dir "src";
+    }
+
+    // Patterns to exclude
+    exclude {
+        dir "Tests";
+        dir ".git";
+    }
+
+}