first commit

lib/pkp/classes/services/queryBuilders/interfaces/EntityQueryBuilderInterface.php

@@ -0,0 +1,89 @@
+<?php
+
+/**
+ * @file classes/services/queryBuilders/interfaces/EntityQueryBuilderInterface.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 EntityQueryBuilderInterface
+ *
+ * @ingroup services_query_builders
+ *
+ * @brief An interface that defines required methods for
+ *   a QueryBuilder that retrieves one of the application's
+ *   entities.
+ */
+
+namespace PKP\services\queryBuilders\interfaces;
+use Illuminate\Database\Query\Builder;
+
+interface EntityQueryBuilderInterface
+{
+    /**
+     * Get a count of the number of rows that match the select
+     * conditions configured in this query builder.
+     *
+     * @return int
+     */
+    public function getCount();
+
+    /**
+     * Get a list of ids that match the select conditions
+     * configured in this query builder.
+     *
+     * @return array
+     */
+    public function getIds();
+
+    /**
+     * Get a query builder with the applied select, where and
+     * join clauses based on builder's configuration
+     *
+     * This returns an instance of Laravel's query builder.
+     *
+     * Call the `get` method on a query builder to return an array
+     * of matching rows.
+     *
+     * ```php
+     * $qb = new \PKP\services\queryBuilders\PublicationQueryBuilder();
+     * $result = $qb
+     *   ->filterByContextIds(1)
+     *   ->getQuery()
+     *   ->get();
+     * ```
+     *
+     * Or use the query builder to retrieve objects from a DAO.
+     * This example retrieves the first 20 matching Publications.
+     *
+     * ```php
+     * $qo = $qb
+     *   ->filterByContextIds(1)
+     *   ->getQuery();
+     * $result = DAORegistry::getDAO('ReviewRoundDAO')->retrieveRange(
+     *   $qo->toSql(),
+     *   $qo->getBindings(),
+     *   new DBResultRange(20, null, 0);
+     * );
+     * $queryResults = new DAOResultFactory($result, $reviewRoundDao, '_fromRow');
+     * $iteratorOfObjects = $queryResults->toIterator();
+     * ```
+     *
+     * Laravel's other query builder methods, such as `first`
+     * and `pluck`, can also be used.
+     *
+     * ```
+     * $qb = new \PKP\services\queryBuilders\PublicationQueryBuilder();
+     * $result = $qb
+     *   ->filterByContextIds(1)
+     *   ->getQuery()
+     *   ->first();
+     * ```
+     *
+     * See: https://laravel.com/docs/5.5/queries
+     *
+     * @return Builder
+     */
+    public function getQuery();
+}