first commit

lib/pkp/classes/category/Category.php

@@ -0,0 +1,168 @@
+<?php
+
+/**
+ * @file classes/category/Category.php
+ *
+ * Copyright (c) 2014-2021 Simon Fraser University
+ * Copyright (c) 2003-2021 John Willinsky
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @class Category
+ *
+ * @brief Describes basic Category properties.
+ */
+
+namespace PKP\category;
+
+class Category extends \PKP\core\DataObject
+{
+    /**
+     * Get ID of context.
+     */
+    public function getContextId(): int
+    {
+        return $this->getData('contextId');
+    }
+
+    /**
+     * Set ID of context.
+     */
+    public function setContextId(int $contextId)
+    {
+        return $this->setData('contextId', $contextId);
+    }
+
+    /**
+     * Get ID of parent category.
+     */
+    public function getParentId(): ?int
+    {
+        return $this->getData('parentId');
+    }
+
+    /**
+     * Set ID of parent category.
+     */
+    public function setParentId(?int $parentId)
+    {
+        return $this->setData('parentId', $parentId);
+    }
+
+    /**
+     * Get sequence of category.
+     */
+    public function getSequence(): float
+    {
+        return (float) $this->getData('sequence');
+    }
+
+    /**
+     * Set sequence of category.
+     */
+    public function setSequence(float $sequence)
+    {
+        return $this->setData('sequence', $sequence);
+    }
+
+    /**
+     * Get category path.
+     */
+    public function getPath(): string
+    {
+        return $this->getData('path');
+    }
+
+    /**
+     * Set category path.
+     */
+    public function setPath(string $path)
+    {
+        return $this->setData('path', $path);
+    }
+
+    /**
+     * Get localized title of the category.
+     */
+    public function getLocalizedTitle(): string
+    {
+        return $this->getLocalizedData('title');
+    }
+
+    /**
+     * Get title of category.
+     */
+    public function getTitle(?string $locale = null)
+    {
+        return $this->getData('title', $locale);
+    }
+
+    /**
+     * Set title of category.
+     */
+    public function setTitle($title, ?string $locale)
+    {
+        return $this->setData('title', $title, $locale);
+    }
+
+    /**
+     * Get localized description of the category.
+     */
+    public function getLocalizedDescription(): ?string
+    {
+        return $this->getLocalizedData('description');
+    }
+
+    /**
+     * Get description of category.
+     */
+    public function getDescription(?string $locale)
+    {
+        return $this->getData('description', $locale);
+    }
+
+    /**
+     * Set description of category.
+     */
+    public function setDescription($description, ?string $locale)
+    {
+        return $this->setData('description', $description, $locale);
+    }
+
+    /**
+     * Get the image.
+     */
+    public function getImage(): ?array
+    {
+        return $this->getData('image');
+    }
+
+    /**
+     * Set the image.
+     */
+    public function setImage(?array $image)
+    {
+        return $this->setData('image', $image);
+    }
+
+    /**
+     * Get the option how the books in this category should be sorted,
+     * in the form: concat(sortBy, sortDir).
+     */
+    public function getSortOption(): ?string
+    {
+        return $this->getData('sortOption');
+    }
+
+    /**
+     * Set the option how the books in this category should be sorted,
+     * in the form: concat(sortBy, sortDir).
+     */
+    public function setSortOption(?string $sortOption)
+    {
+        return $this->setData('sortOption', $sortOption);
+    }
+}
+
+if (!PKP_STRICT_MODE) {
+    class_alias('\PKP\category\Category', '\Category');
+}

lib/pkp/classes/category/Collector.php

@@ -0,0 +1,170 @@
+<?php
+/**
+ * @file classes/category/Collector.php
+ *
+ * Copyright (c) 2014-2021 Simon Fraser University
+ * Copyright (c) 2000-2021 John Willinsky
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @class Collector
+ *
+ * @brief A helper class to configure a Query Builder to get a collection of categories
+ */
+
+namespace PKP\category;
+
+use Illuminate\Database\Query\Builder;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\LazyCollection;
+use PKP\core\interfaces\CollectorInterface;
+use PKP\plugins\Hook;
+
+/**
+ * @template T of Category
+ */
+class Collector implements CollectorInterface
+{
+    public DAO $dao;
+    public ?array $contextIds = null;
+    public ?array $parentIds = null;
+    public ?array $paths = null;
+    public ?array $publicationIds = null;
+    public ?int $count = null;
+    public ?int $offset = null;
+
+    public function __construct(DAO $dao)
+    {
+        $this->dao = $dao;
+    }
+
+    public function getCount(): int
+    {
+        return $this->dao->getCount($this);
+    }
+
+    /**
+     * @return Collection<int,int>
+     */
+    public function getIds(): Collection
+    {
+        return $this->dao->getIds($this);
+    }
+
+    /**
+     * @copydoc DAO::getMany()
+     * @return LazyCollection<int,T>
+     */
+    public function getMany(): LazyCollection
+    {
+        return $this->dao->getMany($this);
+    }
+
+    /**
+     * Filter categories by one or more contexts
+     */
+    public function filterByContextIds(?array $contextIds): self
+    {
+        $this->contextIds = $contextIds;
+        return $this;
+    }
+
+    /**
+     * Filter categories by one or more parent category IDs
+     */
+    public function filterByParentIds(?array $parentIds): self
+    {
+        $this->parentIds = $parentIds;
+        return $this;
+    }
+
+    /**
+     * Filter categories by one or more publication IDs
+     */
+    public function filterByPublicationIds(?array $publicationIds): self
+    {
+        $this->publicationIds = $publicationIds;
+        return $this;
+    }
+
+    /**
+     * Filter categories by one or more paths
+     */
+    public function filterByPaths(?array $paths): self
+    {
+        $this->paths = $paths;
+        return $this;
+    }
+
+    /**
+     * Limit the number of objects retrieved
+     */
+    public function limit(?int $count): self
+    {
+        $this->count = $count;
+        return $this;
+    }
+
+    /**
+     * Offset the number of objects retrieved, for example to
+     * retrieve the second page of contents
+     */
+    public function offset(?int $offset): self
+    {
+        $this->offset = $offset;
+        return $this;
+    }
+
+    /**
+     * @copydoc CollectorInterface::getQueryBuilder()
+     */
+    public function getQueryBuilder(): Builder
+    {
+        $qb = DB::table($this->dao->table . ' as c')
+            ->leftJoin('categories AS pc', 'c.parent_id', '=', 'pc.category_id')
+            ->select(['c.*']);
+
+        $qb->when($this->contextIds !== null, function ($query) {
+            $query->whereIn('c.context_id', $this->contextIds);
+        });
+
+        $qb->when($this->paths !== null, function ($query) {
+            $query->whereIn('c.path', $this->paths);
+        });
+
+        $qb->when($this->publicationIds !== null, function ($query) {
+            $query->whereIn('c.category_id', function ($query) {
+                $query->select('category_id')->from('publication_categories')->whereIn('publication_id', $this->publicationIds);
+            });
+        });
+
+        $qb->when($this->parentIds !== null, function ($query) {
+            // parentIds may contain mixed values and nulls; make sure the mix translates into the query accurately
+            $nonNullParentIds = array_filter($this->parentIds);
+            if (count($nonNullParentIds)) {
+                $query->whereIn('c.parent_id', array_filter($this->parentIds));
+            }
+            if (in_array(null, $this->parentIds)) {
+                if (count($nonNullParentIds)) {
+                    $query->orWhereNull('c.parent_id');
+                } else {
+                    $query->whereNull('c.parent_id');
+                }
+            }
+        });
+
+        $qb->orderBy(DB::raw('(COALESCE((pc.seq * 8192) + pc.category_id, 0) * 8192) + CASE WHEN pc.category_id IS NULL THEN 8192 * ((c.seq * 8192) + c.category_id) ELSE c.seq END'));
+
+        if (isset($this->count)) {
+            $qb->limit($this->count);
+        }
+
+        if (isset($this->offset)) {
+            $qb->offset($this->offset);
+        }
+
+        Hook::call('Category::Collector', [&$qb, $this]);
+
+        return $qb;
+    }
+}

lib/pkp/classes/category/DAO.php

@@ -0,0 +1,174 @@
+<?php
+/**
+ * @file classes/category/DAO.php
+ *
+ * Copyright (c) 2014-2021 Simon Fraser University
+ * Copyright (c) 2000-2021 John Willinsky
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @class DAO
+ *
+ * @brief Read and write categories to the database.
+ */
+
+namespace PKP\category;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\LazyCollection;
+use PKP\core\EntityDAO;
+use PKP\core\traits\EntityWithParent;
+
+/**
+ * @template T of Category
+ * @extends EntityDAO<T>
+ */
+class DAO extends EntityDAO
+{
+    use EntityWithParent;
+
+    /** @copydoc EntityDAO::$schema */
+    public $schema = \PKP\services\PKPSchemaService::SCHEMA_CATEGORY;
+
+    /** @copydoc EntityDAO::$table */
+    public $table = 'categories';
+
+    /** @copydoc EntityDAO::$settingsTable */
+    public $settingsTable = 'category_settings';
+
+    /** @copydoc EntityDAO::$primaryKeyColumn */
+    public $primaryKeyColumn = 'category_id';
+
+    /** @copydoc EntityDAO::$primaryTableColumns */
+    public $primaryTableColumns = [
+        'id' => 'category_id',
+        'parentId' => 'parent_id',
+        'contextId' => 'context_id',
+        'sequence' => 'seq',
+        'path' => 'path',
+        'image' => 'image',
+    ];
+
+    /**
+     * Get the parent object ID column name
+     */
+    public function getParentColumn(): string
+    {
+        return 'context_id';
+    }
+
+    /**
+     * Instantiate a new DataObject
+     */
+    public function newDataObject(): Category
+    {
+        return app(Category::class);
+    }
+
+    /**
+     * Get the number of categories matching the configured query
+     */
+    public function getCount(Collector $query): int
+    {
+        return $query->getQueryBuilder()->count();
+    }
+
+    /**
+     * Get a list of ids matching the configured query
+     *
+     * @return Collection<int,int>
+     */
+    public function getIds(Collector $query): Collection
+    {
+        return $query
+            ->getQueryBuilder()
+            ->pluck('c.' . $this->primaryKeyColumn);
+    }
+
+    /**
+     * Get a collection of categories matching the configured query
+     * @return LazyCollection<int,T>
+     */
+    public function getMany(Collector $query): LazyCollection
+    {
+        $rows = $query
+            ->getQueryBuilder()
+            ->get();
+
+        return LazyCollection::make(function () use ($rows) {
+            foreach ($rows as $row) {
+                yield $row->category_id => $this->fromRow($row);
+            }
+        });
+    }
+
+    /**
+     * @copydoc EntityDAO::fromRow()
+     */
+    public function fromRow(object $row): Category
+    {
+        return parent::fromRow($row);
+    }
+
+    /**
+     * @copydoc EntityDAO::insert()
+     */
+    public function insert(Category $category): int
+    {
+        return parent::_insert($category);
+    }
+
+    /**
+     * @copydoc EntityDAO::update()
+     */
+    public function update(Category $category)
+    {
+        parent::_update($category);
+    }
+
+    /**
+     * @copydoc EntityDAO::delete()
+     */
+    public function delete(Category $category)
+    {
+        parent::_delete($category);
+    }
+
+    /**
+     * Sequentially renumber categories in their sequence order by context ID and optionally parent category ID.
+     *
+     * @param int $parentCategoryId Optional parent category ID
+     */
+    public function resequenceCategories(int $contextId, ?int $parentCategoryId = null)
+    {
+        $categoryIds = DB::table('categories')
+            ->where('context_id', '=', $contextId)
+            ->when($parentCategoryId !== null, function ($query) use ($parentCategoryId) {
+                $query->where($parentCategoryId, '=', $parentCategoryId);
+            })->pluck('category_id');
+
+        $i = 0;
+        foreach ($categoryIds as $categoryId) {
+            DB::table('categories')->where('category_id', '=', $categoryId)->update(['seq' => ++$i]);
+        }
+    }
+
+    /**
+     * Assign a publication to a category
+     */
+    public function insertPublicationAssignment(int $categoryId, int $publicationId)
+    {
+        DB::table('publication_categories')->insert([
+            'category_id' => $categoryId,
+            'publication_id' => $publicationId,
+        ]);
+    }
+
+    /**
+     * Delete the assignment of a category to a publication
+     */
+    public function deletePublicationAssignments(int $publicationId)
+    {
+        DB::table('publication_categories')->where('publication_id', '=', $publicationId)->delete();
+    }
+}

lib/pkp/classes/category/Repository.php

@@ -0,0 +1,191 @@
+<?php
+/**
+ * @file classes/category/Repository.php
+ *
+ * Copyright (c) 2014-2020 Simon Fraser University
+ * Copyright (c) 2000-2020 John Willinsky
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @class Repository
+ *
+ * @brief A repository to find and manage categories.
+ */
+
+namespace PKP\category;
+
+use APP\core\Request;
+use Illuminate\Support\LazyCollection;
+use PKP\plugins\Hook;
+use PKP\services\PKPSchemaService;
+use PKP\validation\ValidatorFactory;
+
+class Repository
+{
+    /** @var DAO $dao */
+    public $dao;
+
+    /** @var string $schemaMap The name of the class to map this entity to its schema */
+    public $schemaMap = maps\Schema::class;
+
+    /** @var Request $request */
+    protected $request;
+
+    /** @var PKPSchemaService<Category> $schemaService */
+    protected $schemaService;
+
+
+    public function __construct(DAO $dao, Request $request, PKPSchemaService $schemaService)
+    {
+        $this->dao = $dao;
+        $this->request = $request;
+        $this->schemaService = $schemaService;
+    }
+
+    /** @copydoc DAO::newDataObject() */
+    public function newDataObject(array $params = []): Category
+    {
+        $object = $this->dao->newDataObject();
+        if (!empty($params)) {
+            $object->setAllData($params);
+        }
+        return $object;
+    }
+
+    /** @copydoc DAO::get() */
+    public function get(int $id, int $contextId = null): ?Category
+    {
+        return $this->dao->get($id, $contextId);
+    }
+
+    /** @copydoc DAO::exists() */
+    public function exists(int $id, int $contextId = null): bool
+    {
+        return $this->dao->exists($id, $contextId);
+    }
+
+    /**
+     * Get the breadcrumb of a category
+     *
+     * @return string For example: Social Sciences > Anthropology
+     */
+    public function getBreadcrumb(Category $category, ?Category $parent = null): string
+    {
+        return !$parent
+            ? $category->getLocalizedTitle()
+            : __('common.categorySeparator', [
+                'parent' => $parent->getLocalizedTitle(),
+                'child' => $category->getLocalizedTitle()
+            ]);
+    }
+
+    /**
+     * Get the breadcrumbs for a Collection of categories
+     */
+    public function getBreadcrumbs(LazyCollection $categories): LazyCollection
+    {
+        return $categories->map(function (Category $category) use ($categories) {
+            /** @var ?Category $parent */
+            $parent = $categories->first(
+                fn (Category $c) => $c->getId() === $category->getParentId()
+            );
+            return $this->getBreadcrumb($category, $parent);
+        });
+    }
+
+    /** @copydoc DAO::getCollector() */
+    public function getCollector(): Collector
+    {
+        return app(Collector::class);
+    }
+
+    /**
+     * Get an instance of the map class for mapping
+     * announcements to their schema
+     */
+    public function getSchemaMap(): maps\Schema
+    {
+        return app('maps')->withExtensions($this->schemaMap);
+    }
+
+    /**
+     * Validate properties for a category
+     *
+     * Perform validation checks on data used to add or edit a category.
+     *
+     * @param array $props A key/value array with the new data to validate
+     * @param array $allowedLocales The context's supported locales
+     * @param string $primaryLocale The context's primary locale
+     *
+     * @return array A key/value array with validation errors. Empty if no errors
+     */
+    public function validate(?Category $object, array $props, array $allowedLocales, string $primaryLocale): array
+    {
+        $validator = ValidatorFactory::make(
+            $props,
+            $this->schemaService->getValidationRules($this->dao->schema, $allowedLocales),
+            []
+        );
+
+        // Check required fields
+        ValidatorFactory::required(
+            $validator,
+            $object,
+            $this->schemaService->getRequiredProps($this->dao->schema),
+            $this->schemaService->getMultilingualProps($this->dao->schema),
+            $allowedLocales,
+            $primaryLocale
+        );
+
+        // Check for input from disallowed locales
+        ValidatorFactory::allowedLocales($validator, $this->schemaService->getMultilingualProps($this->dao->schema), $allowedLocales);
+
+        $errors = [];
+
+        if ($validator->fails()) {
+            $errors = $this->schemaService->formatValidationErrors($validator->errors());
+        }
+
+        Hook::call('Category::validate', [&$errors, $object, $props, $allowedLocales, $primaryLocale]);
+
+        return $errors;
+    }
+
+    /** @copydoc DAO::insert() */
+    public function add(Category $category): int
+    {
+        $id = $this->dao->insert($category);
+        Hook::call('Category::add', [$category]);
+
+        return $id;
+    }
+
+    /** @copydoc DAO::update() */
+    public function edit(Category $category, array $params)
+    {
+        $newCategory = clone $category;
+        $newCategory->setAllData(array_merge($newCategory->_data, $params));
+
+        Hook::call('Category::edit', [$newCategory, $category, $params]);
+
+        $this->dao->update($newCategory);
+    }
+
+    /** @copydoc DAO::delete() */
+    public function delete(Category $category)
+    {
+        Hook::call('Category::delete::before', [$category]);
+        $this->dao->delete($category);
+        Hook::call('Category::delete', [$category]);
+    }
+
+    /**
+     * Delete a collection of categories
+     */
+    public function deleteMany(Collector $collector)
+    {
+        foreach ($collector->getMany() as $category) {
+            /** @var Category $category */
+            $this->delete($category);
+        }
+    }
+}

lib/pkp/classes/category/maps/Schema.php

@@ -0,0 +1,87 @@
+<?php
+/**
+ * @file classes/category/maps/Schema.php
+ *
+ * Copyright (c) 2014-2020 Simon Fraser University
+ * Copyright (c) 2000-2020 John Willinsky
+ * Distributed under the GNU GPL v3. For full terms see the file docs/COPYING.
+ *
+ * @class Schema
+ *
+ * @brief Map categories to the properties defined in the category schema
+ */
+
+namespace PKP\category\maps;
+
+use Illuminate\Support\Enumerable;
+use PKP\category\Category;
+use PKP\services\PKPSchemaService;
+
+class Schema extends \PKP\core\maps\Schema
+{
+    public string $schema = PKPSchemaService::SCHEMA_CATEGORY;
+
+    /**
+     * Map a category
+     *
+     * Includes all properties in the category schema.
+     */
+    public function map(Category $category): array
+    {
+        return $this->mapByProperties($this->getProps(), $category);
+    }
+
+    /**
+     * Summarize a category
+     *
+     * Includes properties with the apiSummary flag in the category schema.
+     */
+    public function summarize(Category $category): array
+    {
+        return $this->mapByProperties($this->getSummaryProps(), $category);
+    }
+
+    /**
+     * Map a collection of Categories
+     *
+     * @see self::map
+     */
+    public function mapMany(Enumerable $collection): Enumerable
+    {
+        $this->collection = $collection;
+        return $collection->map(function ($category) {
+            return $this->map($category);
+        });
+    }
+
+    /**
+     * Summarize a collection of Categories
+     *
+     * @see self::summarize
+     */
+    public function summarizeMany(Enumerable $collection): Enumerable
+    {
+        $this->collection = $collection;
+        return $collection->map(function ($category) {
+            return $this->summarize($category);
+        });
+    }
+
+    /**
+     * Map schema properties of a Category to an assoc array
+     */
+    protected function mapByProperties(array $props, Category $category): array
+    {
+        $output = [];
+
+        foreach ($props as $prop) {
+            switch ($prop) {
+                default:
+                    $output[$prop] = $category->getData($prop);
+                    break;
+            }
+        }
+
+        return $output;
+    }
+}