simply put: Scripts and Proxies - Some technical information about using PIE as a library
PIE can also be used as a library, instead of as a framework. This makes it useful for command-line scripts (such as cron jobs), which you can place in the APP_DIR/scripts/$app folder (the last $app is for namespacing purposes). Each script should start something like:
<?php include(dirname(__FILE__).'/../pie.inc.php'); // put the rest of your script here // and it will be able to use PIE just like you could when it calls your code.
These scripts are meant to be invoked from the command-line interface (CLI). Note that when this happens, there hasn't been any web request, so Pie_Request::url() and Pie_Dispatcher::uri() are both empty.
However, some code in PIE (and often your own apps) needs to know the value of the base URL and controller URL, e.g. to output some links in HTML. Normally, you'd just call Pie_Request::baseUrl(true) to find out the controller URL. But when there was no web request, PIE cannot infer the base and controller URLs from anything.
Therefore, in order for PIE to be used in CLI scripts, you must set the following config fields in APP_DIR/local/app.json:
- pie/web/appRootUrl — this is the base URL
- pie/web/controllerSuffix &mdash this is "index.php" or just ""
Custom front controllers
You can also use PIE as a library in order to have really fast PHP scripts for the web, while still reaping all the benefits of being in a PIE environment (autoloading, events, config, etc.) Just how fast? Well, click here for a demonstration.
Simply put a PHP script into the APP_DIR/web folder, which looks something like
<?php include(dirname(__FILE__).'/pie.inc.php'); // from this point forward, it's as if you're writing a regular PHP script from scratch, // except you already have the PIE config loaded, // you can just start using any class and PIE will autoload it for you, // you can connect to the database connections, and much more. // You can use Pie_Request to get the current URL, URI, base URL, tail or whatever else. // Oh, and the "pie/init" event has already fired by this point.
In some circumstances, you will be faced with a problematic situation, where your server will be accessed through a proxy, or a port forwarding scheme. For example, web browsers may be sending a request to one URL, such as
http://apps.facebook.com/my_app/foo/barbut your server will be receiving a corresponding request for a completely different URL
PIE has a built-in feature to handle these kinds of situations. To use it, simply set the pie/proxies config field to an associative array, where the key is the "destination" URL (the one your server sees in the request) and the value is the "source" URL (the one that the browser sends a request to). PIE will take care of the rest. It uses this array whenever URIs are unrouted to URLs, which has implications for things like hyperlinks in the output.
Complete reference to PHP ON PIE
TODO: include an iframe with PHPDoc-generated reference