diff options
Diffstat (limited to 'lib/public')
37 files changed, 1190 insertions, 185 deletions
diff --git a/lib/public/app.php b/lib/public/app.php index 96162299ec4..bef4e96ae02 100644 --- a/lib/public/app.php +++ b/lib/public/app.php @@ -36,7 +36,7 @@ namespace OCP; class App { /** * Makes ownCloud aware of this app - * @param array with all information + * @param array $data with all information * @return boolean * * @deprecated This method is deprecated. Do not call it anymore. @@ -49,7 +49,7 @@ class App { /** * Adds an entry to the navigation - * @param array containing the data + * @param array $data containing the data * @return boolean * * This function adds a new entry to the navigation visible to users. $data @@ -70,7 +70,7 @@ class App { /** * Marks a navigation entry as active - * @param string id of the entry + * @param string $id id of the entry * @return boolean * * This function sets a navigation entry as active and removes the 'active' @@ -83,8 +83,8 @@ class App { /** * Register a Configuration Screen that should appear in the personal settings section. - * @param $app string appid - * @param $page string page to be included + * @param string $app appid + * @param string $page page to be included * @return void */ public static function registerPersonal( $app, $page ) { diff --git a/lib/public/appframework/apicontroller.php b/lib/public/appframework/apicontroller.php new file mode 100644 index 00000000000..5272f3ed529 --- /dev/null +++ b/lib/public/appframework/apicontroller.php @@ -0,0 +1,93 @@ +<?php +/** + * ownCloud - App Framework + * + * @author Bernhard Posselt + * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE + * License as published by the Free Software Foundation; either + * version 3 of the License, or any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU AFFERO GENERAL PUBLIC LICENSE for more details. + * + * You should have received a copy of the GNU Affero General Public + * License along with this library. If not, see <http://www.gnu.org/licenses/>. + * + */ + +/** + * Public interface of ownCloud for apps to use. + * AppFramework\Controller class + */ + +namespace OCP\AppFramework; + +use OCP\AppFramework\Http\Response; +use OCP\IRequest; + + +/** + * Base class to inherit your controllers from that are used for RESTful APIs + */ +abstract class ApiController extends Controller { + + private $corsMethods; + private $corsAllowedHeaders; + private $corsMaxAge; + + /** + * constructor of the controller + * @param string $appName the name of the app + * @param IRequest $request an instance of the request + * @param string $corsMethods: comma seperated string of HTTP verbs which + * should be allowed for websites or webapps when calling your API, defaults to + * 'PUT, POST, GET, DELETE, PATCH' + * @param string $corsAllowedHeaders: comma seperated string of HTTP headers + * which should be allowed for websites or webapps when calling your API, + * defaults to 'Authorization, Content-Type, Accept' + * @param int $corsMaxAge number in seconds how long a preflighted OPTIONS + * request should be cached, defaults to 1728000 seconds + */ + public function __construct($appName, + IRequest $request, + $corsMethods='PUT, POST, GET, DELETE, PATCH', + $corsAllowedHeaders='Authorization, Content-Type, Accept', + $corsMaxAge=1728000){ + parent::__construct($appName, $request); + $this->corsMethods = $corsMethods; + $this->corsAllowedHeaders = $corsAllowedHeaders; + $this->corsMaxAge = $corsMaxAge; + } + + + /** + * This method implements a preflighted cors response for you that you can + * link to for the options request + * + * @NoAdminRequired + * @NoCSRFRequired + * @PublicPage + */ + public function preflightedCors() { + if(isset($this->request->server['HTTP_ORIGIN'])) { + $origin = $this->request->server['HTTP_ORIGIN']; + } else { + $origin = '*'; + } + + $response = new Response(); + $response->addHeader('Access-Control-Allow-Origin', $origin); + $response->addHeader('Access-Control-Allow-Methods', $this->corsMethods); + $response->addHeader('Access-Control-Max-Age', $this->corsMaxAge); + $response->addHeader('Access-Control-Allow-Headers', $this->corsAllowedHeaders); + $response->addHeader('Access-Control-Allow-Credentials', 'false'); + return $response; + } + + +} diff --git a/lib/public/appframework/controller.php b/lib/public/appframework/controller.php index 758f0a80083..50b5ed3a80d 100644 --- a/lib/public/appframework/controller.php +++ b/lib/public/appframework/controller.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012, 2014 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE @@ -28,7 +28,8 @@ namespace OCP\AppFramework; use OCP\AppFramework\Http\TemplateResponse; -use OCP\AppFramework\IAppContainer; +use OCP\AppFramework\Http\JSONResponse; +use OCP\AppFramework\Http\IResponseSerializer; use OCP\IRequest; @@ -49,19 +50,86 @@ abstract class Controller { */ protected $request; + private $serializer; + private $responders; + /** * constructor of the controller * @param string $appName the name of the app * @param IRequest $request an instance of the request + * @param string $corsMethods: comma seperated string of HTTP verbs which + * should be allowed for websites or webapps when calling your API, defaults to + * 'PUT, POST, GET, DELETE, PATCH' + * @param string $corsAllowedHeaders: comma seperated string of HTTP headers + * which should be allowed for websites or webapps when calling your API, + * defaults to 'Authorization, Content-Type, Accept' + * @param int $corsMaxAge number in seconds how long a preflighted OPTIONS + * request should be cached, defaults to 1728000 seconds */ - public function __construct($appName, IRequest $request){ + public function __construct($appName, + IRequest $request){ $this->appName = $appName; $this->request = $request; + + // default responders + $this->responders = array( + 'json' => function ($response) { + return new JSONResponse($response); + } + ); + } + + + /** + * Registers a serializer that is executed before a formatter is being + * called, useful for turning any data into PHP arrays that can be used + * by a JSONResponse for instance + * @param IResponseSerializer $serializer + */ + protected function registerSerializer(IResponseSerializer $serializer) { + $this->serializer = $serializer; + } + + + /** + * Registers a formatter for a type + * @param string $format + * @param \Closure $responder + */ + protected function registerResponder($format, \Closure $responder) { + $this->responders[$format] = $responder; + } + + + /** + * Serializes and formats a response + * @param mixed $response the value that was returned from a controller and + * is not a Response instance + * @param string $format the format for which a formatter has been registered + * @throws \DomainException if format does not match a registered formatter + * @return Response + */ + public function buildResponse($response, $format='json') { + if(array_key_exists($format, $this->responders)) { + + if ($this->serializer) { + $response = $this->serializer->serialize($response); + } + + $responder = $this->responders[$format]; + + return $responder($response); + + } else { + throw new \DomainException('No responder registered for format ' . + $format . '!'); + } } /** * Lets you access post and get parameters by the index + * @deprecated write your parameters as method arguments instead * @param string $key the key which you want to access in the URL Parameter * placeholder, $_POST or $_GET array. * The priority how they're returned is the following: @@ -79,6 +147,7 @@ abstract class Controller { /** * Returns all params that were received, be it from the request * (as GET or POST) or throuh the URL by the route + * @deprecated use $this->request instead * @return array the array with all parameters */ public function getParams() { @@ -88,6 +157,7 @@ abstract class Controller { /** * Returns the method of the request + * @deprecated use $this->request instead * @return string the method of the request (POST, GET, etc) */ public function method() { @@ -97,6 +167,7 @@ abstract class Controller { /** * Shortcut for accessing an uploaded file through the $_FILES array + * @deprecated use $this->request instead * @param string $key the key that will be taken from the $_FILES array * @return array the file in the $_FILES element */ @@ -107,6 +178,7 @@ abstract class Controller { /** * Shortcut for getting env variables + * @deprecated use $this->request instead * @param string $key the key that will be taken from the $_ENV array * @return array the value in the $_ENV element */ @@ -117,6 +189,7 @@ abstract class Controller { /** * Shortcut for getting cookie variables + * @deprecated use $this->request instead * @param string $key the key that will be taken from the $_COOKIE array * @return array the value in the $_COOKIE element */ @@ -127,6 +200,7 @@ abstract class Controller { /** * Shortcut for rendering a template + * @deprecated return a template response instead * @param string $templateName the name of the template * @param array $params the template parameters in key => value structure * @param string $renderAs user renders a full page, blank only your template diff --git a/lib/public/appframework/db/doesnotexistexception.php b/lib/public/appframework/db/doesnotexistexception.php new file mode 100644 index 00000000000..5861e74f6c8 --- /dev/null +++ b/lib/public/appframework/db/doesnotexistexception.php @@ -0,0 +1,42 @@ +<?php + +/** + * ownCloud - App Framework + * + * @author Bernhard Posselt + * @copyright 2012 Bernhard Posselt dev@bernhard-posselt.com + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE + * License as published by the Free Software Foundation; either + * version 3 of the License, or any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU AFFERO GENERAL PUBLIC LICENSE for more details. + * + * You should have received a copy of the GNU Affero General Public + * License along with this library. If not, see <http://www.gnu.org/licenses/>. + * + */ + + +namespace OCP\AppFramework\Db; + + +/** + * This is returned or should be returned when a find request does not find an + * entry in the database + */ +class DoesNotExistException extends \Exception { + + /** + * Constructor + * @param string $msg the error message + */ + public function __construct($msg){ + parent::__construct($msg); + } + +}
\ No newline at end of file diff --git a/lib/public/appframework/db/entity.php b/lib/public/appframework/db/entity.php new file mode 100644 index 00000000000..8ab42bd9153 --- /dev/null +++ b/lib/public/appframework/db/entity.php @@ -0,0 +1,236 @@ +<?php + +/** +* ownCloud - App Framework +* +* @author Bernhard Posselt +* @copyright 2012 Bernhard Posselt dev@bernhard-posselt.com +* +* This library is free software; you can redistribute it and/or +* modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE +* License as published by the Free Software Foundation; either +* version 3 of the License, or any later version. +* +* This library is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +* GNU AFFERO GENERAL PUBLIC LICENSE for more details. +* +* You should have received a copy of the GNU Affero General Public +* License along with this library. If not, see <http://www.gnu.org/licenses/>. +* +*/ + +namespace OCP\AppFramework\Db; + + +/** + * @method integer getId() + * @method void setId(integer $id) + */ +abstract class Entity { + + public $id; + + private $_updatedFields = array(); + private $_fieldTypes = array('id' => 'integer'); + + + /** + * Simple alternative constructor for building entities from a request + * @param array $params the array which was obtained via $this->params('key') + * in the controller + * @return Entity + */ + public static function fromParams(array $params) { + $instance = new static(); + + foreach($params as $key => $value) { + $method = 'set' . ucfirst($key); + $instance->$method($value); + } + + return $instance; + } + + + /** + * Maps the keys of the row array to the attributes + * @param array $row the row to map onto the entity + */ + public static function fromRow(array $row){ + $instance = new static(); + + foreach($row as $key => $value){ + $prop = ucfirst($instance->columnToProperty($key)); + $setter = 'set' . $prop; + $instance->$setter($value); + } + + $instance->resetUpdatedFields(); + + return $instance; + } + + + /** + * @return an array with attribute and type + */ + public function getFieldTypes() { + return $this->_fieldTypes; + } + + + /** + * Marks the entity as clean needed for setting the id after the insertion + */ + public function resetUpdatedFields(){ + $this->_updatedFields = array(); + } + + + protected function setter($name, $args) { + // setters should only work for existing attributes + if(property_exists($this, $name)){ + if($this->$name === $args[0]) { + return; + } + $this->markFieldUpdated($name); + + // if type definition exists, cast to correct type + if($args[0] !== null && array_key_exists($name, $this->_fieldTypes)) { + settype($args[0], $this->_fieldTypes[$name]); + } + $this->$name = $args[0]; + + } else { + throw new \BadFunctionCallException($name . + ' is not a valid attribute'); + } + } + + + protected function getter($name) { + // getters should only work for existing attributes + if(property_exists($this, $name)){ + return $this->$name; + } else { + throw new \BadFunctionCallException($name . + ' is not a valid attribute'); + } + } + + + /** + * Each time a setter is called, push the part after set + * into an array: for instance setId will save Id in the + * updated fields array so it can be easily used to create the + * getter method + */ + public function __call($methodName, $args){ + $attr = lcfirst( substr($methodName, 3) ); + + if(strpos($methodName, 'set') === 0){ + $this->setter($attr, $args); + } elseif(strpos($methodName, 'get') === 0) { + return $this->getter($attr); + } else { + throw new \BadFunctionCallException($methodName . + ' does not exist'); + } + + } + + + /** + * Mark am attribute as updated + * @param string $attribute the name of the attribute + */ + protected function markFieldUpdated($attribute){ + $this->_updatedFields[$attribute] = true; + } + + + /** + * Transform a database columnname to a property + * @param string $columnName the name of the column + * @return string the property name + */ + public function columnToProperty($columnName){ + $parts = explode('_', $columnName); + $property = null; + + foreach($parts as $part){ + if($property === null){ + $property = $part; + } else { + $property .= ucfirst($part); + } + } + + return $property; + } + + + /** + * Transform a property to a database column name + * @param string $property the name of the property + * @return string the column name + */ + public function propertyToColumn($property){ + $parts = preg_split('/(?=[A-Z])/', $property); + $column = null; + + foreach($parts as $part){ + if($column === null){ + $column = $part; + } else { + $column .= '_' . lcfirst($part); + } + } + + return $column; + } + + + /** + * @return array array of updated fields for update query + */ + public function getUpdatedFields(){ + return $this->_updatedFields; + } + + + /** + * Adds type information for a field so that its automatically casted to + * that value once its being returned from the database + * @param string $fieldName the name of the attribute + * @param string $type the type which will be used to call settype() + */ + protected function addType($fieldName, $type){ + $this->_fieldTypes[$fieldName] = $type; + } + + + /** + * Slugify the value of a given attribute + * Warning: This doesn't result in a unique value + * @param string $attributeName the name of the attribute, which value should be slugified + * @return string slugified value + */ + public function slugify($attributeName){ + // toSlug should only work for existing attributes + if(property_exists($this, $attributeName)){ + $value = $this->$attributeName; + // replace everything except alphanumeric with a single '-' + $value = preg_replace('/[^A-Za-z0-9]+/', '-', $value); + $value = strtolower($value); + // trim '-' + return trim($value, '-'); + } else { + throw new \BadFunctionCallException($attributeName . + ' is not a valid attribute'); + } + } + +} diff --git a/lib/public/appframework/db/mapper.php b/lib/public/appframework/db/mapper.php new file mode 100644 index 00000000000..a23149e796b --- /dev/null +++ b/lib/public/appframework/db/mapper.php @@ -0,0 +1,291 @@ +<?php + +/** + * ownCloud - App Framework + * + * @author Bernhard Posselt + * @author Morris Jobke + * @copyright 2012 Bernhard Posselt dev@bernhard-posselt.com + * @copyright 2013 Morris Jobke morris.jobke@gmail.com + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE + * License as published by the Free Software Foundation; either + * version 3 of the License, or any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU AFFERO GENERAL PUBLIC LICENSE for more details. + * + * You should have received a copy of the GNU Affero General Public + * License along with this library. If not, see <http://www.gnu.org/licenses/>. + * + */ + + +namespace OCP\AppFramework\Db; + +use \OCP\IDb; + + +/** + * Simple parent class for inheriting your data access layer from. This class + * may be subject to change in the future + */ +abstract class Mapper { + + protected $tableName; + protected $entityClass; + protected $db; + + /** + * @param IDb $db Instance of the Db abstraction layer + * @param string $tableName the name of the table. set this to allow entity + * @param string $entityClass the name of the entity that the sql should be + * mapped to queries without using sql + */ + public function __construct(IDb $db, $tableName, $entityClass=null){ + $this->db = $db; + $this->tableName = '*PREFIX*' . $tableName; + + // if not given set the entity name to the class without the mapper part + // cache it here for later use since reflection is slow + if($entityClass === null) { + $this->entityClass = str_replace('Mapper', '', get_class($this)); + } else { + $this->entityClass = $entityClass; + } + } + + + /** + * @return string the table name + */ + public function getTableName(){ + return $this->tableName; + } + + + /** + * Deletes an entity from the table + * @param Entity $entity the entity that should be deleted + */ + public function delete(Entity $entity){ + $sql = 'DELETE FROM `' . $this->tableName . '` WHERE `id` = ?'; + $this->execute($sql, array($entity->getId())); + } + + + /** + * Creates a new entry in the db from an entity + * @param Entity $entity the entity that should be created + * @return Entity the saved entity with the set id + */ + public function insert(Entity $entity){ + // get updated fields to save, fields have to be set using a setter to + // be saved + $properties = $entity->getUpdatedFields(); + $values = ''; + $columns = ''; + $params = array(); + + // build the fields + $i = 0; + foreach($properties as $property => $updated) { + $column = $entity->propertyToColumn($property); + $getter = 'get' . ucfirst($property); + + $columns .= '`' . $column . '`'; + $values .= '?'; + + // only append colon if there are more entries + if($i < count($properties)-1){ + $columns .= ','; + $values .= ','; + } + + array_push($params, $entity->$getter()); + $i++; + + } + + $sql = 'INSERT INTO `' . $this->tableName . '`(' . + $columns . ') VALUES(' . $values . ')'; + + $this->execute($sql, $params); + + $entity->setId((int) $this->db->getInsertId($this->tableName)); + return $entity; + } + + + + /** + * Updates an entry in the db from an entity + * @throws \InvalidArgumentException if entity has no id + * @param Entity $entity the entity that should be created + */ + public function update(Entity $entity){ + // if entity wasn't changed it makes no sense to run a db query + $properties = $entity->getUpdatedFields(); + if(count($properties) === 0) { + return $entity; + } + + // entity needs an id + $id = $entity->getId(); + if($id === null){ + throw new \InvalidArgumentException( + 'Entity which should be updated has no id'); + } + + // get updated fields to save, fields have to be set using a setter to + // be saved + // dont update the id field + unset($properties['id']); + + $columns = ''; + $params = array(); + + // build the fields + $i = 0; + foreach($properties as $property => $updated) { + + $column = $entity->propertyToColumn($property); + $getter = 'get' . ucfirst($property); + + $columns .= '`' . $column . '` = ?'; + + // only append colon if there are more entries + if($i < count($properties)-1){ + $columns .= ','; + } + + array_push($params, $entity->$getter()); + $i++; + } + + $sql = 'UPDATE `' . $this->tableName . '` SET ' . + $columns . ' WHERE `id` = ?'; + array_push($params, $id); + + $this->execute($sql, $params); + } + + + /** + * Runs an sql query + * @param string $sql the prepare string + * @param array $params the params which should replace the ? in the sql query + * @param int $limit the maximum number of rows + * @param int $offset from which row we want to start + * @return \PDOStatement the database query result + */ + protected function execute($sql, array $params=array(), $limit=null, $offset=null){ + $query = $this->db->prepareQuery($sql, $limit, $offset); + + $index = 1; // bindParam is 1 indexed + foreach($params as $param) { + + switch (gettype($param)) { + case 'integer': + $pdoConstant = \PDO::PARAM_INT; + break; + + case 'boolean': + $pdoConstant = \PDO::PARAM_BOOL; + break; + + default: + $pdoConstant = \PDO::PARAM_STR; + break; + } + + $query->bindValue($index, $param, $pdoConstant); + + $index++; + } + + return $query->execute(); + } + + + /** + * Returns an db result and throws exceptions when there are more or less + * results + * @see findEntity + * @param string $sql the sql query + * @param array $params the parameters of the sql query + * @param int $limit the maximum number of rows + * @param int $offset from which row we want to start + * @throws DoesNotExistException if the item does not exist + * @throws MultipleObjectsReturnedException if more than one item exist + * @return array the result as row + */ + protected function findOneQuery($sql, array $params=array(), $limit=null, $offset=null){ + $result = $this->execute($sql, $params, $limit, $offset); + $row = $result->fetch(); + + if($row === false || $row === null){ + throw new DoesNotExistException('No matching entry found'); + } + $row2 = $result->fetch(); + //MDB2 returns null, PDO and doctrine false when no row is available + if( ! ($row2 === false || $row2 === null )) { + throw new MultipleObjectsReturnedException('More than one result'); + } else { + return $row; + } + } + + + /** + * Creates an entity from a row. Automatically determines the entity class + * from the current mapper name (MyEntityMapper -> MyEntity) + * @param array $row the row which should be converted to an entity + * @return Entity the entity + */ + protected function mapRowToEntity($row) { + return call_user_func($this->entityClass .'::fromRow', $row); + } + + + /** + * Runs a sql query and returns an array of entities + * @param string $sql the prepare string + * @param array $params the params which should replace the ? in the sql query + * @param int $limit the maximum number of rows + * @param int $offset from which row we want to start + * @return array all fetched entities + */ + protected function findEntities($sql, array $params=array(), $limit=null, $offset=null) { + $result = $this->execute($sql, $params, $limit, $offset); + + $entities = array(); + + while($row = $result->fetch()){ + $entities[] = $this->mapRowToEntity($row); + } + + return $entities; + } + + + /** + * Returns an db result and throws exceptions when there are more or less + * results + * @param string $sql the sql query + * @param array $params the parameters of the sql query + * @param int $limit the maximum number of rows + * @param int $offset from which row we want to start + * @throws DoesNotExistException if the item does not exist + * @throws MultipleObjectsReturnedException if more than one item exist + * @return Entity the entity + */ + protected function findEntity($sql, array $params=array(), $limit=null, $offset=null){ + return $this->mapRowToEntity($this->findOneQuery($sql, $params, $limit, $offset)); + } + + +} diff --git a/lib/public/appframework/db/multipleobjectsreturnedexception.php b/lib/public/appframework/db/multipleobjectsreturnedexception.php new file mode 100644 index 00000000000..51d8d6bc7e1 --- /dev/null +++ b/lib/public/appframework/db/multipleobjectsreturnedexception.php @@ -0,0 +1,42 @@ +<?php + +/** + * ownCloud - App Framework + * + * @author Bernhard Posselt + * @copyright 2012 Bernhard Posselt dev@bernhard-posselt.com + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE + * License as published by the Free Software Foundation; either + * version 3 of the License, or any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU AFFERO GENERAL PUBLIC LICENSE for more details. + * + * You should have received a copy of the GNU Affero General Public + * License along with this library. If not, see <http://www.gnu.org/licenses/>. + * + */ + + +namespace OCP\AppFramework\Db; + + +/** + * This is returned or should be returned when a find request finds more than one + * row + */ +class MultipleObjectsReturnedException extends \Exception { + + /** + * Constructor + * @param string $msg the error message + */ + public function __construct($msg){ + parent::__construct($msg); + } + +}
\ No newline at end of file diff --git a/lib/public/appframework/http.php b/lib/public/appframework/http.php index 60f314202cc..c6e2ff8846f 100644 --- a/lib/public/appframework/http.php +++ b/lib/public/appframework/http.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt, Thomas Tanghus, Bart Visscher - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE diff --git a/lib/public/appframework/http/downloadresponse.php b/lib/public/appframework/http/downloadresponse.php index d3c2818e828..6b61490341e 100644 --- a/lib/public/appframework/http/downloadresponse.php +++ b/lib/public/appframework/http/downloadresponse.php @@ -4,7 +4,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE diff --git a/lib/public/appframework/http/iresponseserializer.php b/lib/public/appframework/http/iresponseserializer.php new file mode 100644 index 00000000000..c16e106df34 --- /dev/null +++ b/lib/public/appframework/http/iresponseserializer.php @@ -0,0 +1,27 @@ +<?php +/** + * ownCloud - App Framework + * + * @author Bernhard Posselt + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE + * License as published by the Free Software Foundation; either + * version 3 of the License, or any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU AFFERO GENERAL PUBLIC LICENSE for more details. + * + * You should have received a copy of the GNU Affero General Public + * License along with this library. If not, see <http://www.gnu.org/licenses/>. + * + */ + +namespace OCP\AppFramework\Http; + +interface IResponseSerializer { + function serialize($response); +}
\ No newline at end of file diff --git a/lib/public/appframework/http/jsonresponse.php b/lib/public/appframework/http/jsonresponse.php index 6d029b7464a..c6360e0a0f5 100644 --- a/lib/public/appframework/http/jsonresponse.php +++ b/lib/public/appframework/http/jsonresponse.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE diff --git a/lib/public/appframework/http/redirectresponse.php b/lib/public/appframework/http/redirectresponse.php index 416e1533635..a1b482c6b3b 100644 --- a/lib/public/appframework/http/redirectresponse.php +++ b/lib/public/appframework/http/redirectresponse.php @@ -4,7 +4,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE diff --git a/lib/public/appframework/http/response.php b/lib/public/appframework/http/response.php index 45402d9b3b3..20e936bb860 100644 --- a/lib/public/appframework/http/response.php +++ b/lib/public/appframework/http/response.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt, Thomas Tanghus, Bart Visscher - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE @@ -92,6 +92,10 @@ class Response { * @return Response Reference to this object */ public function addHeader($name, $value) { + $name = trim($name); // always remove leading and trailing whitespace + // to be able to reliably check for security + // headers + if(is_null($value)) { unset($this->headers[$name]); } else { diff --git a/lib/public/appframework/http/templateresponse.php b/lib/public/appframework/http/templateresponse.php index f5baf788ada..02589f4e2a4 100644 --- a/lib/public/appframework/http/templateresponse.php +++ b/lib/public/appframework/http/templateresponse.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE @@ -61,12 +61,16 @@ class TemplateResponse extends Response { * constructor of TemplateResponse * @param string $appName the name of the app to load the template from * @param string $templateName the name of the template + * @param array $params an array of parameters which should be passed to the + * template + * @param string $renderAs how the page should be rendered, defaults to user */ - public function __construct($appName, $templateName) { + public function __construct($appName, $templateName, array $params=array(), + $renderAs='user') { $this->templateName = $templateName; $this->appName = $appName; - $this->params = array(); - $this->renderAs = 'user'; + $this->params = $params; + $this->renderAs = $renderAs; } diff --git a/lib/public/appframework/iapi.php b/lib/public/appframework/iapi.php index c4aeea2d4e5..9af251be850 100644 --- a/lib/public/appframework/iapi.php +++ b/lib/public/appframework/iapi.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE diff --git a/lib/public/appframework/middleware.php b/lib/public/appframework/middleware.php index 24f31939935..2e1111e9d5d 100644 --- a/lib/public/appframework/middleware.php +++ b/lib/public/appframework/middleware.php @@ -3,7 +3,7 @@ * ownCloud - App Framework * * @author Bernhard Posselt - * @copyright 2012 Bernhard Posselt nukeawhale@gmail.com + * @copyright 2012 Bernhard Posselt <dev@bernhard-posselt.com> * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE diff --git a/lib/public/backgroundjob.php b/lib/public/backgroundjob.php index 03b94403b47..562228e1e52 100644 --- a/lib/public/backgroundjob.php +++ b/lib/public/backgroundjob.php @@ -94,7 +94,7 @@ class BackgroundJob { /** * @deprecated * gets all regular tasks - * @return associative array + * @return array * * key is string "$klass-$method", value is array( $klass, $method ) */ @@ -115,7 +115,7 @@ class BackgroundJob { * @deprecated * Gets one queued task * @param int $id ID of the task - * @return BackgroundJob\IJob array + * @return BackgroundJob\IJob|null */ public static function findQueuedTask($id) { $jobList = \OC::$server->getJobList(); @@ -125,7 +125,7 @@ class BackgroundJob { /** * @deprecated * Gets all queued tasks - * @return array with associative arrays + * @return array an array of associative arrays */ public static function allQueuedTasks() { $jobList = \OC::$server->getJobList(); @@ -145,7 +145,7 @@ class BackgroundJob { * @deprecated * Gets all queued tasks of a specific app * @param string $app app name - * @return array with associative arrays + * @return array an array of associative arrays */ public static function queuedTaskWhereAppIs($app) { $jobList = \OC::$server->getJobList(); diff --git a/lib/public/backgroundjob/ijoblist.php b/lib/public/backgroundjob/ijoblist.php index c9b546605b8..366b0e37368 100644 --- a/lib/public/backgroundjob/ijoblist.php +++ b/lib/public/backgroundjob/ijoblist.php @@ -12,7 +12,7 @@ interface IJobList { /** * Add a job to the list * - * @param \OCP\BackgroundJob\IJob |string $job + * @param \OCP\BackgroundJob\IJob|string $job * @param mixed $argument The argument to be passed to $job->run() when the job is exectured * @param string $job * @return void @@ -22,7 +22,7 @@ interface IJobList { /** * Remove a job from the list * - * @param IJob $job + * @param \OCP\BackgroundJob\IJob|string $job * @param mixed $argument * @return void */ @@ -31,7 +31,7 @@ interface IJobList { /** * check if a job is in the list * - * @param $job + * @param \OCP\BackgroundJob\IJob|string $job * @param mixed $argument * @return bool */ diff --git a/lib/public/contacts.php b/lib/public/contacts.php index 1b61d7aa4ff..fb88c13bd1b 100644 --- a/lib/public/contacts.php +++ b/lib/public/contacts.php @@ -87,7 +87,7 @@ namespace OCP { * @param string $pattern which should match within the $searchProperties * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! - * @return array of contacts which are arrays of key-value-pairs + * @return array an array of contacts which are arrays of key-value-pairs */ public static function search($pattern, $searchProperties = array(), $options = array()) { $cm = \OC::$server->getContactsManager(); @@ -98,7 +98,7 @@ namespace OCP { * This function can be used to delete the contact identified by the given id * * @param object $id the unique identifier to a contact - * @param $address_book_key + * @param string $address_book_key * @return bool successful or not */ public static function delete($id, $address_book_key) { @@ -111,12 +111,12 @@ namespace OCP { * Otherwise the contact will be updated by replacing the entire data set. * * @param array $properties this array if key-value-pairs defines a contact - * @param $address_book_key string to identify the address book in which the contact shall be created or updated - * @return array representing the contact just created or updated + * @param string $address_book_key identifier of the address book in which the contact shall be created or updated + * @return array an array representing the contact just created or updated */ public static function createOrUpdate($properties, $address_book_key) { $cm = \OC::$server->getContactsManager(); - return $cm->search($properties, $address_book_key); + return $cm->createOrUpdate($properties, $address_book_key); } /** diff --git a/lib/public/contacts/imanager.php b/lib/public/contacts/imanager.php index 005b71f298b..32559220091 100644 --- a/lib/public/contacts/imanager.php +++ b/lib/public/contacts/imanager.php @@ -88,7 +88,7 @@ namespace OCP\Contacts { * @param string $pattern which should match within the $searchProperties * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! - * @return array of contacts which are arrays of key-value-pairs + * @return array an array of contacts which are arrays of key-value-pairs */ function search($pattern, $searchProperties = array(), $options = array()); @@ -107,7 +107,7 @@ namespace OCP\Contacts { * * @param array $properties this array if key-value-pairs defines a contact * @param string $address_book_key identifier of the address book in which the contact shall be created or updated - * @return array representing the contact just created or updated + * @return array an array representing the contact just created or updated */ function createOrUpdate($properties, $address_book_key); diff --git a/lib/public/db.php b/lib/public/db.php index cb876b4d1f9..ba3a4724ce0 100644 --- a/lib/public/db.php +++ b/lib/public/db.php @@ -50,7 +50,7 @@ class DB { /** * Insert a row if a matching row doesn't exists. * @param string $table The optional table name (will replace *PREFIX*) and add sequence suffix - * @param $input array + * @param array $input * * The input array if in the form: * diff --git a/lib/public/files/fileinfo.php b/lib/public/files/fileinfo.php index 37162e09336..b9c8258f21e 100644 --- a/lib/public/files/fileinfo.php +++ b/lib/public/files/fileinfo.php @@ -104,7 +104,7 @@ interface FileInfo { /** * Check whether this is a file or a folder * - * @return \OCP\Files\FileInfo::TYPE_FILE | \OCP\Files\FileInfo::TYPE_FOLDER + * @return \OCP\Files\FileInfo::TYPE_FILE|\OCP\Files\FileInfo::TYPE_FOLDER */ public function getType(); @@ -135,4 +135,18 @@ interface FileInfo { * @return bool */ public function isShareable(); + + /** + * Check if a file or folder is shared + * + * @return bool + */ + public function isShared(); + + /** + * Check if a file or folder is mounted + * + * @return bool + */ + public function isMounted(); } diff --git a/lib/public/iaddressbook.php b/lib/public/iaddressbook.php index dcfe08012e6..70309e8c57a 100644 --- a/lib/public/iaddressbook.php +++ b/lib/public/iaddressbook.php @@ -45,7 +45,7 @@ namespace OCP { * @param string $pattern which should match within the $searchProperties * @param array $searchProperties defines the properties within the query pattern should match * @param array $options - for future use. One should always have options! - * @return array of contacts which are arrays of key-value-pairs + * @return array an array of contacts which are arrays of key-value-pairs */ public function search($pattern, $searchProperties, $options); // // dummy results @@ -56,7 +56,7 @@ namespace OCP { /** * @param array $properties this array if key-value-pairs defines a contact - * @return array representing the contact just created or updated + * @return array an array representing the contact just created or updated */ public function createOrUpdate($properties); // // dummy diff --git a/lib/public/iappconfig.php b/lib/public/iappconfig.php index 2b014df2e42..d43eb70ee04 100644 --- a/lib/public/iappconfig.php +++ b/lib/public/iappconfig.php @@ -13,7 +13,7 @@ namespace OCP; */ interface IAppConfig { /** - * @brief check if a key is set in the appconfig + * check if a key is set in the appconfig * @param string $app * @param string $key * @return bool @@ -21,7 +21,7 @@ interface IAppConfig { public function hasKey($app, $key); /** - * @brief Gets the config value + * Gets the config value * @param string $app app * @param string $key key * @param string $default = null, default value if the key does not exist @@ -33,7 +33,7 @@ interface IAppConfig { public function getValue($app, $key, $default = null); /** - * @brief Deletes a key + * Deletes a key * @param string $app app * @param string $key key * @return bool @@ -43,9 +43,9 @@ interface IAppConfig { public function deleteKey($app, $key); /** - * @brief Get the available keys for an app + * Get the available keys for an app * @param string $app the app we are looking for - * @return array with key names + * @return array an array of key names * * This function gets all keys of an app. Please note that the values are * not returned. @@ -62,7 +62,7 @@ interface IAppConfig { public function getValues($app, $key); /** - * @brief sets a value in the appconfig + * sets a value in the appconfig * @param string $app app * @param string $key key * @param string $value value @@ -73,8 +73,8 @@ interface IAppConfig { public function setValue($app, $key, $value); /** - * @brief Get all apps using the config - * @return array with app ids + * Get all apps using the config + * @return array an array of app ids * * This function returns a list of all apps that have at least one * entry in the appconfig table. @@ -82,7 +82,7 @@ interface IAppConfig { public function getApps(); /** - * @brief Remove app from appconfig + * Remove app from appconfig * @param string $app app * @return bool * diff --git a/lib/public/iavatar.php b/lib/public/iavatar.php index 43fa32556de..1e80682c4f7 100644 --- a/lib/public/iavatar.php +++ b/lib/public/iavatar.php @@ -14,14 +14,14 @@ namespace OCP; interface IAvatar { /** - * @brief get the users avatar - * @param $size integer size in px of the avatar, avatars are square, defaults to 64 + * get the users avatar + * @param int $size size in px of the avatar, avatars are square, defaults to 64 * @return boolean|\OC_Image containing the avatar or false if there's no image */ function get($size = 64); /** - * @brief sets the users avatar + * sets the users avatar * @param Image $data mixed imagedata or path to set a new avatar * @throws Exception if the provided file is not a jpg or png image * @throws Exception if the provided image is not valid @@ -31,7 +31,7 @@ interface IAvatar { function set($data); /** - * @brief remove the users avatar + * remove the users avatar * @return void */ function remove(); diff --git a/lib/public/iavatarmanager.php b/lib/public/iavatarmanager.php index 9b185ae0467..1fd89405983 100644 --- a/lib/public/iavatarmanager.php +++ b/lib/public/iavatarmanager.php @@ -14,9 +14,9 @@ namespace OCP; interface IAvatarManager { /** - * @brief return a user specific instance of \OCP\IAvatar + * return a user specific instance of \OCP\IAvatar * @see \OCP\IAvatar - * @param $user string the ownCloud user id + * @param string $user the ownCloud user id * @return \OCP\IAvatar */ function getAvatar($user); diff --git a/lib/public/idb.php b/lib/public/idb.php new file mode 100644 index 00000000000..82a8a681500 --- /dev/null +++ b/lib/public/idb.php @@ -0,0 +1,51 @@ +<?php + +/** + * ownCloud - App Framework + * + * @author Bernhard Posselt + * @copyright 2012 Bernhard Posselt dev@bernhard-posselt.com + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE + * License as published by the Free Software Foundation; either + * version 3 of the License, or any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU AFFERO GENERAL PUBLIC LICENSE for more details. + * + * You should have received a copy of the GNU Affero General Public + * License along with this library. If not, see <http://www.gnu.org/licenses/>. + * + */ + +namespace OCP; + + +/** + * Small Facade for being able to inject the database connection for tests + */ +interface IDb { + + + /** + * Used to abstract the owncloud database access away + * @param string $sql the sql query with ? placeholder for params + * @param int $limit the maximum number of rows + * @param int $offset from which row we want to start + * @return \OC_DB_StatementWrapper prepared SQL query + */ + public function prepareQuery($sql, $limit=null, $offset=null); + + + /** + * Used to get the id of the just inserted element + * @param string $tableName the name of the table where we inserted the item + * @return int the id of the inserted element + */ + public function getInsertId($tableName); + + +} diff --git a/lib/public/idbconnection.php b/lib/public/idbconnection.php index 656b5e7e5b2..3e6624e07e9 100644 --- a/lib/public/idbconnection.php +++ b/lib/public/idbconnection.php @@ -52,8 +52,8 @@ interface IDBConnection { /** * Insert a row if a matching row doesn't exists. - * @param string The table name (will replace *PREFIX*) to perform the replace on. - * @param array + * @param string $table The table name (will replace *PREFIX*) to perform the replace on. + * @param array $input * * The input array if in the form: * diff --git a/lib/public/il10n.php b/lib/public/il10n.php index 1388274c21a..2c95ddfec18 100644 --- a/lib/public/il10n.php +++ b/lib/public/il10n.php @@ -53,7 +53,7 @@ interface IL10N { * Localization * @param string $type Type of localization * @param array $data parameters for this localization - * @return String or false + * @return string|false * * Returns the localized data. * @@ -72,4 +72,18 @@ interface IL10N { * - params: timestamp (int/string) */ public function l($type, $data); + + + /** + * find the best language + * @param array|string $app details below + * @return string language + * + * If $app is an array, ownCloud assumes that these are the available + * languages. Otherwise ownCloud tries to find the files in the l10n + * folder. + * + * If nothing works it returns 'en' + */ + public function getLanguageCode($app=null); } diff --git a/lib/public/ilogger.php b/lib/public/ilogger.php new file mode 100644 index 00000000000..ad0fcd05a1d --- /dev/null +++ b/lib/public/ilogger.php @@ -0,0 +1,101 @@ +<?php +/** + * Copyright (c) 2014 Bernhard Posselt <dev@bernhard-posselt.com> + * This file is licensed under the Affero General Public License version 3 or + * later. + * See the COPYING-README file. + */ + +namespace OCP; + +/** + * Interface ILogger + * @package OCP + * + * This logger interface follows the design guidelines of PSR-3 + * https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md#3-psrlogloggerinterface + */ +interface ILogger { + /** + * System is unusable. + * + * @param string $message + * @param array $context + * @return null + */ + function emergency($message, array $context = array()); + + /** + * Action must be taken immediately. + * + * @param string $message + * @param array $context + * @return null + */ + function alert($message, array $context = array()); + + /** + * Critical conditions. + * + * @param string $message + * @param array $context + * @return null + */ + function critical($message, array $context = array()); + + /** + * Runtime errors that do not require immediate action but should typically + * be logged and monitored. + * + * @param string $message + * @param array $context + * @return null + */ + function error($message, array $context = array()); + + /** + * Exceptional occurrences that are not errors. + * + * @param string $message + * @param array $context + * @return null + */ + function warning($message, array $context = array()); + + /** + * Normal but significant events. + * + * @param string $message + * @param array $context + * @return null + */ + function notice($message, array $context = array()); + + /** + * Interesting events. + * + * @param string $message + * @param array $context + * @return null + */ + function info($message, array $context = array()); + + /** + * Detailed debug information. + * + * @param string $message + * @param array $context + * @return null + */ + function debug($message, array $context = array()); + + /** + * Logs with an arbitrary level. + * + * @param mixed $level + * @param string $message + * @param array $context + * @return mixed + */ + function log($level, $message, array $context = array()); +} diff --git a/lib/public/iservercontainer.php b/lib/public/iservercontainer.php index 600d81d83af..22176c36b8a 100644 --- a/lib/public/iservercontainer.php +++ b/lib/public/iservercontainer.php @@ -113,6 +113,14 @@ interface IServerContainer { */ function getConfig(); + + /** + * Returns an instance of the db facade + * @return \OCP\IDb + */ + function getDb(); + + /** * Returns the app config manager * diff --git a/lib/public/itags.php b/lib/public/itags.php index f8ebaa668f1..1cba07e9b53 100644 --- a/lib/public/itags.php +++ b/lib/public/itags.php @@ -62,7 +62,7 @@ interface ITags { * ['id' => 1, 'name' = 'Second tag'], * ] * - * @returns array + * @return array */ public function getTags(); diff --git a/lib/public/route/iroute.php b/lib/public/route/iroute.php index d5610e762a8..f511e7af720 100644 --- a/lib/public/route/iroute.php +++ b/lib/public/route/iroute.php @@ -26,7 +26,7 @@ interface IRoute { * The action to execute when this route matches, includes a file like * it is called directly * - * @param $file + * @param string $file * @return void */ public function actionInclude($file); diff --git a/lib/public/share.php b/lib/public/share.php index 230a517b5ee..8566a38c61e 100644 --- a/lib/public/share.php +++ b/lib/public/share.php @@ -41,11 +41,11 @@ class Share extends \OC\Share\Constants { /** * Register a sharing backend class that implements OCP\Share_Backend for an item type - * @param string Item type - * @param string Backend class - * @param string (optional) Depends on item type - * @param array (optional) List of supported file extensions if this item type depends on files - * @return Returns true if backend is registered or false if error + * @param string $itemType Item type + * @param string $class Backend class + * @param string $collectionOf (optional) Depends on item type + * @param array $supportedFileExtensions (optional) List of supported file extensions if this item type depends on files + * @return boolean true if backend is registered or false if error */ public static function registerBackend($itemType, $class, $collectionOf = null, $supportedFileExtensions = null) { return \OC\Share\Share::registerBackend($itemType, $class, $collectionOf, $supportedFileExtensions); @@ -53,7 +53,7 @@ class Share extends \OC\Share\Constants { /** * Check if the Share API is enabled - * @return Returns true if enabled or false + * @return boolean true if enabled or false * * The Share API is enabled by default if not configured */ @@ -77,12 +77,12 @@ class Share extends \OC\Share\Constants { /** * Get the items of item type shared with the current user - * @param string Item type - * @param int Format (optional) Format type must be defined by the backend - * @param mixed Parameters (optional) - * @param int Number of items to return (optional) Returns all by default - * @param bool include collections (optional) - * @return Return depends on format + * @param string $itemType + * @param int $format (optional) Format type must be defined by the backend + * @param mixed $parameters (optional) + * @param int $limit Number of items to return (optional) Returns all by default + * @param bool $includeCollections (optional) + * @return mixed Return depends on format */ public static function getItemsSharedWith($itemType, $format = self::FORMAT_NONE, $parameters = null, $limit = -1, $includeCollections = false) { @@ -92,13 +92,13 @@ class Share extends \OC\Share\Constants { /** * Get the items of item type shared with a user - * @param string Item type - * @param sting user id for which user we want the shares - * @param int Format (optional) Format type must be defined by the backend - * @param mixed Parameters (optional) - * @param int Number of items to return (optional) Returns all by default - * @param bool include collections (optional) - * @return Return depends on format + * @param string $itemType + * @param string $user for which user we want the shares + * @param int $format (optional) Format type must be defined by the backend + * @param mixed $parameters (optional) + * @param int $limit Number of items to return (optional) Returns all by default + * @param bool $includeCollections (optional) + * @return mixed Return depends on format */ public static function getItemsSharedWithUser($itemType, $user, $format = self::FORMAT_NONE, $parameters = null, $limit = -1, $includeCollections = false) { @@ -111,9 +111,9 @@ class Share extends \OC\Share\Constants { * @param string $itemType * @param string $itemTarget * @param int $format (optional) Format type must be defined by the backend - * @param mixed Parameters (optional) - * @param bool include collections (optional) - * @return Return depends on format + * @param mixed $parameters (optional) + * @param bool $includeCollections (optional) + * @return mixed Return depends on format */ public static function getItemSharedWith($itemType, $itemTarget, $format = self::FORMAT_NONE, $parameters = null, $includeCollections = false) { @@ -134,12 +134,12 @@ class Share extends \OC\Share\Constants { /** * Get the item of item type shared with the current user by source - * @param string Item type - * @param string Item source - * @param int Format (optional) Format type must be defined by the backend - * @param mixed Parameters - * @param bool include collections - * @return Return depends on format + * @param string $itemType + * @param string $itemSource + * @param int $format (optional) Format type must be defined by the backend + * @param mixed $parameters + * @param bool $includeCollections + * @return mixed Return depends on format */ public static function getItemSharedWithBySource($itemType, $itemSource, $format = self::FORMAT_NONE, $parameters = null, $includeCollections = false) { @@ -148,9 +148,9 @@ class Share extends \OC\Share\Constants { /** * Get the item of item type shared by a link - * @param string Item type - * @param string Item source - * @param string Owner of link + * @param string $itemType + * @param string $itemSource + * @param string $uidOwner Owner of link * @return Item */ public static function getItemSharedWithByLink($itemType, $itemSource, $uidOwner) { @@ -160,7 +160,7 @@ class Share extends \OC\Share\Constants { /** * Based on the given token the share information will be returned - password protected shares will be verified * @param string $token - * @return array | bool false will be returned in case the token is unknown or unauthorized + * @return array|bool false will be returned in case the token is unknown or unauthorized */ public static function getShareByToken($token, $checkPasswordProtection = true) { return \OC\Share\Share::getShareByToken($token, $checkPasswordProtection); @@ -168,8 +168,8 @@ class Share extends \OC\Share\Constants { /** * resolves reshares down to the last real share - * @param $linkItem - * @return $fileOwner + * @param array $linkItem + * @return array file owner */ public static function resolveReShare($linkItem) { return \OC\Share\Share::resolveReShare($linkItem); @@ -178,12 +178,12 @@ class Share extends \OC\Share\Constants { /** * Get the shared items of item type owned by the current user - * @param string Item type - * @param int Format (optional) Format type must be defined by the backend - * @param mixed Parameters - * @param int Number of items to return (optional) Returns all by default - * @param bool include collections - * @return Return depends on format + * @param string $itemType + * @param int $format (optional) Format type must be defined by the backend + * @param mixed $parameters + * @param int $limit Number of items to return (optional) Returns all by default + * @param bool $includeCollections + * @return mixed Return depends on format */ public static function getItemsShared($itemType, $format = self::FORMAT_NONE, $parameters = null, $limit = -1, $includeCollections = false) { @@ -193,12 +193,12 @@ class Share extends \OC\Share\Constants { /** * Get the shared item of item type owned by the current user - * @param string Item type - * @param string Item source - * @param int Format (optional) Format type must be defined by the backend - * @param mixed Parameters - * @param bool include collections - * @return Return depends on format + * @param string $itemType + * @param string $itemSource + * @param int $format (optional) Format type must be defined by the backend + * @param mixed $parameters + * @param bool $includeCollections + * @return mixed Return depends on format */ public static function getItemShared($itemType, $itemSource, $format = self::FORMAT_NONE, $parameters = null, $includeCollections = false) { @@ -208,12 +208,12 @@ class Share extends \OC\Share\Constants { /** * Get all users an item is shared with - * @param string Item type - * @param string Item source - * @param string Owner - * @param bool Include collections - * @praram bool check expire date - * @return Return array of users + * @param string $itemType + * @param string $itemSource + * @param string $uidOwner + * @param bool $includeCollections + * @param bool $checkExpireDate + * @return array Return array of users */ public static function getUsersItemShared($itemType, $itemSource, $uidOwner, $includeCollections = false, $checkExpireDate = true) { return \OC\Share\Share::getUsersItemShared($itemType, $itemSource, $uidOwner, $includeCollections, $checkExpireDate); @@ -226,26 +226,22 @@ class Share extends \OC\Share\Constants { * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK * @param string $shareWith User or group the item is being shared with * @param int $permissions CRUDS - * @param null $itemSourceName - * @throws \Exception - * @internal param \OCP\Item $string type - * @internal param \OCP\Item $string source - * @internal param \OCP\SHARE_TYPE_USER $int , SHARE_TYPE_GROUP, or SHARE_TYPE_LINK - * @internal param \OCP\User $string or group the item is being shared with - * @internal param \OCP\CRUDS $int permissions + * @param string $itemSourceName + * @param \DateTime $expirationDate * @return bool|string Returns true on success or false on failure, Returns token on success for links + * @throws \Exception */ - public static function shareItem($itemType, $itemSource, $shareType, $shareWith, $permissions, $itemSourceName = null) { - return \OC\Share\Share::shareItem($itemType, $itemSource, $shareType, $shareWith, $permissions, $itemSourceName); + public static function shareItem($itemType, $itemSource, $shareType, $shareWith, $permissions, $itemSourceName = null, \DateTime $expirationDate = null) { + return \OC\Share\Share::shareItem($itemType, $itemSource, $shareType, $shareWith, $permissions, $itemSourceName, $expirationDate); } /** * Unshare an item from a user, group, or delete a private link - * @param string Item type - * @param string Item source - * @param int SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK - * @param string User or group the item is being shared with - * @return Returns true on success or false on failure + * @param string $itemType + * @param string $itemSource + * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK + * @param string $shareWith User or group the item is being shared with + * @return boolean true on success or false on failure */ public static function unshare($itemType, $itemSource, $shareType, $shareWith) { return \OC\Share\Share::unshare($itemType, $itemSource, $shareType, $shareWith); @@ -253,9 +249,9 @@ class Share extends \OC\Share\Constants { /** * Unshare an item from all users, groups, and remove all links - * @param string Item type - * @param string Item source - * @return Returns true on success or false on failure + * @param string $itemType + * @param string $itemSource + * @return boolean true on success or false on failure */ public static function unshareAll($itemType, $itemSource) { return \OC\Share\Share::unshareAll($itemType, $itemSource); @@ -263,15 +259,16 @@ class Share extends \OC\Share\Constants { /** * Unshare an item shared with the current user - * @param string Item type - * @param string Item target - * @return Returns true on success or false on failure + * @param string $itemType + * @param string $itemTarget + * @return boolean true on success or false on failure * * Unsharing from self is not allowed for items inside collections */ public static function unshareFromSelf($itemType, $itemTarget) { return \OC\Share\Share::unshareFromSelf($itemType, $itemTarget); } + /** * sent status if users got informed by mail about share * @param string $itemType @@ -285,12 +282,12 @@ class Share extends \OC\Share\Constants { /** * Set the permissions of an item for a specific user or group - * @param string Item type - * @param string Item source - * @param int SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK - * @param string User or group the item is being shared with - * @param int CRUDS permissions - * @return Returns true on success or false on failure + * @param string $itemType + * @param string $itemSource + * @param int $shareType SHARE_TYPE_USER, SHARE_TYPE_GROUP, or SHARE_TYPE_LINK + * @param string $shareWith User or group the item is being shared with + * @param int $permissions CRUDS permissions + * @return boolean true on success or false on failure */ public static function setPermissions($itemType, $itemSource, $shareType, $shareWith, $permissions) { return \OC\Share\Share::setPermissions($itemType, $itemSource, $shareType, $shareWith, $permissions); @@ -301,7 +298,7 @@ class Share extends \OC\Share\Constants { * @param string $itemType * @param string $itemSource * @param string $date expiration date - * @return Share_Backend + * @return boolean */ public static function setExpirationDate($itemType, $itemSource, $date) { return \OC\Share\Share::setExpirationDate($itemType, $itemSource, $date); @@ -340,23 +337,20 @@ class Share extends \OC\Share\Constants { interface Share_Backend { /** - * Get the source of the item to be stored in the database - * @param string Item source - * @param string Owner of the item - * @return mixed|array|false Source + * Check if this $itemSource exist for the user + * @param string $itemSource + * @param string $uidOwner Owner of the item + * @return boolean|null Source * - * Return an array if the item is file dependent, the array needs two keys: 'item' and 'file' * Return false if the item does not exist for the user - * - * The formatItems() function will translate the source returned back into the item */ public function isValidSource($itemSource, $uidOwner); /** * Get a unique name of the item for the specified user - * @param string Item source - * @param string|false User the item is being shared with - * @param array|null List of similar item names already existing as shared items + * @param string $itemSource + * @param string|false $shareWith User the item is being shared with + * @param array|null $exclude List of similar item names already existing as shared items * @return string Target name * * This function needs to verify that the user does not already have an item with this name. @@ -366,8 +360,8 @@ interface Share_Backend { /** * Converts the shared item sources back into the item in the specified format - * @param array Shared items - * @param int Format + * @param array $items Shared items + * @param int $format * @return TODO * * The items array is a 3-dimensional array with the item_source as the @@ -397,8 +391,9 @@ interface Share_Backend_File_Dependent extends Share_Backend { /** * Get the file path of the item - * @param string Item source - * @param string User that is the owner of shared item + * @param string $itemSource + * @param string $uidOwner User that is the owner of shared item + * @return string|false */ public function getFilePath($itemSource, $uidOwner); @@ -412,7 +407,7 @@ interface Share_Backend_Collection extends Share_Backend { /** * Get the sources of the children of the item - * @param string Item source + * @param string $itemSource * @return array Returns an array of children each inside an array with the keys: source, target, and file_path if applicable */ public function getChildren($itemSource); diff --git a/lib/public/template.php b/lib/public/template.php index 6cc984b12d5..b1264e0c3ad 100644 --- a/lib/public/template.php +++ b/lib/public/template.php @@ -33,8 +33,8 @@ namespace OCP; /** * Make OC_Helper::imagePath available as a simple function - * @param string app - * @param string image + * @param string $app + * @param string $image * @return string to the image * * @see OC_Helper::imagePath @@ -46,7 +46,7 @@ function image_path( $app, $image ) { /** * Make OC_Helper::mimetypeIcon available as a simple function - * @param string mimetype + * @param string $mimetype * @return string to the image of this file type. */ function mimetype_icon( $mimetype ) { @@ -55,7 +55,7 @@ function mimetype_icon( $mimetype ) { /** * Make preview_icon available as a simple function - * @param string path of file + * @param string $path path to file * @return string to the preview of the image */ function preview_icon( $path ) { @@ -76,7 +76,7 @@ function publicPreview_icon ( $path, $token ) { /** * Make OC_Helper::humanFileSize available as a simple function * Example: 2048 to 2 kB. - * @param int size in bytes + * @param int $size in bytes * @return string size as string */ function human_file_size( $bytes ) { @@ -86,8 +86,8 @@ function human_file_size( $bytes ) { /** * Return the relative date in relation to today. Returns something like "last hour" or "two month ago" - * @param int unix timestamp - * @param boolean date only + * @param int $timestamp unix timestamp + * @param boolean $dateOnly * @return OC_L10N_String human readable interpretation of the timestamp */ function relative_modified_date( $timestamp, $dateOnly = false ) { @@ -98,7 +98,7 @@ function relative_modified_date( $timestamp, $dateOnly = false ) { /** * Return a human readable outout for a file size. * @deprecated human_file_size() instead - * @param integer size of a file in byte + * @param integer $bytes size of a file in byte * @return string human readable interpretation of a file size */ function simple_file_size($bytes) { @@ -108,9 +108,9 @@ function simple_file_size($bytes) { /** * Generate html code for an options block. - * @param $options the options - * @param $selected which one is selected? - * @param array the parameters + * @param array $options the options + * @param mixed $selected which one is selected? + * @param array $params the parameters * @return string html options */ function html_select_options($options, $selected, $params=array()) { diff --git a/lib/public/user.php b/lib/public/user.php index 7bac938b838..925410d37d5 100644 --- a/lib/public/user.php +++ b/lib/public/user.php @@ -45,10 +45,10 @@ class User { /** * Get a list of all users - * @param string search pattern - * @param integer $limit - * @param integer $offset - * @return array with all uids + * @param string $search search pattern + * @param int|null $limit + * @param int|null $offset + * @return array an array of all uids */ public static function getUsers( $search = '', $limit = null, $offset = null ) { return \OC_User::getUsers( $search, $limit, $offset ); @@ -56,7 +56,7 @@ class User { /** * Get the user display name of the user currently logged in. - * @param string user id or null for current user + * @param string|null $user user id or null for current user * @return string display name */ public static function getDisplayName( $user = null ) { @@ -65,10 +65,10 @@ class User { /** * Get a list of all display names and user ids. - * @param string search pattern - * @param int limit - * @param int offset - * @return array with all display names (value) and the correspondig uids (key) + * @param string $search search pattern + * @param int|null $limit + * @param int|null $offset + * @return array an array of all display names (value) and the correspondig uids (key) */ public static function getDisplayNames( $search = '', $limit = null, $offset = null ) { return \OC_User::getDisplayNames( $search, $limit, $offset ); diff --git a/lib/public/util.php b/lib/public/util.php index f06ddd66641..3166d4040d8 100644 --- a/lib/public/util.php +++ b/lib/public/util.php @@ -86,21 +86,22 @@ class Util { * if DEBUG mode is enabled * @param string $app app name * @param \Exception $ex exception to log + * @param string $level log level, defaults to \OCP\Util::FATAL */ - public static function logException( $app, \Exception $ex ) { + public static function logException( $app, \Exception $ex, $level = \OCP\Util::FATAL ) { $class = get_class($ex); $message = $class . ': ' . $ex->getMessage(); if ($ex->getCode()) { $message .= ' [' . $ex->getCode() . ']'; } - \OCP\Util::writeLog($app, $message, \OCP\Util::FATAL); + \OCP\Util::writeLog($app, $message, $level); if (defined('DEBUG') and DEBUG) { // also log stack trace $stack = explode("\n", $ex->getTraceAsString()); // first element is empty array_shift($stack); foreach ($stack as $s) { - \OCP\Util::writeLog($app, 'Exception: ' . $s, \OCP\Util::FATAL); + \OCP\Util::writeLog($app, 'Exception: ' . $s, $level); } // include cause @@ -110,7 +111,7 @@ class Util { if ($ex->getCode()) { $message .= '[' . $ex->getCode() . '] '; } - \OCP\Util::writeLog($app, 'Exception: ' . $message, \OCP\Util::FATAL); + \OCP\Util::writeLog($app, 'Exception: ' . $message, $level); } } } @@ -202,7 +203,7 @@ class Util { /** * Creates an url using a defined route - * @param $route + * @param string $route * @param array $parameters * @internal param array $args with param=>value, will be appended to the returned url * @return string the url @@ -292,7 +293,7 @@ class Util { /** * Returns the script name, even if the website uses one or more reverse proxies - * @returns string the script name + * @return string the script name */ public static function getScriptName() { return(\OC_Request::scriptName()); @@ -379,8 +380,8 @@ class Util { * This function is used to sanitize HTML and should be applied on any * string or array of strings before displaying it on a web page. * - * @param string|array of strings - * @return array with sanitized strings or a single sinitized string, depends on the input parameter. + * @param string|array $value + * @return string|array an array of sanitized strings or a single sinitized string, depends on the input parameter. */ public static function sanitizeHTML( $value ) { return(\OC_Util::sanitizeHTML($value)); @@ -457,7 +458,7 @@ class Util { * * @param string $dir the current folder where the user currently operates * @param int $free the number of bytes free on the storage holding $dir, if not set this will be received from the storage directly - * @return number of bytes representing + * @return int number of bytes representing */ public static function maxUploadFilesize($dir, $free = null) { return \OC_Helper::maxUploadFilesize($dir, $free); @@ -475,7 +476,7 @@ class Util { /** * Calculate PHP upload limit * - * @return number of bytes representing + * @return int number of bytes representing */ public static function uploadLimit() { return \OC_Helper::uploadLimit(); @@ -483,7 +484,7 @@ class Util { /** * Returns whether the given file name is valid - * @param $file string file name to check + * @param string $file file name to check * @return bool true if the file name is valid, false otherwise */ public static function isValidFileName($file) { @@ -491,11 +492,19 @@ class Util { } /** - * @brief Generates a cryptographic secure pseudo-random string - * @param Int $length of the random string - * @return String + * Generates a cryptographic secure pseudo-random string + * @param int $length of the random string + * @return string */ public static function generateRandomBytes($length = 30) { return \OC_Util::generateRandomBytes($length); } + + /** + * check if a password is required for each public link + * @return boolean + */ + public static function isPublicLinkPasswordRequired() { + return \OC_Util::isPublicLinkPasswordRequired(); + } } |