diff --git a/developer_manual/app/changelog.rst b/developer_manual/app/changelog.rst index 4a1567043..cfce1f3d9 100644 --- a/developer_manual/app/changelog.rst +++ b/developer_manual/app/changelog.rst @@ -4,39 +4,27 @@ Changelog .. sectionauthor:: Bernhard Posselt -The following changes went into ownCloud 8.1: +The following changes went into ownCloud 8: Breaking changes ================ -None so far - -Features -======== -* There is a new :doc:`OCSResponse and OCSController ` 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 `. -* For more advanced usecases you can now implement the :doc:`CallbackResponse ` interface which allows your response to do its own response rendering -* In addition to passing an array of positional parameters using execute on a mapper method you can now :doc:`pass an associative array ` to use named parameters in SQL queries +* 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! -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: +* `OCP\\AppFramework\\IApi `_: full class. Removal planned in **8.3** +* `OCP\\AppFramework\\IAppContainer `_: methods **getCoreApi** and **log**. Removal planned in **8.3** +* `OCP\\AppFramework\\Controller `_: methods **params**, **getParams**, **method**, **getUploadedFile**, **env**, **cookie**, **render**. Removal planned in **8.3** - * 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**, so the following methods called on the result will no longer work: **fetchRow**, **fetchOne**, **bindParam**. Simply migrate those to their PDO equivalents. +.. note:: Deprecations of constants and methods with namespaces! -9.0 ---- -* The following methods have been moved into the **OCP\\Template::** class instead of being namespaced directly: +* The following methods have been moved into the **OCP\\Template::** class instead of being namespaced directly, Removal planned in **9.0**: * **OCP\\image_path** * **OCP\\mimetype_icon** @@ -46,12 +34,23 @@ This is a deprecation roadmap which lists all current deprecation targets and wi * **OCP\\relative_modified_date** * **OCP\\html_select_options** -* **OCP\\simple_file_size** has been deprecated in favour of **OCP\\Template::human_file_size** -* The **OCP\\PERMISSION_** and **OCP\\FILENAME_INVALID_CHARS** have been moved to **OCP\\Constants::** -* The **OC_GROUP_BACKEND_** and **OC_USER_BACKEND_** have been moved to **OC_Group_Backend::** and **OC_User_Backend::** respectively +* **OCP\\simple_file_size** has been deprecated in favour of **OCP\\Template::human_file_size**. Removal planned in **9.0** +* The **OCP\\PERMISSION_** and **OCP\\FILENAME_INVALID_CHARS** have been moved to **OCP\\Constants::**. Removal planned in **9.0** +* The **OC_GROUP_BACKEND_** and **OC_USER_BACKEND_** have been moved to **OC_Group_Backend::** and **OC_User_Backend::** respectively. Removal planned in **9.0** -8.3 ---- -* `OCP\\AppFramework\\IApi `_: full class -* `OCP\\AppFramework\\IAppContainer `_: methods **getCoreApi** and **log** -* `OCP\\AppFramework\\Controller `_: methods **params**, **getParams**, **method**, **getUploadedFile**, **env**, **cookie**, **render** \ No newline at end of file +Features +======== + +* The :doc:`info.xml ` 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 ` have been added that are related to the app store +* :doc:`Routes ` received the **defaults** parameter to set route variable defaults when not given +* :doc:`Routes ` received the **postfix** parameter to allow multiple urls pointing at the same resource +* :doc:`Menu buttons ` 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 ` have been added +* **OCP\\AppFramework\\HttpResponse** now supports setting cookies +* A :doc:`container ` is now optional +* The :doc:`container ` can now automatically resolve and build classes based on type hints and variable naming conventions +* :doc:`Routes ` can now be returned as an array in **appinfo/routes.php** if the **** tag is set in **appinfo/info.xml**. The :doc:`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 ` have been added to load styles and scripts from your **vendor** folder +* The documentation now features an :doc:`app tutorial ` diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index 76834fa5c..6270194b4 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -14,7 +14,7 @@ To create a controller, simply extend the Controller class and create a method t ` can be rendered by returning a TemplateResponse. A [ - // actual data is in here - ], - // optional - 'statuscode' => 100, - 'status' => 'OK' - ]; - } - - } - -The format parameter works out of the box, no intervention is required. Handling errors --------------- @@ -576,9 +493,9 @@ Each response subclass has access to the **setStatus** method which lets you set -The basic way to run a database query is to use the database connection provided by **OCP\\IDBConnection**. +The basic way to run a database query is to inject the **Db** service. + +.. code-block:: php + + getContainer(); + + /** + * Database Layer + */ + $container->registerService('AuthorDAO', function($c) { + return new AuthorDAO($c->query('ServerContainer')->getDb()); + }); + } + } Inside your database layer class you can now start running queries like: @@ -15,27 +41,27 @@ Inside your database layer class you can now start running queries like: namespace OCA\MyApp\Db; - use OCP\IDBConnection; + use \OCP\IDb; class AuthorDAO { private $db; - public function __construct(IDBConnection $db) { + public function __construct(IDb $db) { $this->db = $db; } public function find($id) { $sql = 'SELECT * FROM `*PREFIX*myapp_authors` ' . 'WHERE `id` = ?'; - $stmt = $this->db->prepare($sql); - $stmt->bindParam(1, $id, \PDO::PARAM_INT); - $stmt->execute(); + $query = $db->prepareQuery($sql); + $query->bindParam(1, $id, \PDO::PARAM_INT); + $result = $query->execute(); - $row = $stmt->fetch(); - - $stmt->closeCursor(); - return $row; + while($row = $result->fetchRow()) { + return $row; + } + $result->closeCursor(); } } @@ -45,7 +71,7 @@ Mappers ======= The aforementioned example is the most basic way write a simple database query but the more queries amass, the more code has to be written and the harder it will become to maintain it. -To generalize and simplify the problem, split code into resources and create an **Entity** and a **Mapper** class for it. The mapper class provides a way to run SQL queries and maps the result onto the related entities. +To generalize and simplify the problem, split code into resources and create an **Entity** and a **Mapper** class for it. The mapper class provides a way to run Sql queries and maps the result onto the related entities. To create a mapper, inherit from the mapper baseclass and call the parent constructor with the following parameters: @@ -61,12 +87,12 @@ To create a mapper, inherit from the mapper baseclass and call the parent constr namespace OCA\MyApp\Db; - use OCP\IDBConnection; - use OCP\AppFramework\Db\Mapper; + use \OCP\IDb; + use \OCP\AppFramework\Db\Mapper; class AuthorMapper extends Mapper { - public function __construct(IDBConnection $db) { + public function __construct(IDb $db) { parent::__construct($db, 'myapp_authors'); } @@ -78,7 +104,7 @@ To create a mapper, inherit from the mapper baseclass and call the parent constr public function find($id) { $sql = 'SELECT * FROM `*PREFIX*myapp_authors` ' . 'WHERE `id` = ?'; - return $this->findEntity($sql, [$id]); + return $this->findEntity($sql, array($id)); } @@ -91,22 +117,14 @@ To create a mapper, inherit from the mapper baseclass and call the parent constr public function authorNameCount($name) { $sql = 'SELECT COUNT(*) AS `count` FROM `*PREFIX*myapp_authors` ' . 'WHERE `name` = ?'; - $stmt = $this->execute($sql, [$name]); + $query = $this->db->prepareQuery($sql); + $query->bindParam(1, $name, \PDO::PARAM_STR); + $result = $query->execute(); - $row = $stmt->fetch(); - $stmt->closeCursor(); - return $row['count']; - } - - - public function authorNameCountNamedArguments($name) { - $sql = 'SELECT COUNT(*) AS `count` FROM `*PREFIX*myapp_authors` ' . - 'WHERE `name` = :name'; - $stmt = $this->execute($sql, [':name' => $name]); - - $row = $stmt->fetch(); - $stmt->closeCursor(); - return $row['count']; + while($row = $result->fetchRow()) { + $result->closeCursor(); + return $row['count']; + } } } @@ -121,7 +139,33 @@ or:: $authorMapper->update($entity); +Mappers should be registered in the constructor to reuse them inside the application: +.. code-block:: php + + getContainer(); + + /** + * Database Layer + */ + $container->registerService('AuthorMapper', function($c) { + return new AuthorMapper($c->query('ServerContainer')->getDb()); + }); + } + } Entities ======== @@ -136,7 +180,7 @@ Entities are data objects that carry all the table's information for one row. Ev // db/author.php namespace OCA\MyApp\Db; - use OCP\AppFramework\Db\Entity; + use \OCP\AppFramework\Db\Entity; class Author extends Entity { @@ -171,7 +215,7 @@ Since all attributes should be protected, getters and setters are automatically // db/author.php namespace OCA\MyApp\Db; - use OCP\AppFramework\Db\Entity; + use \OCP\AppFramework\Db\Entity; class Author extends Entity { protected $stars; @@ -198,7 +242,7 @@ mapping, simply override the **columnToProperty** and **propertyToColumn** metho // db/author.php namespace OCA\MyApp\Db; - use OCP\AppFramework\Db\Entity; + use \OCP\AppFramework\Db\Entity; class Author extends Entity { protected $stars; diff --git a/developer_manual/general/codingguidelines.rst b/developer_manual/general/codingguidelines.rst index 1b9425bb4..39570f6f2 100644 --- a/developer_manual/general/codingguidelines.rst +++ b/developer_manual/general/codingguidelines.rst @@ -30,7 +30,6 @@ The most important labels and their meaning: * #p1-urgent #p2-high #p3-medium #p4-low signify the priority of the bug. * #Junior Job - these are issues which are relatively easy to solve and ideal for people who want to learn how to code in ownCloud * Tags showing the state of the issue or PR, numbered 1-6: - * #1 - Backlog - (please don't use, we prefer using a backlog milestone) * #2 - Triaging - (please don't use, we prefer using the triage label) * #3 - To develop - ready to start development on this @@ -38,7 +37,6 @@ The most important labels and their meaning: * #5 - To Review - ready for review * #6 - Reviewing - review in progress * #7 - To Release - reviewed PR that awaits unfreeze of a branch to get merged - * App tags: #app:files #app:user_ldap #app:files_encryption and so on. These tags indicate the app that is impacted by the issue or which the PR is related to * settings tags: #settings:personal #settings:apps #settings:admin and so on. These tags indicate the settings area that is impacted by the issue or which the PR is related to * db tags: #db:mysql #db:sqlite #db:postgresql and so on. These tags indicate the database that is impacted by the issue or which the PR is related to diff --git a/developer_manual/general/devenv.rst b/developer_manual/general/devenv.rst index 89decf186..eface27f5 100644 --- a/developer_manual/general/devenv.rst +++ b/developer_manual/general/devenv.rst @@ -17,12 +17,10 @@ First `set up your web server and database `_ - .. TODO ON RELEASE: Update version number above on release - * Using the development version from `GitHub`_ which will be explained below. To check out the source from `GitHub`_ you will need to install git (see `Setting up git `_ from the GitHub help) @@ -33,14 +31,14 @@ Gather information about server setup To get started the basic git repositories need to cloned into the web server's directory. Depending on the distribution this will either be * **/var/www** -* **/var/www/html** -* **/srv/http** +* **/var/www/html** +* **/srv/http** Then identify the user and group the web server is running as and the Apache user and group for the **chown** command will either be * **http** -* **www-data** +* **www-data** * **apache** * **wwwrun** @@ -54,7 +52,7 @@ Install the `development tool