Own Cloud Developer Manual

ownCloud Developer Manual
Release 8.1
The ownCloud developers
May 13, 2015
CONTENTS
Table of Contents
1.1 General Contributor Guidelines . . .
1.2 Changelog . . . . . . . . . . . . . .
1.3 Tutorial . . . . . . . . . . . . . . . .
1.4 Create an app . . . . . . . . . . . . .
1.5 Navigation and Pre-App configuration
1.6 App Metadata . . . . . . . . . . . .
1.7 Classloader . . . . . . . . . . . . . .
1.8 Request lifecycle . . . . . . . . . . .
1.9 Routing . . . . . . . . . . . . . . . .
1.10 Middleware . . . . . . . . . . . . . .
1.11 Container . . . . . . . . . . . . . . .
1.12 Controllers . . . . . . . . . . . . . .
1.13 RESTful API . . . . . . . . . . . . .
1.14 Templates . . . . . . . . . . . . . . .
1.15 JavaScript . . . . . . . . . . . . . . .
1.16 CSS . . . . . . . . . . . . . . . . . .
1.17 Translation . . . . . . . . . . . . . .
1.18 Database Schema . . . . . . . . . . .
1.19 Database Access . . . . . . . . . . .
1.20 Configuration . . . . . . . . . . . . .
1.21 Filesystem . . . . . . . . . . . . . .
1.22 Usermanagement . . . . . . . . . . .
1.23 Hooks . . . . . . . . . . . . . . . . .
1.24 Background Jobs (Cron) . . . . . . .
1.25 Logging . . . . . . . . . . . . . . . .
1.26 Testing . . . . . . . . . . . . . . . .
1.27 App Development . . . . . . . . . .
1.28 Android Application Development .
1.29 iOS Application Development . . . .
1.30 Translation . . . . . . . . . . . . . .
1.31 Unit-Testing . . . . . . . . . . . . .
1.32 Theming ownCloud . . . . . . . . .
1.33 Creating and activating a new theme .
1.34 Structure . . . . . . . . . . . . . . .
1.35 How to change images and the logo .
1.36 Testing the new theme out . . . . . .
1.37 Notes for Updates . . . . . . . . . .
1.38 App config . . . . . . . . . . . . . .
1.39 External API . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3
3
23
25
49
49
50
55
56
57
62
65
72
85
87
88
89
97
99
100
104
107
109
111
115
115
117
118
120
129
149
151
154
155
155
155
156
156
157
159
1.40
1.41
1.42
1.43
1.44
ii
OCS Share API . . . . . .

Core Development . . . .
ownCloud Test Pilots . . .
Bugtracker . . . . . . . .
Help and Communication
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
161
164
164
166
175
ownCloud Developer Manual, Release 8.1
If you want to contribute please read the Contributor agreement

App Development Develop apps for
ownCloud and publish on the
ownCloud appstore
Core Development Develop on the

ownCloud internals
Documentation Create and enhance

documentation
ownCloud Test Pilots Help us to test

ownCloud by joining the testing team
Bugtracker Report, triage or fix

bugs to improve quality
Translation Translate
ownCloud
into your language
Help and Communication Help on

IRC, the mailinglist and forum
iOS Application Development

Integration with iOS
Android Application Development

Integrating with Android
CONTENTS
CONTENTS
CHAPTER
ONE
TABLE OF CONTENTS
1.1 General Contributor Guidelines

1.1.1 Community Code of Conduct
Preamble:
In the ownCloud community, participants from all over the world come together to create Free Software for a free
internet. This is made possible by the support, hard work and enthusiasm of thousands of people, including those who
create and use ownCloud software.
This document offers some guidance to ensure ownCloud participants can cooperate effectively in a positive and
inspiring atmosphere, and to explain how together we can strengthen and support each other.
This Code of Conduct is shared by all contributors and users who engage with the ownCloud team and its community
services.
Overview
This Code of Conduct presents a summary of the shared values and common sense thinking in our community. The
basic social ingredients that hold our project together include:
Be considerate
Be respectful
Be collaborative
Be pragmatic
Support others in the community
Get support from others in the community
Our community is made up of several groups of individuals and organizations which can roughly be divided into two
groups:
Contributors, or those who add value to the project through improving ownCloud software and its services
Users, or those who add value to the project through their support as consumers of ownCloud software
This Code of Conduct reflects the agreed standards of behavior for members of the ownCloud community, in any
forum, mailing list, wiki, web site, IRC channel, public meeting or private correspondence within the context of the
ownCloud team and its services. The community acts according to the standards written down in this Code of Conduct
and will defend these standards for the benefit of the community. Leaders of any group, such as moderators of mailing
lists, IRC channels, forums, etc., will exercise the right to suspend access to any person who persistently breaks our
shared Code of Conduct.
Be considerate
Your actions and work will affect and be used by other people and you in turn will depend on the work and actions of
others. Any decision you take will affect other community members, and we expect you to take those consequences
into account when making decisions.
As a contributor, ensure that you give full credit for the work of others and bear in mind how your changes affect
others. It is also expected that you try to follow the development schedule and guidelines.
As a user, remember that contributors work hard on their part of ownCloud and take great pride in it. If you are
frustrated your problems are more likely to be resolved if you can give accurate and well-mannered information to all
concerned.
Be respectful
In order for the ownCloud community to stay healthy its members must feel comfortable and accepted. Treating one
another with respect is absolutely necessary for this. In a disagreement, in the first instance assume that people mean
well.
We do not tolerate personal attacks, racism, sexism or any other form of discrimination. Disagreement is inevitable,
from time to time, but respect for the views of others will go a long way to winning respect for your own view.
Respecting other people, their work, their contributions and assuming well-meaning motivation will make community
members feel comfortable and safe and will result in motivation and productivity.
We expect members of our community to be respectful when dealing with other contributors, users and communities.
Remember that ownCloud is an international project and that you may be unaware of important aspects of other
cultures.
Be collaborative
The Free Software Movement depends on collaboration: it helps limit duplication of effort while improving the quality
of the software produced. In order to avoid misunderstanding, try to be clear and concise when requesting help or
giving it. Remember it is easy to misunderstand emails (especially when they are not written in your mother tongue).
Ask for clarifications if unsure how something is meant; remember the first rule assume in the first instance that
people mean well.
As a contributor, you should aim to collaborate with other community members, as well as with other communities that
are interested in or depend on the work you do. Your work should be transparent and be fed back into the community
when available, not just when ownCloud releases. If you wish to work on something new in existing projects, keep
those projects informed of your ideas and progress.
It may not always be possible to reach consensus on the implementation of an idea, so dont feel obliged to achieve
this before you begin. However, always ensure that you keep the outside world informed of your work, and publish it
in a way that allows outsiders to test, discuss and contribute to your efforts.
Contributors on every project come and go. When you leave or disengage from the project, in whole or in part, you
should do so with pride about what you have achieved and by acting responsibly towards others who come after you
to continue the project.
As a user, your feedback is important, as is its form. Poorly thought out comments can cause pain and the demotivation
of other community members, but considerate discussion of problems can bring positive results. An encouraging word
works wonders.
Chapter 1. Table of Contents
Be pragmatic
ownCloud is a pragmatic community. We value tangible results over having the last word in a discussion. We defend
our core values like freedom and respectful collaboration, but we dont let arguments about minor issues get in the
way of achieving more important results. We are open to suggestions and welcome solutions regardless of their origin.
When in doubt support a solution which helps getting things done over one which has theoretical merits, but isnt
being worked on. Use the tools and methods which help getting the job done. Let decisions be taken by those who do
the work.
Support others in the community
Our community is made strong by mutual respect, collaboration and pragmatic, responsible behavior. Sometimes there
are situations where this has to be defended and other community members need help.
If you witness others being attacked, think first about how you can offer them personal support. If you feel that
the situation is beyond your ability to help individually, go privately to the victim and ask if some form of official
intervention is needed. Similarly you should support anyone who appears to be in danger of burning out, either
through work-related stress or personal problems.
When problems do arise, consider respectfully reminding those involved of our shared Code of Conduct as a first
action. Leaders are defined by their actions, and can help set a good example by working to resolve issues in the spirit
of this Code of Conduct before they escalate.
Get support from others in the community
Disagreements, both political and technical, happen all the time. Our community is no exception to the rule. The goal
is not to avoid disagreements or differing views but to resolve them constructively. You should turn to the community
to seek advice and to resolve disagreements and where possible consult the team most directly involved.
Think deeply before turning a disagreement into a public dispute. If necessary request mediation, trying to resolve
differences in a less highly-emotional medium. If you do feel that you or your work is being attacked, take your time
to breathe through before writing heated replies. Consider a 24 hour moratorium if emotional language is being used
a cooling off period is sometimes all that is needed. If you really want to go a different way, then we encourage you
to publish your ideas and your work, so that it can be tried and tested.
This document is licensed under the Creative Commons Attribution Share Alike 3.0 License.
The authors of this document would like to thank the ownCloud community and those who have worked to create such
a dynamic environment to share in and who offered their thoughts and wisdom in the authoring of this document. We
would also like to thank other vibrant communities that have helped shape this document with their own examples,
especially KDE.
1.1.2 Development Environment

Please follow the steps on this page to set up your development environment.
Set up web server and database
First set up your web server and database (Section: Manual Installation - Prerequisites). .. TODO ON RELEASE:
Update version number above on release
1.1. General Contributor Guidelines
Get the source

There are two ways to obtain ownCloud sources:
Using the stable version
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)
Gather information about server setup
To get started the basic git repositories need to cloned into the web servers directory. Depending on the distribution
this will either be
/var/www
/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
apache
wwwrun
Check out the code
The following commands are using /var/www as the web servers directory and www-data as user name and group.
Install the development tool
After the development tool installation make the directory writable:
sudo chmod o+rw /var/www
Then install ownCloud from git:

ocdev setup --dir /var/www/<folder> base
where <folder> is the folder where you want to install ownCloud.

Adjust rights:
sudo chown -R www-data:www-data /var/www/core/data/
sudo chmod o-rw /var/www
Finally restart the web server (this might vary depending on your distribution):
sudo systemctl restart httpd.service
or:
sudo /etc/init.d/apache2 restart
After the clone Open http://localhost/core (or the corresponding URL) in your web browser to set up your instance.
Enabling debug mode
Note: Do not enable this for production! This can create security problems and is only meant for debugging and
development!
To disable JavaScript and CSS caching debugging has to be enabled in core/config/config.php by adding
this to the end of the file:
DEFINE('DEBUG', true);
Keep the code up-to-date
If you have more than one repository cloned, it can be time consuming to do the same the action to all repositories one
by one. To solve this, you can use the following command template:
find . -maxdepth <DEPTH> -type d -name .git -exec sh -c 'cd "{}"/../ && pwd && <GIT COMMAND>' \;
then, e.g. to pull all changes in all repositories, you only need this:
find . -maxdepth 3 -type d -name .git -exec sh -c 'cd "{}"/../ && pwd && git pull --rebase' \;
or to prune all merged branches, you would execute this:
find . -maxdepth 3 -type d -name .git -exec sh -c 'cd "{}"/../ && pwd && git remote prune origin' \;
It is even easier if you create alias from these commands in case you want to avoid retyping those each time you need
them.
1.1.3 Security Guidelines

This guideline highlights some of the most common security problems and how to prevent them. Please review your
app if it contains any of the following security holes.
Note: Program defensively: for instance always check for CSRF or escape strings, even if you do not need it. This
prevents future problems where you might miss a change that leads to a security hole.
Note:
All App Framework security features depend on the call of the controller through
OCA\AppFramework\App::main. If the controller method is executed directly, no security checks are
being performed!
SQL Injection
SQL Injection occurs when SQL query strings are concatenated with variables.
To prevent this, always use prepared queries:
<?php
$sql = 'SELECT * FROM ùsers` WHERE ìd` = ?';
$query = \OCP\DB::prepare($sql);
$params = array(1);
$result = $query->execute($params);
If the App Framework is used, write SQL queries like this in the a class that extends the Mapper:
<?php
// inside a child mapper class
$sql = 'SELECT * FROM ùsers` WHERE ìd` = ?';
$params = array(1);
$result = $this->execute($sql, $params);
Cross site scripting

Cross site scripting happens when user input is passed directly to templates. A potential attacker might be able to
inject HTML/JavaScript into the page to steal the users session, log keyboard entries, even perform DDOS attacks on
other websites or other malicious actions.
Despite of the fact that ownCloud uses Content-Security-Policy to prevent the execution of inline JavaScript code
developers are still required to prevent XSS. CSP is just another layer of defense that is not implemented in all web
browsers.
To prevent XSS in your app you have to sanitize the templates and all JavaScripts which performs a DOM manipulation.
Templates
Lets assume you use the following example in your application:

<?php
echo $_GET['username'];
An attacker might now easily send the user a link to:

app.php?username=<script src="attacker.tld"></script>
to overtake the user account. The same problem occurs when outputting content from the database or any other
location that is writable by users.
Another attack vector that is often overlooked is XSS in href attributes. HTML allows to execute javascript in href
attributes like this:
<a href="javascript:alert('xss')">
To prevent XSS in your app, never use echo, print() or <%= - use p() instead which will sanitize the input. Also
validate URLs to start with the expected protocol (starts with http for instance)!
Note: Should you ever require to print something unescaped, double check if it is really needed. If there is no other
way (e.g. when including of subtemplates) use print_unescaped with care.
JavaScript
Avoid manipulating the HTML directly via JavaScript, this often leads to XSS since people often forget to sanitize
variables:
var html = '<li>' + username + '</li>"';
If you really want to use JavaScript for something like this use escapeHTML to sanitize the variables:
var html = '<li>' + escapeHTML(username) + '</li>';
An even better way to make your app safer is to use the jQuery built-in function $.text() instead of $.html().
DONT
messageTd.html(username);
DO
messageTd.text(username);
It may also be wise to choose a proper JavaScript framework like AngularJS which automatically handles the
JavaScript escaping for you.
Clickjacking
Clickjacking tricks the user to click into an invisible iframe to perform an arbitrary action (e.g. delete an user account)
To prevent such attacks ownCloud sends the X-Frame-Options header to all template responses. Dont remove this
header if you dont really need it!
This is already built into ownCloud if OC_Template.
Code executions / File inclusions
Code Execution means that an attacker is able to include an arbitrary PHP file. This PHP file runs with all the privileges
granted to the normal application and can do an enormous amount of damage.
Code executions and file inclusions can be easily prevented by never allowing user-input to run through the following
functions:
include()
require()
require_once()
eval()
fopen()
Note: Also never allow the user to upload files into a folder which is reachable from the URL!
DONT
<?php
require("/includes/" . $_GET['file']);
Note: If you have to pass user input to a potential dangerous, double check to be sure that there is no other way. If it
is not possible otherwise sanitize every user parameter and ask people to audit your sanitize function.
Directory Traversal
Very often developers forget about sanitizing the file path (removing all and /), this allows an attacker to traversal
through directories on the server which opens several potential attack vendors including privilege escalations, code
executions or file disclosures.
DONT
<?php
$username = OC_User::getUser();
fopen("/data/" . $username . "/" . $_GET['file'] . ".txt");
DO
<?php
$username = OC_User::getUser();
$file = str_replace(array('/', '\\'), '', $_GET['file']);
fopen("/data/" . $username . "/" . $file . ".txt");
Note: PHP also interprets the backslash () in paths, dont forget to replace it too!
Shell Injection
Shell Injection occurs if PHP code executes shell commands (e.g. running a latex compiler). Before doing this, check
if there is a PHP library that already provides the needed functionality. If you really need to execute a command be
aware that you have to escape every user parameter passed to one of these functions:
exec()
shell_exec()
passthru()
proc_open()
system()
popen()
Note: Please require/request additional programmers to audit your escape function.
10
Without escaping the user input this will allow an attacker to execute arbitrary shell commands on your server.
PHP offers the following functions to escape user input:
escapeshellarg(): Escape a string to be used as a shell argument
escapeshellcmd(): Escape shell metacharacters
DONT
<?php
system('ls '.$_GET['dir']);
DO
<?php
system('ls '.escapeshellarg($_GET['dir']));
Auth bypass / Privilege escalations

Auth bypass/privilege escalations happens when a user is able to perform not authorized actions.
ownCloud offers three simple checks:
OCP\JSON::checkLoggedIn(): Checks if the logged in user is logged in
OCP\JSON::checkAdminUser(): Checks if the logged in user has admin privileges
OCP\JSON::checkSubAdminUser(): Checks if the logged in user has group admin privileges
Using the App Framework, these checks are already automatically performed for each request and have to be explicitly
turned off by using annotations above your controller method, see Controllers.
Additionally always check if the user has the right to perform that action. (e.g. a user should not be able to delete
other users bookmarks).
Sensitive data exposure
Always store user data or configuration files in safe locations, e.g. owncloud/data/ and not in the webroot where they
can be accessed by anyone using a web browser.
Cross site request forgery
Using CSRF one can trick a user into executing a request that he did not want to make. Thus every POST and GET
request needs to be protected against it. The only places where no CSRF checks are needed are in the main template,
which is rendering the application, or in externally callable interfaces.
Note: Submitting a form is also a POST/GET request!
To prevent CSRF in an app, be sure to call the following method at the top of all your files:
<?php
OCP\JSON::callCheck();
If you are using the App Framework, every controller method is automatically checked for CSRF unless you explicitly
exclude it by setting the @NoCSRFRequired annotation before the controller method, see Controllers
11
Unvalidated redirects
This is more of an annoyance than a critical security vulnerability since it may be used for social engineering or
phishing.
Always validate the URL before redirecting if the requested URL is on the same domain or an allowed ressource.
DONT
<?php
header('Location:'. $_GET['redirectURL']);
DO
<?php
header('Location: http://www.example.com'. $_GET['redirectURL']);
Getting help
If you need help to ensure that a function is secure please ask on our mailing list or on our IRC channel #owncloud-dev
on irc.freenode.net.
1.1.4 Coding Style & General Guidelines

General
Ideally, discuss your plans on the mailing list to see if others want to work with you on it
We use Github, please get an account there and clone the repositories you want to work on
Fixes go directly to master, nevertheless they need to be tested thoroughly.
New features are always developed in a branch and only merged to master once they are fully done.
Software should work. We only put features into master when they are complete. Its better to not have a feature
instead of having one that works poorly.
It is best to start working based on an issue - create one if there is none. You describe what you want to do, ask
feedback on the direction you take it and take it from there.
When you are finished, use the merge request function on Github to create a pull request. The other developers
will look at it and give you feedback. You can signify that your PR is ready for review by adding the label 5 ready for review to it. You can also post your merge request to the mailing list to let people know. See the code
review page for more information
It is key to keep changes separate and small. The bigger and more hairy a PR grows, the harder it is to get it in.
So split things up where you can in smaller changes - if you need a small improvement like a API addition for a
big feature addition, get it in first rather than adding it to the big piece of work!
Decisions are made by consensus. We strive for making the best technical decisions and as nobody can know
everything, we collaborate. That means a first negative comment might not be the final word, neither is positive
feedback an immediate GO. ownCloud is built out of modular pieces (apps) and maintainers have a strong
influence. In case of disagreement we consult other seasoned contributors.
We need a signed contributor agreement from you to commit into the core repository (apps dont need that). All
the information is in our Contributor agreement FAQ.
12
Labels
We assign labels to issues and pull requests to make it easy to find them and to signal what needs to be done. Some
of these are assigned by the developers, others by QA, bug triagers, project lead or maintainers and so on. It is not
desired that users/reporters of bugs assign labels themselves, unless they are developers/contributors to ownCloud.
The most important labels and their meaning:
#bug - this issue is a bug
#enhancement - this issue is a feature request/idea for improvement of ownCloud
#design - this needs help from the design team or is a design-related issue/pull request
#sharing - this issue or PR is related to sharing
#technical debt - this issue or PR is about technical debt
#sev1-critical #sev2-high #sev3-medium #sev4-low signify how important the bug is.
#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 dont use, we prefer using a backlog milestone)
#2 - Triaging - (please dont use, we prefer using the triage label)
#3 - To develop - ready to start development on this
#4 - Developing - development in progress
#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_versions 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
browser tags: #browser:ie #browser:safari and so on. These tags indicate the browser that is impacted by the
issue or which the PR is related to
#triage - this issue has to be triaged
#needs info - this issue needs further information from the reporter, see triaging old tag is #clarification request,
please dont use that one anymore.
#discussion - this issue needs to be discussed
#security - this is a security related issue
#windows server - this is related to windows server
#research - this item requires some research before it can continue
#packaging - this is related to packaging
13
#theming - refers to theming issues or improvements

#l10n - refers to translation issues or improvements
#release note - relevant for the release notes
#privacy - refers to issues that might lead to privacy concerns
#wont fix - This problem wont be fixed (can be for a wide variety of reasons...)
If you want a label not in the list above, please first discuss on the mailing list.
Coding
Maximum line-length of 80 characters
Use tabs to indent
A tab is 4 spaces wide
Opening braces of blocks are on the same line as the definition
Quotes: for everything, for HTML attributes (<p class=my_class>)
End of Lines : Unix style (LF / n) only
No global variables or functions
Unit tests
HTML should be HTML5 compliant
Check these database performance tips
When you git pull, always git pull --rebase to avoid generating extra commits like: merged master
into master
User interface
Software should get out of the way. Do things automatically instead of offering configuration options.
Software should be easy to use. Show only the most important elements. Secondary elements only on hover or
via Advanced function.
User data is sacred. Provide undo instead of asking for confirmation - which might be dismissed
The state of the application should be clear. If something loads, provide feedback.
Do not adapt broken concepts (for example design of desktop apps) just for the sake of consistency. We aim to
provide a better interface, so lets find out how to do that!
Regularly reset your installation to see how the first-run experience is like. And improve it.
Ideally do usability testing to know how people use the software.
For further UX principles, read Alex Faaborg from Mozilla.
PHP
The ownCloud coding style guide is based on PEAR Coding Standards.
Always use:
14
<?php
at the start of your php code. The final closing:

?>
should not be used at the end of the file due to the possible issue of sending white spaces.
Comments
All API methods need to be marked with PHPDoc markup. An example would be:
<?php
/**
* Description what method does
* @param Controller $controller the controller that will be transformed
* @param API $api an instance of the API class
* @throws APIException if the api is broken
* @since 4.5
* @return string a name of a user
*/
public function myMethod(Controller $controller, API $api) {
// ...
}
Objects, Functions, Arrays & Variables
Use Pascal case for Objects, Camel case for functions and variables. If you set a default function/method parameter,
do not use spaces. Do not prepend private class members with underscores.
class MyClass {
}
function myFunction($default=null) {
}
$myVariable = 'blue';
$someArray = array(
'foo' => 'bar',
'spam' => 'ham',
);
?>
Operators
Use === and !== instead of == and !=.

15
Heres why:
<?php
var_dump(0 == "a"); // 0 == 0 -> true
var_dump("1" == "01"); // 1 == 1 -> true
var_dump("10" == "1e1"); // 10 == 10 -> true
var_dump(100 == "1e2"); // 100 == 100 -> true
?>
Control Structures
Always use { } for one line ifs

Split long ifs into multiple lines
Always use break in switch statements and prevent a default block with warnings if it shouldnt be accessed
<?php
// single line if
if ($myVar === 'hi') {
$myVar = 'ho';
} else {
$myVar = 'bye';
}
// long ifs
if (
$something === 'something'
|| $condition2
&& $condition3
) {
// your code
}
// for loop
for ($i = 0; $i < 4; $i++) {
// your code
}
switch ($condition) {
case 1:
// action1
break;
case 2:
// action2;
break;
default:
// defaultaction;
break;
}
?>
16
Unit tests
Unit tests must always extend the \Test\TestCase class, which takes care of cleaning up the installation after the
test.
If a test is run with multiple different values, a data provider must be used. The name of the data provider method
must not start with test and must end with Data.
<?php
namespace Test;
class Dummy extends \Test\TestCase {
public function dummyData() {
return array(
array(1, true),
array(2, false),
);
}
/**
* @dataProvider dummyData
*/
public function testDummy($input, $expected) {
$this->assertEquals($expected, \Dummy::method($input));
}
}
JavaScript
In general take a look at JSLint without the whitespace rules.
Use a js/main.js or js/app.js where your program is started
Complete every statement with a ;
Use var to limit variable to local scope
To keep your code local, wrap everything in a self executing function. To access global objects or export things
to the global namespace, pass all global objects to the self executing function.
Use JavaScript strict mode
Use a global namespace object where you bind publicly used functions and objects to
DO:
// set up namespace for sharing across multiple files
var MyApp = MyApp || {};
(function(window, $, exports, undefined) {
'use strict';
// if this function or object should be global, attach it to the namespace
exports.myGlobalFunction = function(params) {
return params;
};
})(window, jQuery, MyApp);
17
DONT (Seriously):
// This does not only make everything global but you're programming
// JavaScript like C functions with namespaces
MyApp = {
myFunction:function(params) {
return params;
},
...
};
Objects & Inheritance
Try to use OOP in your JavaScript to make your code reusable and flexible.
This is how youd do inheritance in JavaScript:
// create parent object and bind methods to it
var ParentObject = function(name) {
this.name = name;
};
ParentObject.prototype.sayHello = function() {
console.log(this.name);
}
// create childobject, call parents constructor and inherit methods

var ChildObject = function(name, age) {
ParentObject.call(this, name);
this.age = age;
};
ChildObject.prototype = Object.create(ParentObject.prototype);
// overwrite parent method
ChildObject.prototype.sayHello = function() {
// call parent method if you want to
ParentObject.prototype.sayHello.call(this);
console.log('childobject');
};
var child = new ChildObject('toni', 23);
// prints:
// toni
// childobject
child.sayHello();
Objects, Functions & Variables
Use Pascal case for Objects, Camel case for functions and variables.
18
var MyObject = function() {

this.attr = "hi";
};
var myFunction = function() {
return true;
};
var myVariable = 'blue';
var objectLiteral = {
value1: 'somevalue'
};
Operators
Use === and !== instead of == and !=.

Heres why:
'' == '0'
0 == ''
0 == '0'
// false
// true
// true
false == 'false'
false == '0'
// false
// true
false == undefined
false == null
null == undefined
// false
// false
// true
' \t\r\n ' == 0
// true
Control Structures
Always use { } for one line ifs

Split long ifs into multiple lines
Always use break in switch statements and prevent a default block with warnings if it shouldnt be accessed
DO:
// single line if
if (myVar === 'hi') {
myVar = 'ho';
} else {
myVar = 'bye';
}
// long ifs
if (
something === 'something'
|| condition2
&& condition3
19
) {
// your code
}
// for loop
for (var i = 0; i < 4; i++) {
// your code
}
// switch
switch (value) {
case 'hi':
// yourcode
break;
default:
console.warn('Entered undefined default block in switch');
break;
}
CSS
Take a look at the Writing Tactical CSS & HTML video on YouTube.
Dont bind your CSS too much to your HTML structure and try to avoid IDs. Also try to make your CSS reusable by
grouping common attributes into classes.
DO:
.list {
list-style-type: none;
}
.list > .list_item {
display: inline-block;
}
.important_list_item {
color: red;
}
DONT:
#content .myHeader ul {
list-style-type: none;
}
#content .myHeader ul li.list_item {
color: red;
display: inline-block;
}
TBD
20
1.1.5 Performance Considerations

This document introduces some common considerations and tips on improving performance of ownCloud. Speed of
ownCloud is important - nobody likes to wait and often, what is just slow for a small amount of data will become
unusable with a large amount of data. Please keep these tips in mind when developing for ownCloud and consider
reviewing your app to make it faster.
Database performance
The database plays an important role in ownCloud performance. The general rule is: database queries are very bad
and should be avoided if possible. The reasons for that are:
Roundtrips: Bigger ownCloud installations have the database not installed on the application server but on
a remote dedicated database server. The problem is that database queries then go over the network. These
roundtrips can add up significantly if you have a lot of queries.
Speed. A lot of people think that databases are fast. This is not always true if you compare it with handing data
internally in PHP or in the filesystem or even use key/value based storages. So every developer should always
double check if the database is really the best place for the data.
Scalability. If you have a big ownCloud cluster setup you usually have several ownCloud/webservers in parallel
and a central database and a central storage. This means that everything that happens on the ownCloud/PHP side
can parallelize and can be scaled. Stuff that is happening in the database and in the storage is critical because it
only exists once and cant be scaled so easily.
We can reduce the load on the database by:
1. Making sure that every query uses an index.
2. Reducing the overall numbers of queries.
3. If you are familiar with cache invalidation you can try caching query results in PHP.
There a several ways to monitor which queries are actually executed on the database.
With MySQL is is very easy with just a bit of configuration:
1. Slow query log.
If you put this into your my.cnf file, every query that takes longer than one second is logged to a logfile:
log_slow_queries = 1
log_slow_queries = /var/log/mysql/mysql-slow.log
long_query_time=1
If a query takes more than a second we have a serious problem of course.

/var/log/mysql/mysql-slow.log while using ownCloud.
You can watch it with tail -f
2. log all queries.

If you reduce the long_query_time to zero than every statement is logged. This is super helpful to see what is going
on. Just do a tail -f on the logfile and click around in the interface or access the WebDAV interface:
long_query_time=0
3. log queries without an index.
21
If you increase the long_query_time to 100 and add log-queries-not-using-indexes, all the queries that are not using
an index are logged. Every query should always use an index. So ideally there should be no output:
log-queries-not-using-indexes
long_query_time=100
Measuring performance
If you do bigger changes in the architecture or the database structure you should always double check the positive or
negative performance impact. There are a few nice small scripts that can be used for this.
The recommendation is to automatically do 10000 PROPFINDs or file uploads, measure the time and compare the
time before and after the change.
Getting help
If you need help with performance or other issues please ask on our mailing list or on our IRC channel #owncloud-dev
on irc.freenode.net.
1.1.6 Debugging
Debug mode
When debug mode is enabled ownCloud, a variety of debugging features are enabled - see debugging documentation.
Add the following to the very end of /config/config.php to enable it:
define( "DEBUG", 1);
Identifying errors
ownCloud uses custom error PHP handling that prevents errors being printed to web server log files or command line
output. Instead, errors are generally stored in ownClouds own log file, located at: /data/owncloud.log
Debugging variables
You should use exceptions if you need to debug variable values manually, and not alternatives like trigger_error()
(which may not be logged).
e.g.:
<?php throw new \Exception( "\$user = $user" ); // should be logged in ownCloud ?>
not:
<?php trigger_error( "\$user = $user" ); // may not be logged anywhere ?>
To disable custom error handling in ownCloud (and have PHP and your web server handle errors instead), see Debug
mode.
22
Debugging Javascript
By default all Javascript files in ownCloud are minified (compressed) into a single file without whitespace. To prevent
this, see Debug mode.
Debugging HTML and templates
By default ownCloud caches HTML generated by templates. This may prevent changes to app templates, for example,
from being applied on page refresh. To disable caching, see Debug mode.
Using alternative app directories
It may be useful to have multiple app directories for testing purposes, so you can conveniently switch between different
versions of applications. See the configuration file documentation for details.
1.1.7 Backporting
General
We backport important fixes and improvements from the current master release to get them to our users faster.
Process
We mostly consider bug fixes for back porting. Occasionally, important changes to the API can be backported to make
it easier for developers to keep their apps working between major releases. If you think a pull request (PR) is relevant
for the stable release, go through these steps:
1. Make sure the PR is merged to master
2. Ask Frank (@karlitschek) and Thomas (@deepdiver1975) if the code should be backported and add the label
backport-request to the PR
3. If Frank or Thomas say yes then create a new branch based on the respective stable branch (stable7 for the 7.0.x
series), cherry-pick the needed commits to that branch and create a PR on GitHub.
4. Specify the corresponding milestone for that series (7.0.x-next-maintenance for the 7.0.x series) to this PR and
reference the original PR in there. This enables the QA team to find the backported items for testing and having
the original PR with detailed description linked.
Note: Before each patch release there is a freeze to be able to test everything as a whole without pulling in new
changes. This freeze is announced on the owncloud-devel mailinglist. While this freeze is active a backport isnt
allowed and has to wait for the next patch release.
The QA team will try to reproduce all the issues with the X.Y.Z-next-maintenance milestone on the relevant release
and verify it is fixed by the patch release (and doesnt cause new problems). Once the patch release is out, the post-fix
-next-maintenance is removed and a new -next-maintenance milestone is created for that series.
1.2 Changelog
The following changes went into ownCloud 8.1:
1.2. Changelog
23
1.2.1 Breaking changes

None so far
1.2.2 Features
There is a new 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
RESTful API
You can now stream files in PHP by using the built in StreamResponse.
For more advanced usecases you can now implement the CallbackResponse interface which allows your response to do its own response rendering
1.2.3 Deprecations
This is a deprecation roadmap which lists all current deprecation targets and will be updated from release to release.
This lists the version when a specific method or class will be removed.
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:
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
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
OCP\preview_icon
OCP\publicPreview_icon
OCP\human_file_size
OCP\relative_modified_date
OCP\html_select_options
24
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
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
8.1
\OC\Preferences and \OC_Preferences
1.3 Tutorial
This tutorial will outline how to create a very simple notes app. The finished app is available on GitHub.
1.3.1 Setup
After the development tool has been installed the development environment needs to be set up. This can be done by
either downloading the zip from the website or cloning it directly from GitHub:
ocdev setup core --dir owncloud
--branch $BRANCH
Note: $BRANCH is the desired ownCloud branch (e.g. stable7 for ownCloud 7, stable8 for ownCloud 8, etc)
First you want to enable debug mode to get proper error messages. To do that add DEFINE(DEBUG, true); at the
end of the owncloud/config/config.php file:
echo "\nDEFINE('DEBUG', true);" >> owncloud/config/config.php
Note: PHP errors are logged to owncloud/data/owncloud.log

Now open another terminal window and start the development server:
cd owncloud
php -S localhost:8080
Afterwards the app can be created in the apps folder:

cd apps
ocdev startapp OwnNotes
1.3. Tutorial
25
This creates a new folder called ownnotes. Now access and set up ownCloud through the webinterface at
http://localhost:8080 and enable the OwnNotes application on the apps page.
The first basic app is now available at http://localhost:8080/index.php/apps/ownnotes/
1.3.2 Routes & Controllers

A typical web application consists of server side and client side code. The glue between those two parts are the URLs.
In case of the notes app the following URLs will be used:
GET /: Returns the interface in HTML
GET /notes: Returns a list of all notes in JSON
GET /notes/1: Returns a note with the id 1 in JSON
DELETE /notes/1: Deletes a note with the id 1
POST /notes: Creates a new note by passing in JSON
PUT /notes/1: Updates a note with the id 1 by passing in JSON
On the client side we can call these URLs with the following jQuery code:
// example for calling the PUT /notes/1 URL
var baseUrl = OC.generateUrl('/apps/ownnotes');
var note = {
title: 'New note',
content: 'This is the note text'
};
var id = 1;
$.ajax({
url: baseUrl + '/notes/' + id,
type: 'PUT',
contentType: 'application/json',
data: JSON.stringify(note)
}).done(function (response) {
// handle success
}).fail(function (response, code) {
// handle failure
});
On the server side we need to register a callback that is executed once the request comes in. The callback itself will
be a method on a controller and the controller will be connected to the URL with a route. The controller and route for
the page are already set up in ownnotes/appinfo/routes.php:
<?php
return ['routes' => [
['name' => 'page#index', 'url' => '/', 'verb' => 'GET']
]];
This route calls the controller OCA\OwnNotes\PageController->index() method which is defined in ownnotes/controller/pagecontroller.php. The controller returns a template, in this case ownnotes/templates/main.php:
Note: @NoAdminRequired and @NoCSRFRequired in the comments above the method turn off security checks, see
Controllers
26
<?php
namespace OCA\OwnNotes\Controller;
use OCP\IRequest;
use OCP\AppFramework\Http\TemplateResponse;
use OCP\AppFramework\Controller;
class PageController extends Controller {
public function __construct($AppName, IRequest $request){
parent::__construct($AppName, $request);
}
/**
* @NoAdminRequired
* @NoCSRFRequired
*/
public function index() {
return new TemplateResponse('ownnotes', 'main');
}
}
Since the route which returns the intial HTML has been taken care of, the controller which handles the AJAX requests
for the notes needs to be set up. Create the following file: ownnotes/controller/notecontroller.php with the following
content:
<?php
use OCP\IRequest;
class NoteController extends Controller {
public function __construct($AppName, IRequest $request){
}
/**
* @NoAdminRequired
*/
// empty for now
}
/**
* @NoAdminRequired
*
* @param int $id
*/
public function show($id) {
// empty for now
}
/**
* @NoAdminRequired
1.3. Tutorial
27
*
* @param string $title
* @param string $content
*/
public function create($title, $content) {
// empty for now
}
/**
* @NoAdminRequired
*
* @param int $id
*/
public function update($id, $title, $content) {
// empty for now
}
/**
* @NoAdminRequired
*
* @param int $id
*/
public function destroy($id) {
// empty for now
}
}
Note: The parameters are extracted from the request body and the url using the controller methods variable names.
Since PHP does not support type hints for primitive types such as ints and booleans, we need to add them as annotations
in the comments. In order to type cast a parameter to an int, add @param int $parameterName
Now the controller methods need to be connected to the corresponding URLs in the ownnotes/appinfo/routes.php
file:
<?php
return [
'routes' =>
['name'
['name'
['name'
['name'
['name'
['name'
]
];
[
=>
=>
=>
=>
=>
=>
'page#index', 'url' => '/', 'verb' => 'GET'],

'note#index', 'url' => '/notes', 'verb' => 'GET'],
'note#show', 'url' => '/notes/{id}', 'verb' => 'GET'],
'note#create', 'url' => '/notes', 'verb' => 'POST'],
'note#update', 'url' => '/notes/{id}', 'verb' => 'PUT'],
'note#destroy', 'url' => '/notes/{id}', 'verb' => 'DELETE']
Since those 5 routes are so common, they can be abbreviated by adding a resource instead:
<?php
return [
'resources' => [
'note' => ['url' => '/notes']
],
28
'routes' => [
['name' => 'page#index', 'url' => '/', 'verb' => 'GET']
]
];
1.3.3 Database
Now that the routes are set up and connected the notes should be saved in the database. To do that first create a
database schema by creating ownnotes/appinfo/database.xml:
<database>
<name>*dbname*</name>
<create>true</create>
<overwrite>false</overwrite>
<charset>utf8</charset>
<table>
<name>*dbprefix*ownnotes_notes</name>
<declaration>
<field>
<name>id</name>
<type>integer</type>
<notnull>true</notnull>
<autoincrement>true</autoincrement>
<unsigned>true</unsigned>
<primary>true</primary>
<length>8</length>
</field>
<field>
<name>title</name>
<type>text</type>
<length>200</length>
<default></default>
</field>
<field>
<name>user_id</name>
<type>text</type>
<default></default>
</field>
<field>
<name>content</name>
<type>clob</type>
<default></default>
</field>
</declaration>
</table>
</database>
To create the tables in the database, the version tag in ownnotes/appinfo/info.xml needs to be increased:
<?xml version="1.0"?>
<info>
1.3. Tutorial
29
<id>ownnotes</id>
<name>Own Notes</name>
<description>My first ownCloud app</description>
<licence>AGPL</licence>
<author>Your Name</author>
<version>0.0.2</version>
<namespace>OwnNotes</namespace>
<category>other</category>
<dependencies>
<owncloud min-version="8" />
</dependencies>
</info>
Reload the page to trigger the database migration.

Now that the tables are created we want to map the database result to a PHP object to be able to control data. First
create an entity in ownnotes/db/note.php:
<?php
namespace OCA\OwnNotes\Db;
use JsonSerializable;
use OCP\AppFramework\Db\Entity;
class Note extends Entity implements JsonSerializable {
protected $title;
protected $content;
protected $userId;
public function jsonSerialize() {
return [
'id' => $this->id,
'title' => $this->title,
'content' => $this->content
];
}
}
Note: A field id is automatically set in the Entity base class

We also define a jsonSerializable method and implement the interface to be able to transform the entity to JSON
easily.
Entities are returned from so called Mappers. Lets create one in ownnotes/db/notemapper.php and add a find and
findAll method:
<?php
namespace OCA\OwnNotes\Db;
use OCP\IDb;
use OCP\AppFramework\Db\Mapper;
class NoteMapper extends Mapper {
30
public function __construct(IDb $db) {

parent::__construct($db, 'ownnotes_notes', '\OCA\OwnNotes\Db\Note');
}
public function find($id, $userId) {
$sql = 'SELECT * FROM *PREFIX*ownnotes_notes WHERE id = ? AND user_id = ?';
return $this->findEntity($sql, [$id, $userId]);
}
public function findAll($userId) {
$sql = 'SELECT * FROM *PREFIX*ownnotes_notes WHERE user_id = ?';
return $this->findEntities($sql, [$userId]);
}
}
Note: The first parent constructor parameter is the database layer, the second one database table and the third is the
entity on which the result should be mapped onto. Insert, delete and update methods are already implemented.
1.3.4 Connect Database & Controllers

The mapper which provides the database access is finished and can be passed into the controller.
You can pass in the mapper by adding it as a type hinted parameter. ownCloud will figure out how to assemble them by
itself . Additionally we want to know the userId of the currently logged in user. Simply add a $UserId parameter to the
constructor (case sensitive!). To do that open ownnotes/controller/notecontroller.php and change it to the following:
<?php
use Exception;
use
use
use
use
OCP\IRequest;
OCP\AppFramework\Http;
OCP\AppFramework\Http\DataResponse;
OCP\AppFramework\Controller;
use OCA\OwnNotes\Db\Note;
use OCA\OwnNotes\Db\NoteMapper;
private $mapper;
private $userId;
public function __construct($AppName, IRequest $request, NoteMapper $mapper, $UserId){
$this->mapper = $mapper;
$this->userId = $UserId;
}
/**
* @NoAdminRequired
*/
1.3. Tutorial
31
return new DataResponse($this->mapper->findAll($this->userId));

}
/**
* @NoAdminRequired
*
* @param int $id
*/
try {
return new DataResponse($this->mapper->find($id, $this->userId));
} catch(Exception $e) {
return new DataResponse([], Http::STATUS_NOT_FOUND);
}
}
/**
* @NoAdminRequired
*
*/
$note = new Note();
$note->setTitle($title);
$note->setContent($content);
$note->setUserId($this->userId);
return new DataResponse($this->mapper->insert($note));
}
/**
* @NoAdminRequired
*
* @param int $id
*/
try {
$note = $this->mapper->find($id, $this->userId);
}
return new DataResponse($this->mapper->update($note));
}
/**
* @NoAdminRequired
*
* @param int $id
*/
try {
$note = $this->mapper->find($id, $this->userId);
32
}
$this->mapper->delete($note);
return new DataResponse($note);
}
}
Note:
The actual exceptions are OCP\AppFramework\Db\DoesNotExistException and
OCP\AppFramework\Db\MultipleObjectsReturnedException but in this example we will treat them as the
same. DataResponse is a more generic response than JSONResponse and also works with JSON.
This is all that is needed on the server side. Now lets progress to the client side.
1.3.5 Making things reusable and decoupling controllers from the database
Lets say our app is now on the app store and and we get a request that we should save the files in the filesystem which
requires access to the filesystem.
The filesystem API is quite different from the database API and throws different exceptions, which means we need to
rewrite everything in the NoteController class to use it. This is bad because a controllers only responsibility should
be to deal with incoming Http requests and return Http responses. If we need to change the controller because the data
storage was changed the code is probably too tightly coupled and we need to add another layer in between. This layer
is called Service.
Lets take the logic that was inside the controller and put it into a separate class inside ownnotes/service/noteservice.php:
<?php
namespace OCA\OwnNotes\Service;
use Exception;
use OCP\AppFramework\Db\DoesNotExistException;
use OCP\AppFramework\Db\MultipleObjectsReturnedException;
use OCA\OwnNotes\Db\NoteMapper;
class NoteService {
private $mapper;
public function __construct(NoteMapper $mapper){
$this->mapper = $mapper;
}
public function findAll($userId) {
return $this->mapper->findAll($userId);
}
private function handleException ($e) {
if ($e instanceof DoesNotExistException ||
$e instanceof MultipleObjectsReturnedException) {
throw new NotFoundException($e->getMessage());
1.3. Tutorial
33
} else {
throw $e;
}
}
public function find($id, $userId) {
try {
return $this->mapper->find($id, $userId);
// in order to be able to plug in different storage backends like files
// for instance it is a good idea to turn storage related exceptions
// into service related exceptions so controllers and service users
// have to deal with only one type of exception
$this->handleException($e);
}
}
public function create($title, $content, $userId) {
$note = new Note();
$note->setUserId($userId);
return $this->mapper->insert($note);
}
public function update($id, $title, $content, $userId) {
try {
$note = $this->mapper->find($id, $userId);
return $this->mapper->update($note);
}
}
public function delete($id, $userId) {
try {
$note = $this->mapper->find($id, $userId);
$this->mapper->delete($note);
return $note;
}
}
}
Following up create the exceptions in ownnotes/service/serviceexception.php:

<?php
use Exception;
class ServiceException extends Exception {}
34
and ownnotes/service/notfoundexception.php:
<?php
class NotFoundException extends ServiceException {}
Remember how we had all those ugly try catches that where checking for DoesNotExistException and simply returned
a 404 response? Lets also put this into a reusable class. In our case we chose a trait so we can inherit methods without
having to add it to our inheritance hirarchie. This will be important later on when youve got controllers that inherit
from the ApiController class instead.
The trait is created in ownnotes/controller/errors.php:
<?php
use Closure;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\DataResponse;
use OCA\OwnNotes\Service\NotFoundException;
trait Errors {
protected function handleNotFound (Closure $callback) {
try {
return new DataResponse($callback());
} catch(NotFoundException $e) {
$message = ['message' => $e->getMessage()];
return new DataResponse($message, Http::STATUS_NOT_FOUND);
}
}
}
Now we can wire up the trait and the service inside the NoteController:
<?php
use OCP\IRequest;
use OCA\OwnNotes\Service\NoteService;
private $service;
private $userId;
use Errors;
1.3. Tutorial
35
public function __construct($AppName, IRequest $request,

NoteService $service, $UserId){
$this->service = $service;
}
/**
* @NoAdminRequired
*/
return new DataResponse($this->service->findAll($this->userId));
}
/**
* @NoAdminRequired
*
* @param int $id
*/
return $this->handleNotFound(function () use ($id) {
return $this->service->find($id, $this->userId);
});
}
/**
* @NoAdminRequired
*
*/
return $this->service->create($title, $content, $this->userId);
}
/**
* @NoAdminRequired
*
* @param int $id
*/
return $this->handleNotFound(function () use ($id, $title, $content) {
return $this->service->update($id, $title, $content, $this->userId);
});
}
/**
* @NoAdminRequired
*
* @param int $id
*/
return $this->service->delete($id, $this->userId);
});
}
36
Great! Now the only reason that the controller needs to be changed is when request/response related things change.
1.3.6 Writing a test for the controller (recommended)

Tests are essential for having happy users and a carefree life. No one wants their users to rant about your app breaking
their ownCloud or being buggy. To do that you need to test your app. Since this amounts to a ton of repetitive tasks,
we need to automate the tests.
Unit Tests
A unit test is a test that tests a class in isolation. It is very fast and catches most of the bugs, so we want many unit
tests.
Because ownCloud uses Dependency Injection to assemble your app, it is very easy to write unit tests by passing mocks into the constructor. A simple test for the update method can be added by adding this to ownnotes/tests/unit/controller/NoteControllerTest.php:
<?php
use PHPUnit_Framework_TestCase;
use OCA\OwnNotes\Service\NotFoundException;
class NoteControllerTest extends PHPUnit_Framework_TestCase {

protected
protected
protected
protected
$controller;
$service;
$userId = 'john';
$request;
public function setUp() {

$this->request = $this->getMockBuilder('OCP\IRequest')->getMock();
$this->service = $this->getMockBuilder('OCA\OwnNotes\Service\NoteService')
->disableOriginalConstructor()
->getMock();
$this->controller = new NoteController(
'ownnotes', $this->request, $this->service, $this->userId
);
}
public function testUpdate() {
$note = 'just check if this value is returned correctly';
$this->service->expects($this->once())
->method('update')
->with($this->equalTo(3),
$this->equalTo('title'),
$this->equalTo('content'),
1.3. Tutorial
37
$this->equalTo($this->userId))
->will($this->returnValue($note));
$result = $this->controller->update(3, 'title', 'content');
$this->assertEquals($note, $result->getData());
}
public function testUpdateNotFound() {

// test the correct status code if no note is found
$this->service->expects($this->once())
->method('update')
->will($this->throwException(new NotFoundException()));
$result = $this->controller->update(3, 'title', 'content');
$this->assertEquals(Http::STATUS_NOT_FOUND, $result->getStatus());
}
}
We can and should also create a test for the NoteService class:
<?php
use PHPUnit_Framework_TestCase;
use OCP\AppFramework\Db\DoesNotExistException;
class NoteServiceTest extends PHPUnit_Framework_TestCase {
private $service;
private $mapper;
private $userId = 'john';
$this->mapper = $this->getMockBuilder('OCA\OwnNotes\Db\NoteMapper')
->getMock();
$this->service = new NoteService($this->mapper);
}
// the existing note
$note = Note::fromRow([
'id' => 3,
'title' => 'yo',
'content' => 'nope'
]);
$this->mapper->expects($this->once())
->method('find')
->with($this->equalTo(3))
->will($this->returnValue($note));
38
// the note when updated

$updatedNote = Note::fromRow(['id' => 3]);
$updatedNote->setTitle('title');
$updatedNote->setContent('content');
->method('update')
->with($this->equalTo($updatedNote))
->will($this->returnValue($updatedNote));
$result = $this->service->update(3, 'title', 'content', $this->userId);
$this->assertEquals($updatedNote, $result);
}
/**
* @expectedException OCA\OwnNotes\Service\NotFoundException
*/
public function testUpdateNotFound() {
// test the correct status code if no note is found
->method('find')
->will($this->throwException(new DoesNotExistException('')));
$this->service->update(3, 'title', 'content', $this->userId);
}
}
If PHPUnit is installed we can run the tests inside ownnotes/ with the following command:
phpunit
Note: You need to adjust the ownnotes/tests/unit/controller/PageControllerTest file to get the tests passing: remove
the testEcho method since that method is no longer present in your PageController and do not test the user id
parameters since they are not passed anymore
Integration Tests
Integration tests are slow and need a fully working instance but make sure that our classes work well together. Instead
of mocking out all classes and parameters we can decide wether to use full instances or replace certain classes. Because
they are slow we dont want as many integration tests as unit tests.
In our case we want to create an integration test for the udpate method without mocking out the NoteMapper class so
we actually write to the existing database.
To do that create a new file called ownnotes/tests/integration/NoteIntegrationTest.php with the following content:
<?php
use OCP\AppFramework\App;
1.3. Tutorial
39
use Test\TestCase;
class NoteIntregrationTest extends TestCase {
private $controller;
private $mapper;
private $userId = 'john';
parent::setUp();
$app = new App('ownnotes');
$container = $app->getContainer();
// only replace the user id
$container->registerService('UserId', function($c) {
return $this->userId;
});
$this->controller = $container->query(
'OCA\OwnNotes\Controller\NoteController'
);
$this->mapper = $container->query(
'OCA\OwnNotes\Db\NoteMapper'
);
}
// create a new note that should be updated
$note = new Note();
$note->setTitle('old_title');
$note->setContent('old_content');
$note->setUserId($this->userId);
$id = $this->mapper->insert($note)->getId();
// fromRow does not set the fields as updated
$updatedNote = Note::fromRow([
'id' => $id,
'user_id' => $this->userId
]);
$updatedNote->setContent('content');
$updatedNote->setTitle('title');
$result = $this->controller->update($id, 'title', 'content');
$this->assertEquals($updatedNote, $result->getData());
// clean up
$this->mapper->delete($result->getData());
}
}
To run the integration tests change into the ownnotes directory and run:
40
phpunit -c phpunit.integration.xml
1.3.7 Adding a RESTful API (optional)

A RESTful API allows other apps such as Android or iPhone apps to access and change your notes. Since syncing is a
big core component of ownCloud it is a good idea to add (and document!) your own RESTful API.
Because we put our logic into the NoteService class it is very easy to reuse it. The only pieces that need to be changed
are the annotations which disable the CSRF check (not needed for a REST call usually) and add support for CORS so
your API can be accessed from other webapps.
With that in mind create a new controller in ownnotes/controller/noteapicontroller.php:
<?php
use OCP\IRequest;
use OCP\AppFramework\ApiController;
use OCA\OwnNotes\Service\NoteService;
class NoteApiController extends ApiController {
private $service;
private $userId;
use Errors;
public function __construct($AppName, IRequest $request,
NoteService $service, $UserId){
$this->service = $service;
}
/**
* @CORS
* @NoCSRFRequired
* @NoAdminRequired
*/
return new DataResponse($this->service->findAll($this->userId));
}
/**
* @CORS
* @NoCSRFRequired
* @NoAdminRequired
*
* @param int $id
*/
return $this->service->find($id, $this->userId);
});
1.3. Tutorial
41
}
/**
* @CORS
* @NoCSRFRequired
* @NoAdminRequired
*
*/
return $this->service->create($title, $content, $this->userId);
}
/**
* @CORS
* @NoCSRFRequired
* @NoAdminRequired
*
* @param int $id
*/
return $this->handleNotFound(function () use ($id, $title, $content) {
return $this->service->update($id, $title, $content, $this->userId);
});
}
/**
* @CORS
* @NoCSRFRequired
* @NoAdminRequired
*
* @param int $id
*/
return $this->service->delete($id, $this->userId);
});
}
}
All that is left is to connect the controller to a route and enable the built in preflighted CORS method which is defined
in the ApiController base class:
<?php
return [
'resources' => [
'note' => ['url' => '/notes'],
'note_api' => ['url' => '/api/0.1/notes']
],
'routes' => [
['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
['name' => 'note_api#preflighted_cors', 'url' => '/api/0.1/{path}',
'verb' => 'OPTIONS', 'requirements' => ['path' => '.+']]
42
]
];
Note: It is a good idea to version your API in your URL

You can test the API by running a GET request with curl:
curl -u user:password http://localhost:8080/index.php/apps/ownnotes/api/0.1/notes
Since the NoteApiController is basically identical to the NoteController, the unit test for it simply inherits its tests
from the NoteControllerTest. Create the file ownnotes/tests/unit/controller/NoteApiControllerTest.php:
<?php
require_once __DIR__ . '/NoteControllerTest.php';
class NoteApiControllerTest extends NoteControllerTest {
parent::setUp();
$this->controller = new NoteApiController(
'ownnotes', $this->request, $this->service, $this->userId
);
}
}
1.3.8 Adding JavaScript and CSS

To create a modern webapp you need to write JavaScript. You can use any JavaScript framework but for this tutorial
we want to keep it as simple as possible and therefore only include the templating library handlebarsjs. Download the
file into ownnotes/js/handlebars.js and include it at the very top of ownnotes/templates/main.php before the other
scripts and styles:
<?php
script('ownnotes', 'handlebars');
Note: jQuery is included by default on every page.
1.3.9 Creating a navigation

The template file ownnotes/templates/part.navigation.php contains the navigation. ownCloud defines many handy
CSS styles which we are going to reuse to style the navigation. Adjust the file to contain only the following code:
Note: $l->t() is used to make your strings translatable and p() is used to print escaped HTML

<div style="display:none" id="new-note-string"><?php p($l->t('New note')); ?></div>
1.3. Tutorial
43
<script id="navigation-tpl" type="text/x-handlebars-template">

<li id="new-note"><a href="#"><?php p($l->t('Add note')); ?></a></li>
{{#each notes}}
<li class="note with-menu {{#if active}}active{{/if}}" data-id="{{ id }}">
<a href="#">{{ title }}</a>
<div class="app-navigation-entry-utils">
<ul>
<li class="app-navigation-entry-utils-menu-button svg"><button></button></li>
</ul>
</div>
<div class="app-navigation-entry-menu">
<ul>
<li><button class="delete icon-delete svg" title="delete"></button></li>
</ul>
</div>
</li>
{{/each}}
</script>
<ul></ul>
1.3.10 Creating the content

The template file ownnotes/templates/part.content.php contains the content. It will just be a textarea and a button,
so replace the content with the following:
<script id="content-tpl" type="text/x-handlebars-template">
{{#if note}}
<div class="input"><textarea>{{ note.content }}</textarea></div>
<div class="save"><button><?php p($l->t('Save')); ?></button></div>
{{else}}
<div class="input"><textarea disabled></textarea></div>
<div class="save"><button disabled><?php p($l->t('Save')); ?></button></div>
{{/if}}
</script>
<div id="editor"></div>
1.3.11 Wiring it up
When the page is loaded we want all the existing notes to load. Furthermore we want to display the current note when
you click on it in the navigation, a note should be deleted when we click the deleted button and clicking on New note
should create a new note. To do that open ownnotes/js/script.js and replace the example code with the following:
(function (OC, window, $, undefined) {
'use strict';
$(document).ready(function () {
var translations = {
newNote: $('#new-note-string').text()
};
44
// this notes object holds all our notes

var Notes = function (baseUrl) {
this._baseUrl = baseUrl;
this._notes = [];
this._activeNote = undefined;
};
Notes.prototype = {
load: function (id) {
var self = this;
this._notes.forEach(function (note) {
if (note.id === id) {
note.active = true;
self._activeNote = note;
} else {
note.active = false;
}
});
},
getActive: function () {
return this._activeNote;
},
removeActive: function () {
var index;
var deferred = $.Deferred();
var id = this._activeNote.id;
this._notes.forEach(function (note, counter) {
if (note.id === id) {
index = counter;
}
});
if (index !== undefined) {
// delete cached active note if necessary
if (this._activeNote === this._notes[index]) {
delete this._activeNote;
}
this._notes.splice(index, 1);
$.ajax({
url: this._baseUrl + '/' + id,
method: 'DELETE'
}).done(function () {
deferred.resolve();
}).fail(function () {
deferred.reject();
});
} else {
deferred.reject();
}
return deferred.promise();
},
create: function (note) {
var self = this;
$.ajax({
1.3. Tutorial
45
url: this._baseUrl,
method: 'POST',
}).done(function (note) {
self._notes.push(note);
self._activeNote = note;
self.load(note.id);
deferred.resolve();
deferred.reject();
});
},
getAll: function () {
return this._notes;
},
loadAll: function () {
var self = this;
$.get(this._baseUrl).done(function (notes) {
self._activeNote = undefined;
self._notes = notes;
deferred.resolve();
deferred.reject();
});
},
updateActive: function (title, content) {
var note = this.getActive();
note.title = title;
note.content = content;
return $.ajax({
url: this._baseUrl + '/' + note.id,
method: 'PUT',
});
}
};
// this will be the view that is used to update the html
var View = function (notes) {
this._notes = notes;
};
View.prototype = {
renderContent: function () {
var source = $('#content-tpl').html();
var template = Handlebars.compile(source);
var html = template({note: this._notes.getActive()});
$('#editor').html(html);
// handle saves
var textarea = $('#app-content textarea');
46
var self = this;

$('#app-content button').click(function () {
var content = textarea.val();
var title = content.split('\n')[0]; // first line is the title
self._notes.updateActive(title, content).done(function () {
self.render();
alert('Could not update note, not found');
});
});
},
renderNavigation: function () {
var source = $('#navigation-tpl').html();
var template = Handlebars.compile(source);
var html = template({notes: this._notes.getAll()});
$('#app-navigation ul').html(html);
// create a new note
var self = this;
$('#new-note').click(function () {
var note = {
title: translations.newNote,
content: ''
};
self._notes.create(note).done(function() {
self.render();
$('#editor textarea').focus();
alert('Could not create note');
});
});
// show app menu
$('#app-navigation .app-navigation-entry-utils-menu-button').click(function () {
var entry = $(this).closest('.note');
entry.find('.app-navigation-entry-menu').toggleClass('open');
});
// delete a note
$('#app-navigation .note .delete').click(function () {
var entry = $(this).closest('.note');
entry.find('.app-navigation-entry-menu').removeClass('open');
self._notes.removeActive().done(function () {
self.render();
alert('Could not delete note, not found');
});
});
// load a note
$('#app-navigation .note > a').click(function () {
var id = parseInt($(this).parent().data('id'), 10);
self._notes.load(id);
self.render();
1.3. Tutorial
47
$('#editor textarea').focus();
});
},
render: function () {
this.renderNavigation();
this.renderContent();
}
};
var notes = new Notes(OC.generateUrl('/apps/ownnotes/notes'));
var view = new View(notes);
notes.loadAll().done(function () {
view.render();
alert('Could not load notes');
});
});
})(OC, window, jQuery);
1.3.12 Apply finishing touches

Now the only thing left is to style the textare in a nicer fashion. To do that open ownnotes/css/style.css and replace
the content with the following CSS code:
#app-content-wrapper {
height: 100%;
}
#editor {
height: 100%;
width: 100%;
}
#editor .input {
height: calc(100% - 51px);
width: 100%;
}
#editor .save {
height: 50px;
width: 100%;
text-align: center;
border-top: 1px solid #ccc;
background-color: #fafafa;
}
#editor textarea {
height: 100%;
width: 100%;
border: 0;
margin: 0;
border-radius: 0;
overflow-y: auto;
48
}
#editor button {
height: 44px;
}
Congratulations! Youve written your first ownCloud app. You can now either try to further improve the tutorial notes
app or start writing your own app.
1.4 Create an app

After youve set up the development environment and installed the dev tool change into the ownCloud apps directory:
cd /var/www/core/apps
Then run:
ocdev startapp MyApp --email [email protected] --author "Your Name" --description "My first app" --ow
This will create all the needed files in the current directory. For more information on how to customize the generated
app, see the Projects GitHub page or run:
ocdev startapp -h
1.4.1 Enable the app

The app can now be enabled on the ownCloud apps page
1.4.2 App architecture

The following directories have now been created:
appinfo/: Contains app metadata and configuration
controller/: Contains the controllers
css/: Contains the CSS
js/: Contains the JavaScript files
templates/: Contains the templates
tests/: Contains the tests
1.5 Navigation and Pre-App configuration

The appinfo/app.php is the first file that is loaded and executed in ownCloud. Depending on the purpose of the
app it usually just contains the navigation setup, and maybe Background Jobs (Cron) and Hooks registrations. This is
how an example appinfo/app.php could look like:
1.4. Create an app
49
<?php
\OC::$server->getNavigationManager()->add(function () {
$urlGenerator = \OC::$server->getURLGenerator();
return [
// the string under which your app will be referenced in owncloud
'id' => 'myapp',
// sorting weight for the navigation. The higher the number, the higher
// will it be listed in the navigation
'order' => 10,
// the route that will be shown on startup
'href' => $urlGenerator->linkToRoute('myapp.page.index'),
// the icon that will be shown in the navigation
// this file needs to exist in img/
'icon' => $urlGenerator->imagePath('myapp', 'app.svg'),
// the title of your application. This will be used in the
// navigation or on the settings page of your app
'name' => \OC::$server->getL10N('myapp')->t('My App'),
];
});
// execute OCA\MyApp\BackgroundJob\Task::run when cron is called
\OC::$server->getJobList()->add('OCA\MyApp\BackgroundJob\Task');
// execute OCA\MyApp\Hooks\User::deleteUser before a user is being deleted
\OCP\Util::connectHook('OC_User', 'pre_deleteUser', 'OCA\MyApp\Hooks\User', 'deleteUser');
Although it is also possible to include JavaScript or CSS for other apps by placing the addScript or addStyle functions
inside this file, it is strongly discouraged, because the file is loaded on each request (also such requests that do not
return HTML, but e.g. json or webdav).
<?php
\OCP\Util::addScript('myapp', 'script'); // include js/script.js for every app
\OCP\Util::addStyle('myapp', 'style'); // include css/style.css for every app
1.6 App Metadata

The appinfo/info.xml contains metadata about the app:
<info>
<id>yourappname</id>
<name>Your App</name>
<description>Your App description</description>
<version>1.0</version>
<licence>AGPL</licence>
<author>Your Name</author>
<requiremin>5</requiremin>
<namespace>YourAppsNamespace</namespace>
50
<types>
<type>filesystem</type>
</types>
<documentation>
<user>http://doc.owncloud.org</user>
<admin>http://doc.owncloud.org</admin>
</documentation>
<category>other</category>
<website>http://www.owncloud.org</website>
<bugs>http://github.com/owncloud/theapp/issues</bugs>
<repository type="git">http://github.com/owncloud/theapp.git</repository>
<ocsid>1234</ocsid>
<dependencies>
<php min-version="5.4" max-version="5.5"/>
<database>sqlite</database>
<database>mysql</database>
<command os="linux">grep</command>
<command os="windows">notepad.exe</command>
<lib min-version="1.2">xml</lib>
<lib max-version="2.0">intl</lib>
<lib>curl</lib>
<os>Linux</os>
<owncloud min-version="6.0.4" max-version="8"/>
</dependencies>

<public>
<file id="caldav">appinfo/caldav.php</file>
</public>
<remote>
<file id="caldav">appinfo/caldav.php</file>
</remote>
<standalone />
<default_enable />
<shipped>true</shipped>

</info>
1.6.1 id
Required: This field contains the internal app name, and has to be the same as the folder name of the app. This id
needs to be unique in ownCloud, meaning no other app should have this id.
1.6. App Metadata
51
1.6.2 name
Required: This is the human-readable name/title of the app that will be displayed in the app overview page.
1.6.3 description
Required: This contains the description of the app which will be shown in the apps overview page.
1.6.4 version
Contains the version of your app. Please also provide the same version in the appinfo/version.
1.6.5 licence
Required: The licence of the app. This licence must be compatible with the AGPL and must not be proprietary, for
instance:
AGPL 3 (recommended)
MIT
If a proprietary/non AGPL compatible licence should be used, the ownCloud Enterprise Edition must be used.
1.6.6 author
Required: The name of the app author or authors.
1.6.7 requiremin
Required if not added in the <dependencies> tag. The minimal version of ownCloud.
1.6.8 namespace
Required if routes.php returns an array. If your app is namespaced like \OCA\MyApp\Controller\PageController
the required namespace value is MyApp. If not given it tries to default to the first letter upper cased app id, e.g. myapp
would be tried under Myapp
1.6.9 types
ownCloud allows to specify four kind of types. Currently supported types:
prelogin: apps which needs to load on the login page
filesystem: apps which provides filesystem functionality (e.g. files sharing app)
authentication: apps which provided authentication backends
logging: apps which implement a logging system
52
1.6.10 documentation
link to admin and user documentation
1.6.11 website
link to project web page
1.6.12 repository
Link to the version control repo
1.6.13 bugs
Link to the bug tracker
1.6.14 category
Category on the app store. Can be one of the following:
other
multimedia
pim
productivity
games
tools
1.6.15 ocsid
The apps id on the app store, e.g.: https://apps.owncloud.com/content/show.php/QOwnNotes?content=168497 would
have the ocsid 168497. If given helps users to install and update the same app from the app store
Dependencies
All tags within the dependencies tag define a set of requirements which have to be fulfilled in order to operate properly.
As soon as one of these requirements is not met the app cannot be installed.
1.6.16 php
Defines the minimum and the maximum version of php which is required to run this app.
1.6.17 database
Each supported database has to be listed in here. Valid values are sqlite, mysql, pgsql, oci and mssql. In the future it
will be possible to specify versions here as well. In case no database is specified it is assumed that all databases are
supported.
1.6. App Metadata
53
1.6.18 command
Defines a command line tool to be available. With the attribute os the required operating system for this tool can be
specified. Valid values for the os attribute are as returned by the php function php_uname.
1.6.19 lib
Defines a required php extension with required minimum and/or maximum version. The names for the libraries have
to match the result as returned by the php function get_loaded_extensions. The explicit version of an extension is read
from phpversion - with some exception as to be read up in the code base
1.6.20 os
Defines the required target operating system the app can run on. Valid values are as returned by the php function
php_uname.
1.6.21 owncloud
Defines minimum and maximum versions of the ownCloud core. In case undefined the values will be taken from the
tag requiremin.
Deprecated
The following sections are just listed for reference and should not be used because
public/remote: Use RESTful API instead because youll have to use External API which is known to be buggy
(works only properly with GET/POST)
standalone/default_enable: They tell core what do on setup, you will not be able to even activate your app if it
has those entries. This should be replaced by a config file inside core.
1.6.22 public
Used to provide a public interface (requires no login) for the app.
cloud/index.php/public. Example with id set to calendar:
The id is appended to the URL /own-
/owncloud/index.php/public/calendar
Also take a look at External API.
1.6.23 remote
Same as public but requires login. The id is appended to the URL /owncloud/index.php/remote. Example with id set
to calendar:
/owncloud/index.php/remote/calendar
Also take a look at External API.
54
1.6.24 standalone
Can be set to true to indicate that this app is a webapp. This can be used to tell GNOME Web for instance to treat this
like a native application.
1.6.25 default_enable
Core apps only: Used to tell ownCloud to enable them after the installation.
1.6.26 shipped
Core apps only: Used to tell ownCloud that the app is in the standard release.
Please note that if this attribute is set to FALSE or not set at all, every time you disable the application, all the files of
the application itself will be REMOVED from the server!
1.7 Classloader
The classloader is provided by ownCloud and loads all your classes automatically. The only thing left to include by
yourself are 3rdparty libraries. Those should be loaded in appinfo/application.php.
The classloader works like this:
Take the full qualifier of a class:
\OCA\MyApp\Controller\PageController
If it starts with \OCA include file from the apps directory

Cut off \OCA:
\MyApp\Controller\PageController
Convert all charactes to lowercase:

\myapp\controller\pagecontroller
Replace \ with /:
/myapp/controller/pagecontroller
Append .php:
/myapp/controller/pagecontroller.php
Prepend /apps because of the OCA namespace and include the file:
require_once '/apps/myapp/controller/pagecontroller.php';
1.7. Classloader
55
In
other
words:
In
order
for
the
PageController
class
the
class
\OCA\MyApp\Controller\PageController
needs
to
be
/apps/myapp/controller/pagecontroller.php
to
be
stored
autoloaded,
in
the
1.8 Request lifecycle

A typical HTTP request consists of the following:
An URL: e.g. /index.php/apps/myapp/something
Request Parameters: e.g. ?something=true&name=tom
A Method: e.g. GET
Request headers: e.g. Accept: application/json
The following sections will present an overview over how that request is being processed to provide an in depth view
over how ownCloud works. If you are not interested in the internals or dont want to execute anything before and after
your controller, feel free to skip this section and continue directly with defining your apps routes.
1.8.1 Front controller

In the beginning, all requests are sent to ownClouds index.php which in turn executes lib/base.php. This
file inspects the HTTP headers and abstracts away differences between different web servers and initializes the basic
classes. Afterwards the basic apps are being loaded in the following order:
Authentication backends
Filesystem
Logging
The type of the app is determined by inspecting the apps configuration file (appinfo/info.xml). Loading apps
means that the main file (appinfo/app.php) of each installed app is being loaded and executed. That means that if
you want to execute code before a specific app is being run, you can place code in your apps Navigation and Pre-App
configuration file.
Afterwards the following steps are performed:
Try to authenticate the user
Load and execute all the remaining apps Navigation and Pre-App configuration files
Load and run all the routes in the apps appinfo/routes.php
Execute the router
1.8.2 Router
The router parses the apps routing files (appinfo/routes.php), inspects the requests method and url, queries
the controller from the Container and then passes control to the dispatcher. The dispatcher is responsible for running
the hooks (called Middleware) before and after the controller, executing the controller method and rendering the
output.
56
1.8.3 Middleware
A Middleware is a convenient way to execute common tasks such as custom authentication before or after a controller
method is being run. You can execute code at the following locations:
before the call of the controller method
after the call of the controller method
after an exception is thrown (also if it is thrown from a middleware, e.g. if an authentication fails)
before the output is rendered
1.8.4 Container
The Container is the place where you define all of your classes and in particular all of your controllers. The container
is responsible for assembling all of your objects (instantiating your classes) that should only have one single instance
without relying on globals or singletons. If you want to know more about why you should use it and what the benefits
are, read up on the topic in Container.
1.8.5 Controller
The controller contains the code that you actually want to run after a request has come in. Think of it like a callback
that is executed if everything before went fine.
The controller returns a response which is then run through the middleware again (afterController and beforeOutput
hooks are being run), HTTP headers are being set and the responses render method is being called and printed.
1.9 Routing
Routes map an URL and a method to a controller method. Routes are defined inside appinfo/routes.php by
passing a configuration array to the registerRoutes method. An example route would look like this:
<?php
namespace OCA\MyApp\AppInfo;
$application = new Application();
$application->registerRoutes($this, array(
'routes' => array(
array('name' => 'page#index', 'url' => '/', 'verb' => 'GET'),
)
));
The route array contains the following parts:

url: The url that is matched after /index.php/apps/myapp
name: The controller and the method to call; page#index is being mapped to PageController->index(), articles_api#drop_latest would be mapped to ArticlesApiController->dropLatest(). The controller that matches the
page#index name would have to be registered in the following way inside appinfo/application.php:
<?php
1.9. Routing
57
use \OCP\AppFramework\App;
use \OCA\MyApp\Controller\PageController;
class Application extends App {

public function __construct(array $urlParams=array()){
parent::__construct('myapp', $urlParams);
$container = $this->getContainer();
/**
* Controllers
*/
$container->registerService('PageController', function($c) {
return new PageController(
$c->query('AppName'),
$c->query('Request')
);
});
}
}
method (Optional, defaults to GET): The HTTP method that should be matched, (e.g. GET, POST, PUT,
DELETE, HEAD, OPTIONS, PATCH)
requirements (Optional): lets you match and extract URLs that have slashes in them (see Matching suburls)
postfix (Optional): lets you define a route id postfix. Since each route name will be transformed to a route id
(page#method -> myapp.page.method) and the route id can only exist once you can use the postfix option to
alter the route id creation by adding a string to the route id e.g.: name => page#method, postfix => test
will yield the route id myapp.page.methodtest. This makes it possible to add more than one route/url for a
controller method
defaults (Optional): If this setting is given, a default value will be assumed for each url parameter which is not
present. The default values are passed in as a key => value par array
1.9.1 Extracting values from the URL

It is possible to extract values from the URL to allow RESTful URL design. To extract a value, you have to wrap it
inside curly braces:
<?php
// Request: GET /index.php/apps/myapp/authors/3
// appinfo/routes.php
array('name' => 'author#show', 'url' => '/authors/{id}', 'verb' => 'GET'),
// controller/authorcontroller.php
class AuthorController {
// $id is '3'
58
}
}
The identifier used inside the route is being passed into controller method by reflecting the method parameters. So
basically if you want to get the value {id} in your method, you need to add $id to your method parameters.
1.9.2 Matching suburls

Sometimes its needed to match more than one URL fragment. An example would be to match a request for all URLs
that start with OPTIONS /index.php/apps/myapp/api. To do this, use the requirements parameter in your route
which is an array containing pairs of key => regex:
<?php
// Request: OPTIONS /index.php/apps/myapp/api/my/route
array('name' => 'author_api#cors', 'url' => '/api/{path}', 'verb' => 'OPTIONS',
'requirements' => array('path' => '.+')),
// controller/authorapicontroller.php
class AuthorApiController {
public function cors($path) {
// $path will be 'my/route'
}
}
1.9.3 Default values for suburl

Apart from matching requirements, suburl may also have default value. Say you want to support pagination (a page
parameter) for your /posts suburl that displays posts entries list. You may set a default value to page parameter, that
will be used if not already set in the url. Use the defaults parameter in your route which is an array containing pairs
of urlparameter => defaultvalue:
<?php
// Request: GET /index.php/app/myapp/post
array(
'name'
=> 'post#index',
'url'
=> '/post/{page}',
'verb'
=> 'GET',
'defaults' => array('page' => 1) // this allows same url as /index.php/myapp/post/1
),
// controller/postcontroller.php
class PostController
{
public function index($page = 1)
1.9. Routing
59
{
// $page will be 1
}
}
1.9.4 Registering resources

When dealing with resources, writing routes can become quite repetitive since most of the time routes for the following
tasks are needed:
Get all entries
Get one entry by id
Create an entry
Update an entry
Delete an entry
To prevent repetition, its possible define resources. The following routes:
<?php
'routes' => array(
array('name' => 'author#index', 'url' => '/authors', 'verb' => 'GET'),
array('name' => 'author#show', 'url' => '/authors/{id}', 'verb' => 'GET'),
array('name' => 'author#create', 'url' => '/authors', 'verb' => 'POST'),
array('name' => 'author#update', 'url' => '/authors/{id}', 'verb' => 'PUT'),
array('name' => 'author#destroy', 'url' => '/authors/{id}', 'verb' => 'DELETE'),
// your other routes here
)
));
can be abbreviated by using the resources key:

<?php
'resources' => array(
'author' => array('url' => '/authors')
),
'routes' => array(
// your other routes here
)
));
60
1.9.5 Using the URLGenerator

Sometimes its useful to turn a route into a URL to make the code independent from the URL design or to generate an
URL for an image in img/. For that specific use case, the ServerContainer provides a service that can be used in your
container:
<?php
use \OCA\MyApp\Controller\PageController;

/**
* Controllers
*/
$container->registerService('PageController', function($c) {
return new PageController(
$c->query('Request'),
// inject the URLGenerator into the page controller
$c->query('ServerContainer')->getURLGenerator()
);
});
}
}
Inside the PageController the URL generator can now be used to generate an URL for a redirect:
<?php
namespace OCA\MyApp\Controller;
use
use
use
use
\OCP\IRequest;
\OCP\IURLGenerator;
\OCP\AppFramework\Controller;
\OCP\AppFramework\Http\RedirectResponse;

private $urlGenerator;
public function __construct($appName, IRequest $request,
IURLGenerator $urlGenerator) {
parent::__construct($appName, $request);
$this->urlGenerator = $urlGenerator;
}
1.9. Routing
61
/**
* redirect to /apps/news/myapp/authors/3
*/
public function redirect() {
// route name: author_api#do_something
// route url: /apps/news/myapp/authors/{id}
// # needs to be replaced with a . due to limitations and prefixed
// with your app id
$route = 'myapp.author_api.do_something';
$parameters = array('id' => 3);
$url = $this->urlGenerator->linkToRoute($route, $parameters);
return new RedirectResponse($url);
}
}
URLGenerator is case sensitive, so appName must match exactly the name you use in configuration. If you use a
CamelCase name as myCamelCaseApp,
<?php
$route = 'myCamelCaseApp.author_api.do_something';
1.10 Middleware
Middleware is logic that is run before and after each request and is modelled after Djangos Middleware system. 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 cant 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.
<?php
namespace OCA\MyApp\Middleware;
use \OCP\AppFramework\Middleware;
class CensorMiddleware extends Middleware {
62
/**
* this replaces "bad words" with "********" in the output
*/
public function beforeOutput($controller, $methodName, $output){
return str_replace('bad words', '********', $output);
}
}
The middleware can be registered in the Container and added using the registerMiddleware method:
<?php
use \OCA\MyApp\Middleware\CensorMiddleware;
class MyApp extends App {
/**
* Define your dependencies in here
*/
/**
* Middleware
*/
$container->registerService('CensorMiddleware', function($c){
return new CensorMiddleware();
});
// executed in the order that it is registered
$container->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.
1.10.1 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:
<?php
namespace OCA\MyApp\Middleware;
1.10. Middleware
63
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:

<?php
use \OCA\MyApp\Middleware\HeaderMiddleware;
class MyApp extends App {
/**
*/
/**
* Middleware
*/
$container->registerService('HeaderMiddleware', function($c){
return new HeaderMiddleware($c->query('ControllerMethodReflector'));
});
// executed in the order that it is registered
$container->registerMiddleware('HeaderMiddleware');
}
}
64
Note: An annotation always starts with an uppercase letter
1.11 Container
The App Framework assembles the application by using a container based on the software pattern Dependency Injection. This makes the code easier to test and thus easier to maintain.
If you are unfamiliar with this pattern, watch the following videos:
Dependency Injection and the art of Services and Containers Tutorial
Google Clean Code Talks
1.11.1 Dependency Injection

Dependency Injection sounds pretty complicated but it just means: Dont new dependencies in your constructor or
methods but pass them in. So this:
<?php
// without dependency injection
class AuthorMapper {
private $db;
public function __construct() {
$this->db = new Db();
}
}
would turn into this by using Dependency Injection:

<?php
// with dependency injection
class AuthorMapper {
private $db;
public function __construct($db) {
$this->db = $db;
}
}
1.11.2 Using a container

Passing dependencies into the constructor rather than instantiating them in the constructor has the following drawback:
Every line in the source code where new AuthorMapper is being used has to be changed, once a new constructor
argument is being added to it.
1.11. Container
65
The solution for this particular problem is to limit the new AuthorMapper to one file, the container. The container
contains all the factories for creating these objects and is configured in appinfo/application.php.
To add the apps classes simply open the appinfo/application.php use the registerService method on the
container object:
<?php
use \OCA\MyApp\Controller\AuthorController;
use \OCA\MyApp\Service\AuthorService;
use \OCA\MyApp\Db\AuthorMapper;
/**
*/
/**
* Controllers
*/
$container->registerService('AuthorController', function($c){
return new AuthorController(
$c->query('AuthorService')
);
});
/**
* Services
*/
$container->registerService('AuthorService', function($c){
return new AuthorService(
$c->query('AuthorMapper')
);
});
/**
* Services
*/
$container->registerService('AuthorMapper', function($c){
return new AuthorMapper(
$c->query('ServerContainer')->getDb()
);
});
}
}
66
1.11.3 How the container works

The container works in the following way:
A request comes in and is matched against a route (for the AuthorController in this case)
The matched route queries AuthorController service form the container:
return new AuthorController(
$c->query('AuthorService')
);
The AppName is queried and returned from the baseclass

The Request is queried and returned from the server container
AuthorService is queried:
$container->registerService('AuthorService', function($c){
$c->query('AuthorMapper')
);
});
AuthorMapper is queried:
$container->registerService('AuthorMappers', function($c){
$c->query('ServerContainer')->getDb()
);
});
The database connection is returned from the server container

Now AuthorMapper has all of its dependencies and the object is being returned
AuthorService gets the AuthorMapper and returns the object
AuthorController gets the AuthorService and finally the controller can be newed and the object is being
returned
So basically the container is used as a giant factory to build all the classes that are needed for the application. Because
it centralizes all the creation of objects (the new Class() lines), it is very easy to add new constructor parameters
without breaking existing code: only the __construct method and the container line where the new is being called
need to be changed.
1.11.4 Use automatic dependency assembly (recommended)

New in version 8.
Since ownCloud 8 it is possible to omit the appinfo/application.php and use automatic dependency assembly instead.
1.11. Container
67
How does automatic assembly work

Automatic assembly creates new instances of classes just by looking at the class name and its constructor parameters.
For each constructor parameter the type or the variable name is used to query the container, e.g.:
SomeType $type will use $container->query(SomeType)
$variable will use $container->query(variable)
If all constructor parameters are resolved, the class will be created, saved as a service and returned.
So basically the following is now possible:
<?php
namespace OCA\MyApp;
class MyTestClass {}
class MyTestClass2 {
public $class;
public $appName;
public function __construct(MyTestClass $class, $AppName) {
$this->class = $class;
$this->appName = $AppName;
}
}
$container = new \OCP\App('myapp');
$class2 = $container->query('OCA\MyApp\MyTestClass2');
$class2 instanceof MyTestClass2; // true
$class2->class instanceof MyTestClass; // true
$class2->appName === 'appname'; // true
$class2 === $container->query('OCA\MyApp\MyTestClass2');
// true
Note: $AppName is resolved because the container registered a parameter under the key AppName which will return
the app id. The lookup is case sensitive so while $AppName will work correctly, using $appName as a constructor
parameter will fail.
How does it affect the request lifecycle

A request comes in
All apps routes.php files are loaded
If a routes.php file returns an array, and an appname/appinfo/application.php exists, include it, create
a new instance of \OCA\AppName\AppInfo\Application.php and register the routes on it. That way a
container can be used while still benefitting from the new routes behavior
If a routes.php file returns an array, but there is no appname/appinfo/application.php, create a new
\OCP\App instance with the app id and register the routes on it
A request is matched for the route, e.g. with the name page#index
The appropriate container is being queried for the entry PageController (to keep backwards compability)
68
If the entry does not exist, the container is queried for OCA\AppName\Controller\PageController and if no entry
exists, the container tries to create the class by using reflection on its constructor parameters
How does this affect controllers
The only thing what needs to be done to add a route and a controller method is now:
myapp/appinfo/routes.php
<?php
]];
myapp/appinfo/controller/pagecontroller.php
<?php
class PageController {
public function __construct($AppName, \OCP\IRequest $request) {
}
// your code here
}
}
There is no need to wire up anything in appinfo/application.php. Everyting will be done automatically.

How to deal with interface and primitive type parameters
Interfaces and primitive types can not be instantiated, so the container can not automatically assemble them. The
actual implementation needs to be wired up in the container:
<?php
class Application extends \OCP\AppFramework\App {
/**
*/
// AuthorMapper requires a location as string called $TableName
$container->registerParameter('TableName', 'my_app_table');
// the interface is called IAuthorMapper and AuthorMapper implements it
$container->registerService('OCA\MyApp\Db\IAuthorMapper', function ($c) {
1.11. Container
69
return $c->query('OCA\MyApp\Db\AuthorMapper');
});
}
}
Predefined core services

The following parameter names and type hints can be used inject core services instead of using $container>getServer()->getServiceX()
Parameters:
AppName: The app id
WebRoot: The path to the ownCloud installation
UserId: The id of the current user
Types:
OCP\IAppConfig
OCP\IAppManager
OCP\IAvatarManager
OCP\Activity\IManager
OCP\ICache
OCP\ICacheFactory
OCP\IConfig
OCP\AppFramework\Utility\IControllerMethodReflector
OCP\Contacts\IManager
OCP\IDateTimeZone
OCP\IDb
OCP\IDBConnection
OCP\Diagnostics\IEventLogger
OCP\Diagnostics\IQueryLogger
OCP\Files\Config\IMountProviderCollection
OCP\Files\IRootFolder
OCP\IGroupManager
OCP\IL10N
OCP\ILogger
OCP\BackgroundJob\IJobList
OCP\INavigationManager
OCP\IPreview
OCP\IRequest
70
OCP\AppFramework\Utility\ITimeFactory
OCP\ITagManager
OCP\ITempManager
OCP\Route\IRouter
OCP\ISearch
OCP\ISearch
OCP\Security\ICrypto
OCP\Security\IHasher
OCP\Security\ISecureRandom
OCP\IURLGenerator
OCP\IUserManager
OCP\IUserSession
How to enable it
To make use of this new feature, the following things have to be done:
appinfo/info.xml requires to provide another field called namespace where the namespace of the app is
defined. The required namespace is the one which comes after the top level namespace OCA\, e.g.: for
OCA\MyBeautifulApp\Some\OtherClass the needed namespace would be MyBeautifulApp and would be
added to the info.xml in the following way:
<info>
<namespace>MyBeautifulApp</namespace>

</info>
appinfo/routes.php: Instead of creating a new Application class instance, simply return the routes array like:
<?php
]];
Note: A namespace tag is required because you can not deduce the namespace from the app id
1.11.5 Which classes should be added

In general all of the apps controllers need to be registered inside the container. Then following question is: What goes
into the constructor of the controller? Pass everything into the controller constructor that is responsible matches one
of the following criteria:
It does I/O (database, write/read to files)
It is a global (e.g. $_POST, etc. This is in the request class by the way)
1.11. Container
71
The output does not depend on the input variables (also called impure function), e.g. time, random number
generator
It is a service, basically it would make sense to swap it out for a different object
What not to inject:
It is pure data and has methods that only act upon it (arrays, data objects)
It is a pure function
1.12 Controllers
Controllers are used to connect routes with app logic. Think of it as callbacks that are executed once a request has
come in. Controllers are defined inside the controller/ directory.
To create a controller, simply extend the Controller class and create a method that should be executed on a request:
<?php
class AuthorController extends Controller {
}
}
1.12.1 Connecting a controller and a route

To connect a controller and a route the controller has to be registered in the Container like this:
<?php
use OCP\AppFramework\App;
use OCA\MyApp\Controller\AuthorApiController;

/**
* Controllers
*/
$container->registerService('AuthorApiController', function($c) {
return new AuthorApiController(
72
$c->query('Request')
);
});
}
}
Every controller needs the app name and the request object passed into their parent constructor, which can easily be
injected like shown in the example code above. The important part is not the class name but rather the string which is
passed in as the first parameter of the registerService method.
The other part is the route name. An example route name would look like this:
author_api#some_method
This name is processed in the following way:

Remove the underscore and uppercase the next character:
authorApi#someMethod
Split at the # and uppercase the first letter of the left part:
AuthorApi
someMethod
Append Controller to the first part:

AuthorApiController
someMethod
Now retrieve the service listed under AuthorApiController from the container, look up the parameters of
the someMethod method in the request, cast them if there are PHPDoc type annotations and execute the
someMethod method on the controller with those parameters.
1.12.2 Getting request parameters

Parameters can be passed in many ways:
Extracted from the URL using curly braces like {key} inside the URL (see Routing)
Appended to the URL as a GET request (e.g. ?something=true)
application/x-www-form-urlencoded from a form or jQuery
application/json from a POST, PATCH or PUT request
All those parameters can easily be accessed by adding them to the controller method:
<?php
1.12. Controllers
73
// this method will be executed with the id and name parameter taken
// from the request
public function doSomething($id, $name) {
}
}
It is also possible to set default parameter values by using PHP default method values so common values can be
omitted:
<?php
/**
* @param int $id
*/
public function doSomething($id, $name='john', $job='author') {
// GET ?id=3&job=killer
// $id = 3
// $name = 'john'
// $job = 'killer'
}
}
Casting parameters
URL, GET and application/x-www-form-urlencoded have the problem that every parameter is a string, meaning that:
?doMore=false
would be passed in as the string false which is not what one would expect. To cast these to the correct types, simply
add PHPDoc in the form of:
@param type $name
<?php
/**
* @param int $id
* @param bool $doMore
* @param float $value
74
*/
public function doSomething($id, $doMore, $value) {
// GET /index.php/apps/myapp?id=3&doMore=false&value=3.5
// => $id = 3
//
$doMore = false
//
$value = 3.5
}
}
The following types will be casted:

bool or boolean
float
int or integer
JSON parameters
It is possible to pass JSON using a POST, PUT or PATCH request. To do that the Content-Type header has to be set to
application/json. The JSON is being parsed as an array and the first level keys will be used to pass in the arguments,
e.g.:
POST /index.php/apps/myapp/authors
Content-Type: application/json
{
"name": "test",
"number": 3,
"publisher": true,
"customFields": {
"mail": "[email protected]",
"address": "Somewhere"
}
}
<?php
public
//
//
//
//
}
function create($name, $number, $publisher, $customFields) {

$name = 'test'
$number = 3
$publisher = true
$customFields = array("mail" => "[email protected]", "address" => "Somewhere")
Reading headers, files, cookies and environment variables

Headers, files, cookies and environment variables can be accessed directly from the request object:
1.12. Controllers
75
<?php
use OCP\IRequest;
public function someMethod() {
$type = $this->request->getHeader('Content-Type'); // $_SERVER['HTTP_CONTENT_TYPE']
$cookie = $this->request->getCookie('myCookie'); // $_COOKIES['myCookie']
$file = $this->request->getUploadedFile('myfile'); // $_FILES['myfile']
$env = $this->request->getEnv('SOME_VAR'); // $_ENV['SOME_VAR']
}
}
Why should those values be accessed from the request object and not from the global array like $_FILES? Simple:
because its bad practice and will make testing harder.
Reading and writing session variables
To set, get or modify session variables, the ISession object has to be injected into the controller.
Then session variables can be accessed like this:
Note: The session is closed automatically for writing, unless you add the @UseSession annotation!
<?php
use OCP\ISession;
use OCP\IRequest;
private $session;
public function __construct($AppName, IRequest $request, ISession $session) {
$this->session = $session;
}
/**
* The following annotation is only needed for writing session values
* @UseSession
*/
public function writeASessionVariable() {
// read a session variable
$value = $this->session['value'];
// write a session variable
$this->session['value'] = 'new value';
}
76
Setting cookies
Cookies can be set or modified directly on the response class:
<?php
use DateTime;
use OCP\IRequest;
class BakeryController extends Controller {
/**
* Adds a cookie "foo" with value "bar" that expires after user closes the browser
* Adds a cookie "bar" with value "foo" that expires 2015-01-01
*/
public function addCookie() {
$response = new TemplateResponse(...);
$response->addCookie('foo', 'bar');
$response->addCookie('bar', 'foo', new DateTime('2015-01-01 00:00'));
return $response;
}
/**
* Invalidates the cookie "foo"
* Invalidates the cookie "bar" and "bazinga"
*/
public function invalidateCookie() {
$response = new TemplateResponse(...);
$response->invalidateCookie('foo');
$response->invalidateCookies(array('bar', 'bazinga'));
return $response;
}
}
1.12.3 Responses
Similar to how every controller receives a request object, every controller method has to to return a Response. This
can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder.
JSON
Returning JSON is simple, just pass an array to a JSONResponse:
<?php
1.12. Controllers
77
use OCP\AppFramework\Http\JSONResponse;
public function returnJSON() {
$params = array('test' => 'hi');
return new JSONResponse($params);
}
}
Because returning JSON is such an common task, theres even a shorter way how to do this:
<?php
public function returnJSON() {
return array('test' => 'hi');
}
}
Why does this work? Because the dispatcher sees that the controller did not return a subclass of a Response and asks
the controller to turn the value into a Response. Thats where responders come in.
Responders
Responders are short functions that take a value and return a response. They are used to return different kinds of
responses based on a format parameter which is supplied by the client. Think of an API that is able to return both
XML and JSON depending on if you call the URL with:
?format=xml
or:
?format=json
The appropriate responder is being chosen by the following criteria:

First the dispatcher checks the Request if there is a format parameter, e.g.:
?format=xml
or:
/index.php/apps/myapp/authors.{format}
78
If there is none, take the Accept header, use the first mimetype and cut off application/. In the following example
the format would be xml:
Accept: application/xml, application/json
If there is no Accept header or the responder does not exist, format defaults to json.
By default there is only a responder for JSON but more can be added easily:
<?php
public function returnHi() {
// XMLResponse has to be implemented
$this->registerResponder('xml', function($value) {
if ($value instanceof DataResponse) {
return new XMLResponse(
$value->getData(),
$value->getStatus(),
$value->getHeaders()
);
} else {
return new XMLResponse($value);
}
});
return array('test' => 'hi');
}
}
Note: The above example would only return XML if the format parameter was xml. If you want to return an
XMLResponse regardless of the format parameter, extend the Response class and return a new instance of it from the
controller method instead.
New in version 8.
Because returning values works fine in case of a success but not in case of failure that requires a custom HTTP error
code, you can always wrap the value in a DataResponse. This works for both normal responses and error responses.
<?php
use OCP\AppFramework\Http\Http;
public function returnHi() {
try {
1.12. Controllers
79
return new DataResponse(calculate_hi());

} catch (\Exception $ex) {
return new DataResponse(array('msg' => 'not found!'), Http::STATUS_NOT_FOUND);
}
}
}
Templates
A template can be rendered by returning a TemplateResponse. A TemplateResponse takes the following parameters:
appName: tells the template engine in which app the template should be located
templateName: the name of the template inside the template/ folder without the .php extension
parameters: optional array parameters that can is available in the template through $_, e.g.:
array('key' => 'something')
can be accessed through:

$_['key']
renderAs: defaults to user, tells ownCloud if it should include it in the web interface, or in case blank is passed
solely render the template
<?php
$templateName = 'main'; // will use templates/main.php
$parameters = array('key' => 'hi');
return new TemplateResponse($this->appName, $templateName, $parameters);
}
}
Redirects
A redirect can be achieved by returning a RedirectResponse:
<?php
use OCP\AppFramework\Http\RedirectResponse;
80

public function toGoogle() {
return new RedirectResponse('https://google.com');
}
}
Downloads
A file download can be triggered by returning a DownloadResponse:
<?php
use OCP\AppFramework\Http\DownloadResponse;
public function downloadXMLFile() {
$path = '/some/path/to/file.xml';
$contentType = 'application/xml';
return new DownloadResponse($path, $contentType);
}
}
Creating custom responses

If no premade Response fits the needed usecase, its possible to extend the Response baseclass and custom Response.
The only thing that needs to be implemented is the render method which returns the result as string.
Creating a custom XMLResponse class could look like this:
<?php
namespace OCA\MyApp\Http;
use OCP\AppFramework\Http\Response;
class XMLResponse extends Response {
private $xml;
public function construct(array $xml) {
$this->addHeader('Content-Type', 'application/xml');
$this->xml = $xml;
}
public function render() {
$root = new SimpleXMLElement('<root/>');
array_walk_recursive($this->xml, array ($root, 'addChild'));
return $xml->asXML();
1.12. Controllers
81
}
}
Streamed and lazily rendered responses

New in version 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:
<?php
use OCP\AppFramework\Http\StreamResponse;
public function downloadXMLFile() {
return new StreamResponse('/some/path/to/file.xml');
}
}
If you want to use a custom, lazily rendered response

OCP\AppFramework\Http\ICallbackResponse for your response:
simply
implement
the
interface
<?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.
Modifying the Content Securicy Policy

New in version 8.1.
By default ownCloud disables all resources which are not served on the same domain, forbids cross domain requests
and disables inline CSS and JavaScript by setting a Content Security Policy. However if an app relies on thirdparty
media or other features which are forbidden by the current policy the policy can be relaxed.
82
Note: Double check your content and edge cases before you relax the policy! Also read the documentation provided
by MDN
To relax the policy pass an instance of the ContentSecurityPolicy class to your response. The methods on the class can
be chained.
The following methods turn off security features by passing in true as the $isAllowed parameter
allowInlineScript (bool $isAllowed)
allowInlineStyle (bool $isAllowed)
allowEvalScript (bool $isAllowed)
The following methods whitelist domains by passing in a domain or * for any domain:
addAllowedScriptDomain (string $domain)
addAllowedStyleDomain (string $domain)
addAllowedFontDomain (string $domain)
addAllowedImageDomain (string $domain)
addAllowedConnectDomain (string $domain)
addAllowedMediaDomain (string $domain)
addAllowedObjectDomain (string $domain)
addAllowedFrameDomain (string $domain)
addAllowedChildSrcDomain (string $domain)
The following policy for instance allows images, audio and videos from other domains:
<?php
use OCP\AppFramework\Http\ContentSecurityPolicy;
$response = new TemplateResponse('myapp', 'main');
$csp = new ContentSecurityPolicy();
$csp->addAllowedImageDomain('*');
->addAllowedMediaDomain('*');
$response->setContentSecurityPolicy($csp);
}
}
OCS
New in version 8.1.
Note: This is purely for compatibility reasons. If you are planning to offer an external API, go for a RESTful API
1.12. Controllers
83
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:
<?php
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
Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an
appropriate HTTP error code to signal the client that an error occurred.
Each response subclass has access to the setStatus method which lets you set an HTTP status code. To return a
JSONResponse signaling that the author with id 1 has not been found, use the following code:
<?php
use OCP\AppFramework\Http\JSONResponse;
class AuthorController extends Controller {
try {
// try to get author with $id
} catch (NotFoundException $ex) {
84
return new JSONResponse(array(), Http::STATUS_NOT_FOUND);

}
}
}
1.12.4 Authentication
By default every controller method enforces the maximum security, which is:
Ensure that the user is admin
Ensure that the user is logged in
Check the CSRF token
Most of the time though it makes sense to also allow normal users to access the page and the PageController->index()
method should not check the CSRF token because it has not yet been sent to the client and because of that cant work.
To turn off checks the following Annotations can be added before the controller:
@NoAdminRequired: Also users that are not admins can access the page
@NoCSRFRequired: Dont check the CSRF token (use this wisely since you might create a security hole, to
understand what it does see Security Guidelines)
@PublicPage: Everyone can access that page without having to log in
A controller method that turns off all checks would look like this:
<?php
use OCP\IRequest;
/**
* @NoAdminRequired
* @NoCSRFRequired
* @PublicPage
*/
public function freeForAll() {
}
}
1.13 RESTful API

Offering a RESTful API is not different from creating a route and controllers for the web interface. It is recommended
though to inherit from ApiController and add @CORS annotations to the methods so that also web applications will
be able to access the API.
1.13. RESTful API
85
<?php
use \OCP\AppFramework\ApiController;
use \OCP\IRequest;
class AuthorApiController extends ApiController {
public function __construct($appName, IRequest $request) {
parent::__construct($appName, $request);
}
/**
* @CORS
*/
}
}
CORS also needs a separate URL for the preflighted OPTIONS request that easily be added by adding the following
route:
<?php
array(
'name' => 'author_api#preflighted_cors',
'url' => '/api/1.0/{path}',
'verb' => 'OPTIONS',
'requirements' => array('path' => '.+')
)
Keep in mind that multiple apps will likely depend on the API interface once it is published and they will move at
different speeds to react on changes implemented in the API. Therefore it is recommended to version the API in the
URL to not break existing apps when backwards incompatible changes are introduced:
/index.php/apps/myapp/api/1.0/resource
1.13.1 Modifying the CORS headers

By default the following values will be used for the preflighted OPTIONS request:
Access-Control-Allow-Methods: PUT, POST, GET, DELETE, PATCH
Access-Control-Allow-Headers: Authorization, Content-Type, Accept
Access-Control-Max-Age: 1728000
To add an additional method or header or allow less headers, simply pass additional values to the parent constructor:
<?php
use \OCP\AppFramework\ApiController;
86
use \OCP\IRequest;
class AuthorApiController extends ApiController {
public function __construct($appName, IRequest $request) {
parent::__construct(
$appName,
$request,
'PUT, POST, GET, DELETE, PATCH',
'Authorization, Content-Type, Accept',
1728000);
}
}
1.14 Templates
ownCloud provides its own templating system which is basically plain PHP with some additional functions and preset
variables. All the parameters which have been passed from the controller are available in an array called $_[], e.g.:
array('key' => 'something')
can be accessed through:

$_['key']
Note: To prevent XSS the following PHP functions for printing are forbidden: echo, print() and <?=. Instead
use the p() function for printing your values. Should you require unescaped printing, double check for XSS and use:
print_unescaped.
Printing values is done by using the p() function, printing HTML is done by using print_unescaped()
templates/main.php
<?php foreach($_['entries'] as $entry){ ?>
<p><?php p($entry); ?></p>
<?php
}
1.14.1 Including templates

Templates can also include other templates by using the $this->inc(templateName) method.
<?php print_unescaped($this->inc('sub.inc')); ?>
The parent variables will also be available in the included templates, but should you require it, you can also pass new
variables to it by using the second optional parameter as array for $this->inc.
templates/sub.inc.php
1.14. Templates
87
<div>I am included, but I can still access the parents variables!</div>

<?php p($_['name']); ?>
<?php print_unescaped($this->inc('other_template', array('variable' => 'value'))); ?>
1.14.2 Including CSS and JavaScript

To include CSS or JavaScript use the style and script functions:
<?php
script('myapp', 'script'); // add js/script.js
style('myapp', 'style'); // add css/style.css
1.14.3 Including images

To generate links to images use the image_path function:
<img src="<?php print_unescaped(image_path('myapp', 'app.png')); ?> />
1.15 JavaScript
The JavaScript files reside in the js/ folder and should be included in the template:
<?php
// add one file
script('myapp', 'script');
// adds js/script.js
// add multiple files in the same app

script('myapp', array('script', 'navigation'));
//
adds js/script.js js/navigation.js
// add vendor files (also allows the array syntax)

vendor_script('myapp', 'script'); // adds vendor/script.js
The recommended JavaScript framework to use is AngularJS. A nice tutorial screencast collection can be found on
Egghead.io
1.15.1 Sending the CSRF token

If any other JavaScript request library than jQuery is being used, the requests need to send the CSRF token as an HTTP
header named requesttoken. The token is available in the global variable oc_requesttoken.
For AngularJS the following lines would need to be added:
var app = angular.module('MyApp', []).config(['$httpProvider', function($httpProvider) {
$httpProvider.defaults.headers.common.requesttoken = oc_requesttoken;
}]);
88
1.15.2 Generating URLs

To send requests to ownCloud the base URL where ownCloud is currently running is needed. To get the base URL
use:
var baseUrl = OC.generateUrl('');
Full URLs can be genrated by using:

var authorUrl = OC.generateUrl('/apps/myapp/authors/1');
1.16 CSS
The CSS files reside in the css/ folder and should be included in the template:
<?php
// include one file
style('myapp', 'style');
// adds js/style.css
// include multiple files for the same app

style('myapp', array('style', 'navigation'));
// adds js/style.css, js/navigation.css
// include vendor file (also allows vendor syntax)

vendor_style('myapp', 'style'); // adds vendor/style.css
Web Components go into the component/ folder and can be imported like this:
<?php
// include one file
component('myapp', 'tabs');
// adds component/tabs.html
// include multiple files for the same app

component('myapp', array('tabs', 'forms'));
// adds component/tabs.html, component/forms.html
Note: Keep in mind that Web Components are still very new and you might need to add polyfills using Polymer
1.16.1 Standard layout

To use the commonly used layout consisting of sidebar navigation and content the app-navigation and app-content
ids can be used:
<div id="app">
<div id="app-navigation">Your navigation</div>
<div id="app-content">
<div id="app-content-wrapper">
Your content in here
</div>
</div>
</div>
1.16. CSS
89
For built in mobile support your content has to be wrapped inside another div with the id app-content-wrapper.
1.16.2 Navigation
ownCloud provides a default CSS navigation layout. If list entries should have 16x16 px icons, the with-icon class
can be added to the base ul. The maximum supported indention level is two, further indentions are not recommended.
<div id="app-navigation">
<ul class="with-icon">
<li><a href="#">First level entry</a></li>
<li>
<a href="#">First level container</a>
<ul>
<li><a href="#">Second level entry</a></li>
<li><a href="#">Second level entry</a></li>
</ul>
</li>
</ul>
</div>
Folders
Folders are like normal entries and are only supported for the first level. In contrast to normal entries, the links which
show the title of the folder need to have the icon-folder css class.
If the folder should be collapsible, the collapsible class and a button with the class collapse are needed. After adding
the collapsible class the folders child entries can be toggled by adding the open class to the list element:
<li class="collapsible open">
<button class="collapse"></button>
<a href="#" class="icon-folder">Folder name</a>
<ul>
<li><a href="#">Folder contents</a></li>
</ul>
</li>
</ul>
</div>
Drag and drop

The class which should be applied to a first level element (li) that hosts or can host a second level is drag-and-drop.
This will cause the hovered entry to slide down giving a visual hint that it can accept the dragged element. In case of
jQuery UIs droppable feature, the hoverClass option should be set to the drag-and-drop class.
<li class="drag-and-drop">
<a href="#" class="icon-folder">Folder name</a>
90
<ul>
</ul>
</li>
</ul>
</div>
Menus
New in version 8.
To add actions that affect the current list element you can add a menu for second and/or first level elements by adding
the button and menu inside the corresponding li element and adding the with-menu css class:
<ul>
<li class="with-counter with-menu">
<a href="#">First level entry</a>
<div class="app-navigation-entry-utils">
<ul>
<li class="app-navigation-entry-utils-counter">15</li>
<li class="app-navigation-entry-utils-menu-button svg"><button></button></li>
</ul>
</div>
<div class="app-navigation-entry-menu open">
<ul>
<li><button class="icon-rename svg" title="rename"></button></li>
<li><button class="icon-delete svg" title="delete"></button></li>
</ul>
</div>
</li>
</div>
The div with the class app-navigation-entry-utils contains only the button (class: app-navigation-entry-utils-menubutton) to display the menu but in many cases another entry is needed to display some sort of count (mails count,
unread feed count, etc.). In that case add the with-counter class to the list entry to adjust the correct padding and
text-oveflow of the entrys title.
The count should be limitted to 999 and turn to 999+ if any higher number is given. If AngularJS is used the following
filter can be used to get the correct behaviour:
app.filter('counterFormatter', function () {
'use strict';
return function (count) {
if (count > 999) {
return '999+';
}
return count;
};
});
1.16. CSS
91
Use it like this:

<li class="app-navigation-entry-utils-counter">{{ count | counterFormatter }}</li>
The menu is hidden by default (display: none) and has to be triggered by adding the open class to the app-navigationentry-menu div.
In case of AngularJS the following small directive can be added to handle all the display and click logic out of the box:
app.run(function ($document, $rootScope) {
'use strict';
$document.click(function (event) {
$rootScope.$broadcast('documentClicked', event);
});
});
app.directive('appNavigationEntryUtils', function () {
'use strict';
return {
restrict: 'C',
link: function (scope, elm) {
var menu = elm.siblings('.app-navigation-entry-menu');
var button = $(elm)
.find('.app-navigation-entry-utils-menu-button button');
button.click(function () {
menu.toggleClass('open');
});
scope.$on('documentClicked', function (scope, event) {
if (event.target !== button[0]) {
menu.removeClass('open');
}
});
}
};
});
Editing
New in version 8.
Often an edit option is needed an entry. To add one for a given entry simply hide the title and add the following div
inside the entry:
<li>
<a href="#" class="hidden">First level entry</a>
<div class="app-navigation-entry-edit">
<form>
<input type="text" value="First level entry" autofocus-on-insert>
<input type="submit" value="" class="action icon-checkmark">
</form>
</div>
92
</li>
</ul>
</div>
If AngularJS is used you want to autofocus the input box. This can be achieved by placing the show condition inside
an ng-if on the app-navigation-entry-edit div and adding the following directive:
app.directive('autofocusOnInsert', function () {
'use strict';
return function (scope, elm) {
elm.focus();
};
});
ng-if is required because it removes/inserts the element into the DOM dynamically instead of just adding a display:
none to it like ng-show and ng-hide.
Undo entry
New in version 8.
If you want to undo a performed action on a navigation entry such as deletion, you should show the undo directly in
place of the entry and make it disappear after location change or 7 seconds:
<li>
<a href="#" class="hidden">First level entry</a>
<div class="app-navigation-entry-deleted">
<div class="app-navigation-entry-deleted-description">Deleted X</div>
<button class="app-navigation-entry-deleted-button icon-history" title="Undo"></butt
</div>
</li>
</ul>
</div>
1.16.3 Settings Area

To create a settings area create a div with the id app-settings inside the app-navgiation div:
<div id="app">

<div id="app-settings">
<div id="app-settings-header">
<button class="settings-button"
data-apps-slide-toggle="#app-settings-content"
></button>
1.16. CSS
93
</div>
<div id="app-settings-content">

</div>
</div>
</div>
</div>
The data attribute data-apps-slide-toggle slides up a target area using a jQuery selector and hides the area if the user
clicks outside of it.
1.16.4 Icons
To use icons which are shipped in core, special class to apply the background image are supplied. All of these classes
use background-position: center and background-repeat: no-repeat.
icon-breadcrumb:
icon-loading:
icon-loading-dark:
icon-loading-small:
icon-add:
icon-caret:
icon-caret-dark:
icon-checkmark:
icon-checkmark-white:
icon-clock:
icon-close:
icon-confirm:
icon-delete:
icon-download:
icon-history:
icon-info:
icon-lock:
94
icon-logout:
icon-mail:
icon-more:
icon-password:
icon-pause:
icon-pause-big:
icon-play:
icon-play-add:
icon-play-big:
icon-play-next:
icon-play-previous:
icon-public:
icon-rename:
icon-search:
icon-settings:
icon-share:
icon-shared:
icon-sound:
icon-sound-off:
icon-star:
icon-starred:
icon-toggle:
icon-triangle-e:
icon-triangle-n:
icon-triangle-s:
icon-upload:
1.16. CSS
95
icon-upload-white:
icon-user:
icon-view-close:
icon-view-next:
icon-view-pause:
icon-view-play:
icon-view-previous:
icon-calendar-dark:
icon-contacts-dark:
icon-file:
icon-files:
icon-folder:
icon-filetype-text:
icon-filetype-folder:
icon-home:
icon-link:
icon-music:
icon-picture:
96
1.17 Translation
ownClouds translation system is powered by Transifex. To start translating sign up and enter a group. If your
community app should be added to Transifex contact someone of the core developers to set it up for you.
1.17.1 PHP
Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor
<?php

/**
* Controllers
*/
$container->registerService('AuthorService', function($c) {
$c->query('L10N')
);
});
$container->registerService('L10N', function($c) {
return $c->query('ServerContainer')->getL10N($c->query('AppName'));
});
}
}
Strings can then be translated in the following way:

<?php
namespace OCA\MyApp\Service;
use \OCP\IL10N;
class AuthorService {
private $trans;
public function __construct(IL10N $trans){
$this->trans = $trans;
}
1.17. Translation
97
public function getLanguageCode() {

return $this->trans->getLanguageCode();
}
public sayHello() {
return $this->trans->t('Hello');
}
public function getAuthorName($name) {
return $this->trans->t('Getting author %s', array($name));
}
public function getAuthors($count, $city) {
return $this->trans->n(
'%n author is currently in the city %s', // singular string
'%n authors are currently in the city %s', // plural string
$count,
array($city)
);
}
}
1.17.2 Templates
In every template the global variable $l can be used to translate the strings using its methods t() and n():
<div><?php p($l->t('Showing %s files', $_['count'])); ?></div>
<button><?php p($l->t('Hide')); ?></button>
1.17.3 JavaScript
There is currently no good way to translate JavaScript strings. One way to still use translated strings in the scripts is
to create an invisible HTML element with all the translations in it which can be parsed in the JavaScript code:
<ul id="translations">
<li id="add-new"><?php p($l->t('Add new file')); ?></li>
</ul>
var addNewTranslation = $('#add-new').text();
1.17.4 Hints
In case some translation strings may be translated wrongly because they have multiple meanings, you can add hints
which will be shown in the Transifex web-interface:
<ul id="translations">
<li id="add-new">
<?php
98
// TRANSLATORS Will be shown inside a popup and asks the user to add a new file
p($l->t('Add new file'));
?>
</li>
</ul>
1.17.5 Creating your own translatable files

If Transifex is not the right choice or the app is not accepted for translation, generate the gettext strings by yourself by
creating an l10n/ directory in the app folder and executing:
cd /srv/http/owncloud/apps/myapp/l10n
perl l10n.pl read myapp
The translation script requires Locale::PO and gettext, installable via:

apt-get install liblocale-po-perl gettext
The above script generates a template that can be used to translate all strings of an app. This template is located in the
folder template/ with the name myapp.pot. It can be used by your favored translation tool which then creates a
.po file. The .po file needs to be place in a folder named like the language code with the app name as filename - for
example l10n/es/myapp.po. After this step the perl script needs to be invoked to transfer the po file into our own
fileformat that is more easily readable by the server code:
perl l10n.pl write myapp
Now the following folder structure is available:

myapp/l10n
|-- es
|
|-- myapp.po
|-- es.js
|-- es.json
|-- es.php
|-- l10n.pl
|-- templates
|-- myapp.pot
You then just need the .php, .json and .js files for a working localized app.
1.18 Database Schema

ownCloud uses a database abstraction layer on top of either PDO, depending on the availability of PDO on the server.
The database schema is inside appinfo/database.xml in MDB2s XML scheme notation where the placeholders
*dbprefix* (*PREFIX* in your SQL) and *dbname* can be used for the configured database table prefix and database
name.
An example database XML file would look like this:
1.18. Database Schema
99
<?xml version="1.0" encoding="UTF-8" ?>

<database>
<name>*dbname*</name>
<create>true</create>
<overwrite>false</overwrite>
<charset>utf8</charset>
<table>
<name>*dbprefix*yourapp_items</name>
<declaration>
<field>
<name>id</name>
<type>integer</type>
<default>0</default>
<autoincrement>1</autoincrement>
<length>4</length>
</field>
<field>
<name>user</name>
<type>text</type>
<length>64</length>
</field>
<field>
<name>name</name>
<type>text</type>
</field>
<field>
<name>path</name>
<type>clob</type>
</field>
</declaration>
</table>
</database>
To update the tables used by the app, simply adjust the database.xml file and increase the app version number in
appinfo/version to trigger an update.
1.19 Database Access

The basic way to run a database query is to use the database connection provided by OCP\IDBConnection.
Inside your database layer class you can now start running queries like:
<?php
// db/authordao.php
namespace OCA\MyApp\Db;
use OCP\IDBConnection;
class AuthorDAO {
100
private $db;
public function __construct(IDBConnection $db) {
$this->db = $db;
}
public function find($id) {
$sql = 'SELECT * FROM `*PREFIX*myapp_authors` ' .
'WHERE ìd` = ?';
$stmt = $this->db->prepare($sql);
$stmt->bindParam(1, $id, \PDO::PARAM_INT);
$stmt->execute();
$row = $stmt->fetch();
$stmt->closeCursor();
return $row;
}
}
1.19.1 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 create a mapper, inherit from the mapper baseclass and call the parent constructor with the following parameters:
Database connection
Table name
Optional: Entity class name, defaults to \OCA\MyApp\Db\Author in the example below
<?php
// db/authormapper.php
use OCP\IDBConnection;
use OCP\AppFramework\Db\Mapper;
class AuthorMapper extends Mapper {
public function __construct(IDBConnection $db) {
parent::__construct($db, 'myapp_authors');
}
/**
* @throws \OCP\AppFramework\Db\DoesNotExistException if not found
* @throws \OCP\AppFramework\Db\MultipleObjectsReturnedException if more than one result
*/
1.19. Database Access
101
public function find($id) {

$sql = 'SELECT * FROM `*PREFIX*myapp_authors` ' .
'WHERE ìd` = ?';
return $this->findEntity($sql, [$id]);
}
public function findAll($limit=null, $offset=null) {

$sql = 'SELECT * FROM `*PREFIX*myapp_authors`';
return $this->findEntities($sql, $limit, $offset);
}
public function authorNameCount($name) {

$sql = 'SELECT COUNT(*) AS `count` FROM `*PREFIX*myapp_authors` ' .
'WHERE `name` = ?';
$stmt = $this->execute($sql, [$name]);
$row = $stmt->fetch();
$stmt->closeCursor();
return $row['count'];
}
}
Note: The cursor is closed automatically for all INSERT, DELETE, UPDATE queries and when calling the methods
findOneQuery, findEntities, findEntity, delete, insert and update. For custom calls using execute you should
always close the cursor after you are done with the fetching to prevent database lock problems on SqLite
Every mapper also implements default methods for deleting and updating an entity based on its id:
$authorMapper->delete($entity);
or:
$authorMapper->update($entity);
1.19.2 Entities
Entities are data objects that carry all the tables information for one row. Every Entity has an id field by default that
is set to the integer type. Table rows are mapped from lower case and underscore separated names to pascal case
attributes:
Table column name: phone_number
Property name: phoneNumber
<?php
// db/author.php
class Author extends Entity {
102
protected $stars;
protected $name;
protected $phoneNumber;
public function __construct() {
// add types in constructor
$this->addType('stars', 'integer');
}
}
Types
The following properties should be annotated by types, to not only assure that the types are converted correctly for
storing them in the database (e.g. PHP casts false to the empty string which fails on postgres) but also for casting them
when they are retrieving from the database.
The following types can be added for a field:
integer
float
boolean
Accessing attributes
Since all attributes should be protected, getters and setters are automatically generated for you:
<?php
// db/author.php
protected $stars;
protected $name;
}
$author = new Author();
$author->setId(3);
$author->getPhoneNumber()
// null
Custom attribute to database column mapping

By default each attribute will be mapped to a database column by a certain convention, e.g. phoneNumber will be
mapped to the column phone_number and vice versa. Sometimes it is needed though to map attributes to different
columns because of backwards compability. To define a custom mapping, simply override the columnToProperty
and propertyToColumn methods of the entity in question:
1.19. Database Access
103
<?php
// db/author.php
protected $stars;
protected $name;
// map attribute phoneNumber to the database column phonenumber
public function columnToProperty($column) {
if ($column === 'phonenumber') {
return 'phoneNumber';
} else {
return parent::columnToProperty($column);
}
}
public function propertyToColumn($property) {
if ($column === 'phoneNumber') {
return 'phonenumber';
} else {
return parent::propertyToColumn($property);
}
}
}
Slugs
Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain
values, the entity baseclass provides a slugify method for it:
<?php
$author = new Author();
$author->setName('Some*thing');
$author->slugify('name'); // Some-thing
1.20 Configuration
The config allows the app to set global, app and user settings can be injected from the ServerContainer. All values are
saved as strings and must be casted to the correct value.
<?php
104

/**
* Controllers
*/
$c->query('Config'),
$c->query('AppName')
);
});
$container->registerService('Config', function($c) {
return $c->query('ServerContainer')->getConfig();
});
}
}
1.20.1 System values

System values are saved in the config/config.php and allow to modify and read the global configuration:
<?php
use \OCP\IConfig;
private $config;
private $appName;
public function __construct(IConfig $config, $appName){
$this->config = $config;
$this->appName = $appName;
}
public function getSystemValue($key) {
return $this->config->getSystemValue($key);
}
public function setSystemValue($key, $value) {
$this->config->setSystemValue($key, $value);
}
}
1.20. Configuration
105
1.20.2 App values

App values are saved in the database per app and are useful for setting global app settings:
<?php
use \OCP\IConfig;
private $config;
private $appName;
}
public function getAppValue($key) {
return $this->config->getAppValue($this->appName, $key);
}
public function setAppValue($key, $value) {
$this->config->setAppValue($this->appName, $key, $value);
}
}
1.20.3 User values

User values are saved in the database per user and app and are good for saving user specific app settings:
<?php
use \OCP\IConfig;
private $config;
private $appName;
}
public function getUserValue($key, $userId) {
return $this->config->getUserValue($userId, $this->appName, $key);
}
public function setUserValue($key, $userId, $value) {
$this->config->setUserValue($userId, $this->appName, $key, $value);
106
}
}
1.21 Filesystem
Because users can choose their storage backend, the filesystem should be accessed by using the appropriate filesystem
classes.
Filesystem classes can be injected from the ServerContainer by calling the method getRootFolder(), getUserFolder()
or getAppFolder():
<?php
use \OCA\MyApp\Storage\AuthorStorage;

/**
* Storage Layer
*/
$container->registerService('AuthorStorage', function($c) {
return new AuthorStorage($c->query('RootStorage'));
});
$container->registerService('RootStorage', function($c) {
return $c->query('ServerContainer')->getRootFolder();
});
}
}
1.21.1 Writing to a file

All methods return a Folder object on which files and folders can be accessed, or filesystem operations can be performed relatively to their root. For instance for writing to file:owncloud/data/myfile.txt you should get the root folder
and use:
<?php
namespace OCA\MyApp\Storage;
class AuthorStorage {
1.21. Filesystem
107
private $storage;
public function __construct($storage){
$this->storage = $storage;
}
public function writeTxt($content) {
// check if file exists and write to it if possible
try {
try {
$file = $this->storage->get('/myfile.txt');
} catch(\OCP\Files\NotFoundException $e) {
$this->storage->touch('/myfile.txt');
$file = $this->storage->get('/myfile.txt');
}
// the id can be accessed by $file->getId();
$file->putContent($content);
} catch(\OCP\Files\NotPermittedException $e) {
// you have to create this exception by yourself ;)
throw new StorageException('Cant write to file');
}
}
}
1.21.2 Reading from a file

Files and folders can also be accessed by id, by calling the getById method on the folder.
<?php
private $storage;
}
public function getContent($id) {
try {
$file = $this->storage->getById($id);
if($file instanceof \OCP\Files\File) {
return $file->getContent();
} else {
throw new StorageException('Can not read from folder');
}
throw new StorageException('File does not exist');
}
}
}
108
1.22 Usermanagement
Users can be managed using the UserManager which is injected from the ServerContainer:
<?php
use \OCA\MyApp\Service\UserService;

/**
* Controllers
*/
$container->registerService('UserService', function($c) {
return new UserService(
$c->query('UserManager')
);
});
$container->registerService('UserManager', function($c) {
return $c->query('ServerContainer')->getUserManager();
});
}
}
1.22.1 Creating users

Creating a user is done by passing a username and password to the create method:
<?php
class UserService {
private $userManager;
public function __construct($userManager){
$this->userManager = $userManager;
}
public function create($userId, $password) {
return $this->userManager->create($userId, $password);
}
}
1.22. Usermanagement
109
1.22.2 Modifying users

Users can be modified by getting a user by the userId or by a search pattern. The returned user objects can then be
used to:
Delete them
Set a new password
Disable/Enable them
Get their home directory
<?php
class UserService {
}
public function delete($userId) {
return $this->userManager->get($userId)->delete();
}
// recoveryPassword is used for the encryption app to recover the keys
public function setPassword($userId, $password, $recoveryPassword) {
return $this->userManager->get($userId)->setPassword($password, $recoveryPassword);
}
public function disable($userId) {
return $this->userManager->get($userId)->setEnabled(false);
}
public function getHome($userId) {
return $this->userManager->get($userId)->getHome();
}
}
1.22.3 User Session Information

To login, logout or getting the currently logged in user, the UserSession has to be injected from the ServerContainer:
<?php
use \OCA\MyApp\Service\UserService;

110
/**
* Controllers
*/
$container->registerService('UserService', function($c) {
return new UserService(
$c->query('UserSession')
);
});
$container->registerService('UserSession', function($c) {
return $c->query('ServerContainer')->getUserSession();
});
// currently logged in user, userId can be gotten by calling the
// getUID() method on it
$container->registerService('User', function($c) {
return $c->query('UserSession')->getUser();
});
}
}
Then users can be logged in by using:

<?php
class UserService {
private $userSession;
public function __construct($userSession){
$this->userSession = $userSession;
}
public function login($userId, $password) {
return $this->userSession->login($userId, $password);
}
public function logout() {
$this->userSession->logout();
}
}
1.23 Hooks
Hooks are used to execute code before or after an event has occurred. This is for instance useful to run cleanup code
after users, groups or files have been deleted. Hooks should be registered in the app.php:
1.23. Hooks
111
<?php
$app = new Application();
$app->getContainer()->query('UserHooks')->register();
The hook logic should be in a separate class that is being registered in the Container
<?php
use \OCA\MyApp\Hooks\UserHooks;

/**
* Controllers
*/
$container->registerService('UserHooks', function($c) {
return new UserHooks(
$c->query('ServerContainer')->getUserManager()
);
});
}
}
<?php
namespace OCA\MyApp\Hooks;
class UserHooks {
}
public function register() {
$callback = function($user) {
// your code that executes before $user is deleted
};
$userManager->listen('\OC\User', 'preDelete', $callback);
}
}
112
1.23.1 Available hooks

The scope is the first parameter that is passed to the listen method, the second parameter is the method and the third
one the callback that should be executed once the hook is being called, e.g.:
<?php
// listen on user predelete
$callback = function($user) {
// your code that executes before $user is deleted
};
$userManager->listen('\OC\User', 'preDelete', $callback);
Hooks can also be removed by using the removeListener method on the object:
<?php
// delete previous callback
$userManager->removeListener(null, null, $callback);
The following hooks are available:

Session
Injectable from the ServerContainer by calling the method getUserSession().
Hooks available in scope \OC\User:
preSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
postSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
preDelete (\OC\User\User $user)
postDelete (\OC\User\User $user)
preCreateUser (string $uid, string $password)
postCreateUser (\OC\User\User $user)
preLogin (string $user, string $password)
postLogin (\OC\User\User $user)
logout ()
UserManager
Injectable from the ServerContainer by calling the method getUserManager().
Hooks available in scope \OC\User:
preSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
postSetPassword (\OC\User\User $user, string $password, string $recoverPassword)
preDelete (\OC\User\User $user)
postDelete (\OC\User\User $user)
preCreateUser (string $uid, string $password)
1.23. Hooks
113
postCreateUser (\OC\User\User $user, string $password)

GroupManager
Hooks available in scope \OC\Group:
preAddUser (\OC\Group\Group $group, \OC\User\User $user)
postAddUser (\OC\Group\Group $group, \OC\User\User $user)
preRemoveUser (\OC\Group\Group $group, \OC\User\User $user)
postRemoveUser (\OC\Group\Group $group, \OC\User\User $user)
preDelete (\OC\Group\Group $group)
postDelete (\OC\Group\Group $group)
preCreate (string $groupId)
postCreate (\OC\Group\Group $group)
Filesystem Root
Injectable from the ServerContainer by calling the method getRootFolder(), getUserFolder() or getAppFolder().
Filesystem hooks available in scope \OC\Files:
preWrite (\OCP\Files\Node $node)
postWrite (\OCP\Files\Node $node)
preCreate (\OCP\Files\Node $node)
postCreate (\OCP\Files\Node $node)
preDelete (\OCP\Files\Node $node)
postDelete (\OCP\Files\Node $node)
preTouch (\OCP\Files\Node $node, int $mtime)
postTouch (\OCP\Files\Node $node)
preCopy (\OCP\Files\Node $source, \OCP\Files\Node $target)
postCopy (\OCP\Files\Node $source, \OCP\Files\Node $target)
preRename (\OCP\Files\Node $source, \OCP\Files\Node $target)
postRename (\OCP\Files\Node $source, \OCP\Files\Node $target)
Filesystem Scanner
Filesystem scanner hooks available in scope \OC\Utils\Scanner:
scanFile (string $absolutePath)
scanFolder (string $absolutePath)
114
1.24 Background Jobs (Cron)

Background/cron jobs are usually registered in the appinfo/app.php by using the addRegularTask method, the
class and the method to run:
<?php
\OCP\Backgroundjob::addRegularTask('\OCA\MyApp\Cron\SomeTask', 'run');
The class for the above example would live in cron/sometask.php. Try to keep the method as small as possible
because its hard to test static methods. Simply reuse the app container and execute a service that was registered in it.
<?php
namespace OCA\MyApp\Cron;
use \OCA\MyApp\AppInfo\Application;
class SomeTask {
public static function run() {
$app = new Application();
$container = $app->getContainer();
$container->query('SomeService')->run();
}
}
Dont forget to configure the cron service on the server by executing:

sudo crontab -u http -e
where http is your web server user, and add:

*/15
* php -f /srv/http/owncloud/cron.php
1.25 Logging
The logger can be injected from the ServerContainer:
<?php

1.24. Background Jobs (Cron)
115
/**
* Controllers
*/
$c->query('Logger'),
$c->query('AppName')
);
});
$container->registerService('Logger', function($c) {
return $c->query('ServerContainer')->getLogger();
});
}
}
and then be used in the following way:

<?php
use \OCP\ILogger;
private $logger;
private $appName;
public function __construct(ILogger $logger, $appName){
$this->logger = $logger;
}
public function log($message) {
$this->logger->error($message, array('app' => $this->appName));
}
}
The following methods are available:

emergency
alert
critical
error
warning
notice
info
debug
116
1.26 Testing
All PHP classes can be tested with PHPUnit, JavaScript can be tested by using Karma.
1.26.1 PHP
The PHP tests go into the tests/ directory. Unfortunately the classloader in core requires a running server (as in fully
configured and setup up with a database connection). This is unfortunately too complicated and slow so a separate
classloader has to be provided. If the app has been generated with the ocdev startapp command, the classloader is
already present in the the tests/ directory and PHPUnit can be run with:
phpunit tests/
PHP classes should be tested by accessing them from the container to ensure that the container is wired up properly.
Services that should be mocked can be replaced directly in the container.
A test for the AuthorStorage class in Filesystem:
<?php
private $storage;
}
public function getContent($id) {
try {
$file = $this->storage->getById($id);
if($file instanceof \OCP\Files\File) {
return $file->getContent();
} else {
throw new StorageException('Can not read from folder');
}
throw new StorageException('File does not exist');
}
}
}
would look like this:

<?php
// tests/storage/AuthorStorageTest.php
namespace OCA\MyApp\Tests\Storage;
class AuthorStorageTest extends \Test\TestCase {
private $container;
private $storage;
1.26. Testing
117
protected function setUp() {

parent::setUp();
$app = new \OCA\MyApp\AppInfo\Application();
$this->container = $app->getContainer();
$this->storage = $storage = $this->getMockBuilder('\OCP\Files\Folder')
->getMock();
$this->container->registerService('RootStorage', function($c) use ($storage) {
return $storage;
});
}
/**
* @expectedException \OCA\MyApp\Storage\StorageException
*/
public function testFileNotFound() {
$this->storage->expects($this->once())
->method('get')
->will($this->throwException(new \OCP\Files\NotFoundException()));
$this->container['AuthorStorage']->getContent(3);
}
}
Make sure to extend the \Test\TestCase class with your test and always call the parent methods, when overwriting setUp(), setUpBeforeClass(), tearDown() or tearDownAfterClass() method from the TestCase. These methods set up important stuff and clean up the system after the test, so the next test can run without side
effects, like remaining files and entries in the file cache, etc.
1.27 App Development

1.27.1 Intro
Before you start, please check if there already is a similar app you could contribute to. Also, feel free to communicate
your idea and plans to the user mailing list or developer mailing list so other contributors might join in.
Then, please make sure you have set up a development environment:
Development Environment
Before starting to write an app please read the security and coding guidelines:
Security Guidelines
Coding Style & General Guidelines
After this you can start with the tutorial
Tutorial
118
1.27.2 App development

Take a look at the changes in this version:
Changelog
Create a new app:
Create an app
Inner parts of an app:
Navigation and Pre-App configuration
App Metadata
Classloader
Requests
How a request is being processed:
Request lifecycle
Routing
Middleware
Container
Controllers | RESTful API
View
The apps presentation layer:
Templates
JavaScript
CSS
Translation
Storage
Create database tables, run Sql queries, store/retrieve configuration information and access the filesystem:
Database Schema
Database Access
Configuration
Filesystem
Authentication & Users
Creating, deleting, updating, searching, login and logout:
Usermanagement
1.27. App Development
119
Hooks
Listen on events like user creation and execute code:
Hooks
Background Jobs
Periodically run code in the background:
Background Jobs (Cron)
Logging
Log to the data/owncloud.log:
Logging
Testing
Write automated tests to ensure stability and ease maintenance:
Testing
PHPDoc Class Documentation
ownCloud class and function documentation:
ownCloud App API
1.28 Android Application Development

ownCloud provides an official ownCloud Android client, which gives its users access to their files on their ownCloud.
It also includes functionality like automatically uploading pictures and videos to ownCloud.
For third party application developers, ownCloud offers the ownCloud Android library under the MIT license.
1.28.1 Android ownCloud Client development

If you are interested in working on the ownCloud android client, you can find the source code in github. The setup and
process of contribution is documented here.
You might want to start with doing one or two junior jobs to get into the code and note our General Contributor
Guidelines
Note that contribution to the Android client require signing the ownCloud Contributor Agreement.
120
1.28.2 ownCloud Android Library

This document will describe how to the use ownCloud Android Library. The ownCloud Android Library allows a
developer to communicate with any ownCloud server; among the features included are file synchronization, upload
and download of files, delete rename files and folders, etc.
This library may be added to a project and seamlessly integrates any application with ownCloud.
The tool needed is any IDE for Android. This guide includes some screenshots showing examples in Eclipse.
Library Installation
Obtaining the library
The ownCloud Android library may be obtained from the following Github repository:
https://github.com/owncloud/android-library
Once obtained, this code should be compiled. The Github repository not only contains the library, but also a sample
project, sample_client sample_client properties/android/librerias , which will assist in learning how to use the library.
Add the library to a project
There are different methods to add an external library to a project, then we will describe one of them.
1. Compile the ownCloud Android Library
2. Define a dependency within your project.
For that, access to Properties > Android > Library ** ** and click on add and select the ownCloud Android library
1.28. Android Application Development
121
Then all the public classes and methods of the library will be available for your own app.
Examples
Init the library
Start using the library; it is needed to init the object mClient that will be in charge of keeping the communication with
the server.
Code example
public class MainActivity extends Activity
implements OnRemoteOperationListener,
OnDatatransferProgressListener {
122
private OwnCloudClient mClient;

private Handler mHandler = new Handler();
...
public void onCreate(Bundle savedInstanceState) {
...
// Parse URI to the base URL of the ownCloud server
Uri serverUri = Uri.parse(getString(R.string.server_base_url));
// Create client object to perform remote operations
mClient = OwnCloudClientFactory.createOwnCloudClient(
serverUri,
this,
// Activity or Service context
true);
Set credentials
Authentication on the app is possible by 3 different methods:

Basic authentication, user name and password
Bearer access token (oAuth2)
Cookie (SAML-based single-sign-on)
Code example
package com.owncloud.android.lib.common;
public class OwnCloudClient extends HttpClient {
...
// Set basic credentials
client.setCredentials(
OwnCloudCredentialsFactory.newBasicCredentials(username, password)
);
// Set bearer access token
OwnCloudCredentialsFactory.newBearerCredentials(accessToken)
);
// Set SAML2 session token
OwnCloudCredentialsFactory.newSamlSsoCredentials(cookie)
);
}
Create a folder
Create a new folder on the cloud server, the info needed to be sent is the path of the new folder.
123
Code example
private void startFolderCreation(String newFolderPath) {

CreateRemoteFolderOperation createOperation = new CreateRemoteFolderOperation(newFolderPath, false
createOperation.execute( mClient , this , mHandler);
}
@Override
public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) {
if (operation instanceof CreateRemoteFolderOperation) {
if (result.isSuccess()) {
// do your stuff here
}
}
...
}
Read folder
Get the content of an existing folder on the cloud server, the info needed to be sent is the path of the folder, in the
example shown it has been asked the content of the root folder. As answer of this method, it will be received an array
with all the files and folders stored in the selected folder.
Code example
private void startReadRootFolder() {

ReadRemoteFolderOperation refreshOperation = new ReadRemoteFolderOperation(FileUtils.PATH_SEPARATO
// root folder
refreshOperation.execute(mClient, this, mHandler);
}
@Override
if (operation instanceof ReadRemoteFolderOperation) {
List< RemoteFile > files = result.getData();
}
}
...
}
Read file
Get information related to a certain file or folder, information obtained is: filePath, filename, isDirectory,
size and date.
Code example
private void startReadFileProperties(String filePath) {
ReadRemoteFileOperation readOperation = new ReadRemoteFileOperation(filePath);
readOperation.execute(mClient, this, mHandler);
124
}
@Override
if (operation instanceof ReadRemoteFileOperation) {
RemoteFile file = result.getData()[0];
}
}
...
}
Delete file or folder
Delete a file or folder on the cloud server. The info needed is the path of folder/file to be deleted.
Code example
private void startRemoveFile(String filePath) {
RemoveRemoteFileOperation removeOperation = new RemoveRemoteFileOperation(remotePath);
removeOperation.execute( mClient , this , mHandler);
}
@Override
if (operation instanceof RemoveRemoteFileOperation) {
}
}
...
}
Download a file
Download an existing file on the cloud server. The info needed is path of the file on the server and targetDirectory,
path where the file will be stored on the device.
Code example
private void startDownload(String filePath, File targetDirectory) {

DownloadRemoteFileOperation downloadOperation = new DownloadRemoteFileOperation(filePath, targetDi
downloadOperation.addDatatransferProgressListener(this);
downloadOperation.execute( mClient, this, mHandler);
}
@Override
public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) {
if (operation instanceof DownloadRemoteFileOperation) {
125
}
}
}
@Override
public void onTransferProgress( long progressRate, long totalTransferredSoFar, long totalToTransfer,
mHandler.post( new Runnable() {
@Override
public void run() {
// do your UI updates about progress here
}
});
}
Upload a file
Upload a new file to the cloud server. The info needed is fileToUpload, path where the file is stored on the device,
remotePath, path where the file will be stored on the server and mimeType.
Code example
private void startUpload (File fileToUpload, String remotePath, String mimeType) {

UploadRemoteFileOperation uploadOperation = new UploadRemoteFileOperation( fileToUpload.getAbsolut
uploadOperation.addDatatransferProgressListener(this);
uploadOperation.execute(mClient, this, mHandler);
}
@Override
if (operation instanceof UploadRemoteFileOperation) {
}
}
}
@Override
public void onTransferProgress(long progressRate, long totalTransferredSoFar, long totalToTransfer,
mHandler.post( new Runnable() {
@Override
public void run() {
// do your UI updates about progress here
}
});
}
Move a file or folder
Move an exisintg file or folder to a different location in the ownCloud server. Parameters needed are the path to the
file or folder to move, and the new path desired for it. The parent folder of the new path must exist in the server.
When the parameter overwrite is set to true, the file or folder is moved even if the new path is already used by a
different file or folder. This one will be replaced by the former.
126
Code example
private void startFileMove(String filePath, String newFilePath, boolean overwrite) {

MoveRemoteFileOperation moveOperation = new MoveRemoteFileOperation(filePath, newFilePath, overwri
moveOperation.execute( mClient , this , mHandler);
}
@Override
if (operation instanceof MoveRemoteFileOperation) {
}
}
...
}
Read shared items by link
Get information about what files and folder are shared by link (the object mClient contains the information about the
server url and account)
Code example
private void startAllSharesRetrieval() {
GetRemoteSharesOperation getSharesOp = new GetRemoteSharesOperation();
getSharesOp.execute( mClient , this , mHandler);
}
@Override
if (operation instanceof GetRemoteSharesOperation) {
ArrayList< OCShare > shares = new ArrayList< OCShare >();
for (Object obj: result.getData()) {
shares.add(( OCShare) obj);
}
}
}
}
Get the share resources for a given file or folder
Get information about what files and folder are shared by link on a certain folder. The info needed is filePath, path of
the file/folder on the server, the Boolean variable, getReshares, come from the Sharing api, from the moment it is not
in use within the ownCloud Android library.
Code example
private void startSharesRetrievalForFileOrFolder(String filePath, boolean getReshares) {

GeteRemoteSharesForFileOperation operation = new GetRemoteSharesForFileOperation(filePath, getResh
operation.execute( mClient, this, mHandler);
127
private void startSharesRetrievalForFilesInFolder(String folderPath, boolean getReshares) {

GetRemoteSharesForFileOperation operation = new GetRemoteSharesForFileOperation(folderPath, getRes
}
@Override
if (operation instanceof GetRemoteSharesForFileOperation) {
ArrayList< OCShare > shares = new ArrayList< OCShare >();
for (Object obj: result.getData()) {
shares.add(( OCShare) obj);
}
}
}
}
Share link of file or folder
Share a file or a folder from your cloud server by link.

The info needed is filePath, the path of the item that you want to share and Password, this comes from the Sharing api,
from the moment it is not in use within the ownCloud Android library.
Code example
private void startCreationOfPublicShareForFile(String filePath, String password) {

CreateRemoteShareOperation operation = new CreateRemoteShareOperation(filePath, ShareType.PUBLIC_L
operation.execute( mClient , this , mHandler);
}
private void startCreationOfGroupShareForFile(String filePath, String groupId) {

CreateRemoteShareOperation operation = new CreateRemoteShareOperation(filePath, ShareType.GROUP, g
operation.execute(mClient, this, mHandler);
}
private void startCreationOfUserShareForFile(String filePath, String userId) {

CreateRemoteShareOperation operation = new CreateRemoteShareOperation(filePath, ShareType.USER, us
operation.execute(mClient, this, mHandler);
}
@Override
if (operation instanceof CreateRemoteShareOperation) {
OCShare share = (OCShare) result.getData ().get(0);
}
}
}
128
Delete a share resource
Stop sharing by link a file or a folder from your cloud server.

The info needed is the object OCShare that you want to stop sharing by link.
Code example
private void startShareRemoval(OCShare share) {

RemoveRemoteShareOperation operation = new RemoveRemoteShareOperation((int) share.getIdRemoteShare
}
@Override
if (operation instanceof RemoveRemoteShareOperation) {
}
}
}
Tips
Credentials must be set before calling any method

Paths must not be on URL Encoding
Correct path: http://www.myowncloudserver.com/owncloud/remote.php/webdav/PopMusic
Wrong path: http://www.myowncloudserver.com/owncloud/remote.php/webdav/Pop%20Music/
There are some forbidden characters to be used in folder and files names on the server, same on the ownCloud
Android Library ,/,<,>,:,,|,?,*
Upload and download actions may be cancelled thanks to the objects uploadOperation.cancel(), downloadOperation.cancel()
Unit tests, before launching unit tests you have to enter your account information (server url, user and password)
on TestActivity.java
1.29 iOS Application Development

ownCloud provides an official ownCloud iOS client, which gives its users access to their files on their ownCloud. It
also includes functionality like automatically uploading pictures and videos to ownCloud.
For third party application developers, ownCloud offers the ownCloud iOS library under the MIT license.
1.29.1 iOS ownCloud Client development

If you are interested in working on the ownCloud iOS client, you can find the source code in github. The setup and
process of contribution is documented here.
You might want to start with doing one or two junior jobs to get into the code and note our General Contributor
Guidelines
1.29. iOS Application Development
129
Note that contribution to the iOS client require signing the iOS addendum to the ownCloud Contributor Agreement.
You are permitted to test the iOS client on Apple hardware thanks to the iOS license exception.
1.29.2 ownCloud iOS Library

This document will describe how to the use ownCloud iOS library. The ownCloud iOS library for iOS allows a
developer to communicate with any ownCloud server; among the features included are file synchronization, upload
and download of files, delete rename and move of files and folders and share files or folders by link among others.
This library may be added to a project and seamlessly integrates any application with ownCloud.
The tool needed is Xcode 6, this guide includes some screenshots showing examples in Xcode 6.
Library Installation
Obtaining the library
The ownCloud iOS library may be obtained from the following Github repository:
[email protected]:owncloud/ios-library.git
Once obtained, this code should be compiled with Xcode 6. The Github repository not only contains the library,
ownCloud iOS library, but also contains a sample project, OCLibraryExample, which will assist in learning how to
use the library.
Add the library to a project
There are two methods to add this library to a project.

Reference the headers and library binary file (.a) directly.
Include the library as a subproject.
Which method to choose depends on user preference as well as whether the source code and project file of the static
library are available.
Reference headers and library binary files Follow these steps if this is the desired method.
1. Compile the ownCloud iOS library and run the project. A libownCloudiOS.a file will be generated.
The following files are required:
Library file
libownCloudiOS.a (Library)
Library Classes
OCCommunication.h (Accessors) Import in the communication class
OCErrorMsg.h (Error Messages) Import in the communication class
OCFileDto.h and OCFileDto.m (File/Folder object) Import when using
readFolder and readFile methods
OCFrameworkConstants.h (Customize constants)
130
2. Add the library file to the project. From the Build Phases tab, scroll to Link binary files and select the + to
add a library. Select the library file.
3. Add the path of the library header files. Under the Build Settings tab, select the target library and add the path in
the Header Search Paths field.
131
4. Remaining in the Build Setting tab, add the flag -Obj-C under the Other Linker Flags option.
At this stage, the library is included on your project and you can start communicating with the ownCloud server.
132
Include the library as a subproject Follow these steps if this is the desired method.
5. Add the file ownCloud iOS library.xcodeproj to the project via drag and drop.
6. Within the project, navigate to the Build Phases tab. Under the Target Dependencies section, select the + and
choose the library target.
133
7. Link the library file to the project target. Under the Build Phases tab, select the + under the Link Binary with
Libraries section and select the library file.
134
8. Add the flag -Obj-C to Other Linker Flags under the project target on the Build Settings tab.
9. Finally add the path of the library headers. Under the Build Settings tab, add the path under the Header Search
Paths option.
Sources
Creating a static library in iOS tutorial (raywenderlich.com)
135
Apple iOS static library documentation

Examples
Init the library
Start using the library, it is needed to init the object OCCommunication.

We recommend using the singleton method in the AppDelegate class in order to use the ownCloud iOS library.
Code example
#import "OCCommunication.h"
+ (OCCommunication *)sharedOCCommunication
{
static OCCommunication* sharedOCCommunication = nil;
if (sharedOCCommunication == nil)
{
sharedOCCommunication = [ [ OCCommunicationalloc] init ];
}
return sharedOCCommunication;
}
Also could happen that you need to overwrite the class AFURLSessionManager to manage SSL Certificates
#import "OCCommunication.h"
+ (OCCommunication*)sharedOCCommunication
{
static OCCommunication* sharedOCCommunication = nil;
if (sharedOCCommunication == nil)
{
//Network Upload queue for NSURLSession (iOS 7)
NSURLSessionConfiguration *configuration = [NSURLSessionConfiguration backgroundSessionConfigura
configuration.HTTPMaximumConnectionsPerHost = 1;
configuration.requestCachePolicy = NSURLRequestReloadIgnoringLocalCacheData;
OCURLSessionManager *uploadSessionManager = [[OCURLSessionManager alloc] initWithSessionConfigur
[uploadSessionManager.operationQueue setMaxConcurrentOperationCount:1];
[uploadSessionManager setSessionDidReceiveAuthenticationChallengeBlock:^NSURLSessionAuthChalleng
return NSURLSessionAuthChallengePerformDefaultHandling;
}];
sharedOCCommunication = [[OCCommunication alloc] initWithUploadSessionManager:uploadSessionManag

}
return sharedOCCommunication;
}
Set credentials
Authentication on the app is possible by 3 different methods:
136
Basic authentication, user name and password

Cookie
Token (oAuth)
Code example
#Basic authentication, user name and password
[[ AppDelegate sharedOCCommunication ] setCredentialsWithUser : userName andPassword : password ];
#Authentication with cookie
[[ AppDelegate sharedOCCommunication ] setCredentialsWithCookie : cookie ];
#Authentication with token
[[ AppDelegate sharedOCCommunication ] setCredentialsOauthWithToken : token ];
Create a folder
Create a new folder on the cloud server, the info needed to be sent is the path of the new folder.
Code example
[[ AppDelegate sharedOCCommunication ] createFolder :path onCommunication : [ AppDelegate sharedOCCo

successRequest :^( NSHTTPURLResponse *response, NSString *redirectedServer) {
//Folder Created
}
failureRequest :^( NSHTTPURLResponse *response, NSError *error) {
//Failure
switch (response.statusCode) {
case kOCErrorServerUnauthorized :
//Bad credentials
break;
case kOCErrorServerForbidden :
//Forbidden
break;
case kOCErrorServerPathNotFound :
//Not Found
break;
case kOCErrorServerTimeout :
//timeout
break;
default:
//default
break;
}
}
errorBeforeRequest :^( NSError *error) {
//Error before request
137
if (error.code == OCErrorForbidenCharacters) {
//Forbidden characters
}
else
{
//Other error
}
}];
Read folder
Get the content of an existing folder on the cloud server, the info needed to be sent is the path of the folder. As answer
of this method, it will be received an array with all the files and folders stored in the selected folder.
Code example
[[ AppDelegate sharedOCCommunication] readFolder:path onCommunication:[ AppDelegate sharedOCCommunic

successRequest:^( NSHTTPURLResponse *response, NSArray *items, NSString *redirectedServer) {
//Success
for ( OCFileDto * ocFileDto in items) {
NSLog( @"item path: %@%@" , ocFileDto.filePath, ocFileDto.fileName);
}
}
failureRequest:^( NSHTTPURLResponse *response, NSError *error) {
//Failure
case kOCErrorServerPathNotFound :
//Path not found
break;
//Bad credentials
break;
case kOCErrorServerForbidden :
//Forbidden
break;
case kOCErrorServerTimeout :
//Timeout
break ;
default :
break;
}
}];
Read file
Get information related to a certain file or folder. Although, more information can be obtained, the library only gets
the eTag.
Other properties of the file or folder may be obtained: filePath, filename, isDirectory, size and date
138
Code example
[[ AppDelegate sharedOCCommunication ] readFile :path onCommunication :[ AppDelegate sharedOCCommuni

successRequest :^( NSHTTPURLResponse *response, NSArray *items, NSString *redirectedServer) {
OCFileDto *ocFileDto = [items objectAtIndex : 0 ];
NSLog ( @"item etag: %lld" , ocFileDto. etag); }
case kOCErrorServerPathNotFound:
//Path not found
break;
case kOCErrorServerUnauthorized:
//Bad credentials
break;
case kOCErrorServerForbidden:
//Forbidden
break;
case kOCErrorServerTimeout:
//Timeout
break;
default:
break;
}
}];
Move file or folder
Move a file or folder from their current path to a new one on the cloud server. The info needed is the origin path and
the destiny path.
Code example
[[ AppDelegate sharedOCCommunication ] moveFileOrFolder :sourcePath toDestiny :destinyPath onCommuni

//File/Folder moved or renamed
}
//Failure
//Path not found
break;
//Bad credentials
break;
//Forbidden
break;
//Timeout
break;
default:
break;
139
}
}
errorBeforeRequest :^( NSError *error) {
if (error.code == OCErrorMovingTheDestinyAndOriginAreTheSame) {
//The destiny and the origin are the same
}
else if (error.code == OCErrorMovingFolderInsideHimself) {
//Moving folder inside himself
}
else if (error.code == OCErrorMovingDestinyNameHaveForbiddenCharacters) {
//Forbidden Characters
}
else
{
//Default
}
}];
Delete file or folder
Delete a file or folder on the cloud server. The info needed is the path to delete.
Code example
[[ AppDelegate sharedOCCommunication ] deleteFileOrFolder :path onCommunication :[ AppDelegate
sharedOCCommunication ] successRequest :^( NSHTTPURLResponse *response, NSString *redirectedServer)
//File or Folder deleted
}
//Path not found
break;
//Bad credentials
break;
//Forbidden
break;
//Timeout
break;
default:
break;
}
}];
140
Download a file
Download an existing file on the cloud server. The info needed is the server URL, path of the file on the server and
localPath, path where the file will be stored on the device and a boolean to indicate if is neccesary to use LIFO queue
or FIFO.
Code example
NSOperation *op = nil;

op = [[ AppDelegate sharedOCCommunication ] downloadFile :remotePath toDestiny :localPath withLIFOSy
progressDownload :^( NSUInteger bytesRead, long long totalBytesRead, long long totalBytesExpectedToR
//Calculate percent
float percent = ( float)totalBytesRead / totalBytesExpectedToRead;
NSLog ( @"Percent of download: %f" , percent); }
successRequest :^(NSHTTPURLResponse *response, NSString *redirectedServer) {
//Download complete
}
failureRequest :^(NSHTTPURLResponse *response, NSError *error) {
switch (response. statusCode) {
//Bad credentials
break;
//Forbidden
break;
case kOCErrorProxyAuth:
//Proxy access required
break;
//Path not found
break;
default:
//Default
break;
}
}
shouldExecuteAsBackgroundTaskWithExpirationHandler :^{
[op cancel ];
}];
Download a file with background session
Download an existing file storaged on the cloud server using background session, only supported by iOS 7 and higher.
The info needed is, the server URL: path where the file is stored on the server; localPath: path where the file will be
stored on the device; and NSProgress: object where get the callbacks of the upload progress.
To get the callbacks of the progress is needed use a KVO in the progress object. We add the code in this example of
the call to set the KVO and the method where catch the notifications.
Code example
141
NSURLSessionDownloadTask *downloadTask = nil;

NSProgress *progress = nil;
downloadTask = [_sharedOCCommunication downloadFileSession:serverUrl toDestiny:localPath defaultPrio

//Upload complete
} failureRequest:^(NSURLResponse *response, NSError *error) {
switch (error.code) {
case kCFURLErrorUserCancelledAuthentication:
//Authentication cancelled
break;
default:
//Bad credentials
break;
//Forbidden
break;
break;
//Path not found
break;
default:
//Default
break;
}
break;
}
}];
// Observe fractionCompleted using KVO

[progress addObserver:self forKeyPath:@"fractionCompleted" options:NSKeyValueObservingOptionNew con
//Method to catch the progress notifications with callbacks

- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change
{
if ([keyPath isEqualToString:@"fractionCompleted"] && [object isKindOfClass:[NSProgress class]])
NSProgress *progress = (NSProgress *)object;
float percent = roundf (progress.fractionCompleted * 100);
//We make it on the main thread because we came from a delegate
dispatch_async(dispatch_get_main_queue(), ^{
NSLog(@"Progress is %f", percent);
});
}
}
142
Set callback when background download task finishes
Method to set callbacks of the pending download transfers when the app starts. Its used when there are pendings
download background transfers. The block is executed when a pending background task finishes.
Code example
[[AppDelegate sharedOCCommunication] setDownloadTaskComleteBlock:^NSURL *(NSURLSession *session, NSU
}];
Set progress callback with pending background download tasks
Method to set progress callbacks of the pending download transfers. Its used when there are pendings background
download transfers. The block is executed when a pending task get a input porgress.
Code example
[[AppDelegate sharedOCCommunication] setDownloadTaskDidGetBodyDataBlock:^(NSURLSession *session, NSU
}];
Upload a file
Upload a new file to the cloud server. The info needed is localPath, path where the file is stored on the device and
server URL, path where the file will be stored on the server.
Code example
NSOperation *op = nil;

op = [[ AppDelegate sharedOCCommunication ] uploadFile :localPath toDestiny : remotePath onCommunica
progressUpload :^( NSUInteger bytesWrote, long long totalBytesWrote, long long totalBytesExpectedToW
//Calculate upload percent
if ( totalBytesExpectedToRead/1024 != 0) {
if ( bytesWrote > 0) {
float percent = totalBytesWrote* 100 / totalBytesExpectedToRead;
NSLog ( @"Percent: %f" , percent);
}
}
}
//Upload complete
}
failureRequest :^( NSHTTPURLResponse *response, NSString *redirectedServer, NSError *error) {
switch (response. statusCode) {
//Bad credentials
break;
143
//Forbidden
break;
break;
//Path not found
break;
default:
//Default
break;
}
}
failureBeforeRequest :^( NSError *error) {
switch (error.code) {
case OCErrorFileToUploadDoesNotExist:
//File does not exist
break;
default:
//Default
break;
}
}
shouldExecuteAsBackgroundTaskWithExpirationHandler :^{
[op cancel];
}];
Upload a file with background session
Upload a new file to the cloud server using background session, only supported by iOS 7 and higher.
The info needed is localPath, path where the file is stored on the device and server URL, path where the file will be
stored on the server and NSProgress object where get the callbacks of the upload progress.
To get the callbacks of the progress is needed use a KVO in the progress object. We add the code in this example of
the call to set the KVO and the method where catch the notifications.
Code example
NSURLSessionUploadTask *uploadTask = nil;
NSProgress *progress = nil;
uploadTask = [[AppDelegate sharedOCCommunication] uploadFileSession:localPath toDestiny:remotePath o

//Upload complete
} failureRequest:^(NSURLResponse *response, NSString *redirectedServer, NSError *error) {
//Bad credentials
break;
//Forbidden
break;
break;
144
//Path not found
break;
default:
//Default
break;
}
}];
// Observe fractionCompleted using KVO

[progress addObserver:self forKeyPath:@"fractionCompleted" options:NSKeyValueObservingOptionNew con
//Method to catch the progress notifications with callbacks

- (void)observeValueForKeyPath:(NSString *)keyPath ofObject:(id)object change:(NSDictionary *)change
{
if ([keyPath isEqualToString:@"fractionCompleted"] && [object isKindOfClass:[NSProgress class]])
NSProgress *progress = (NSProgress *)object;
float percent = roundf (progress.fractionCompleted * 100);
//We make it on the main thread because we came from a delegate
dispatch_async(dispatch_get_main_queue(), ^{
NSLog(@"Progress is %f", percent);
});
}
}
Set callback when background task finish
Method to set callbacks of the pending transfers when the app starts. Its used when there are pendings background
transfers. The block is executed when a pending background task finished.
Code example
[[AppDelegate sharedOCCommunication] setTaskDidCompleteBlock:^(NSURLSession *session, NSURLSessionTa
}];
Set progress callback with pending background tasks
Method to set progress callbacks of the pending transfers. Its used when there are pendings background transfers.
The block is executed when a pending task get a input porgress.
Code example
[[AppDelegate sharedOCCommunication] setTaskDidSendBodyDataBlock:^(NSURLSession *session, NSURLSessi
145
}];
Check if the server supports Sharing api
The Sharing API is included in ownCloud 5.0.13 and greater versions. The info needed is activeUser.url, the server
URL that you want to check.
Code Example
[[ AppDelegate sharedOCCommunication ] hasServerShareSupport :_activeUser.url onCommunication :[ App

successRequest :^( NSHTTPURLResponse *response, BOOL hasSupport, NSString *redirectedServer) {
}
failureRequest :^( NSHTTPURLResponse *response, NSError *error){
}
}];
Read shared all items by link
Get information about what files and folder are shared by link.
The info needed is Path, the server URL that you want to check.
Code example
[[ AppDelegate sharedOCCommunication ] readSharedByServer :path onCommunication :[ AppDelegate share

successRequest :^( NSHTTPURLResponse *response, NSArray *items, NSString *redirectedServer) {
NSLog ( @"Item: %d" , items);
}
NSLog ( @"error: %@" , error);
NSLog ( @"Operation error: %d" , response.statusCode);
}];
Read shared items by link of a path
Get information about what files and folder are shared by link in a specific path.
The info needed is the server URL that you want to check and the specific path tha you want to check.
Code example
[[AppDelegate sharedOCCommunication] readSharedByServer:serverPath andPath:path onCommunication:[App

NSLog ( @"Item: %d" , items);
146
} failureRequest:^(NSHTTPURLResponse *response, NSError *error) {

}];
Share link of file or folder
Share a file or a folder from your cloud server by link. The info needed is Path, your server URL and the path of the
item that you want to share (for example /folder/file.pdf)
Code example
[[ AppDelegate sharedOCCommunication ] shareFileOrFolderByServer :path andFileOrFolderPath :itemPath

successRequest :^( NSHTTPURLResponse *response, NSString *token, NSString *redirectedServer) {
NSString *sharedLink = [ NSString stringWithFormat:@ `path/public.php?service=files&t=%@ <mailto:pat

, token];
}
[ _delegate endLoading ];
DLog ( @error.code: %d , error. code);
DLog (@server.error: %d, response. statusCode);
int code = response. statusCode ;
if (error.code == kOCErrorServerPathNotFound) {
}
switch (code) {
//File to share not exists
break;
//Error login
break;
//Permission error
break;
//Not possible to connect to server
break;
default:
if (error.code == kOCErrorServerPathNotFound) {
//File to share not exists
} else {
//Not possible to connect to the server
}
break;
}
}];
}
147

}];
Unshare a folder or file by link
Stop sharing by link a file or a folder from your cloud server.

The info needed is Path, your server URL and the Id of the item that you want to Unshare.
Before unsharing an item, you have to read the shared items on the selected server, using the method readSharedByServer so that you get the array items with all the shared elements. These are objects OCShareDto, one of their
properties is idRemoteShared, parameter needed to unshared an element.
Code example
[[ AppDelegate sharedOCCommunication ] unShareFileOrFolderByServer :path andIdRemoteSharedShared :sh

//File unshared
}
//Error
}
];
Check if file of folder is shared
Check if a specific file or folder is shared in your cloud server.

Teh info need is Path, your server URL and the Id of the item that you want.
Before check an item, you have to read the shared items on the selected server, using the method readSharedByServer
so that you get the array items with all the shared elements. These are objects OCShareDto, one of their properties
is idRemoteShared, parameter needed to unshared an element.
Code example
[[AppDelegate sharedOCCommunication] isShareFileOrFolderByServer:path andIdRemoteShared:_shareDto.id

//File/Folder is shared
} failureRequest:^(NSHTTPURLResponse *response, NSError *error) {
//File/Folder is not shared
}];
Tips
Credentials must be set before calling any method

Paths must not be on URL Encoding
Correct path: http://www.myowncloudserver.com/owncloud/remote.php/webdav/Pop_Music/
148
Wrong path: http://www.myowncloudserver.com/owncloud/remote.php/webdav/Pop%20Music/

There are some forbidden characters to be used in folder and files names on the server, same on the ownCloud
iOS library , /,<,>,:,,,?,*
To move a folder the origin path and the destination path must end with /
To move a file the origin path and the destination path must not end with /
Upload and download actions may be cancelled thanks to the object NSOperation
Unit tests, before launching unit tests you have to enter your account information (server url, user and password)
on OCCommunicationLibTests.m
1.30 Translation
1.30.1 Make text translatable
In HTML or PHP wrap it like this <?php p($l->t(This is some text));?> or this <?php
print_unescaped($l->t(This is some text));?> For the right date format use <?php
p($l->l(date, time()));?>. Change the way dates are shown by editing /core/l10n/l10n-[lang].php To
translate text in javascript use: t(appname,text to translate);
Note: print_unescaped() should be preferred only if you would like to display HTML code. Otherwise, using
p() is strongly preferred to escape HTML characters against XSS attacks.
1.30.2 You shall never split sentences!

Reason:
Translators lose the context and they have no chance to possible re-arrange words.
Example:
<?php p($l->t('Select file from')) . ' '; ?><a href='#' id="browselink"><?php p($l->t('local filesys
Translators will translate:

Select file from
local filesystem
or
cloud
By translating these individual strings for sure the case will be lost of local filesystem and cloud. The two white spaces
with the or will get lost while translating as well.
Html on translation string:
Html tags in translation strings is ugly but usually translators can handle this.
1.30. Translation
149
What about variable in the strings?

In case you need to add variables to the translation strings do it like that:
$l->t('%s is available. Get <a href="%s">more information</a>', array($data['versionstring'], $data[
1.30.3 Automated synchronization of translations

Multiple nightly jobs have been setup in order to synchronize translations - its a multi-step process: perl l10n.pl
read will rescan all php and javascript files and generate the templates. The templates are pushed to Transifex (tx
push -s). All translations are pulled from Transifex (tx pull -a). perl l10n.pl write will write the php files
containing the translations. Finally the changes are pushed to git.
Please follow the steps below to add translation support to your app:
Create a folder l10n. Create the file ignorelist which can contain files which shall not be scanned during step 4.
Edit l10n/.tx/config and copy/past a config section and adopt it by changing the app/folder name. Run perl
l10n.pl read with l10n Add the newly created translation template (l10n/Templates/<appname>.pot) to git and
commit the changes above. After the next nightly sync job a new resource will appear on Transifex and from now on
every night the latest translations will arrive.
Translation sync jobs:
https://ci.owncloud.org/view/translation-sync/
Caution: information below is in general not needed!
1.30.4 Manual quick translation update:

cd l10n/ && perl l10n.pl read && tx push -s && tx pull -a && perl l10n.pl write && cd ..
The translation script requires Locale::PO, installable via apt-get install liblocale-po-perl
1.30.5 Configure transifex

tx init
for resource in calendar contacts core files media gallery settings
do
tx set --auto-local -r owncloud.$resource "<lang>/$resource.po" --source-language=en \
--source-file "templates/$resource.pot" --execute
done
150
1.31 Unit-Testing
1.31.1 PHP unit testing
Getting PHPUnit
ownCloud uses PHPUnit >= 3.7 for unit testing.
To install it, either get it via your packagemanager:
sudo apt-get install phpunit
or install it manually:
wget https://phar.phpunit.de/phpunit.phar
chmod +x phpunit.phar
sudo mv phpunit.phar /usr/local/bin/phpunit
After the installation the phpunit command is available:

phpunit --version
And you can update it using:

phpunit --self-update
You can find more information in the PHPUnit documentation: https://phpunit.de/manual/current/en/installation.html

Writing PHP unit tests
To get started, do the following:
Create a directory called tests in the top level of your application
Create a php file in the directory and require_once your class which you want to test.
Then you can simply run the created test with phpunit.
Note: If you use ownCloud functions in your class under test (i.e: OC::getUser()) youll need to bootstrap ownCloud
or use dependency injection.
Note: Youll most likely run your tests under a different user than the web server. This might cause problems with
your PHP settings (i.e: open_basedir) and requires you to adjust your configuration.
An example for a simple test would be:
/srv/http/owncloud/apps/myapp/tests/testaddtwo.php
<?php
namespace OCA\Myapp\Tests;
class TestAddTwo extends \Test\TestCase {
protected $testMe;
1.31. Unit-Testing
151
protected function setUp() {

parent::setUp();
$this->testMe = new \OCA\Myapp\TestMe();
}
public function testAddTwo(){
$this->assertEquals(5, $this->testMe->addTwo(3));
}
}
/srv/http/owncloud/apps/myapp/lib/testme.php
<?php
namespace OCA\Myapp;
class TestMe {
public function addTwo($number){
return $number + 2;
}
}
In /srv/http/owncloud/apps/myapp/ you run the test with:

phpunit tests/testaddtwo.php
Make sure to extend the \Test\TestCase class with your test and always call the parent methods, when overwriting setUp(), setUpBeforeClass(), tearDown() or tearDownAfterClass() method from the TestCase. These methods set up important stuff and clean up the system after the test, so the next test can run without side
effects, like remaining files and entries in the file cache, etc.
For more resources on PHPUnit visit: http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html
Bootstrapping ownCloud
If you use ownCloud functions or classes in your code, youll need to make them available to your test by bootstrapping
ownCloud.
To do this, youll need to provide the --bootstrap argument when running PHPUnit
/srv/http/owncloud:
phpunit --bootstrap tests/bootstrap.php apps/myapp/tests/testsuite.php
If you run the test under a different user than your web server, youll have to adjust your php.ini and file rights.
/etc/php/php.ini:
open_basedir = none
/srv/http/owncloud:
152
su -c "chmod a+r config/config.php"

su -c "chmod a+rx data/"
su -c "chmod a+w data/owncloud.log"
Running unit tests for the ownCloud core project

The core project provides a script that runs all the core unit tests using different database backends like sqlite, mysql,
pgsql, oci (for Oracle):
./autotest.sh
To run tests only for sqlite:

./autotest.sh sqlite
To run a specific test suite (note that the test file path is relative to the tests directory):
./autotest.sh sqlite lib/share/share.php
Further Reading
http://googletesting.blogspot.de/2008/08/by-miko-hevery-so-you-decided-to.html
http://www.phpunit.de/manual/current/en/writing-tests-for-phpunit.html
http://www.youtube.com/watch?v=4E4672CS58Q&feature=bf_prev&list=PLBDAB2BA83BB6588E
Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin)
1.31.2 JavaScript unit testing for core

JavaScript Unit testing for core and core apps is done using the Karma test runner with Jasmine.
Installing Node JS
To run the JavaScript unit tests you will need to install Node JS.
You can get it here: http://nodejs.org/
After that you will need to setup the Karma test environment. The easiest way to do this is to run the automatic test
script first, see next section.
Running all tests
To run all tests, just run:
./autotest-js.sh
This will also automatically set up your test environment.
1.31. Unit-Testing
153
Debugging tests in the browser

To debug tests in the browser, you need to run Karma in browser mode:
karma start tests/karma.config.js
From there, open the URL http://localhost:9876 in a web browser.

On that page, click on the Debug button.
An empty page will appear, from which you must open the browser console (F12 in Firefox/Chrome).
Every time you reload the page, the unit tests will be relaunched and will output the results in the browser console.
Unit test paths
JavaScript unit test examples can be found in apps/files/tests/js/
Unit tests for the core app JavaScript code can be found in core/js/tests/specs
Documentation
Here are some useful links about how to write unit tests with Jasmine and Sinon:
Karma test runner: http://karma-runner.github.io
Jasmine: http://pivotal.github.io/jasmine
Sinon (for mocking and stubbing): http://sinonjs.org/
1.32 Theming ownCloud

Themes can be used to customize the look and feel of ownCloud. Themes can relate to the following topics of
owncloud:
Theming the web-frontend
Theming the owncloud Desktop client
This documentation contains only the Web-frontend adaptations so far.
1.32.1 Getting started

A good idea getting starting with a dynamically created website is to inspect it with web developer tools, that are
found in almost any browser. They show the generated HTML and the CSS Code, that the client/browser is receiving:
With this facts you can easily determine, where the following object-related attributes for the phenomenons are settled:
place
colour
links
graphics
154
In owncloud standard theme everything is held very simple. This allows you quick adapting. In an unchanged ownCloud version CSS files and the standard pictures reside in /owncloud/themes/default folder. The next thing you should
do, before starting any changes is: Make a backup of your current theme(s) e.g.:
Goto . . . /owncloud/themes
cp -r default default.old
1.33 Creating and activating a new theme

There are two basic ways of creating new themings:
Doing all new from scratch
Starting from an existing theme and doing everything step by step and more experimentally
Depending on how you created your new theme it will be necessary to
put a new theme into the /themes -folder. The theme can be activated by putting theme => themename, into
the config.php file.
make all changes in the /themes/default -file
1.34 Structure
The folder structure of a theme is exactly the same as the main ownCloud structure. You can override js files, images
and templates with own versions. CSS files are loaded additionally to the default files so you can override CSS
properties.
1.35 How to change images and the logo

A new logo which you may want to insert can be added as follows:
1.35.1 Figure out the path of the old logo

Replace the old picture, which position you found out as described under 1.3. by adding an extension in case you want
to re-use it later.
1.35.2 Creating an own logo

If you want to do a quick exchange like (1) its important to know the size of the picture before you start creating an
own logo:
Go to the place in the filesystem, that has been shown by the web developer tool/s
You can look up sizing in most cases via the file properties inside your file-manager
Create an own picture/logo with the same size then
The (main) pictures, that can be found inside ownCloud standard theming are the following:
The logo at the login-page above the credentials-box: . . . /owncloud/themes/default/core/img/logo.svg
The logo, thats always in the left upper corner after login: . . . /owncloud/themes/default/core/img/logo-wide.svg
1.33. Creating and activating a new theme
155
1.35.3 Inserting your new logo

Inserting a new logo into an existing theme is as simple as replacing the old logo with the new (generated) one. You
can use: scalable vector graphics (.svg) or common graphics formats for the internet such as portable network graphics
(.png) or .jepg Just insert the new created picture by using the unchanged name of the old picture.
1.35.4 changing the default colours

With a web-developer tool like Mozilla-Inspector, you also get easily displayed the color of the background you
clicked on. On the top of the login page you can see a case- distinguished setting for different browsers:
/* HEADERS */
...
background: #1d2d42; /* Old browsers */
background: -moz-linear-gradient(top, #33537a 0%, #1d2d42 100%); /* FF3.6+ */
background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#F1B3A4), color-stop(100%,
background: -webkit-linear-gradient(top, #33537a 0%,#1d2d42 100%); /* Chrome10+,Safari5.1+ */
background: -o-linear-gradient(top, #33537a 0%,#1d2d42 100%); /* Opera11.10+ */
background: -ms-linear-gradient(top, #33537a 0%,#1d2d42 100%); /* IE10+ */
background: linear-gradient(top, #33537a 0%,#1d2d42 100%); /* W3C */
The different background-assignments indicate the headers for a lot of different browser types. What you most likely
want to do is change the #35537a (lighter blue) and #ld2d42 (dark blue) color to the colours of our choice. In
some older and other browsers, there is just one color, but in the rest showing gradients is possible. The login page
background is a horizontal gradient. The first hex number, #35537a, is the top color of the gradient at the login screen.
The second hex number, #ld2d42 is the bottom color of the gradient at the login screen. The gradient in top of the
normal view after login is also defined by these CSS-settings, so that they take effect in logged in situation as well.
Change these colors to the hex color of your choice: As usual:
the first two figures give the intensity of the red channel,
the second two give the green intensity and the
third pair gives the blue value.
Save your CSS-file and refresh to see the new login screen. The other major color scheme is the blue header bar on
the main navigation page once you log in to ownCloud. This color we will change with the above as well. Save the
file and refresh the browser for the changes to take effect.
1.36 Testing the new theme out

There are different options for doing so:
If youre using a tool like the Inspector tools inside Mozilla, you can test out the CSS-Styles immediately inside
the css-attributes, while looking at them.
If you have a developing/testing server as described in 1. you can test out the effects in a real environment
permanently.
1.37 Notes for Updates

In case of theming it is recommended to the user, not to perform these adaptations inside the folder /themes/default.
Please perform the following steps, to avoid conflicts with other upcoming updates:
156
create a new folder inside /themes: for example: /themes/MyTheme

Copy the folders /themes/default/core and /themes/default/settings to /themes/MyTheme
edit the file /config/config.php
Insert: theme => MyTheme, into this file
Within the folder /themes/MyTheme all files, which are needed for theming are save from coming updates. All
company theming must be done exclusively here from now on.
In case, that one of the following files is affected due to an upgrade,
/themes/default/settings/templates/apps.php
/themes/default/defaults.php
the files listed below, have to be replaced by those listed above:
/themes/MyTheme/settings/templates/apps.php
/themes/MyTheme/defaults.php
But this is unlikely at least in the upcoming updates (5.0.x). ownCloud aims to give further information in this case.
1.38 App config

<?php
define("DEBUG", true);
$CONFIG = array(
/* Flag to indicate ownCloud is successfully installed (true = installed) */
"installed" => false,
/* Type of database, can be sqlite, mysql or pgsql */
"dbtype" => "sqlite",
/* Name of the ownCloud database */
"dbname" => "owncloud",
/* User to access the ownCloud database */
"dbuser" => "",
/* Password to access the ownCloud database */
"dbpassword" => "",
/* Host running the ownCloud database */
"dbhost" => "",
/* Prefix for the ownCloud tables in the database */
"dbtableprefix" => "",
/* Define the salt used to hash the user passwords. All your user passwords are lost if you lose thi
"passwordsalt" => "",
/* Force use of HTTPS connection (true = use HTTPS) */
"forcessl" => false,
/* Theme to use for ownCloud */
1.38. App config
157
"theme" => "",

/* Path to the 3rdparty directory */
"3rdpartyroot" => "",
/* URL to the 3rdparty directory, as seen by the browser */
"3rdpartyurl" => "",
/* Default app to load on login */
"defaultapp" => "files",
/* Enable the help menu item in the settings */
"knowledgebaseenabled" => true,
/* URL to use for the help page, server should understand OCS */
"knowledgebaseurl" => "http://api.apps.owncloud.com/v1",
/* Enable installing apps from the appstore */
"appstoreenabled" => true,
/* URL of the appstore to use, server should understand OCS */
"appstoreurl" => "http://api.apps.owncloud.com/v1",
/* Mode to use for sending mail, can be sendmail, smtp, qmail or php, see PHPMailer docs */
"mail_smtpmode" => "sendmail",
/* Host to use for sending mail, depends on mail_smtpmode if this is used */
"mail_smtphost" => "127.0.0.1",
/* authentication needed to send mail, depends on mail_smtpmode if this is used
* (false = disable authentication)
*/
"mail_smtpauth" => false,
/* Username to use for sendmail mail, depends on mail_smtpauth if this is used */
"mail_smtpname" => "",
/* Password to use for sendmail mail, depends on mail_smtpauth if this is used */
"mail_smtppassword" => "",
/* Check 3rdparty apps for malicious code fragments */
"appcodechecker" => "",
/* Check if ownCloud is up to date */
"updatechecker" => true,
/* Place to log to, can be owncloud and syslog (owncloud is log menu item in admin menu) */
"log_type" => "owncloud",
/* File for the owncloud logger to log to, (default is ownloud.log in the data dir */
"logfile" => "",
/* Loglevel to start logging at. 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR (default is WARN) */
"loglevel" => "",
/* Lifetime of the remember login cookie, default is 15 days */
"remember_login_cookie_lifetime" => 60*60*24*15,
158
/* The directory where the user data is stored, default to data in the owncloud
* directory. The sqlite database is also stored here, when sqlite is used.
*/
// "datadirectory" => "",
"apps_paths" => array(
/* Set an array of path for your apps directories

key 'path' is for the fs path and the key 'url' is for the http path to your
applications paths. 'writable' indicate if the user can install apps in this folder.
You must have at least 1 app folder writable or you must set the parameter : appstoreenabled to fal
*/
array(
'path'=> '/var/www/owncloud/apps',
'url' => '/apps',
'writable' => true,
),
),
);
1.38.1 Using alternative app directories

ownCloud can be set to use a custom app directory in /config/config.php. Customise the following code and add it to
your config file:
'apps_paths' =>
array (
0 =>
array (
'path' => OC::$SERVERROOT.'/apps',
'url' => '/apps',
'writable' => true,
),
1 =>
array (
'path' => OC::$SERVERROOT.'/apps2',
'url' => '/apps2',
'writable' => false,
),
),
ownCloud will use the first app directory which it finds in the array with writable set to true.
1.39 External API

1.39.1 Introduction
The external API inside ownCloud allows third party developers to access data provided by ownCloud apps. ownCloud
follows the OCS v1.7 specification (draft).
1.39. External API
159
1.39.2 Usage
Registering Methods
Methods are registered inside the appinfo/routes.php using OCP\API
<?php
\OCP\API::register(
'get',
'/apps/yourapp/url',
function($urlParameters) {
return new \OC_OCS_Result($data);
},
'yourapp',
\OC_API::ADMIN_AUTH
);
Returning Data
Once the API backend has matched your URL, your callable function as defined in $action will be executed. This
method is passed as array of parameters that you defined in $url. To return data back the the client, you should return
an instance of OC_OCS_Result. The API backend will then use this to construct the XML or JSON response.
Authentication & Basics
Because REST is stateless you have to send user and password each time you access the API. Therefore running
ownCloud with SSL is highly recommended otherwise everyone in your network can log your credentials:
https://user:[email protected]/ocs/v1.php/apps/yourapp
Output
The output defaults to XML. If you want to get JSON append this to the URL:
?format=json
Output from the application is wrapped inside a data element:

XML:
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>

160
</data>
</ocs>
JSON:
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": null
},
"data": {
// data here
}
}
}
Statuscodes
The statuscode can be any of the following numbers:
100 - successful
996 - server error
997 - not authorized
998 - not found
999 - unknown error
1.40 OCS Share API

The OCS Share API allows you to access the sharing API from outside over pre-defined OCS calls.
The base URL for all calls to the share API is: <owncloud_base_url>/ocs/v1.php/apps/files_sharing/api/v1
1.40.1 Get All Shares

Get all shares from the user.
Syntax: /shares
Method: GET
Result: XML with all shares
Statuscodes:
100 - successful
404 - couldnt fetch shares
1.40. OCS Share API
161
1.40.2 Get Shares from a specific file or folder

Get all shares from a given file/folder.
Syntax: /shares
Method: GET
URL Arguments: path - (string) path to file/folder
URL Arguments: reshares - (boolean) returns not only the shares from the current user but all shares from the
given file.
URL Arguments: subfiles - (boolean) returns all shares within a folder, given that path defines a folder
Mandatory fields: path
Result: XML with the shares
Statuscodes
100 - successful
400 - not a directory (if the subfile argument was used)
404 - file doesnt exist
1.40.3 Get information about a known Share

Get information about a given share.
Syntax: /shares/<share_id>
Method: GET
Arguments: share_id - (int) share ID
Result: XML with the share information
Statuscodes:
100 - successful
404 - share doesnt exist
1.40.4 Create a new Share

Share a file/folder with a user/group or as public link.
Syntax: /shares
Method: POST
POST Arguments: path - (string) path to the file/folder which should be shared
POST Arguments: shareType - (int) 0 = user; 1 = group; 3 = public link
POST Arguments: shareWith - (string) user / group id with which the file should be shared
POST Arguments: publicUpload - (boolean) allow public upload to a public shared folder (true/false)
POST Arguments: password - (string) password to protect public link Share with
POST Arguments: permissions - (int) 1 = read; 2 = update; 4 = create; 8 = delete; 16 = share; 31 = all (default:
31, for public shares: 1)
162
Mandatory fields: shareType, path and shareWith for shareType 0 or 1.

Result: XML containing the share ID (int) of the newly created share
Statuscodes:
100 - successful
400 - unknown share type
403 - public upload was disabled by the admin
404 - file couldnt be shared
1.40.5 Delete Share

Remove the given share.
Method: DELETE
Statuscodes:
100 - successful
404 - file couldnt be deleted
1.40.6 Update Share

Update a given share. Only one value can be updated per request.
Method: PUT
PUT Arguments: permissions - (int) update permissions (see Create share above)
PUT Arguments: password - (string) updated password for public link Share
PUT Arguments: publicUpload - (boolean) enable (true) /disable (false) public upload for public shares.
PUT Arguments: expireDate - (string) set a expire date for public link shares. This argument expects a well
formated date string, e.g. YYYY-MM-DD
Note: Only one of the update parameters can be specified at once.
Statuscodes:
100 - successful
400 - wrong or no update parameter given
403 - public upload disabled by the admin
404 - couldnt update share
1.40. OCS Share API
163
1.41 Core Development

1.41.1 Intro
Please make sure you have set up a development environment:
Development Environment
1.41.2 Core related docs

Translation
Unit-Testing
Theming ownCloud
App config
OCS Share API
External API
1.42 ownCloud Test Pilots

The ownCloud Test Pilots help to test and improve different server and client setups with ownCloud.
1.42.1 Why do you want to join

There are many different setups and people have different interests. If we want ownCloud to run well on NginX for
instance someone has to test this configuration.
Furthermore, during bug fixing the ownCloud developers often do not have the possibility to reproduce the bug in a
given environment nor they are able confirm that it was fixed. As a member of the Test Pilot Team you could act as
a contact person for a specific area to help developers fix the bugs you care about. Testing ownCloud before it is
released is the best way of making sure it does what you need it to!
Another benefit is a closer relationship to the developers: You know what people are responsible for which parts
and it is easier to get help.
If you want you will be listed as an active contributor on the owncloud.org page.
1.42.2 Who can join

Anyone who is interested in improving the quality on his/her setup and is willing to communicate with developers and
other testers.
1.42.3 How do you join

Simply register on the testpilot mailing list and send an introduction of your personal setup and interests to [email protected]
You can also join the #owncloud-testing channel on irc.freenode.net but keep in mind that we may take longer to
answer ;)
164
For further questions or help you can also send a mail to:
[email protected] (IRC: dragotin)
[email protected] (IRC: Raydiation)
1.42.4 What do you do

You will receive mails from the mailinglist and also from the bug tracker if developers need your help. Also there
will be announcements of new releases and preview releases on the mailing list which give you the possibility to test
releases early on and help developers to fix them.
We are looking forward to working with you :)
1.42.5 How do you test

Testing follows these steps:
Set up your testing environment
Pick something to test
Test it
Back to 2 until something unexpected/bad happens
Check if what you found is really a bug
File the bug
1.42.6 Installing ownCloud

Testing starts with setting up a testing environment. We urge you to not put your production data on testing releases
unless you have a backup somewhere!
Start by installing ownCloud, either on real hardware or in a VM.
You can find instructions for installation in the admin documentation.
Please note that we are still working on the documentation and if you bump into a problem, you can help us fix it.
Small things can be edited straight on github.
1.42.7 The Real Testing

Testing is a matter of trying out some scenarios you decide or were asked to test, for example, sharing a folder and
mounting it on another ownCloud instance. If it works awesome, move on. If it doesnt, find out as much as you can
about why it doesnt and use that for a bug report.
This is the stage where you should see if your issue is already reported by checking the issue tracker. It might even be
fixed, sometimes! It can also be fruitful to contact the developers on irc. Tell them youre testing ownCloud and share
what problem you bumped into. Or just ask on the test-pilots mailing list.
Finally, if the issue you bump into is a clear bug and the developers are not aware of it, file it as a new issue. See
Bugtracker
1.42. ownCloud Test Pilots
165
1.43 Bugtracker
1.43.1 Code Reviews on GitHub
Given enough eyeballs, all bugs are shallow
Linus Law
Introduction
In order to increase the code quality within ownCloud, developers are requested to perform code reviews. As we are
now heavily using the GitHub platform these code review shall take place on GitHub as well.
Precondition
From now on no direct commits/pushes to master or any of the stable branches are allowed in general. Every code
change - even one liners - have to be reviewed!
How will it work?
1. A developer will submit his changes on GitHub via a pull request (PR). GitHub:help - using pull requests
2. Within the pull request the developer could already name other developers (using @GitHubusername) and ask
them for review.
3. Using Labels section on the right side, they add 5 - To review label if the patch is complete. If they have no
permission to do that, other developers may add this Label in case PR author had indicated.
4. Other developers (either named or at free will) have a look at the changes and are welcome to write comments
within the comment field.
5. In case the reviewer is okay with the changes and thinks all his comments and suggestions have been take into
account a :+1 on the comment will signal a positive review.
6. Before a pull request will be merged into master or the corresponding branch at least 2 reviewers need to give
:+1 score.
7. Our continuous integration server will give an additional indicator for the quality of the pull request.
Examples
Read our coding guidelines for information on what a good pull request and good ownCloud code looks like.
These are two examples that are considered to be good examples of how pull requests should be handled
https://github.com/owncloud/core/pull/121
https://github.com/owncloud/core/pull/146
Questions?
Feel free to drop a line on the mailing list or join us on IRC.
166
1.43.2 Kanban Board

This chapter contains a lot of information about the development process the ownCloud community tries to follow,
so please take your time to digest all the information. In any case remember this page as the documentation on how
it should be done. Nothing here is set in stone, so if you think something should be changed please discuss it on the
mailing list.
Kanban Board = github issues + huboard
We are using http://huboard.com to visualize ownCloud github issues as a kanban board (see: core, apps, client):
As you may have noticed, the columns of the kanban board represent the life-cycle of an issue (be it a Bug or an
Enhancement). An issue flows from the 1 - Backlog on the left to the 7 - To release column on the right and is not
closed until it has been released. Instead we pull an issue to the next column by changing the label.
The Labels
The following list shows what the labels mean in the life-cycle and will hopefully help you decide how to label an
issue.
Backlog
Why do we have it? To keep us focused on finishing issues that we started, new issues will be hidden in this column.
In huboard you can see the list of things that we could think about by clicking the small arrow in the top left
corner of the concept column header.
What does a developer think? Maybe later.
When can I pull? Since this is the bucket for whatever might be done you should only pick issues from the backlog
when there is no other issue that you can work on. It is more important to finish an issue currently on the Kanban
board than to pull a new one into the flow because only released issues have a value to our users!
Who is Assigned? Either a maintainer feels directly responsible for the issue and assigns himself or the gatekeeper
(the guys having a look at unassigned bugs) will try to determine the responsible developer.
1.43. Bugtracker
167
Concept
Why do we have it? Our think before you act phase serves two purposes. A Bug is in the concept phase while we are
trying to figure out why something is broken (analysis). An Enhancement is in the concept phase until we have
decided how to implement it (design).
What does a developer think? Ill write a Scenario for our BDD in Gherkin and post it as a comment. I can always
look at the existing ones to get an inspiration how to phrase them as Given . . . when . . . then . . .
When can I pull? As long as you think and discuss on how to implement an enhancement or how to solve a bug you
should leave the concept label assigned. Two things should be documented in a comment to the issue before
moving it to the To develop step:
At least one Scenario written in Gherkin that tells you and the tester when the issue is ready to be
released.
A concept describing the planned implementation. This can be as simple as a this just needs changes to
the login screen css or so complex that you link to a blog entry somewhere else.
Who is Assigned? The maintainer that feels responsible for the issue.
To Develop
Why do we have it? Now that we have a plan, any developer can pick an issue from this column and start implementing it. If the issue is also marked with Junior Job this might be a good starting point for new developers.
What does a developer think? Nice! I can safely implement it that way because more than one person has put his
brain to the task of coming up with a good solution. Here! Me! Ill do it!
When can I pull? If you feel like diving into the code and getting your hands dirty you should look for issues with
this label. In the comments, there should be a gherkin scenario to tell you when you are done and a concept
describing how to implement it. Before you start move the issue to the Developing step by assigning the 4
Developing label.
Who is Assigned? No one. Especially not if you are working on something else!
Developing
Why do we have it? This is where the magic happens. If its a Bug the fix will be submitted as a PULL REQUEST
to the master or corresponding stable branch. If its an Enhancement code will be committed to a feature branch.
What does a developer think? You know, Im at it. By the way, Ill also write unit tests. When Im done Ill push
the issue with a commit containing push GH-# where # is the issue number. If I have an idea of who should
review it I can also notify them with @githubusername
When can I pull? As long as you are writing code for the issue or if any unit test fails you should leave the 4
Developing label assigned. Two things should have been implemented before moving the issue to the To
review step:
The enhancement or bug in question
Unit tests for the changed and added code.
Who is Assigned? The most active developer should assign himself.
168
To Review
Why do we have it? Instead of directly committing to master we agree that a second set of eyes will spot bugs
and increase our code quality and give us an opportunity to learn from each other. See also our Code Review
Documentation
What does a developer think? Ill check the Scenario described earlier works as expected. If necessary Ill update
the related Gherkin Scenarios. Jenkins will test the scenario on all kinds of platforms, web server and database
combinations with cucumber.
When can I pull? If you feel like making sure an issue works as expected you should look for issues with this label.
In the comments you should find a gherkin scenario that can be used as a checklist for what to try. Before you
start move the issue to the Reviewing step by assigning the 6 Reviewing label.
Who is Assigned? No one. Especially not if you are working on something else!
Reviewing
Why do we have it? With the Gherkin Scenario from the Concept Phase reviewers have a checklist to test if a Bug
has been solved and if an Enhancement works as expected. The most eager reviewer we have is Jenkins.
When it comes to testing he soldiers on going through the different combinations of platform, web server and
database.
What does a developer think? Damn! If I had written the Gherkin Scenarios and Cucumber Step Definitions I
could leave the task of testing this on the different combinations of platform, web server and database to Jenkins.
Ill miss something when doing this manually.*
When can I pull? As long as you are reviewing the issue the you should leave the 6 Reviewing label assigned.
Before moving the issue to the To review step the issue should have been resolved, meaning that not only the
issue has been implemented but also no other functionality has been broken.
Who is Assigned? The most active reviewer should assign himself.
To Release
Why do we have it? This is a list of issues that will make it into the next release. It serves as a source for the
changelog, as well as a reminder of the work we can already be proud of.
What does a developer think? Look at all the shiny things we will release with the next version of ownCloud!
When can I pull? This is the last step of the Kanban board. When the Release finally happens the issue will be closed
and removed from the board.
Who is Assigned? No one.
While we stated before that said that we push issues to the next column, we can of course move the item back and
forth arbitrarily. Basically you can drag the issue around in the huboard or just change the label when viewing the
issue in the GitHub.
Reviewing considered impossible?
How can you possibly review an issue when it requires you to test various combinations of browsers, platforms,
databases and maybe even app combinations? Well, you cant. But you can write a gherkin scenario that can be used
to write an automated test that is executed by Jenkins on every commit to the main repositories. If for some reason
Jenkins cannot be used for the review you will find yourself in the very uncomfortable situation where you release half
tested code that will hopefully not eat user data. Seriously! Write gherkin scenarios!
1.43. Bugtracker
169
Other Labels
Priority Labels
Panic should be used with caution. It is reserved for Bugs that would result in the loss of files or other user data.
An Enhancement marked as Panic is expected by ownCloud users for the next release. In either case an open
Panic issue will prevent a release.
Attention is not as hard as Panic. But we really want this in the next release and will dedicate more effort for it.
But if we think the issue is not ready for the next release we will postpone it to the next one.
Regression is something that worked in a previous release but is now not working as expected or missing. If a
certain functionality is up for code refactoring, the developer should describe all possible use cases as a Gherkin
scenarios beforehand, so that any scenarios that isnt implemented before the required milestone can be marked
as a regression. If a regression is found after a release, the reporter or the developer triaging the issue should
describe the functionality as a Gherkin scenario and either fix it or assign it to the developer in charge of that
part.
App Labels
In the apps repository there are labels like app:gallery and app:calendar. The app: prefix is used to allow
developers to filter issues related to a specific app.
Resolution Status
Fixed Should be assigned to issues in to Release

Wont fix Reason is given as a comment
Duplicate Corresponding bug is given in a comment (using #guthubissuenumber)
Misc Labels
Needs info Either from a developer or the bug reporter. This is nearly as severe as Panic, because no further
action can be taken
L18n A translation issue go see our transifex
Junior Job The issue is considered a good starting point to get involved in ownCloud development
Milestones equal Releases
Releases are planned via milestones which contain all the Enhancements and Bugs that we plan to release when the
Deadline is met. When the Deadline approaches we will push new Enhancement request and less important bugs to
the next milestone. This way a milestone will upon release contain all the issues that make up the changelog for the
release. Furthermore, huboard allows us to filter the Kanban board by Milestone, making it especially easy to focus
on the current Release.
1.43.3 ownCloud Bug Triaging

Bug Triaging is the process of checking bug reports to see if they are still valid (the problem might be solved since the
bug was reported), reproducing them when possible (to make sure it really is an ownCloud issue and not a configuration
170
problem) and in general making sure the bug is useful for a developer who wants to fix it. If the bug is not useful and
cant be augmented by the original reporter or the triaging contributor, it has to be closed.
Why do you want to join
Helping to bring the number if issues down makes it easier for developers to spend their time productively and bug
triagers thus contribute greatly to ownCloud development! Triaging a bug doesnt take long so the work comes in
small chunks and you dont need many skills, just some patience and sometimes perseverance.
Bug triagers who contribute significantly should ask to be listed as an active contributor on the owncloud.org page!
How do you triage bugs
The process of checking, reproducing and closing invalid issues is called bug triaging. Issues can be divided in one
of three kinds:
1. Bugs or feature requests which come with all needed information to allow a developer to fix or work on them
2. Incomplete or duplicate bug reports or feature requests
3. Irrelevant or wrong bug reports or feature requests
The job of a bug triager is to identify the Ones for developers to look at, help remove, merge or improve any Two to
a One and dismiss Threes in a friendly and emphatic way.
Triaging follows these steps:
Find an issue somebody should look at
Be that somebody and see if the issue content is useful for a developer
Reply and close, ask a question, add information or a label.
Find the next bug-to-be-dealt-with and repeat!
General considerations
You need a github account to contribute to bug triaging.
If you are not familiar with the github issue tracker interface (which is used by ownCloud to handle bug reports),
you may find this guide useful.
You will initially only be able to comment on issues. The ability to close issues or assign labels will be given
liberally to those who have shown to be willing and able to contribute. Just ask on IRC!
Read our bug reporting guidelines so you know what a good report should look like and where things belong.
The issue template asks specifically for some information developers need to solve issues.
It might even be fixed, sometimes! It can also be fruitful to contact the developers on irc. Tell them youre
triaging bugs and share what problem you bumped into. Or just ask on the test-pilots mailing list.
To ensure no two people are working on the same issue, we ask you to simply add a comment like I am triaging
this in the issue you want to work on, and when done, before or after executing the triaging actions, note
similarly that youre done.
To be able to tag and close issues, you need to have access to the repository. For the core and sync
app repositories this also means having signed the contributor agreement. However, this isnt really
needed for triaging as you can comment after youre done triaging and somebody else can execute
those actions.
1.43. Bugtracker
171
Finding bugs to triage

Github offers several search queries which can be useful to find a list of bugs which deserve a closer look:
The bugs least recently commented on
Least commented issues
Bugs which need info
But there are more methods. For example, if you are a user of ownCloud with a specific setup like using nginx as web
server or dropbox as storage, or using the encryption app, you could look for bugs with these keywords. You can then
use your knowledge of your installation and your installation itself to see if bugs are (still) valid or reproduce them.
Once you have picked an issue, add a comment that youve started triaging:
I am triaging this bug
Checking if the issue is useful
Much content from https://techbase.kde.org/Contribute/Bugsquad/Guide_To_BugTriaging
The goal of triaging is to have only useful bug reports for the developers. And you dont have to know much to be able
to judge at least some bug reports to be less than useful. There are duplications, incomplete reports and so on. Here is
the work flow for each bug:
Lets go over each step.
172
Finding duplicates
To find duplicates, the search tool in github is your first stop. In this screen you can easily search for a few keywords
from the bug report. If you find other bugs with the same content, decide what the best bug report is (often the oldest
or the one where one or more developers have already started to engage and discuss the problem). That is the master
bug report, you can now close the other one (or comment that it can be closed as duplicate).
If the bug report you were reviewing contains additional information, you can add that information to the master bug
report in a comment. Mention this bug report (using #<bug report number>) so a developer can look up the original,
closed, report and perhaps ask the initial reporter there for additional information.
If you cant find anything, look in closed bug reports. The problem might be solved already and be listed there! Of
course, these other bug reports might be closed as duplicates of the one you are looking at now - if you cant find one
that is solved nor can find any duplicates, you can move on to the next step. If you are unsure, just add a comment:
might be a duplicate of #<bug nr here> will usually suffice.
When the issue is a feature request, you can be helpful in the same way: merge related requests by adding information
of one to the other and closing the first.
Note: Be polite: when you need to request information or feedback be clear and polite, and you will get more
information in less time. Think about how youd like to be treated, were you to report a bug!
Note: You can answer more quickly and friendly using one of these templates.
Note: Often our github issue tracker is a place for discussions about solutions. Be friendly, inclusive and respect
other peoples position.
Determining relevance of issue
Not all issues are relevant for ownCloud. Bugs can be due to a specific configuration or unsupported platforms.
Raspberry Pis suffer from SQLite time-outs, nginx has problems Apache doesnt and Microsoft Server with IIS is not
well supported. While external issues are not always a reason to close a report, be sure that they are clear: does the
user use the standard platform? Ask for information if this is missing.
Last but not least, the problem might be due to the user doing something that simply does not work. Your general
ownCloud knowledge might be helpful here - if this is the case, you can often swiftly close the issue with a comment
about what went wrong.
Note: You might have to say no to some requests, for example when a problem has been solved in a new release but
wont become available for the release the reporter is using; or when a solution has been chosen which the reporter is
unhappy about. Be considerate. People feel surprisingly strong about ownCloud, and you should take care to explain
that we dont aim to ignore them; on the contrary. But sometimes, decisions which benefit the majority of users dont
help an individual. The extensibility and open availability of the code of ownCloud is here to relieve the pain of such
decisions.
Determining if the report is complete
Now that you know that the bug report is unique, and that is not an external issue, you need to check all the needed
information is there.
Check our bug reporting guidelines and make sure bug reports comply with it! The information asked in the issue
template is needed for developers to solve issues.
1.43. Bugtracker
173
Once you added a request for more information, add a #needinfo tag.
If there has been a request for more information on the report, either by you, a developer or somebody else, but the
original reporter (or somebody else who might have the answer) has not responded for 1 month or longer, you can
close the issue. Be polite and note that whoever can answer the question can re-open the issue!
Reproducing the issue
An important step of bug triaging is trying to reproduce the bugs, this means, using the information the reporters added
to the bug report to force (recreate, reproduce, repeat) the bug in the application.
This is needed in order to differentiate random/race condition bugs of reproducible ones (which may be reproduced by
developers too; and they can fix them).
To reproduce an issue, please refer to our testing documents: ownCloud Test Pilots
If you cant reproduce an issue in a newer version of ownCloud, it is most likely fixed and can be closed. Comment
that you failed to reproduce the problem, and if the reporter can confirm (or doesnt respond for a long time), you can
close the issue. Also, be sure to add what exactly you tested with - the ownCloud Master or a branch (and if so, when),
or did you use a release, and if so - what version?
Finalizing and tagging
Once you are done reproducing an issue, it is time to finish up and make clear to the developers what they can do:
If it is a genuine bug (or you are pretty sure it is) add the Bug tag.
If it is a genuine feature request (or you are pretty sure it is) add the enhancement tag.
If the issue is clearly related to something specific, @mention a maintainer. examples: @schiesbn for encryption, @blizzz for LDAP, @PVince81 for quota stuff... You can find a list of maintainers here.
Now, the developers can pick the issue up. Note that while we wish we would always pick up and solve problems
promptly, not all areas of ownCloud get the same amount of attention and contribution, so this can occasionally take a
long time.
Collaboration
You can just get started with bug triaging. But if you want, you can register on the testpilot mailing list and perhaps
introduce yourself to [email protected]. On this list we announce and discuss testing and bug triaging related
subjects.
You can also join the #owncloud-testing channel on irc.freenode.net (link for IRC clients and link to webchat) to ask
questions but keep in mind that people arent active 24/7 and it can occasionally take a while to get a response. Last
but not least, ownCloud contributor Jan Borchardt has a great guide for developers and triagers about dealing with
issues, including some stock answers and thoughts on how to deal with pull requests.
For further questions or help you can also send a mail to:
X (IRC: Y)
We are looking forward to working with you!
Credit: this document is in debt to the extensive KDE guide to bug triaging.
Thank you for helping ownCloud by reporting bugs. Before submitting an issue, please read Issue submission guidelines first.
If the issue is with the ownCloud server, report it to the Core repository
174
If the issue is with the ownCloud client, report it to the Client repository
If the issue with with an ownCloud app, report it to where that app is developed
If the app is listed in our main github repository report it to the correct sub repository
If the app is listed in the apps repository report it there
Please note that the mailing list should not be used for bug reports, as it is hard to track them there.
1.44 Help and Communication

1.44.1 Mailing lists
Communicate via mail on our mailing lists.
1.44.2 IRC channels

Chat with us on IRC. All channels are on irc.freenode.net
Setup: #owncloud
Testing: #owncloud-testing
Development: #owncloud-dev
Design: #owncloud-design
1.44.3 Maintainers
Contact a maintainer of a certain app or division
1.44. Help and Communication
175

Own Cloud Developer Manual

Uploaded by

Copyright:

Available Formats

Own Cloud Developer Manual

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Own Cloud Developer Manual

Uploaded by

Copyright:

Available Formats

ownCloud Developer Manual

The ownCloud developers

May 13, 2015

OCS Share API . . . . . .

ownCloud Developer Manual, Release 8.1

If you want to contribute please read the Contributor agreement

Core Development Develop on the

Documentation Create and enhance

ownCloud Test Pilots Help us to test

Bugtracker Report, triage or fix

Help and Communication Help on

iOS Application Development

Android Application Development

ownCloud Developer Manual, Release 8.1

1.1 General Contributor Guidelines

ownCloud Developer Manual, Release 8.1

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

1.1.2 Development Environment

1.1. General Contributor Guidelines

ownCloud Developer Manual, Release 8.1

Get the source

Then install ownCloud from git:

where <folder> is the folder where you want to install ownCloud.

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

sudo /etc/init.d/apache2 restart

Keep the code up-to-date

or to prune all merged branches, you would execute this:

1.1.3 Security Guidelines

1.1. General Contributor Guidelines

ownCloud Developer Manual, Release 8.1

Cross site scripting

Lets assume you use the following example in your application:

An attacker might now easily send the user a link to:

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

ownCloud Developer Manual, Release 8.1

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

Auth bypass / Privilege escalations

ownCloud Developer Manual, Release 8.1

1.1.4 Coding Style & General Guidelines

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

1.1. General Contributor Guidelines

ownCloud Developer Manual, Release 8.1

#theming - refers to theming issues or improvements

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

at the start of your php code. The final closing:

Objects, Functions, Arrays & Variables

Use === and !== instead of == and !=.

ownCloud Developer Manual, Release 8.1

Always use { } for one line ifs

Chapter 1. Table of Contents

ownCloud Developer Manual, Release 8.1

1.1. General Contributor Guidelines

ownCloud Developer Manual, Release 8.1