1: <?php
  2: /**
  3:  * This file is part of the Pipeliner API client library for PHP
  4:  *
  5:  * Copyright 2014 Pipelinersales, Inc. All Rights Reserved.
  6:  * For the full license information, see the attached LICENSE file.
  7:  */
  8: 
  9: namespace PipelinerSales\ApiClient\Repository;
 10: 
 11: use PipelinerSales\ApiClient\Entity;
 12: use PipelinerSales\ApiClient\EntityCollection;
 13: use PipelinerSales\ApiClient\EntityCollectionIterator;
 14: use PipelinerSales\ApiClient\Http\PipelinerHttpException;
 15: use PipelinerSales\ApiClient\Http\Response;
 16: use PipelinerSales\ApiClient\Http\CreatedResponse;
 17: use PipelinerSales\ApiClient\PipelinerClientException;
 18: 
 19: /**
 20:  * An interface for retrieving and manipulating entities.
 21:  */
 22: interface RepositoryInterface
 23: {
 24: 
 25:     // flags for batch operations:
 26:     
 27:     /** If any error occurs, no entity will be processed, and the entire batch will be rolled back. */
 28:     const FLAG_ROLLBACK_ON_ERROR = 0;
 29: 
 30:     /** If an error occurs for an entity, the entity is ignored and the system continues with the next one. */
 31:     const FLAG_IGNORE_ON_ERROR = 1;
 32: 
 33:     /** If any error occurs during the update of an entity (e.g. the entity doesn’t exists),
 34:      *  the entity will be inserted instead, and a new unique identificator will be generated */
 35:     const FLAG_INSERT_ON_UPDATE = 2;
 36: 
 37:     /** The method will return a list of IDs which cannot be deleted.
 38:      * Can be used with combination with FLAG_IGNORE_ON_ERROR. */
 39:     const FLAG_GET_NO_DELETED_ID = 4;
 40: 
 41:     /** If any error occurs for an entity, the entity is ignored and the system continues with the next one. */
 42:     const FLAG_IGNORE_AND_RETURN_ERRORS = 8;
 43: 
 44:     /** Only updated fields in the entity will be validated instead of all fields. */
 45:     const FLAG_VALIDATE_ONLY_UPDATED_FIELDS = 256;
 46: 
 47:     // flags for save operations about which fields to send:
 48: 
 49:     /** Partial update, send only fields which have been modified since the entity was last loaded/saved */
 50:     const SEND_MODIFIED_FIELDS = 0;
 51: 
 52:     /** Send all fields that exist within the entity */
 53:     const SEND_ALL_FIELDS = 1;
 54: 
 55:     /**
 56:      * Creates a new entity. Please note that this entity won't exist on the
 57:      * server until you save it by calling the save method.
 58:      *
 59:      * @return Entity
 60:      */
 61:     public function create();
 62: 
 63:     /**
 64:      * Deletes an entity
 65:      *
 66:      * @param mixed $entity the entity to delete, or an array of multiple entities
 67:      * @param integer $flags used only if multiple entities are provided,
 68:      * flags described on {@link http://workspace.pipelinersales.com/community/api/data/Methods_rest.html}
 69:      * @return Response response to the delete HTTP request
 70:      * @throws PipelinerHttpException
 71:      * @throws PipelinerClientException when the entity provided doesn't have an ID,
 72:      * which usually means that it's a newly created entity that wasn't saved yet
 73:      */
 74:     public function delete($entity, $flags = self::FLAG_ROLLBACK_ON_ERROR);
 75: 
 76:     /**
 77:      * Deletes one or more entities specified by their ID
 78:      *
 79:      * @param mixed $id the ID of the entity to delete, or an array containing multiple IDs
 80:      * @param integer $flags used only if multiple IDs are provided,
 81:      * flags described on {@link http://workspace.pipelinersales.com/community/api/data/Querying_rest.html}
 82:      * @return Response response to the delete HTTP request
 83:      * @throws PipelinerHttpException
 84:      */
 85:     public function deleteById($id, $flags = 0);
 86: 
 87:     /**
 88:      * Returns a collection of all entities satisfying the provided criteria
 89:      *
 90:      * @param mixed $criteria Can be one of the following
 91:      * <ul>
 92:      * <li>null - fetches all entities up to a default limit of 25</li>
 93:      * <li>a {@see Criteria} object</li>
 94:      * <li>a {@see Filter} object</li>
 95:      * <li>a {@see Sort} object</li>
 96:      * <li>a query string following the format described at
 97:      * {@link http://workspace.pipelinersales.com/community/api/data/Querying_rest.html}</li>
 98:      * <li>an array with keys corresponding to the format at
 99:      * {@link http://workspace.pipelinersales.com/community/api/data/Querying_rest.html}</li>
100:      * </ul>
101:      * @return EntityCollection
102:      * @throws PipelinerHttpException when retrieving data from the server fails
103:      * @throws PipelinerClientException when provided criteria is invalid
104:      */
105:     public function get($criteria = null);
106: 
107:     /**
108:      * Returns an entity with the specified ID
109:      *
110:      * @param string $id
111:      * @throws PipelinerHttpException
112:      * @return Entity
113:      */
114:     public function getById($id);
115: 
116:     /**
117:      * Uploads an entity to the server.
118:      *
119:      * @param mixed $entity the entity to upload, an {@see Entity} object or an associative array
120:      * @param integer $sendFields whether to upload all the fields for Entity objects, or just the fields
121:      * which have been modified in code since the entity was loaded/saved
122:      * @return Response|CreatedResponse response to the HTTP request
123:      * @throws PipelinerHttpException
124:      */
125:     public function save($entity, $sendFields = self::SEND_MODIFIED_FIELDS);
126: 
127:     /**
128:      * Updates multiple entities at once
129:      *
130:      * @param mixed $data entities to update, where each entity is either an entity object or an associative array
131:      * with keys corresponding to fields and values to the entity's values.
132:      * See the setEntities method at
133:      * {@link http://workspace.pipelinersales.com/community/api/data/Methods_rest.html}
134:      * @param integer $flags flags described on
135:      * {@link http://workspace.pipelinersales.com/community/api/data/Methods_rest.html}
136:      * @param integer $sendFields whether to upload all the fields for Entity objects, or just the fields
137:      * which have been modified in code since the entity was loaded/saved
138:      * @return Response response to the HTTP request
139:      * @throws PipelinerHttpException
140:      */
141:     public function bulkUpdate($data, $flags = self::FLAG_ROLLBACK_ON_ERROR, $sendFields = self::SEND_MODIFIED_FIELDS);
142: 
143:     /**
144:      * Returns an iterator set to the offset of the query's criteria
145:      *
146:      * @param EntityCollection $collection
147:      * @return EntityCollectionIterator
148:      */
149:     public function getEntireRangeIterator(EntityCollection $collection);
150: }
151: