fix #889

developer_manual/app/changelog.rst

@@ -4,27 +4,38 @@ Changelog
 
 .. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
 
-The following changes went into ownCloud 8:
+The following changes went into ownCloud 8.1:
 
 
 Breaking changes
 ================
+None so far
+
+Features
+========
+* There is a new :doc:`OCSResponse and OCSController <controllers>` which allows you to easily migrate OCS code to the App Framework. This was added purely for compatibility reasons and the preferred way of doing APIs is using a :doc:`api`
+* You can now stream files in PHP by using the built in :doc:`StreamResponse <controllers>`.
+* For more advanced usecases you can now implement the :doc:`CallbackResponse <controllers>` interface which allows your response to do its own response rendering
 
-* Setting session variables inside a controller requires the **@UseSession** annotation, otherwise the session will be closed
-* Applications not using the AppFramework need now to register their routes as well in **appinfo/routes.php**. See https://mailman.owncloud.org/pipermail/devel/2014-August/000565.html
 
 Deprecations
 ============
+This is a deprecation roadmap which lists all current deprecation targets and will be updated from release to release:
 
 .. note:: Deprecations on interfaces also affect the implementing classes!
 
-* `OCP\\AppFramework\\IApi <https://github.com/owncloud/core/blob/d59c4e832fea87d03d199a3211186a47fd252c32/lib/public/appframework/iapi.php>`_: full class. Removal planned in **8.3**
-* `OCP\\AppFramework\\IAppContainer <https://github.com/owncloud/core/blob/d59c4e832fea87d03d199a3211186a47fd252c32/lib/public/appframework/iappcontainer.php>`_: methods **getCoreApi** and **log**. Removal planned in **8.3**
-* `OCP\\AppFramework\\Controller <https://github.com/owncloud/core/blob/d59c4e832fea87d03d199a3211186a47fd252c32/lib/public/appframework/controller.php>`_: methods **params**, **getParams**, **method**, **getUploadedFile**, **env**, **cookie**, **render**. Removal planned in **8.3**
+10.0
+----
+* **OCP\\IDb**: This interface and the implementing classes will be removed in favor of **OCP\\IDbConnection**. Various layers in between have also been removed to be consistent with the PDO classes. This leads to the following changes:
 
-.. note:: Deprecations of constants and methods with namespaces!
+ * Replace all calls on the db using **getInsertId** with **lastInsertId**
+ * Replace all calls on the db using **prepareQuery** with **prepare**
+ * The **__construct** method of **OCP\\AppFramework\\Db\\Mapper** no longer requires an instance of **OCP\\IDb** but an instance of **OCP\\IDbConnection**
+ * The **execute** method on **OCP\\AppFramework\\Db\\Mapper** no longer returns an instance of **OC_DB_StatementWrapper** but an instance of **PDOStatement**
 
-* The following methods have been moved into the **OCP\\Template::<method>** class instead of being namespaced directly, Removal planned in **9.0**:
+9.0
+---
+* The following methods have been moved into the **OCP\\Template::<method>** class instead of being namespaced directly:
 
  * **OCP\\image_path**
  * **OCP\\mimetype_icon**
@@ -34,23 +45,12 @@ Deprecations
  * **OCP\\relative_modified_date**
  * **OCP\\html_select_options**
 
-* **OCP\\simple_file_size** has been deprecated in favour of **OCP\\Template::human_file_size**. Removal planned in **9.0**
-* The **OCP\\PERMISSION_<permission>** and **OCP\\FILENAME_INVALID_CHARS** have been moved to **OCP\\Constants::<old name>**. Removal planned in **9.0**
-* The **OC_GROUP_BACKEND_<method>** and **OC_USER_BACKEND_<method>** have been moved to **OC_Group_Backend::<method>** and **OC_User_Backend::<method>** respectively. Removal planned in **9.0**
+* **OCP\\simple_file_size** has been deprecated in favour of **OCP\\Template::human_file_size**
+* The **OCP\\PERMISSION_<permission>** and **OCP\\FILENAME_INVALID_CHARS** have been moved to **OCP\\Constants::<old name>**
+* The **OC_GROUP_BACKEND_<method>** and **OC_USER_BACKEND_<method>** have been moved to **OC_Group_Backend::<method>** and **OC_User_Backend::<method>** respectively
 
-Features
-========
-
-* The :doc:`info.xml <info>` file in **appinfo/info.xml** now supports library, command, php and database dependencies that are checked before app installation
-* Various other tags for :doc:`info.xml <info>` have been added that are related to the app store
-* :doc:`Routes <routes>` received the **defaults** parameter to set route variable defaults when not given
-* :doc:`Routes <routes>` received the **postfix** parameter to allow multiple urls pointing at the same resource
-* :doc:`Menu buttons <css>` can now be added easily for navigation entries
-* **OCP\\AppFramework\\DataResponse** can now be used to wrap data and set Http error codes when using responders
-* :doc:`Navigation entry undo and edit styles <css>` have been added
-* **OCP\\AppFramework\\HttpResponse** now supports setting cookies
-* A :doc:`container <container>` is now optional
-* The :doc:`container <container>` can now automatically resolve and build classes based on type hints and variable naming conventions
-* :doc:`Routes <routes>` can now be returned as an array in **appinfo/routes.php** if the **<namespace>** tag is set in **appinfo/info.xml**. The :doc:`container <container>` must either be omitted or available under **appinfo/application.php** and named **OCA\\YourApp\\YourNamespace\\AppInfo\\Application**
-* **vendor_script** and **vendor_style** :doc:`template functions <templates>` have been added to load styles and scripts from your **vendor** folder
-* The documentation now features an :doc:`app tutorial <tutorial>`
+8.3
+---
+* `OCP\\AppFramework\\IApi <https://github.com/owncloud/core/blob/d59c4e832fea87d03d199a3211186a47fd252c32/lib/public/appframework/iapi.php>`_: full class
+* `OCP\\AppFramework\\IAppContainer <https://github.com/owncloud/core/blob/d59c4e832fea87d03d199a3211186a47fd252c32/lib/public/appframework/iappcontainer.php>`_: methods **getCoreApi** and **log**
+* `OCP\\AppFramework\\Controller <https://github.com/owncloud/core/blob/d59c4e832fea87d03d199a3211186a47fd252c32/lib/public/appframework/controller.php>`_: methods **params**, **getParams**, **method**, **getUploadedFile**, **env**, **cookie**, **render**

developer_manual/app/controllers.rst

@@ -14,7 +14,7 @@ To create a controller, simply extend the Controller class and create a method t
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
+    use OCP\AppFramework\Controller;
 
     class AuthorController extends Controller {
 
@@ -34,9 +34,9 @@ To connect a controller and a route the controller has to be registered in the :
     <?php
     namespace OCA\MyApp\AppInfo;
 
-    use \OCP\AppFramework\App;
+    use OCP\AppFramework\App;
 
-    use \OCA\MyApp\Controller\AuthorApiController;
+    use OCA\MyApp\Controller\AuthorApiController;
 
 
     class Application extends App {
@@ -98,7 +98,7 @@ All those parameters can easily be accessed by adding them to the controller met
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
+    use OCP\AppFramework\Controller;
 
     class PageController extends Controller {
 
@@ -117,7 +117,7 @@ It is also possible to set default parameter values by using PHP default method
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
+    use OCP\AppFramework\Controller;
 
     class PageController extends Controller {
 
@@ -150,7 +150,7 @@ would be passed in as the string *'false'* which is not what one would expect. T
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
+    use OCP\AppFramework\Controller;
 
     class PageController extends Controller {
 
@@ -196,7 +196,7 @@ It is possible to pass JSON using a POST, PUT or PATCH request. To do that the *
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
+    use OCP\AppFramework\Controller;
 
     class PageController extends Controller {
 
@@ -218,8 +218,8 @@ Headers, files, cookies and environment variables can be accessed directly from
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\IRequest;
+    use OCP\AppFramework\Controller;
+    use OCP\IRequest;
 
     class PageController extends Controller {
 
@@ -256,8 +256,8 @@ Returning JSON is simple, just pass an array to a JSONResponse:
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http\JSONResponse;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\JSONResponse;
 
     class PageController extends Controller {
 
@@ -275,7 +275,7 @@ Because returning JSON is such an common task, there's even a shorter way how to
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
+    use OCP\AppFramework\Controller;
 
     class PageController extends Controller {
 
@@ -321,8 +321,8 @@ By default there is only a responder for JSON but more can be added easily:
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http\DataResponse;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\DataResponse;
 
     class PageController extends Controller {
 
@@ -357,9 +357,9 @@ Because returning values works fine in case of a success but not in case of fail
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http\DataResponse;
-    use \OCP\AppFramework\Http\Http;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\DataResponse;
+    use OCP\AppFramework\Http\Http;
 
     class PageController extends Controller {
 
@@ -395,8 +395,8 @@ A :doc:`template <templates>` can be rendered by returning a TemplateResponse. A
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http\TemplateResponse;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\TemplateResponse;
 
     class PageController extends Controller {
 
@@ -417,8 +417,8 @@ A redirect can be achieved by returning a RedirectResponse:
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http\RedirectResponse;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\RedirectResponse;
 
     class PageController extends Controller {
 
@@ -437,8 +437,8 @@ A file download can be triggered by returning a DownloadResponse:
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http\DownloadResponse;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\DownloadResponse;
 
     class PageController extends Controller {
 
@@ -462,7 +462,7 @@ Creating a custom XMLResponse class could look like this:
     <?php
     namespace OCA\MyApp\Http;
 
-    use \OCP\AppFramework\Http\Response;
+    use OCP\AppFramework\Http\Response;
 
     class XMLResponse extends Response {
 
@@ -481,6 +481,89 @@ Creating a custom XMLResponse class could look like this:
 
     }
 
+Streamed and lazily rendered responses
+--------------------------------------
+.. versionadded:: 8.1
+
+By default all responses are rendered at once and sent as a string through middleware. In certain cases this is not a desirable behavior, for instance if you want to stream a file in order to save memory. To do that use the now available **OCP\\AppFramework\\Http\\StreamResponse** class:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http\StreamResponse;
+
+    class PageController extends Controller {
+
+        public function downloadXMLFile() {
+            return new StreamResponse('/some/path/to/file.xml');
+        }
+
+    }
+
+
+
+
+If you want to use a custom, lazily rendered response simply implement the interface **OCP\\AppFramework\\Http\\ICallbackResponse** for your response:
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Http;
+
+    use OCP\AppFramework\Http\Response;
+    use OCP\AppFramework\Http\ICallbackResponse;
+
+    class LazyResponse extends Response implements ICallbackResponse {
+
+        public function callback(IOutput $output) {
+            // custom code in here
+        }
+
+    }
+
+.. note:: Because this code is rendered after several usually built in helpers, you need to take care of errors and proper HTTP caching by yourself.
+
+OCS
+---
+.. versionadded:: 8.1
+
+.. note:: This is purely for compatibility reasons. If you are planning to offer an external API, go for a :doc:`api` instead.
+
+In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** baseclass and return your data in the form of an array in the following way:
+
+
+.. code-block:: php
+
+    <?php
+    namespace OCA\MyApp\Controller;
+
+    use OCP\AppFramework\OCSController;
+
+    class ShareController extends OCSController {
+
+        /**
+         * @NoAdminRequired
+         * @NoCSRFRequired
+         * @PublicPage
+         * @CORS
+         */
+        public function getShares() {
+            return [
+                'data' => [
+                    // actual data is in here
+                ],
+                // optional
+                'statuscode' => 100,
+                'status' => 'OK'
+            ];
+        }
+
+    }
+
+The format parameter works out of the box, no intervention is required.
 
 Handling errors
 ---------------
@@ -493,9 +576,9 @@ Each response subclass has access to the **setStatus** method which lets you set
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\AppFramework\Controller;
-    use \OCP\AppFramework\Http;
-    use \OCP\AppFramework\Http\JSONResponse;
+    use OCP\AppFramework\Controller;
+    use OCP\AppFramework\Http;
+    use OCP\AppFramework\Http\JSONResponse;
 
     class AuthorController extends Controller {
 
@@ -536,8 +619,8 @@ A controller method that turns off all checks would look like this:
     <?php
     namespace OCA\MyApp\Controller;
 
-    use \OCP\IRequest;
-    use \OCP\AppFramework\Controller;
+    use OCP\IRequest;
+    use OCP\AppFramework\Controller;
 
     class PageController extends Controller {
 
@@ -551,3 +634,5 @@ A controller method that turns off all checks would look like this:
         }
 
     }
+
+