1: <?php
2: /**
3: * Partner API Library
4: *
5: * @copyright Copyright (c) 2020 Asseco Data Systems SA
6: * @license license.txt
7: */
8:
9: /**
10: * A basic class for all operations.
11: *
12: * This class contains some common methods and properties for all operations.
13: * All the public methods are a common interface which can be used when dealing
14: * with an actual operation.
15: *
16: * A derived class has to redefine the $_operation protected field with an actual
17: * operation name. It also has to contain a constructor which assigns proper message
18: * objects to $_input an $_output protected fields.
19: *
20: * The $_input field is not publicly accessible therefore a derived class
21: * should define methods for setting and adding input data.
22: *
23: * @package operations
24: */
25: abstract class PartnerAPIOperation {
26:
27: /**
28: * An object for communication with the Partner API WebService
29: *
30: * @var PartnerAPIService
31: */
32: protected $_service = NULL;
33:
34: /**
35: * The input message according to WSDL file.
36: *
37: * @var PartnerAPIMessage
38: */
39: protected $_input = NULL;
40:
41: /**
42: * The output message according to WSDL file.
43: *
44: * @var PartnerAPIMessage
45: */
46: protected $_output = NULL;
47:
48: /**
49: * The name of a operation.
50: *
51: * This field must be redefined in an inheriting class and contain the name
52: * of operation.
53: *
54: * @var string
55: */
56: protected $_operation = 'undefined';
57:
58: /**
59: * Sets a service object which is used for communication with Partner API WebService.
60: *
61: * Each operation have to send its data to the Partner API WebService.
62: * To do it, the operation uses a service object which contains all the
63: * necessary functionality for communication.
64: *
65: * @param PartnerAPIService $service A service object
66: */
67: public function setService(PartnerAPIService $service) {
68: $this->_service = $service;
69: $this->_input->setCredentials($service->getUserName(), $service->getPassword());
70: }
71:
72: /**
73: * Returns the service set by the setService() method.
74: *
75: * @return PartnerAPIService
76: */
77: public function getService() {
78: return $this->_service;
79: }
80:
81: /**
82: * Returns all the data stored for the operation.
83: *
84: * The returned data is the data which will be sent to the Partner API WebService.
85: * It is not necessary to call this method in any time unless you just want
86: * to check what data is beeing sent.
87: *
88: * The argument $omitNullValues tells if elements which value is NULL
89: * will be omitted.
90: *
91: * @param bool $omitNullValues
92: * @return array All the operation data
93: */
94: public function getInputDataAsArray($omitNullValues = FALSE) {
95: return $this->_input->getDataAsArray($omitNullValues);
96: }
97:
98: /**
99: * Returns all the data returned from the Partner API WebService for the operation.
100: *
101: * The returned array contains the data which was returned from the Partner API WebService.
102: *
103: * @return array All the operation's response data
104: */
105: public function getOutputDataAsArray() {
106: return $this->_output->getDataAsArray();
107: }
108:
109: /**
110: * Returns a message containing response from a service.
111: *
112: * This is an object of type derived from PartnerAPIMessage and
113: * it contains all the response returned from a service.
114: *
115: * @return PartnerAPIMessage
116: */
117: public function getResponseMessage() {
118: return $this->_output;
119: }
120:
121: /**
122: * Returns an object representing the header part of a response.
123: *
124: * This is a helper method useful when accessing the response's header.
125: *
126: * @return PartnerAPITypeResponseHeader
127: */
128: public function getResponseHeader() {
129: return $this->_output->getResponseHeader();
130: }
131:
132: /**
133: * Tells if calling an operation was successful.
134: *
135: * If not, the error part of the header have to be checked.
136: *
137: * @return bool
138: */
139: public function isSuccess() {
140: return $this->_output->getResponseHeader()->successCode == 0;
141: }
142:
143:
144: /**
145: * Returns all error of an operation.
146: *
147: * This method always returns an array. It can be empty or have one or
148: * more error objects.
149: *
150: * @return PartnerAPITypeError[]
151: */
152: public function getErrors() {
153: $errorsTab = array();
154: $errors = $this->_output->getResponseHeader()->errors;
155: if (! is_null($errors)) {
156: $errorsTab = $errors->Error;
157: if (! is_array($errorsTab))
158: $errorsTab = array($errorsTab);
159: }
160: return $errorsTab;
161: }
162:
163: /**
164: * Returns localized response time.
165: *
166: * The header part of a response contains date and time in GMT timezone.
167: * This method returns the date and time of the response converted to
168: * local timezone set for PHP interpreter.
169: *
170: * @return string Localized date and time of response
171: */
172: public function getResponseTimeLocal() {
173: return date('Y-m-d H:i:s', strtotime($this->_output->getResponseHeader()->timestamp));
174: }
175:
176: /**
177: * Sends the input data to a service.
178: *
179: * This method sends all input data, which has been previously set, to the service object.
180: * Then the output data are set with the data returned in a response.
181: * A bool value is returned and it indicates if the operation was successful.
182: *
183: * @return bool Tells if calling an operation was successful
184: */
185: public function call() {
186: $data = $this->getInputDataAsArray(TRUE);
187: $response = $this->_service->call($this->_operation, $data);
188: $this->_output->setData($response);
189: return $this->getResponseHeader()->successCode == 0;
190: }
191:
192: /**
193: * Returns an array with descriptions of errors that have occured.
194: *
195: * The returned array is an array of arrays containing the following keys:
196: * code, number, text, where code is a success code, number is a error
197: * number and text is a description of an error.
198: *
199: * @return array
200: */
201: public function getErrorTexts() {
202: if ($this->isSuccess())
203: return array();
204: require_once 'certumPartnerAPI/exceptions/errors.php';
205: $e = new PartnerAPIError();
206: return $e->getText($this->_service->getLang(), $this->getResponseHeader()->successCode, $this->getErrors());
207: }
208:
209: }
210: