[Pkg-owncloud-commits] [owncloud-doc] 59/270: add middleware docs

[David Prévot]

This is an automated email from the git hooks/post-receive script.

taffit pushed a commit to branch master
in repository owncloud-doc.

commit 6648f7e3a620659b37a3089a5d87e55ae93462c5
Author: Bernhard Posselt <dev at bernhard-posselt.com>
Date:   Sun May 11 16:42:56 2014 +0200

    add middleware docs
---
 developer_manual/app/middleware.rst | 139 +++++++++++++++++++++++++++++++++++-
 1 file changed, 138 insertions(+), 1 deletion(-)

diff --git a/developer_manual/app/middleware.rst b/developer_manual/app/middleware.rst
index ef74d23..e85ea4d 100644
--- a/developer_manual/app/middleware.rst
+++ b/developer_manual/app/middleware.rst
@@ -1,4 +1,141 @@
+==========
 Middleware
 ==========
 
-.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
\ No newline at end of file
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
+Middleware is logic that is run before and after each request and is modelled after `Django's Middleware system <https://docs.djangoproject.com/en/dev/topics/http/middleware/>`_. It offers the following hooks:
+
+* **beforeController**: This is executed before a controller method is being executed. This allows you to plug additional checks or logic before that method, like for instance security checks
+* **afterException**: This is being run when either the beforeController method or the controller method itself is throwing an exception. The middleware is asked in reverse order to handle the exception and to return a response. If the middleware can't handle the exception, it throws the exception again
+* **afterController**: This is being run after a successful controllermethod call and allows the manipulation of a Response object. The middleware is run in reverse order
+* **beforeOutput**: This is being run after the response object has been rendered and allows the manipulation of the outputted text. The middleware is run in reverse order
+
+To generate your own middleware, simply inherit from the Middleware class and overwrite the methods that should be used.
+
+
+.. code-block:: php
+
+  <?php
+
+  namespace OCA\MyApp\Middleware;
+
+  use \OCP\AppFramework\Middleware;
+
+
+  class CensorMiddleware extends Middleware {
+
+      /**
+       * this replaces "fuck" with "****"" in the output
+       */
+      public function beforeOutput($controller, $methodName, $output){
+          return str_replace($output, 'fuck', '****');
+      }
+
+  }
+
+The middleware can be registered in the :doc:`container` and added using the **registerMiddleware** method:
+
+.. code-block:: php
+
+  <?php
+
+  namespace OCA\MyApp\AppInfo;
+
+  use \OCP\AppFramework\App;
+
+  use \OCA\MyApp\Middleware\CensorMiddleware;
+
+  class MyApp extends App {
+
+
+    /**
+     * Define your dependencies in here
+     */
+    public function __construct(array $urlParams=array()){
+      parent::__construct('myapp', $urlParams);
+
+      $container = $this->getContainer();
+
+      /**
+       * Middleware
+       */
+      $container->registerService('CensorMiddleware', function($c){
+          return new CensorMiddleware();
+      });
+
+      // executed in the order that it is registered
+      $this->registerMiddleware('CensorMiddleware');
+
+
+.. note::
+
+  The order is important! The middleware that is registered first gets run first in the **beforeController** method. For all other hooks, the order is being reversed, meaning: if a middleware is registered first, it gets run last.
+
+
+Parsing annotations 
+===================
+Sometimes its useful to conditionally execute code before or after a controller method. This can be done by defining custom annotations. An example would be to add a custom authentication method or simply add an additional header to the response. To access the parsed annotations, inject the **ControllerMethodReflector** class:
+
+.. code-block:: php
+
+  <?php
+
+  namespace OCA\MyApp\Middleware;
+
+  use \OCP\AppFramework\Middleware;
+  use \OCP\AppFramework\Utility\ControllerMethodReflector;
+  use \OCP\IRequest;
+
+  class HeaderMiddleware extends Middleware {
+
+    private $reflector;
+
+    public function __construct(ControllerMethodReflector $reflector) {
+        $this->reflector = $reflector;
+    }
+
+    /**
+     * Add custom header if @MyHeader is used
+     */
+    public function afterController($controller, $methodName, IResponse $response){
+        if($this->reflector->hasAnnotation('MyHeader')) {
+            $response->addHeader('My-Header', 3);
+        }
+        return $response;
+    }
+
+  }
+
+Now adjust the container to inject the reflector:
+
+.. code-block:: php
+
+  <?php
+
+  namespace OCA\MyApp\AppInfo;
+
+  use \OCP\AppFramework\App;
+
+  use \OCA\MyApp\Middleware\HeaderMiddleware;
+
+  class MyApp extends App {
+
+
+    /**
+     * Define your dependencies in here
+     */
+    public function __construct(array $urlParams=array()){
+      parent::__construct('myapp', $urlParams);
+
+      $container = $this->getContainer();
+
+      /**
+       * Middleware
+       */
+      $container->registerService('HeaderMiddleware', function($c){
+          return new HeaderMiddleware($c->query('ControllerMethodReflector'));
+      });
+
+      // executed in the order that it is registered
+      $this->registerMiddleware('HeaderMiddleware');
\ No newline at end of file

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git