1: <?php
2:
3: namespace ShippoClient\Http\Request\Addresses;
4:
5: use ShippoClient\Http\Request\CommonParameter;
6: use TurmericSpice\Container;
7: use TurmericSpice\Container\InvalidAttributeException;
8: use TurmericSpice\ReadWriteAttributes;
9:
10: /**
11: * Address objects are used for creating Shipment, obtaining Rates and printing Labels,
12: * and thus are one of the fundamental building blocks of the Shippo API.
13: */
14: class CreateObject extends CommonParameter
15: {
16: use ReadWriteAttributes {
17: toArray as public __toArray;
18: }
19:
20: const OBJECT_PURPOSE_QUOTE = 'QUOTE';
21: const OBJECT_PURPOSE_PURCHASE = 'PURCHASE';
22:
23: /**
24: * Quote Address can be generated by only passing selected address information.
25: * Quote Address can only be used for obtaining shipping Rate quotes
26: * and cannot be used to purchase Labels.
27: * Address that should be used for purchases must be fully entered,
28: * i.e., a complete street address with all required fields must be passed.
29: *
30: * Required
31: *
32: * @return string
33: * @throws InvalidAttributeException
34: */
35: public function getObjectPurpose()
36: {
37: $allowed = [static::OBJECT_PURPOSE_QUOTE, static::OBJECT_PURPOSE_PURCHASE];
38:
39: return $this->attributes->mustHave('object_purpose')->asString(function ($value) use ($allowed) {
40: return in_array($value, $allowed, true);
41: });
42: }
43:
44: /**
45: * First and Last Name of the addressee
46: *
47: * Required for purchase
48: *
49: * @return string
50: * @throws InvalidAttributeException
51: */
52: public function getName()
53: {
54: if ($this->getObjectPurpose() === static::OBJECT_PURPOSE_PURCHASE) {
55: return $this->attributes->mustHave('name')->asString();
56: }
57: return $this->attributes->mayHave('name')->asString();
58: }
59:
60: /**
61: * Company Name
62: *
63: * Optional
64: *
65: * @return string
66: */
67: public function getCompany()
68: {
69: return $this->attributes->mayHave('company')->asString();
70: }
71:
72: /**
73: * First street line, which is usually the street name.
74: * Note that a building's street number should be passed separately (see below).
75: *
76: * Required for purchase
77: *
78: * @return string
79: * @throws InvalidAttributeException
80: */
81: public function getStreet1()
82: {
83: if ($this->getObjectPurpose() === static::OBJECT_PURPOSE_PURCHASE) {
84: return $this->attributes->mustHave('street1')->asString();
85: }
86: return $this->attributes->mayHave('street1')->asString();
87: }
88:
89: /**
90: * Street number of the addressed building.
91: * This field can be included in street1 for all carriers except for DHL Paket (Germany).
92: *
93: * Optional
94: *
95: * @return string
96: */
97: public function getStreetNo()
98: {
99: return $this->attributes->mayHave('street_no')->asString();
100: }
101:
102: /**
103: * Second street line.
104: *
105: * Optional
106: *
107: * @return string
108: */
109: public function getStreet2()
110: {
111: return $this->attributes->mayHave('street2')->asString();
112: }
113:
114: /**
115: * Name of a city. When creating a Quote Address, sending a city is optional but will yield more accurate Rates.
116: * Please bear in mind that city names may be ambiguous (there are 34 Springfields in the US).
117: * Passing a state or a ZIP code (see below), if known, will yield more accurate results.
118: *
119: * Required for purchase
120: *
121: * @return string
122: * @throws InvalidAttributeException
123: */
124: public function getCity()
125: {
126: if ($this->getObjectPurpose() === static::OBJECT_PURPOSE_PURCHASE) {
127: return $this->attributes->mustHave('city')->asString();
128: }
129: return $this->attributes->mayHave('city')->asString();
130: }
131:
132: /**
133: * Postal code of an Address. When creating a Quote Address,
134: * sending a ZIP is optional but will yield more accurate Rates.
135: *
136: * Required for purchase
137: *
138: * @return string
139: * @throws InvalidAttributeException
140: */
141: public function getZip()
142: {
143: if ($this->getObjectPurpose() === static::OBJECT_PURPOSE_PURCHASE) {
144: return $this->attributes->mustHave('zip')->asString();
145: }
146: return $this->attributes->mayHave('zip')->asString();
147: }
148:
149: /**
150: * State values are only required for shipments from
151: * the United States and Canada(most carriers only accept two-character state abbreviations).
152: * However, to receive more accurate quotes, passing it is generally recommended.
153: *
154: * Required for purchase for some countries
155: *
156: * @return string
157: * @throws InvalidAttributeException
158: */
159: public function getState()
160: {
161: if (in_array($this->getCountry(), ['US', 'CA'], true)) {
162: return $this->attributes->mustHave('state')->asString();
163: }
164: return $this->attributes->mayHave('state')->asString();
165: }
166:
167: /**
168: * Example: 'US' or 'DE'.
169: * All accepted values can be found on the Official ISO Website(http://www.iso.org/).
170: * Sending a country is always required.
171: *
172: * Required
173: *
174: * @return string
175: * @throws InvalidAttributeException
176: */
177: public function getCountry()
178: {
179: return $this->attributes->mustHave('country')->asString(function ($country) {
180: return (bool)preg_match('/^[A-Z]{2}$/', $country);
181: });
182: }
183:
184: /**
185: * Address containing a phone number allow carriers to call the recipient when delivering the Parcel.
186: * This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.
187: *
188: * Optional for domestic, required for international
189: *
190: * @return string
191: * @throws InvalidAttributeException
192: */
193: public function getPhone()
194: {
195: return $this->attributes->mayHave('phone')->asString();
196: }
197:
198: /**
199: * E-mail address of the contact person, RFC3696/5321-compliant.
200: *
201: * Required for purchase
202: *
203: * @return string
204: * @throws InvalidAttributeException
205: */
206: public function getEmail()
207: {
208: $validation = function ($email) {
209: return filter_var($email, FILTER_VALIDATE_EMAIL);
210: };
211: if ($this->getObjectPurpose() === static::OBJECT_PURPOSE_PURCHASE) {
212: return $this->attributes->mustHave('email')->asString($validation);
213: }
214: return $this->attributes->mayHave('email')->asString($validation);
215: }
216:
217: /**
218: * Indicates whether the address provided is a residential address or not
219: *
220: * Optional
221: *
222: * @return null|bool
223: */
224: public function getIsResidential()
225: {
226: $is_residential = $this->attributes->mayHave('is_residential')->value();
227: if ($is_residential === null) {
228: return null;
229: }
230:
231: return (bool)$is_residential;
232: }
233:
234: public function toArray()
235: {
236: return array_filter($this->__toArray());
237: }
238: }
239: