-
Notifications
You must be signed in to change notification settings - Fork 1
Methodical Endpoints
Methodical endpoints allow the composition of static files with executable files while retaining the fine-grain control over application execution that Interchange endpoints offer. While incompatible with non-Interchange compatible products (i.e.: Wordpress, phpBB, etc.), methodical endpoints can provide a significant amount of flexibility to the development flow of a web application and can help modularize code by moving flow control out of your endpoint.php file.
Methodical endpoints are enabled identically to app endpoints in the index.json file, though they use the type "methods" instead of the type "app". Methodical endpoints automatically enable "streaming" support for static files.
Note that while URL caching DOES apply to methodical endpoints, there is (currently) no implementation to cache the particular static or methods file (or specific function) which is associated with a URL within a methodical endpoint. As such, in order to minimize overhead, it is wise for developers to use shallow directory structures for traffic-heavy paths.
When a methodical endpoint is encountered, Interchange begins by looping through each segment of the path following the endpoint's trigger. For instance, if your index.json file defines a methodical endpoint to exist at my-subdomain.example.com/dynamic/methodical/, then the Interchange will start iterating the URL http://my-subdomain.example.com/dynamic/methodical/class/method/parameter at class.
On each iteration, Interchange checks to see if the path provided within the endpoint is actually a file at that depth in the file structure (excluding PHP files). If it is, the file is served as a static file. For instance, Interchange would test if /endpoints/my_endpoint/static/css/default.css exists and load it if the path static/css/default.css was passed.
If no static file exists at the defined path, Interchange instead tests to see whether a directory exists. If it does, the current iteration is halted and Interchange skips to the next iteration (continuing the iteration within that directory).
If neither an appropriate file nor a directory can be found, a 404 is thrown.
If a file exists at the location described by the path with the extra extension .methods.php, then the file is loaded and the methodical endpoint mechanism switches into high gear. For instance, the file /endpoints/my_endpoint/folder/my_methods.methods.php would be triggered by the URL path folder/my_methods.
Upon triggering a PHP methods file, the file is loaded just as any other PHP file would be loaded (i.e.: as in a traditional endpoint). After it is loaded and has fully executed, Interchange tests whether a class named methods has been implemented. If the class is not implemented, further processing is ignored and the methodical flow is exited normally.
On the other hand, if the class IS implemented, a new instance of the class is created and stored. At this point, Interchange stops iterating the URL in search of a file and instead looks for a method to call within the newly instantiated methods object. If there are no more segments to the URL path, then Interchange tests to see if the methods class implements the function __default. This is a non-standard "magic" function that is used if there is no method specified by the URL. If the __default function does not exist in the methods class provided by the loaded methods file, then a 404 is returned.
As a matter of convenience, reserved words in PHP can be safely used as method names by prefixing them with an underscore. Interchange will automatically test for the "escaped" version of a method name if it is unable to find the method as-is.
At this point, once a methods file has been loaded, the methods object has been instantiated, and a method on that object has been chosen, the remainder of the segments of the path specified by the URL are stored as parameters to be passed to the chosen function.
Once all iteration has completed, the method is called with appropriate parameters.
Note: URL query string parameters are not analyzed during routing of methodical endpoints. These can be handled by the individual methods files, the chosen function, or by any other code.
Suppose you want to handle requests that point to directories or the root. For instance, consider the URL http://foo.bar/. If the root of the domain foo.bar was configured to be a methodical endpoint, there would be no URL segments to iterate over, and consequentially---under the rules so far---the request would throw a 404.
Default method files solve this problem. If the end of the path's iteration occurs (or the path iteration never takes place) and a methods file still has not been chosen, Interchange tests to see whether __default.methods.php exists at the deepest path that was attainable. If it does, it is loaded as the methods file. Interchange will then, instead of throwing a 404, proceed with normal execution (wherein a test for an implementation of the methods class takes place, followed by a test for whether the __default method is implemented in the methods class, etc.).
No method may be called on a default method file.
Note that the name __default is reserved by Interchange. The __default.methods.php file cannot be accessed by placing __default in the URL.
If when a methods file is loaded an exception is thrown, Interchange will automatically throw a 404 error.