diff --git a/developer_manual/app/filesystem.rst b/developer_manual/app/filesystem.rst index 70910ec0c..8a54506f4 100644 --- a/developer_manual/app/filesystem.rst +++ b/developer_manual/app/filesystem.rst @@ -1,19 +1,20 @@ Filesystem ========== - ownCloud handling of filesystems is very flexible. A variety of local and remote filesystem types are supported, as well as a variety of hooks and optional features such as encryption and version control. It is important that apps use the correct methods for interacting with files in order to maintain this flexibility. -In some cases using PHP’s internal filesystem functions directly will be sufficient, such as unlink() and mkdir(). Most of the time however it is necessary to use one of ownCloud’s filesystem classes. This documentation assumes that you are working with files stored within a user’s directory (as opposed to ownCloud core files), and therefore need to use OC_Filesystem. +In some cases using PHP’s internal filesystem functions directly will be sufficient, such as **unlink()** and **mkdir()**. Most of the time however it is necessary to use one of ownCloud’s filesystem classes. This documentation assumes that you are working with files stored within a user’s directory (as opposed to ownCloud core files), and therefore need to use **OC_Filesystem**. Using PHP filesystem functions directly --------------------------------------- -An example of when it is approprite to use PHP’s filesystem functions instead of OC_Filesystem is if you are storing temporary files which will not be saved, or whose saving is taken care of by external code. ownCloud’s zip compression class does this (OC_Archive_ZIP), and returns the temporarily stored compressed file so that external code can determine what to do with it. Parts of ownCloud’s installation procedure also fall into this category, as certain files need only be saved temporarily in order to set up more permanent storage options. +An example of when it is approprite to use PHP’s filesystem functions instead of **OC_Filesystem** is if you are storing temporary files which will not be saved, or whose saving is taken care of by external code. ownCloud’s zip compression class does this (**OC_Archive_ZIP**), and returns the temporarily stored compressed file so that external code can determine what to do with it. Parts of ownCloud’s installation procedure also fall into this category, as certain files need only be saved temporarily in order to set up more permanent storage options. Using ownCloud’s filesystem methods ----------------------------------- -Most filesystem interaction should make use of OC_Filesystem. By using the methods within this class you ensure that non-standard and future ownCloud configurations, as well as other filesystem-related apps, will function correctly with your code. Static methods for performing most filesystem operations are provided, including: +Most filesystem interaction should make use of **OC_Filesystem**. By using the methods within this class you ensure that non-standard and future ownCloud configurations, as well as other filesystem-related apps, will function correctly with your code. Static methods for performing most filesystem operations are provided, including: + +.. note:: needs to be reworked into rst class defs * mkdir( $path ) * rmdir( $path ) @@ -43,14 +44,17 @@ Most filesystem interaction should make use of OC_Filesystem. By using the metho * free_space( $path ) * search( $query ) -OC_Filesystem must be initiated before it can be used using the OC_Filesystem::init() method (the class is follows the `singleton pattern`_). init() takes one argument, which is the root directory to be used within the virtual filesystem that OC_Filesystem will work with. +.. note:: **Do not use singletons inside your code!**. It is an antipattern and makes your code hard to test + +OC_Filesystem must be initiated before it can be used using the OC_Filesystem::**init()** method (the class is follows the `singleton pattern`_). **init()** takes one argument, which is the root directory to be used within the virtual filesystem that **OC_Filesystem** will work with. Example: .. code-block:: php - - OC_Filesystem::init( '/' . $user . '/' . $root ); - OC_Filesystem::mkdir( 'test' ); - if ( OC_Filesystem::is_dir('test') ) { echo 'OC_Filesystem is being used correctly'; }`` + + `_ , you can show your objects in a (one-level) hierarchy or you can simply use comma-separated strings. -The API is mainly designed for objects using `vCard`_ or `iCalendar `_ as storage, as they all have a CATEGORIES property from which the categories are extracted, and were they will be saved so that client apps like Apples `iCal `_ and `KDEs Kontact `_ can use them as well. Currently the API is used in the Calendar, Task and Contacts apps, plus recently the 3rd party Journal app. +The API is mainly designed for objects using `vCard`_ or `iCalendar `_ as storage, as they all have a **CATEGORIES** property from which the categories are extracted, and were they will be saved so that client apps like Apples `iCal `_ and `KDEs Kontact `_ can use them as well. Currently the API is used in the Calendar, Task and Contacts apps, plus recently the 3rd party Journal app. -Internally the categories and the object/category relations are stored using the category, the user ID, the object ID and a type identifier to be able uniquely identify where a category "belongs to". The types are similar to the types used in the `Share API `_ for example `contact`, `event` or `task`. +Internally the categories and the object/category relations are stored using the category, the user ID, the object ID and a type identifier to be able uniquely identify where a category "belongs to". The types are similar to the types used in the :doc:`share-api` for example `contact`, `event` or `task`. Besides being used for categories, the API also supports setting objects as favorites. Favorites are simply a separate category internally, but convenience methods for getting/setting objects as favorites are available. @@ -22,10 +22,14 @@ The API can be used both from PHP and via a simple Javascript object. PHP --- +.. todo:: Provide an easier example with less text + As example I will use a very simplified version of how it is used in the Contacts app. The real implementation is optimized for speed and low memory consumption, but there's no need to show that here. First check if any categories have been saved for `contact` objects, if not scan all vCards for categories: +.. todo:: use comments inside the php source to explain the functionality + .. code-block:: php $id, 'name' => $name)` maps. +.. todo:: use a proper rst syntax for class definitions + .. code-block:: php public function idsForCategory($category); @@ -105,9 +115,12 @@ Returns an array of integer object ids. `$category` can again be either the inte Favorites --------- +.. todo:: use a proper rst syntax for class definitions .. code-block:: php + `_ version 3.0