Permalink
Browse files

Added benefits

  • Loading branch information...
1 parent 5eee81d commit c6ec05a2cfff54187ccfbda69a41f4ce25c9a2ce @CHH committed Mar 6, 2012
Showing with 121 additions and 10 deletions.
  1. +75 −10 README.md
  2. +46 −0 doc/Builder-API.spec.md
View
@@ -11,7 +11,9 @@ Feedback on this, so please stay, read it and send your feedback
to [@yuri41](http://twitter.com/yuri41) or submit
an Issue to the [Issue Tracker](http://github.com/CHH/Pod/issues).
----
+Everything is up for discussion (including the name)!
+
+* * *
> Pod, the socket for holding the bit in a boring tool.
>
@@ -21,17 +23,77 @@ Pod is a simple interface between the PHP Application and the Web
Server. Pod is a port of the [Rack Specification][rack_spec], with
some things done the "PHP way".
-[rack_spec]: http://rack.rubyforge.org/doc/SPEC.html
+* * *
+
+I want to thank Christian Neukirchen for the [Rack
+Specification][rack] and the Python Community for
+[PEP 333][] (and [PEP 3333][]). These are _great_ examples
+of __very well written__ Specs and were a big help and inspiration.
+
+[rack]: http://rack.rubyforge.org/doc/SPEC.html
+[pep 333]: http://www.python.org/dev/peps/pep-0333/
+[pep 3333]: http://www.python.org/dev/peps/pep-3333/
+
+## Mission
+
+ * Pod aims to provide a simple specification
+ for an easy to implement interface between PHP
+ applications and servers.
+ * Provide an interface common to all web frameworks.
+ * Provide an interface for middleware components which can be shared
+ between web frameworks.
+ * A common library which handles web server inconsistencies via
+ Handlers.
+
+### Why $\_SERVER is flawed
+
+The `$_SERVER` variable has one big flaw: it's entirely up to the server
+which keys exist and what the values contain.
+
+> $_SERVER is an array containing information such as headers, paths, and script locations.
+> The entries in this array are created by the web server. There is no guarantee that
+> every web server will provide any of these; servers may omit some,
+> or provide others not listed here.
+>
+> &mdash; <http://www.php.net/$_SERVER>
-Pod's mission is to make applications truly agnostic of the
-web server they run on and provide a unifed interface between
-traditional ways of running PHP web applications (Apache, FCGI) _and_
-Application Servers.
+Most of `$_SERVER` is taken from the CGI Specification though, but
+there ain't any obligatory contract, which **specifies** what must be there
+and what values the application can expect.
+
+### Benefits for Web Server Authors
+
+ * A well though-out and tried Spec, which is also successful in other
+ languages, like Ruby, Python and Perl.
+ * Simple to implement, the environment is a simple PHP array,
+ containing key value pairs.
+ * Makes more efficient implementations possible, because the
+ application can be loaded once and then the callback can be used
+ to pass requests to the application.
+
+### Benefits for Application Authors
+
+ * Provides consistent request data, independent from the underlying Web
+ Server.
+ * Enables framework independent middleware components which
+ can be used to share common components between
+ multiple PHP web applications, for example Routing, Mounting of
+ multiple applications, Session handling and much more.
+ * Enables mending of multiple applications without server
+ configuration.
+
+### Benefits for Framework Authors
+
+ * Framework authors can focus on whatever features which make
+ their framework special, instead of writing the same dumb
+ workarounds for different web servers over and over again.
+ * Common interface to share HTTP components (e.g. Routers) with other
+ frameworks.
## Install
Pod is installed via [Composer](https://github.com/composer/composer).
-To install it add this to your `composer.json`:
+To install it, add this to your `composer.json`:
# composer.json
{
@@ -139,8 +201,11 @@ Then register it in the chain:
$this->register(new FormatOverride);
-### Connecting to an Application Server
+## Servers
+
+Servers should provide a **Handler** to interface with applications.
Handlers should implement a `run` method which takes any Pod callback.
-The `run` method should provide the initial environment and build up a
-HTTP response from the response array returned by the callback.
+The `run` method should provide the initial environment, invoke the
+callback and send a HTTP response back to the client.
+
View
@@ -0,0 +1,46 @@
+
+# Builder API Ideas
+
+## Return Middleware Chain as Array
+
+ # pod_config.php
+ <?php
+
+ use Pod\Component\UrlMapper,
+ Pod\Component\FormatOverride;
+
+ return [
+ new FormatOverride,
+ new UrlMapper([
+ "{^/blog/?(.*)}" => new BlogApplication,
+ "{^/hello/?(.*)}" => new HelloWorldApplication
+ ]),
+ "defaultApp"
+ ];
+
+Pro:
+
+ * Makes order of middleware components within the chain visible.
+
+Con:
+
+ * App could be added in the middle of the chain, which means
+ middleware after the app will not be called. Major WTF.
+
+## Builder Instance as $this
+
+ # pod_config.php
+ <?php
+
+ use Pod\Component\UrlMapper,
+ Pod\Component\FormatOverride;
+
+ $this->register(new FormatOverride);
+
+ $this->register(new UrlMapper([
+ "{^/blog/?(.*)}" => new BlogApplication,
+ "{^/hello/?(.*)}" => new HelloWorldApplication
+ ]);
+
+ # This app is called after all middleware components.
+ $this->run("fooApplication");

0 comments on commit c6ec05a

Please sign in to comment.