Cleanup phpdoc comments
[civicrm-core.git] / CRM / Utils / Address.php
CommitLineData
6a488035
TO
1<?php
2/*
3 +--------------------------------------------------------------------+
06b69b18 4 | CiviCRM version 4.5 |
6a488035 5 +--------------------------------------------------------------------+
06b69b18 6 | Copyright CiviCRM LLC (c) 2004-2014 |
6a488035
TO
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
9 | |
10 | CiviCRM is free software; you can copy, modify, and distribute it |
11 | under the terms of the GNU Affero General Public License |
12 | Version 3, 19 November 2007 and the CiviCRM Licensing Exception. |
13 | |
14 | CiviCRM is distributed in the hope that it will be useful, but |
15 | WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
17 | See the GNU Affero General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Affero General Public |
20 | License and the CiviCRM Licensing Exception along |
21 | with this program; if not, contact CiviCRM LLC |
22 | at info[AT]civicrm[DOT]org. If you have questions about the |
23 | GNU Affero General Public License or the licensing of CiviCRM, |
24 | see the CiviCRM license FAQ at http://civicrm.org/licensing |
25 +--------------------------------------------------------------------+
26*/
27
28/**
29 * Address utilties
30 *
31 * @package CRM
32 */
33class CRM_Utils_Address {
34
35 /**
100fef9d 36 * Format an address string from address fields and a format string
6a488035
TO
37 *
38 * Format an address basing on the address fields provided.
39 * Use Setting's address_format if there's no format specified.
40 *
f4aaa82a
EM
41 * @param array $fields the address fields
42 * @param string $format the desired address format
43 * @param boolean $microformat if true indicates, the address to be built in hcard-microformat standard.
44 * @param boolean $mailing if true indicates, the call has been made from mailing label
45 * @param boolean $individualFormat if true indicates, the call has been made for the contact of type 'individual'
46 *
47 * @param null $tokenFields
6a488035
TO
48 *
49 * @return string formatted address string
50 *
51 * @static
52 */
53 static function format(
54 $fields,
55 $format = NULL,
56 $microformat = FALSE,
57 $mailing = FALSE,
58 $individualFormat = FALSE,
59 $tokenFields = NULL
60 ) {
61 static $config = NULL;
62
63 if (!$format) {
64 $format =
65 CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'address_format');
66 }
67
68 if ($mailing) {
69 $format =
70 CRM_Core_BAO_Setting::getItem(CRM_Core_BAO_Setting::SYSTEM_PREFERENCES_NAME, 'mailing_format');
71 }
72
73 $formatted = $format;
74
75 $fullPostalCode = CRM_Utils_Array::value('postal_code', $fields);
76 if (!empty($fields['postal_code_suffix'])) {
77 $fullPostalCode .= "-$fields[postal_code_suffix]";
78 }
79
80 // make sure that some of the fields do have values
81 $emptyFields = array(
82 'supplemental_address_1',
83 'supplemental_address_2',
84 'state_province_name',
85 'county',
86 );
87 foreach ($emptyFields as $f) {
88 if (!isset($fields[$f])) {
89 $fields[$f] = NULL;
90 }
91 }
92
93 $contactName = CRM_Utils_Array::value('display_name', $fields);
94 if (!$individualFormat) {
95 if (isset($fields['id'])) {
96 $type = CRM_Contact_BAO_Contact::getContactType($fields['id']);
97 }
98 else {
99 $type = 'Individual';
100 }
101
102 if ($type == 'Individual') {
103 $contactName = CRM_Utils_Array::value('addressee_display', $fields);
104 }
105 }
106
107 if (!$microformat) {
108 // replacements in case of Individual Name Format
109 $replacements = array(
110 'contact.display_name' => CRM_Utils_Array::value('display_name', $fields),
111 'contact.individual_prefix' => CRM_Utils_Array::value('individual_prefix', $fields),
e171748b 112 'contact.formal_title' => CRM_Utils_Array::value('formal_title', $fields),
6a488035
TO
113 'contact.first_name' => CRM_Utils_Array::value('first_name', $fields),
114 'contact.middle_name' => CRM_Utils_Array::value('middle_name', $fields),
115 'contact.last_name' => CRM_Utils_Array::value('last_name', $fields),
116 'contact.individual_suffix' => CRM_Utils_Array::value('individual_suffix', $fields),
117 'contact.address_name' => CRM_Utils_Array::value('address_name', $fields),
118 'contact.street_address' => CRM_Utils_Array::value('street_address', $fields),
119 'contact.supplemental_address_1' => CRM_Utils_Array::value('supplemental_address_1', $fields),
120 'contact.supplemental_address_2' => CRM_Utils_Array::value('supplemental_address_2', $fields),
121 'contact.city' => CRM_Utils_Array::value('city', $fields),
122 'contact.state_province_name' => CRM_Utils_Array::value('state_province_name', $fields),
123 'contact.county' => CRM_Utils_Array::value('county', $fields),
124 'contact.state_province' => CRM_Utils_Array::value('state_province', $fields),
125 'contact.postal_code' => $fullPostalCode,
126 'contact.country' => CRM_Utils_Array::value('country', $fields),
127 'contact.world_region' => CRM_Utils_Array::value('world_region', $fields),
128 'contact.geo_code_1' => CRM_Utils_Array::value('geo_code_1', $fields),
129 'contact.geo_code_2' => CRM_Utils_Array::value('geo_code_2', $fields),
130 'contact.current_employer' => CRM_Utils_Array::value('current_employer', $fields),
131 'contact.nick_name' => CRM_Utils_Array::value('nick_name', $fields),
132 'contact.email' => CRM_Utils_Array::value('email', $fields),
133 'contact.im' => CRM_Utils_Array::value('im', $fields),
134 'contact.do_not_email' => CRM_Utils_Array::value('do_not_email', $fields),
135 'contact.do_not_phone' => CRM_Utils_Array::value('do_not_phone', $fields),
136 'contact.do_not_mail' => CRM_Utils_Array::value('do_not_mail', $fields),
137 'contact.do_not_sms' => CRM_Utils_Array::value('do_not_sms', $fields),
138 'contact.do_not_trade' => CRM_Utils_Array::value('do_not_trade', $fields),
139 'contact.job_title' => CRM_Utils_Array::value('job_title', $fields),
140 'contact.birth_date' => CRM_Utils_Array::value('birth_date', $fields),
141 'contact.gender' => CRM_Utils_Array::value('gender', $fields),
142 'contact.is_opt_out' => CRM_Utils_Array::value('is_opt_out', $fields),
143 'contact.home_URL' => CRM_Utils_Array::value('home_URL', $fields),
144 'contact.preferred_mail_format' => CRM_Utils_Array::value('preferred_mail_format', $fields),
145 'contact.phone' => CRM_Utils_Array::value('phone', $fields),
146 'contact.home_URL' => CRM_Utils_Array::value('home_URL', $fields),
147 'contact.contact_source' => CRM_Utils_Array::value('contact_source', $fields),
148 'contact.external_identifier' => CRM_Utils_Array::value('external_identifier', $fields),
149 'contact.contact_id' => CRM_Utils_Array::value('id', $fields),
150 'contact.household_name' => CRM_Utils_Array::value('display_name', $fields),
151 'contact.organization_name' => CRM_Utils_Array::value('display_name', $fields),
152 'contact.legal_name' => CRM_Utils_Array::value('legal_name', $fields),
153 'contact.preferred_communication_method' => CRM_Utils_Array::value('preferred_communication_method', $fields),
aa62b355 154 'contact.communication_style' => CRM_Utils_Array::value('communication_style', $fields),
6a488035
TO
155 'contact.addressee' => CRM_Utils_Array::value('addressee_display', $fields),
156 'contact.email_greeting' => CRM_Utils_Array::value('email_greeting_display', $fields),
157 'contact.postal_greeting' => CRM_Utils_Array::value('postal_greeting_display', $fields),
158 );
159 }
160 else {
161 $replacements = array(
162 'contact.address_name' => "<span class=\"address-name\">" . $fields['address_name'] . "</span>",
163 'contact.street_address' => "<span class=\"street-address\">" . $fields['street_address'] . "</span>",
164 'contact.supplemental_address_1' => "<span class=\"extended-address\">" . $fields['supplemental_address_1'] . "</span>",
165 'contact.supplemental_address_2' => $fields['supplemental_address_2'],
166 'contact.city' => "<span class=\"locality\">" . $fields['city'] . "</span>",
167 'contact.state_province_name' => "<span class=\"region\">" . $fields['state_province_name'] . "</span>",
168 'contact.county' => "<span class=\"region\">" . $fields['county'],
169 'contact.state_province' => "<span class=\"region\">" . $fields['state_province'] . "</span>",
170 'contact.postal_code' => "<span class=\"postal-code\">" . $fullPostalCode . "</span>",
171 'contact.country' => "<span class=\"country-name\">" . $fields['country'] . "</span>",
172 'contact.world_region' => "<span class=\"region\">" . $fields['world_region'] . "</span>",
173 );
174
175 // erase all empty ones, so we dont get blank lines
176 foreach (array_keys($replacements) as $key) {
177 $exactKey = substr($key, 0, 8) == 'contact.' ? substr($key, 8) : $key;
178 if ($key != 'contact.postal_code' &&
179 CRM_Utils_Array::value($exactKey, $fields) == NULL
180 ) {
181 $replacements[$key] = '';
182 }
183 }
184 if (empty($fullPostalCode)) {
185 $replacements['contact.postal_code'] = '';
186 }
187 }
188
189 // replacements in case of Custom Token
190 if (stristr($formatted, 'custom_')) {
191 $customToken = array_keys($fields);
192 foreach ($customToken as $value) {
193 if (substr($value, 0, 7) == 'custom_') {
194 $replacements["contact.{$value}"] = $fields["{$value}"];
195 }
196 }
197 }
198
199 // also sub all token fields
200 if ($tokenFields) {
201 foreach ($tokenFields as $token) {
202 $replacements["{$token}"] = CRM_Utils_Array::value("{$token}", $fields);
203 }
204 }
205
206 // for every token, replace {fooTOKENbar} with fooVALUEbar if
207 // the value is not empty, otherwise drop the whole {fooTOKENbar}
208 foreach ($replacements as $token => $value) {
785374a6 209 if ($value && is_string($value) || is_numeric($value)) {
6a488035
TO
210 $formatted = preg_replace("/{([^{}]*)\b{$token}\b([^{}]*)}/u", "\${1}{$value}\${2}", $formatted);
211 }
212 else {
213 $formatted = preg_replace("/{[^{}]*\b{$token}\b[^{}]*}/u", '', $formatted);
214 }
215 }
216
217 // drop any {...} constructs from lines' ends
218 if (!$microformat) {
219 $formatted = "\n$formatted\n";
220 }
221 else {
222 if ($microformat == 1) {
223 $formatted = "\n<div class=\"location vcard\"><span class=\"adr\">\n$formatted</span></div>\n";
224 }
225 else {
226 $formatted = "\n<div class=\"vcard\"><span class=\"adr\">$formatted</span></div>\n";
227 }
228 }
229
230 $formatted = preg_replace('/\n{[^{}]*}/u', "\n", $formatted);
231 $formatted = preg_replace('/{[^{}]*}\n/u', "\n", $formatted);
232
233 // if there are any 'sibling' {...} constructs, replace them with the
234 // contents of the first one; for example, when there's no state_province:
235 // 1. {city}{, }{state_province}{ }{postal_code}
236 // 2. San Francisco{, }{ }12345
237 // 3. San Francisco, 12345
238 $formatted = preg_replace('/{([^{}]*)}({[^{}]*})+/u', '\1', $formatted);
239
240 // drop any remaining curly braces leaving their contents
241 $formatted = str_replace(array('{', '}'), '', $formatted);
242
243 // drop any empty lines left after the replacements
244 $formatted = preg_replace('/^[ \t]*[\r\n]+/m', '', $formatted);
245
246 if (!$microformat) {
247 $finalFormatted = $formatted;
248 }
249 else {
250 // remove \n from each line and only add at the end
251 // this hack solves formatting issue, when we convert nl2br
252 $lines = array();
253 $count = 1;
254 $finalFormatted = NULL;
255 $formattedArray = explode("\n", $formatted);
256 $formattedArray = array_filter($formattedArray);
257
258 foreach ($formattedArray as $line) {
259 $line = trim($line);
260 if ($line) {
261 if ($count > 1 && $count < count($formattedArray)) {
262 $line = "$line\n";
263 }
264 $finalFormatted .= $line;
265 $count++;
266 }
267 }
268 }
269 return $finalFormatted;
270 }
271
5bc392e6
EM
272 /**
273 * @param $format
274 *
275 * @return array
276 */
6a488035
TO
277 static function sequence($format) {
278 // also compute and store the address sequence
279 $addressSequence = array(
280 'address_name',
281 'street_address',
282 'supplemental_address_1',
283 'supplemental_address_2',
284 'city',
285 'county',
286 'state_province',
287 'postal_code',
288 'country',
289 );
290
291 // get the field sequence from the format
292 $newSequence = array();
293 foreach ($addressSequence as $field) {
294 if (substr_count($format, $field)) {
295 $newSequence[strpos($format, $field)] = $field;
296 }
297 }
298 ksort($newSequence);
299
300 // add the addressSequence fields that are missing in the addressFormat
301 // to the end of the list, so that (for example) if state_province is not
302 // specified in the addressFormat it's still in the address-editing form
303 $newSequence = array_merge($newSequence, $addressSequence);
304 $newSequence = array_unique($newSequence);
305 return $newSequence;
306 }
307}
308