diff options
Diffstat (limited to 'lib/models/resources/ResourceCategory.php')
| -rw-r--r-- | lib/models/resources/ResourceCategory.php | 806 |
1 files changed, 806 insertions, 0 deletions
diff --git a/lib/models/resources/ResourceCategory.php b/lib/models/resources/ResourceCategory.php new file mode 100644 index 0000000..cfe323a --- /dev/null +++ b/lib/models/resources/ResourceCategory.php @@ -0,0 +1,806 @@ +<?php + +/** + * ResourceCategory.php - model class for resource categories + * + * The ResourceCategory class can be used as a Factory for + * Resource objects. + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License as + * published by the Free Software Foundation; either version 2 of + * the License, or (at your option) any later version. + * + * @author Moritz Strohm <strohm@data-quest.de> + * @copyright 2017 + * @license http://www.gnu.org/licenses/gpl-2.0.html GPL version 2 + * @category Stud.IP + * @package resources + * @since 4.1 + * + * @property string $id database column + * @property string $name database column + * @property string $description database column + * @property int $system database column + * @property int|null $iconnr database column + * @property string $class_name database column + * @property int $mkdate database column + * @property int $chdate database column + * @property SimpleORMapCollection|ResourceCategoryProperty[] $property_links has_many ResourceCategoryProperty + * @property SimpleORMapCollection|ResourcePropertyDefinition[] $property_definitions has_and_belongs_to_many ResourcePropertyDefinition + */ +class ResourceCategory extends SimpleORMap +{ + private static $cache; + + protected static function configure($config = []) + { + $config['db_table'] = 'resource_categories'; + + $config['has_and_belongs_to_many']['property_definitions'] = [ + 'class_name' => ResourcePropertyDefinition::class, + 'assoc_foreign_key' => 'property_id', + 'thru_table' => 'resource_category_properties', + 'thru_key' => 'category_id', + 'order_by' => 'ORDER BY name ASC' + ]; + + $config['has_many']['property_links'] = [ + 'class_name' => ResourceCategoryProperty::class, + 'assoc_func' => 'findByCategory_id', + 'foreign_key' => 'id', + 'on_delete' => 'delete' + ]; + + $config['registered_callbacks']['after_create'][] = function ($category) { + self::$cache[$category->id] = $category; + }; + $config['registered_callbacks']['after_store'][] = function ($category) { + self::$cache[$category->id] = $category; + }; + $config['registered_callbacks']['after_delete'][] = function ($category) { + unset(self::$cache[$category->id]); + }; + + parent::configure($config); + } + + /** + * Retrieves all resource categories from the database. + * @param bool $force_reload + * @return ResourceCategory[] An array of ResourceCategory objects + * or an empty array if no resource categories are defined. + */ + public static function findAll($force_reload = false) + { + if (!is_array(self::$cache) || $force_reload) { + self::$cache = []; + foreach (self::findBySql('1 ORDER BY name') as $one) { + self::$cache[$one->id] = $one; + } + } + return self::$cache; + } + + public static function find($id) + { + $all = self::findAll(); + return $all[$id] ?? null; + } + + /** + * "Converts" a category-ID to a class name by looking up the + * class name of a specified category. + * + * @param string $category_id The category-ID of the specified category. + * + * @return string The class name field of the category which is specified + * by $category_id. In case no category could be found, an empty + * string is returned. + */ + public static function getClassNameById($category_id) + { + $category = self::find($category_id); + if ($category) { + return $category->class_name; + } + return ''; + } + + public function hasResources() + { + $db = DBManager::get(); + $stmt = $db->prepare( + "SELECT 1 FROM resources WHERE category_id = :category_id LIMIT 1" + ); + $stmt->execute(['category_id' => $this->id]); + return $stmt->fetchColumn() !== false; + } + + /** + * Retrieves the definitions of all properties that are available + * for this resource category. + * + * @param string[] excluded_properties An array with the names + * of the properties that shall be excluded from the result set. + * + * @return ResourcePropertyDefinition[] An array of resource property + * definitions. + */ + public function getPropertyDefinitions($excluded_properties = []) + { + if (is_array($excluded_properties) && count($excluded_properties)) { + return ResourcePropertyDefinition::findBySql( + "INNER JOIN resource_category_properties rcp + ON resource_property_definitions.property_id = rcp.property_id + WHERE + rcp.category_id = :category_id + AND resource_property_definitions.name NOT IN ( + :excluded_properties + ) + ORDER BY resource_property_definitions.name ASC", + [ + 'category_id' => $this->id, + 'excluded_properties' => $excluded_properties + ] + ); + } + + //No excluded properties are specified. + //We can return all property definitions. + return ResourcePropertyDefinition::findBySql( + "INNER JOIN resource_category_properties rcp + ON resource_property_definitions.property_id = rcp.property_id + WHERE + rcp.category_id = :category_id + ORDER BY resource_property_definitions.name ASC", + [ + 'category_id' => $this->id + ] + ); + } + + /** + * This method returns the same properties as getPropertyDefinitions, + * but grouped and ordered by the property groups and the position of the + * property in that group. + * + * @return array An array with the group names as keys and the properties + * in the second array dimension. The structure of the array + * is as follows: + * [ + * group1 name => [ + * property1, + * property2, + * ... + * ], + * group2 name => [ + * ... + * ] + * ] + */ + public function getGroupedPropertyDefinitions($excluded_properties = []) + { + if (is_array($excluded_properties) && count($excluded_properties)) { + $definitions = ResourcePropertyDefinition::findBySql( + "INNER JOIN resource_category_properties rcp + ON resource_property_definitions.property_id = rcp.property_id + LEFT JOIN resource_property_groups rpg + ON resource_property_definitions.property_group_id = rpg.id + WHERE + rcp.category_id = :category_id + AND resource_property_definitions.name NOT IN ( + :excluded_properties + ) + ORDER BY + type DESC, rpg.position ASC, rpg.name ASC, + resource_property_definitions.property_group_pos, + resource_property_definitions.name ASC", + [ + 'category_id' => $this->id, + 'excluded_properties' => $excluded_properties + ] + ); + + $empty_index = _('Sonstige'); + $empty_property_group = [ + $empty_index => [] + ]; + $property_groups = []; + foreach ($definitions as $definition) { + if ($definition->group && $definition->group->name) { + $group_name = $definition->group->name; + if (!is_array($property_groups[$group_name])) { + $property_groups[$group_name] = []; + } + $property_groups[$group_name][] = $definition; + } else { + $empty_property_group[$empty_index][] = $definition; + } + } + if ($empty_property_group[$empty_index]) { + return array_merge($property_groups, $empty_property_group); + } else { + return $property_groups; + } + } + + //No excluded properties are specified. + //We can return all property definitions. + $definitions = ResourcePropertyDefinition::findBySql( + "INNER JOIN resource_category_properties rcp + ON resource_property_definitions.property_id = rcp.property_id + LEFT JOIN resource_property_groups rpg + ON resource_property_definitions.property_group_id = rpg.id + WHERE + rcp.category_id = :category_id + ORDER BY + rpg.position ASC, rpg.name ASC, + resource_property_definitions.property_group_pos, + resource_property_definitions.name ASC", + [ + 'category_id' => $this->id + ] + ); + + $empty_index = _('Sonstige'); + $empty_property_group = [ + $empty_index => [] + ]; + $property_groups = []; + foreach ($definitions as $definition) { + if ($definition->group->name) { + $group_name = $definition->group->name; + if (!is_array($property_groups[$group_name])) { + $property_groups[$group_name] = []; + } + $property_groups[$group_name][] = $definition; + } else { + $empty_property_group[$empty_index][] = $definition; + } + } + if ($empty_property_group[$empty_index]) { + return array_merge($property_groups, $empty_property_group); + } else { + return $property_groups; + } + } + + /** + * Adds a property to this category. If the property doesn't exist + * it will be created. + * + * @param string $name The name of the property. + * @param string $type The type of the property. + * @param bool $requestable Whether the property is requestable or not. + * Defaults to false. + * @param bool $protected Whether the property is protected or not. + * Defaults to false. + * @param string $write_permission_level + * @return ResourceCategoryProperty The created or updated + * resource category property. + * @throws ResourcePropertyDefinitionException If the property definition + * cannot be created. + * + * @throws ResourcePropertyException If the property cannot be created. + */ + public function addProperty( + $name = '', + $type = 'bool', + $requestable = false, + $protected = false, + $write_permission_level = 'autor' + ) + { + if (!$name) { + throw new ResourcePropertyException( + _('Es wurde kein Name für die Eigenschaft angegeben!') + ); + } + + $defined_types = ResourcePropertyDefinition::getDefinedTypes(); + + if (!in_array($type, $defined_types)) { + throw new ResourcePropertyException( + sprintf( + _('Der Eigenschaftstyp %s ist ungültig!'), + $type + ) + ); + } + + if (!in_array($write_permission_level, ['user', 'autor', 'tutor', 'admin'])) { + throw new ResourcePropertyException( + sprintf( + _('Die Rechtestufe %s ist ungültig!'), + $write_permission_level + ) + ); + } + + $existing_property = ResourceCategoryProperty::findOneBySql( + 'INNER JOIN resource_property_definitions rpd + ON resource_category_properties.property_id = rpd.property_id + WHERE + resource_category_properties.category_id = :category_id + AND + rpd.name = :name + AND + rpd.type = :type', + [ + 'category_id' => $this->id, + 'name' => $name, + 'type' => $type + ] + ); + + if ($existing_property) { + $existing_property->requestable = $requestable ? '1' : '0'; + $existing_property->protected = $protected ? '1' : '0'; + if ($existing_property->isDirty() && !$existing_property->store()) { + throw new ResourcePropertyException( + sprintf( + _('Fehler beim Aktualisieren der Eigenschaft %1$s (vom Typ %2$s)!'), + $name, + $type + ) + ); + } + return $existing_property; + } else { + $definition = ResourcePropertyDefinition::findOneBySql( + 'name = :name AND type = :type', + [ + 'name' => $name, + 'type' => $type + ] + ); + + if (!$definition) { + $definition = new ResourcePropertyDefinition(); + $definition->name = $name; + $definition->type = $type; + if (!$definition->store()) { + throw new ResourcePropertyDefinitionException( + sprintf( + _('Fehler beim Speichern der Definition der Eigenschaft %1$s (vom Typ %2$s)!'), + $name, + $type + ) + ); + } + } + + $property = new ResourceCategoryProperty(); + $property->property_id = $definition->id; + $property->category_id = $this->id; + $property->requestable = $requestable ? '1' : '0'; + $property->protected = $protected ? '1' : '0'; + + if ($property->store()) { + return $property; + } else { + throw new ResourcePropertyException( + sprintf( + _('Fehler beim Speichern der neuen Eigenschaft %1$s (vom Typ %2$s)!'), + $name, + $type + ) + ); + } + } + } + + /** + * Creates a resource object which belongs to this category. + * All properties which are mandatory for resources of this + * category are set to default values unless they are specified in the + * properties array. + * + * @param string $name The name of the new resource. + * @param string $description The description of the new resource. + * @param string $parent_id The parent resource's ID (if any). + * @param array $properties An associative array in the form [$key] = $value + * containing the defined properties which can be set to this resource. + * @param bool $ignore_invalid If set to true, invalid values or invalid + * property names are ignored and no exception is thrown if an invalid + * value or property name occurs. Instead an invalid valud will be replaced + * with a default value and an invalid property name will not result + * in a set property. + * + * @return Resource New Resource object which is a member of this resource category. + * @throws InvalidResourceException if the resource cannot be stored. + * @throws ResourcePropertyException If the name of the resource property + * is not defined for this resource category. + * @throws InvalidResourceCategoryException if the class_name attribute of + * the resource category contains a class name of a class which is not + * derived from the Resource class. + */ + public function createResource( + $name = '', + $description = '', + $parent_id = '', + $properties = [], + $ignore_invalid = false + ) + { + if (($this->class_name != 'Resource') and + !is_subclass_of($this->class_name, 'Resource')) { + //Invalid resource category specification: + //All class names for a resource category must be derived from the + //resource class! + throw new InvalidResourceCategoryException( + sprintf( + _('Die Ressourcenkategorie %1$s ist ungültig, da die dort angegebene Klasse %2$s nicht von der Klasse Resource abgeleitet ist!'), + $this->name, + $this->class_name + ) + ); + } + + $resource = new $this->class_name; + $resource->parent_id = $parent_id; + $resource->category_id = $this->id; + $resource->name = $name; + $resource->description = $description; + + if (!$resource->store()) { + throw new InvalidResourceException( + sprintf( + _('Fehler beim Speichern der Resource %1$s!'), + $resource->name + ) + ); + } + + //The resource is stored. We can now store its attributes: + if ($properties) { + foreach ($properties as $name => $state) { + try { + $resource->setProperty($name, $state); + } catch (ResourcePropertyException $e) { + if (!$ignore_invalid) { + throw $e; + } + } + } + } + + return $resource; + } + + /** + * Returns the default state for a resource property. + * Depending on the type of the resource property + * different state is returned. + * + * @param ResourcePropertyDefinition $definition The definition of a + * resource property whose default state shall be returned. + * + * @return mixed The default state for the property type, + * specified by the given property definition. + */ + protected function setPropertyDefaultState( + ResourcePropertyDefinition $definition + ) + { + switch ($definition->type) { + case 'bool': + return false; + case 'num': + return 0; + case 'select': + //Set the first option as default. + //For that, we have to split the option list first, + //since it containts semicolon separated values: + $options = explode(';', $definition->options); + return $options[0]; + case 'user': + //Return the ID of the current user: + return User::findCurrent()->id; + case 'position': + return '+0.0+0.0+0.0CRSWGS_84/'; + case 'institute': + case 'fileref': + case 'url': + case 'text': + return ''; + } + } + + /** + * Creates a ResourceProperty object for a specified Resource object. + * + * @param Resource $resource The resource for which the ResourceProperty + * object shall be built. + * @param string $name The name of the property. + * @param string $state The value of the property. + * + * @return ResourceProperty A ResourceProperty object + * for the given Resource object. + * @throws ResourcePropertyException If the name of the resource property + * is not defined for this resource category. + * + * @throws InvalidResourceCategoryException If this resource category + * doesn't match the category of the resource object. + */ + public function createDefinedResourceProperty(Resource $resource, $name, $state = null) + { + if ($resource->category_id != $this->id) { + throw new InvalidResourceCategoryException( + sprintf( + _('Die Ressource %1$s ist kein Mitglied der Ressourcenkategorie %2$s!'), + $resource->name, + $this->name + ) + ); + } + + if (!$resource->id) { + //The resource has no ID: probably it is a new resource. + if ($resource->isNew()) { + //We need an ID so we have to create one: + $resource->getNewId(); + } else { + throw new InvalidResourceException( + sprintf( + _('Die Ressource %1$s besitzt keine ID!'), + $resource->name + ) + ); + } + } + + + //get property definition: + $definition = ResourcePropertyDefinition::findOneBySql( + 'INNER JOIN resource_category_properties rcp + ON rcp.property_id = resource_property_definitions.property_id + WHERE category_id = :category_id + AND name = :name + LIMIT 1', + [ + 'category_id' => $this->id, + 'name' => $name + ] + ); + + if (!$definition) { + //Property is undefined for this resource category: + throw new ResourcePropertyException( + sprintf( + _('Die Eigenschaft %1$s ist für die Ressourcenkategorie %2$s nicht definiert!'), + $name, + $this->name + ) + ); + } + + $property = new ResourceProperty(); + $property->resource_id = $resource->id; + $property->property_id = $definition->id; + + //if state is not set we can set it to defined default values + //for some state types: + if ($state === null) { + $property->state = self::setPropertyDefaultState($definition); + } else { + $property->state = $state; + } + + return $property; + } + + /** + * Creates a ResourceRequestProperty object + * for a specified ResourceRequest object. + * + * @param ResourceRequest $request The resource request for which the + * ResourceRequestProperty object shall be built. + * @param string $name The name of the property. + * @param string $state The value of the property. + * + * @return ResourceRequestProperty A ResourceProperty object for the + * given Resource object. + * @throws ResourcePropertyException If the name of the resource property is + * not defined for the resource category of the resource request. + * + * @throws InvalidResourceCategoryException If this resource category + * doesn't match the resource category of the resource request object. + */ + public function createDefinedResourceRequestProperty( + ResourceRequest $request, + $name, + $state = null + ) + { + if ($request->category_id != $this->id) { + throw new InvalidResourceCategoryException( + sprintf( + _('Die Resourcenanfrage %1$s ist kein Mitglied der Ressourcenkategorie %2$s!'), + $request->name, + $this->name + ) + ); + } + + if (!$request->id) { + //The request has no ID: probably it is a new resource request. + if ($request->isNew()) { + //We need an ID so we have to create one: + $request->id = $request->getNewId(); + } else { + throw new InvalidResourceRequestException( + sprintf( + _('Die Ressourcenanfrage %1$s besitzt keine ID!'), + $request->name + ) + ); + } + } + + //get property definition: + $definition = ResourcePropertyDefinition::findOneBySql( + 'INNER JOIN resource_category_properties rcp + ON rcp.property_id = resource_property_definitions.property_id + WHERE category_id = :category_id + AND name = :name + LIMIT 1', + [ + 'category_id' => $this->id, + 'name' => $name + ] + ); + + if (!$definition) { + //Property is undefined for this resource category: + throw new ResourcePropertyException( + sprintf( + _('Die Eigenschaft %1$s ist für die Ressourcenkategorie %2$s nicht definiert!'), + $name, + $this->name + ) + ); + } + + $property = new ResourceRequestProperty(); + $property->request_id = $request->id; + $property->property_id = $definition->id; + + //if state is not set we can set it to defined default values + //for some state types: + if ($state === null) { + $property->state = self::setPropertyDefaultState($definition); + } else { + $property->state = $state; + } + + return $property; + } + + public function getRequestableProperties() + { + return ResourcePropertyDefinition::findBySql( + "INNER JOIN resource_category_properties + USING (property_id) + WHERE + resource_category_properties.category_id = :category_id + AND + resource_category_properties.requestable = '1' + ORDER BY type DESC, name ASC", + [ + 'category_id' => $this->id + ] + ); + } + + /** + * Determines if this resource category has a property with the + * specified name and type. + * + * @param string $name The requested property name. + * @param string $type The requested property type (optional). + * + * @return bool True, if a property with the specified name and type + * exists, false otherwise. + */ + public function hasProperty($name = '', $type = null) + { + if ($type) { + return ResourceCategoryProperty::countBySql( + 'INNER JOIN resource_property_definitions + USING (property_id) + WHERE + name = :name + AND + type = :type + AND + category_id = :category_id', + [ + 'name' => $name, + 'type' => $type, + 'category_id' => $this->id + ] + ) > 0; + } else { + return ResourceCategoryProperty::countBySql( + 'INNER JOIN resource_property_definitions + USING (property_id) + WHERE + name = :name + AND + category_id = :category_id', + [ + 'name' => $name, + 'category_id' => $this->id + ] + ) > 0; + } + } + + /** + * Determines if the user has write permissions for the + * resource property specified by its name. + * + * @param string The name of the resource property definition. + * @param User $user The user whose permissions shall be checked. + * @param Resource|null $resource An optional resource that shall be used + * to check for non-global permissions. + * + * @return bool True, if the user has write permissions, false otherwise. + * @throws ResourcePropertyDefinitionException If no property is found. + * + */ + public function userHasPropertyWritePermissions(string $name, User $user, $resource = null) + { + $property = ResourcePropertyDefinition::findOneBySql( + 'name = :name', + [ + 'name' => $name + ] + ); + + if (!$property) { + throw new ResourcePropertyDefinitionException( + sprintf( + _('Die Ressourceneigenschaft %s existiert nicht!'), + $name + ) + ); + } + + if ($property->write_permission_level == 'admin-global') { + return ResourceManager::userHasGlobalPermission( + $user, + 'admin' + ); + } elseif ($resource instanceof Resource) { + //It must be a permission for the specified resource. + return $resource->userHasPermission( + $user, + $property->write_permission_level + ); + } else { + //We cannot check permissions. + return false; + } + } + + /** + * Get the icon of a category + * @param string $role + * @return Icon + */ + public function getIcon($role = Icon::ROLE_INFO) + { + if ($this->iconnr == 0) { + //No special icon + return Icon::create('resources', $role); + } elseif ($this->iconnr == 1) { + return Icon::create('home', $role); + } else { + //No known icon + return Icon::create('resources', $role); + } + } +} |