first commit

lib/pkp/classes/services/interfaces/EntityPropertyInterface.php

@@ -0,0 +1,58 @@
+<?php
+/**
+ * @file classes/services/interfaces/EntityPropertyInterface.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 EntityPropertyInterface
+ *
+ * @ingroup services_interfaces
+ *
+ * @brief An interface describing the methods a service class will implement to
+ *  convert an entity into an assoc array of properties. These methods are
+ *  typically evoked when producing a response to an API request.
+ */
+
+namespace PKP\services\interfaces;
+
+interface EntityPropertyInterface
+{
+    /**
+     * Returns the values for the requested list of properties
+     *
+     * @param object $entity The object to convert
+     * @param array $props The properties to include in the result
+     * @param array $args Additional variable which may be required
+     *		$args['request'] PKPRequest Required
+     *		$args['slimRequest'] SlimRequest
+     *
+     * @return array
+     */
+    public function getProperties($entity, $props, $args = null);
+
+    /**
+     * Returns summary properties for an entity
+     *
+     * @param object $entity The object to convert
+     * @param array $args Additional variables which may be required
+     *		$args['request'] PKPRequest Required
+     *		$args['slimRequest'] SlimRequest
+     *
+     * @return array
+     */
+    public function getSummaryProperties($entity, $args = null);
+
+    /**
+     * Returns full properties for an entity
+     *
+     * @param object $entity The object to convert
+     * @param array $args Additional variable which may be required
+     *		$args['request'] PKPRequest Required
+     *		$args['slimRequest'] SlimRequest
+     *
+     * @return array
+     */
+    public function getFullProperties($entity, $args = null);
+}

lib/pkp/classes/services/interfaces/EntityReadInterface.php

@@ -0,0 +1,83 @@
+<?php
+/**
+ * @file classes/services/interfaces/EntityReadInterface.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 EntityReadInterface
+ *
+ * @ingroup services_interfaces
+ *
+ * @brief An interface describing the methods a service class will implement to
+ *  get one object or a collection of objects.
+ */
+
+namespace PKP\services\interfaces;
+use Illuminate\Database\Query\Builder;
+
+interface EntityReadInterface
+{
+    /**
+     * Get one object of the entity type by its ID
+     *
+     * @param int $id
+     *
+     * @return object
+     */
+    public function get($id);
+
+    /**
+     * Get a count of the number of objects matching $args
+     *
+     * @param array $args Assoc array describing which rows should be counted
+     *
+     * @return int
+     */
+    public function getCount($args = []);
+
+    /**
+     * Get a list of ids matching $args
+     *
+     * @param array $args Assoc array describing which ids should be retrieved
+     *
+     * @return array
+     */
+    public function getIds($args = []);
+
+    /**
+     * Get a collection of objects limited, filtered and sorted by $args
+     *
+     * @param array $args Assoc array describing which objects should be retrieved
+     *
+     * @return \Iterator
+     */
+    public function getMany($args = []);
+
+    /**
+     * Get the max count of objects matching $args
+     *
+     * This method is identical to `self::getCount()` except that any pagination
+     * arguments such as `count` or `offset` will be ignored.
+     *
+     * Usually, this is used with `self::getMany()` to return the total number of
+     * items available according to the selection criteria.
+     *
+     * @param array $args Assoc array describing which objects should be counted
+     *
+     * @return int
+     */
+    public function getMax($args = []);
+
+    /**
+     * Get a QueryBuilder for this entity configured
+     * according to the $args passed
+     *
+     * @param array $args Assoc array describing how the querybuilder should be
+     * configured.
+     *
+     * @return Builder
+     */
+    public function getQueryBuilder($args = []);
+}

lib/pkp/classes/services/interfaces/EntityWriteInterface.php

@@ -0,0 +1,87 @@
+<?php
+/**
+ * @file classes/services/interfaces/EntityWriteInterface.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 EntityWriteInterface
+ *
+ * @ingroup services_interfaces
+ *
+ * @brief An interface describing the methods a service class will implement to
+ *  validate, add, edit and delete an object.
+ */
+
+namespace PKP\services\interfaces;
+
+interface EntityWriteInterface
+{
+    // The type of action against which data should be validated. When adding an
+    // entity, required properties must be present and not empty.
+    public const VALIDATE_ACTION_ADD = 'add';
+    public const VALIDATE_ACTION_EDIT = 'edit';
+
+    /**
+     * Validate the properties of an object
+     *
+     * Passes the properties through the SchemaService to validate them, and
+     * performs any additional checks needed to validate the entity.
+     *
+     * This does NOT authenticate the current user to perform the action.
+     *
+     * @param string $action The type of action required (add/edit). One of the
+     *  VALIDATE_ACTION_... constants.
+     * @param array $props The data to validate
+     * @param array $allowedLocales Which locales are allowed for this entity
+     * @param string $primaryLocale
+     *
+     * @return array List of error messages. The array keys are property names
+     */
+    public function validate($action, $props, $allowedLocales, $primaryLocale);
+
+    /**
+     * Add a new object
+     *
+     * This does not check if the user is authorized to add the object, or
+     * validate or sanitize this object.
+     *
+     * @param object $object
+     * @param \APP\core\Request $request
+     *
+     * @return object
+     */
+    public function add($object, $request);
+
+    /**
+     * Edit an object
+     *
+     * This does not check if the user is authorized to edit the object, or
+     * validate or sanitize the new object values.
+     *
+     * @param object $object
+     * @param array $params Key/value array of new data
+     * @param \APP\core\Request $request
+     *
+     * @return object
+     */
+    public function edit($object, $params, $request);
+
+    /**
+     * Delete an object
+     *
+     * This does not check if the user is authorized to delete the object or if
+     * the object exists.
+     *
+     * @param object $object
+     *
+     * @return bool
+     */
+    public function delete($object);
+}
+
+if (!PKP_STRICT_MODE) {
+    define('VALIDATE_ACTION_ADD', EntityWriteInterface::VALIDATE_ACTION_ADD);
+    define('VALIDATE_ACTION_EDIT', EntityWriteInterface::VALIDATE_ACTION_EDIT);
+}