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: