Completed
Pull Request — master (#329)
by
unknown
02:01
created

Field::set_help_text()   A

Complexity

Conditions 1
Paths 1

Size

Total Lines 4
Code Lines 3

Duplication

Lines 0
Ratio 0 %

Code Coverage

Tests 0
CRAP Score 2

Importance

Changes 0
Metric Value
cc 1
eloc 3
c 0
b 0
f 0
nc 1
nop 1
dl 0
loc 4
ccs 0
cts 0
cp 0
crap 2
rs 10
1
<?php
2
3
namespace Carbon_Fields\Field;
4
5
use Carbon_Fields\Carbon_Fields;
6
use Carbon_Fields\Pimple\Container as PimpleContainer;
7
use Carbon_Fields\Datastore\Datastore_Interface;
8
use Carbon_Fields\Datastore\Datastore_Holder_Interface;
9
use Carbon_Fields\Value_Set\Value_Set;
10
use Carbon_Fields\Helper\Helper;
11
use Carbon_Fields\Exception\Incorrect_Syntax_Exception;
12
13
/**
14
 * Base field class.
15
 * Defines the key container methods and their default implementations.
16
 * Implements factory design pattern.
17
 */
18
class Field implements Datastore_Holder_Interface {
19
20
	/**
21
	 * Array of field class names that have had their activation method called
22
	 *
23
	 * @var array<string>
24
	 */
25
	protected static $activated_field_types = array();
26
27
	/**
28
	 * Globally unique field identificator. Generated randomly
29
	 *
30
	 * @var string
31
	 */
32
	protected $id;
33
34
	/**
35
	 * Stores the initial <kbd>$type</kbd> variable passed to the <code>factory()</code> method
36
	 *
37
	 * @see factory
38
	 * @var string
39
	 */
40
	public $type;
41
42
	/**
43
	 * Array of ancestor field names
44
	 *
45
	 * @var array
46
	 */
47
	protected $hierarchy = array();
48
49
	/**
50
	 * Array of complex entry ids
51
	 *
52
	 * @var array
53
	 */
54
	protected $hierarchy_index = array();
55
56
	/**
57
	 * Field value
58
	 *
59
	 * @var Value_Set
60
	 */
61
	protected $value_set;
62
63
	/**
64
	 * Default field value
65
	 *
66
	 * @var mixed
67
	 */
68
	protected $default_value = '';
69
70
	/**
71
	 * Sanitized field name used as input name attribute during field render
72
	 *
73
	 * @see factory()
74
	 * @see set_name()
75
	 * @var string
76
	 */
77
	protected $name;
78
79
	/**
80
	 * Field name prefix
81
	 *
82
	 * @see set_name()
83
	 * @var string
84
	 */
85
	protected $name_prefix = '_';
86
87
	/**
88
	 * The base field name which is used in the container.
89
	 *
90
	 * @see set_base_name()
91
	 * @var string
92
	 */
93
	protected $base_name;
94
95
	/**
96
	 * Field name used as label during field render
97
	 *
98
	 * @see factory()
99
	 * @see set_label()
100
	 * @var string
101
	 */
102
	protected $label;
103
104
	/**
105
	 * Additional text containing information and guidance for the user
106
	 *
107
	 * @see help_text()
108
	 * @var string
109
	 */
110
	protected $help_text;
111
112
	/**
113
	 * Field DataStore instance to which save, load and delete calls are delegated
114
	 *
115
	 * @see set_datastore()
116
	 * @see get_datastore()
117
	 * @var Datastore_Interface
118
	 */
119
	protected $datastore;
120
121
	/**
122
	 * Flag whether the datastore is the default one or replaced with a custom one
123
	 *
124
	 * @see set_datastore()
125
	 * @see get_datastore()
126
	 * @var boolean
127
	 */
128
	protected $has_default_datastore = true;
129
130
	/**
131
	 * The type of the container this field is in
132
	 *
133
	 * @see get_context()
134
	 * @var string
135
	 */
136
	protected $context;
137
138
	/**
139
	 * Whether or not this value should be auto loaded. Applicable to theme options only.
140
	 *
141
	 * @see set_autoload()
142
	 * @var bool
143
	 */
144
	protected $autoload = false;
145
146
	/**
147
	 * Whether or not this field will be initialized when the field is in the viewport (visible).
148
	 *
149
	 * @see set_lazyload()
150
	 * @var bool
151
	 */
152
	protected $lazyload = false;
153
154
	/**
155
	 * Key-value array of attribtues and their values
156
	 *
157
	 * @var array
158
	 */
159
	protected $attributes = array();
160
161
	/**
162
	 * Array of attributes the user is allowed to change
163
	 *
164
	 * @var array<string>
165
	 */
166
	protected $allowed_attributes = array( 'max', 'maxLength', 'min', 'pattern', 'placeholder', 'readOnly', 'step', 'type' );
167
168
	/**
169
	 * The width of the field.
170
	 *
171
	 * @see set_width()
172
	 * @var int
173
	 */
174
	protected $width = 0;
175
176
	/**
177
	 * Custom CSS classes.
178
	 *
179
	 * @see set_classes()
180
	 * @var array
181
	 */
182
	protected $classes = array();
183
184
	/**
185
	 * Whether or not this field is required.
186
	 *
187
	 * @see set_required()
188
	 * @var bool
189
	 */
190
	protected $required = false;
191
192
	/**
193
	 * Stores the field conditional logic rules.
194
	 *
195
	 * @var array
196
	 */
197
	protected $conditional_logic = array();
198
199
	/**
200
	 * Whether the field should be included in the response of the requests to the REST API
201
	 *
202
	 * @see  set_visible_in_rest_api
203
	 * @see  get_visible_in_rest_api
204
	 * @var boolean
205
	 */
206
	protected $visible_in_rest_api = false;
207
208
	/**
209
	 * Clone the Value_Set object as well
210
	 *
211
	 * @var array
212
	 */
213
	public function __clone() {
214
		$this->set_value_set( clone $this->get_value_set() );
215
	}
216
217
	/**
218
	 * Create a new field of type $raw_type and name $name and label $label.
219
	 *
220
	 * @param string $raw_type
221
	 * @param string $name lower case and underscore-delimited
222
	 * @param string $label (optional) Automatically generated from $name if not present
223
	 * @return Field
224
	 */
225 15
	public static function factory( $raw_type, $name, $label = null ) {
226 15
		$type = Helper::normalize_type( $raw_type );
227
228
		// stop hidden symbol support when the end user is creating fields ][
229
		// @see Field::set_name()
230 15
		if ( ! Helper::is_valid_entity_id( $name ) ) {
231 5
			Incorrect_Syntax_Exception::raise( 'Field names can only contain lowercase alphanumeric characters, dashes and underscores ("' . $name . '" passed).' );
232
			return null;
233
		}
234
235 10
		if ( Carbon_Fields::has( $type, 'fields' ) ) {
236
			return Carbon_Fields::resolve_with_arguments( $type, array(
237
				'type' => $type,
238
				'name' => $name,
239
				'label' => $label,
240
			), 'fields' );
241
		}
242
243
		// Fallback to class name-based resolution
244 10
		$class = Helper::type_to_class( $type, __NAMESPACE__, '_Field' );
245 10 View Code Duplication
		if ( ! class_exists( $class ) ) {
246 4
			Incorrect_Syntax_Exception::raise( 'Unknown field type "' . $raw_type . '".' );
247 1
			$class = __NAMESPACE__ . '\\Broken_Field';
248 1
		}
249
250 7
		$field = new $class( $type, $name, $label );
251 7
		return $field;
252
	}
253
254
	/**
255
	 * An alias of factory().
256
	 *
257
	 * @see    Field::factory()
258
	 * @return Field
259
	 */
260 15
	public static function make() {
261 15
		return call_user_func_array( array( get_class(), 'factory' ), func_get_args() );
262
	}
263
264
	/**
265
	 * Create a field from a certain type with the specified label.
266
	 *
267
	 * @param string $type  Field type
268
	 * @param string $name  Field name
269
	 * @param string $label Field label
270
	 */
271 7
	public function __construct( $type, $name, $label ) {
272 7
		Carbon_Fields::verify_boot();
273
274 7
		$this->type = $type;
275 7
		$this->set_base_name( $name );
276 7
		$this->set_name( $name );
277 7
		$this->set_label( $label );
278
279
		// Pick random ID
280 7
		$random_string = md5( mt_rand() . $this->get_name() . $this->get_label() );
281 7
		$random_string = substr( $random_string, 0, 5 ); // 5 chars should be enough
282 7
		$this->id = 'carbon-' . $random_string;
283
284 7
		$this->init();
285 7
	}
286
287
	/**
288
	 * Returns the type of the field based on the class.
289
	 * The class is stripped by the "CarbonFields" prefix.
290
	 * Also the "Field" suffix is removed.
291
	 * Then underscores and backslashes are removed.
292
	 *
293
	 * @return string
294
	 */
295
	public function get_type() {
296
		return Helper::class_to_type( get_class( $this ), '_Field' );
297
	}
298
299
	/**
300
	 * Activate the field once the container is attached.
301
	 */
302
	public function activate() {
303
		$this->admin_init();
304
305
		add_action( 'admin_print_footer_scripts', array( get_class(), 'admin_hook_scripts' ), 5 );
306
		add_action( 'admin_print_footer_scripts', array( get_class(), 'admin_hook_styles' ), 5 );
307
		static::activate_field_type( get_class( $this ) );
308
309
		do_action( 'carbon_fields_field_activated', $this );
310
	}
311
312
	/**
313
	 * Activate a field type
314
	 *
315
	 * @param string $class_name
316
	 */
317
	public static function activate_field_type( $class_name ) {
318
		if ( in_array( $class_name, static::$activated_field_types ) ) {
319
			return;
320
		}
321
322
		add_action( 'admin_print_footer_scripts', array( $class_name, 'admin_enqueue_scripts' ), 5 );
323
		call_user_func( array( $class_name, 'field_type_activated' ) );
324
325
		static::$activated_field_types[] = $class_name;
326
	}
327
328
	/**
329
	 * Prepare the field type for use
330
	 * Called once per field type when activated
331
	 */
332
	public static function field_type_activated() {}
333
334
	/**
335
	 * Get array of hierarchy field names
336
	 *
337
	 * @return array
338
	 */
339
	public function get_hierarchy() {
340
		return $this->hierarchy;
341
	}
342
343
	/**
344
	 * Set array of hierarchy field names
345
	 *
346
	 * @return Field $this
347
	 */
348
	public function set_hierarchy( $hierarchy ) {
349
		$this->hierarchy = $hierarchy;
350
		return $this;
351
	}
352
353
	/**
354
	 * Get array of hierarchy indexes
355
	 *
356
	 * @return array
357
	 */
358
	public function get_hierarchy_index() {
359
		return $this->hierarchy_index;
360
	}
361
362
	/**
363
	 * Set array of hierarchy indexes
364
	 *
365
	 * @return Field $this
366
	 */
367
	public function set_hierarchy_index( $hierarchy_index ) {
368
		$hierarchy_index = ( ! empty( $hierarchy_index ) ) ? $hierarchy_index : array();
369
		$this->hierarchy_index = $hierarchy_index;
370
		return $this;
371
	}
372
373
	/**
374
	 * Return whether the field is a root field and holds a single value
375
	 *
376
	 * @return bool
377
	 */
378 3
	public function is_simple_root_field() {
379 3
		$hierarchy = $this->get_hierarchy();
380
		return (
381 3
			empty( $hierarchy )
382 3
			&&
383 2
			in_array( $this->get_value_set()->get_type(), array( Value_Set::TYPE_SINGLE_VALUE, Value_Set::TYPE_MULTIPLE_PROPERTIES ) )
384 3
		);
385
	}
386
387
	/**
388
	 * Perform instance initialization
389
	 */
390
	public function init() {}
391
392
	/**
393
	 * Instance initialization when in the admin area
394
	 * Called during field boot
395
	 */
396
	public function admin_init() {}
397
398
	/**
399
	 * Enqueue scripts and styles in admin
400
	 * Called once per field type
401
	 */
402
	public static function admin_enqueue_scripts() {}
403
404
	/**
405
	 * Get value from datastore
406
	 *
407
	 * @param bool $fallback_to_default
408
	 * @return mixed
409
	 */
410
	protected function get_value_from_datastore( $fallback_to_default = true ) {
411
		$value = $this->get_datastore()->load( $this );
412
413
		if ( $value === null && $fallback_to_default ) {
414
			$value = $this->get_default_value();
415
		}
416
417
		return $value;
418
	}
419
420
	/**
421
	 * Load value from datastore
422
	 */
423 2
	public function load() {
424 2
		$this->set_value( $this->get_value_from_datastore() );
425 2
	}
426
427
	/**
428
	 * Save value to storage
429
	 */
430 1
	public function save() {
431 1
		$delete_on_save = apply_filters( 'carbon_fields_should_delete_field_value_on_save', true, $this );
432 1
		if ( $delete_on_save ) {
433 1
			$this->delete();
434 1
		}
435
436 1
		$save = apply_filters( 'carbon_fields_should_save_field_value', true, $this->get_value(), $this );
437 1
		if ( $save ) {
438 1
			$this->get_datastore()->save( $this );
439 1
		}
440 1
	}
441
442
	/**
443
	 * Delete value from storage
444
	 */
445 1
	public function delete() {
446 1
		$this->get_datastore()->delete( $this );
447 1
	}
448
449
	/**
450
	 * Load the field value from an input array based on it's name
451
	 *
452
	 * @param  array $input Array of field names and values.
453
	 * @return Field $this
454
	 */
455 2
	public function set_value_from_input( $input ) {
456 2
		if ( isset( $input[ $this->get_name() ] ) ) {
457 1
			$this->set_value( $input[ $this->get_name() ] );
458 1
		} else {
459 1
			$this->clear_value();
460
		}
461 2
		return $this;
462
	}
463
464
	/**
465
	 * Return whether the datastore instance is the default one or has been overriden
466
	 *
467
	 * @return boolean
468
	 */
469
	public function has_default_datastore() {
470
		return $this->has_default_datastore;
471
	}
472
473
	/**
474
	 * Get the DataStore instance
475
	 *
476
	 * @return Datastore_Interface $datastore
477
	 */
478 1
	public function get_datastore() {
479 1
		return $this->datastore;
480
	}
481
482
	/**
483
	 * Set datastore instance
484
	 *
485
	 * @param  Datastore_Interface $datastore
486
	 * @param  boolean             $set_as_default
487
	 * @return Field               $this
488
	 */
489 1
	public function set_datastore( Datastore_Interface $datastore, $set_as_default = false ) {
490 1
		if ( $set_as_default && ! $this->has_default_datastore() ) {
491
			return $this; // datastore has been overriden with a custom one - abort changing to a default one
492
		}
493 1
		$this->datastore = $datastore;
494 1
		$this->has_default_datastore = $set_as_default;
495 1
		return $this;
496
	}
497
498
	/**
499
	 * Return the type of the container this field is in
500
	 *
501
	 * @return string
502
	 */
503
	public function get_context() {
504
		return $this->context;
505
	}
506
507
	/**
508
	 * Assign the type of the container this field is in
509
	 *
510
	 * @param  string $context
511
	 * @return Field  $this
512
	 */
513
	public function set_context( $context ) {
514
		$this->context = $context;
515
		return $this;
516
	}
517
518
	/**
519
	 * Get the Value_Set object
520
	 *
521
	 * @return Value_Set
522
	 */
523 2
	public function get_value_set() {
524 2
		if ( $this->value_set === null ) {
525 1
			$this->set_value_set( new Value_Set() );
526 1
		}
527 2
		return $this->value_set;
528
	}
529
530
	/**
531
	 * Set the Value_Set object
532
	 *
533
	 * @param  Value_Set $value_set
534
	 * @return Field     $this
535
	 */
536 1
	public function set_value_set( $value_set ) {
537 1
		$this->value_set = $value_set;
538 1
		return $this;
539
	}
540
541
	/**
542
	 * Alias for $this->get_value_set()->get(); with fallback to default value
543
	 *
544
	 * @return mixed
545
	 */
546 3
	public function get_value() {
547 3
		if ( $this->get_value_set()->get() === null ) {
548 1
			$this->set_value( $this->get_default_value() );
549 1
		}
550 3
		return $this->get_value_set()->get();
551
	}
552
553
	/**
554
	 * Alias for $this->get_value_set()->get_set(); with fallback to default value
555
	 *
556
	 * @return array<array>
557
	 */
558
	public function get_full_value() {
559
		if ( $this->get_value_set()->get_set() === null ) {
560
			$this->set_value( $this->get_default_value() );
561
		}
562
		return $this->get_value_set()->get_set();
563
	}
564
565
	/**
566
	 * Return a differently formatted value for end-users
567
	 *
568
	 * @return mixed
569
	 */
570 2
	public function get_formatted_value() {
571 2
		return $this->get_value();
572
	}
573
574
	/**
575
	 * Alias for $this->get_value_set()->set( $value );
576
	 */
577 1
	public function set_value( $value ) {
578 1
		$this->get_value_set()->set( $value );
579 1
		return $this;
580
	}
581
582
	/**
583
	 * Clear the field value to a blank one (but not the default one)
584
	 */
585
	public function clear_value() {
586
		$this->get_value_set()->clear();
587
	}
588
589
	/**
590
	 * Get default field value
591
	 *
592
	 * @return mixed
593
	 */
594 1
	public function get_default_value() {
595 1
		return $this->default_value;
596
	}
597
598
	/**
599
	 * Set default field value
600
	 *
601
	 * @param  mixed $default_value
602
	 * @return Field $this
603
	 */
604 1
	public function set_default_value( $default_value ) {
605 1
		$this->default_value = $default_value;
606 1
		return $this;
607
	}
608
609
	/**
610
	 * Return the field base name.
611
	 *
612
	 * @return string
613
	 */
614
	public function get_base_name() {
615
		return $this->base_name;
616
	}
617
618
	/**
619
	 * Set field base name as defined in the container.
620
	 *
621
	 * @return Field $this
622
	 */
623
	public function set_base_name( $name ) {
624
		$this->base_name = $name;
625
		return $this;
626
	}
627
628
	/**
629
	 * Return the field name
630
	 *
631
	 * @return string
632
	 */
633 2
	public function get_name() {
634 2
		return $this->name;
635
	}
636
637
	/**
638
	 * Set field name.
639
	 * Use only if you are completely aware of what you are doing.
640
	 *
641
	 * @param  string $name Field name, either sanitized or not
642
	 * @return Field  $this
643
	 */
644 2
	public function set_name( $name ) {
645 2
		if ( empty( $name ) ) {
646
			Incorrect_Syntax_Exception::raise( 'Field name can\'t be empty' );
647
			return $this;
648
		}
649
650
		// symbols ][ are supported in a hidden way - required for widgets to work (WP imposes dashes and square brackets on field names)
651 2
		$field_name_characters = Helper::get_field_name_characters_pattern();
1 ignored issue
show
Comprehensibility Naming introduced by
The variable name $field_name_characters exceeds the maximum configured length of 20.

Very long variable names usually make code harder to read. It is therefore recommended not to make variable names too verbose.

Loading history...
652 2
		$regex = '/\A[' . $field_name_characters . '\[\]]+\z/';
653
		if ( ! preg_match( $regex, $name ) ) {
654
			Incorrect_Syntax_Exception::raise( 'Field names  can only contain lowercase alphanumeric characters, dashes and underscores ("' . $name . '" passed).' );
655
			return $this;
656
		}
657 2
658 2
		$name_prefix = $this->get_name_prefix();
659
		$name = ( substr( $name, 0, strlen( $name_prefix ) ) !== $name_prefix ? $name_prefix . $name : $name );
660 2
661 2
		$this->name = $name;
662
		return $this;
663
	}
664
665
	/**
666
	 * Return the field name prefix
667
	 *
668
	 * @return string
669 3
	 */
670 3
	public function get_name_prefix() {
671
		return $this->name_prefix;
672
	}
673
674
	/**
675
	 * Set field name prefix
676
	 * Use only if you are completely aware of what you are doing.
677
	 *
678
	 * @param  string $name_prefix
679
	 * @return Field  $this
680 3
	 */
681 3
	public function set_name_prefix( $name_prefix ) {
682 3
		$name_prefix = strval( $name_prefix );
683 3
		$old_prefix_length = strlen( $this->name_prefix );
684 3
		$this->name_prefix = '';
685
		$this->set_name( substr( $this->get_name(), $old_prefix_length ) );
686 3
687 3
		$this->name_prefix = $name_prefix;
688 3
		$this->set_name( $this->name_prefix . $this->get_name() );
689
		return $this;
690
	}
691
692
	/**
693
	 * Return field label.
694
	 *
695
	 * @return string
696
	 */
697
	public function get_label() {
698
		return $this->label;
699
	}
700
701
	/**
702
	 * Set field label.
703
	 *
704
	 * @param  string $label If null, the label will be generated from the field name
705
	 * @return Field  $this
706
	 */
707 View Code Duplication
	public function set_label( $label ) {
0 ignored issues
show
Duplication introduced by
This method seems to be duplicated in your project.

Duplicated code is one of the most pungent code smells. If you need to duplicate the same code in three or more different places, we strongly encourage you to look into extracting the code into a single class or operation.

You can also find more detailed suggestions in the “Code” section of your repository.

Loading history...
708
		if ( is_null( $label ) ) {
709
			// Try to guess field label from it's name
710
			$label = Helper::normalize_label( $this->get_name() );
711
		}
712
713
		$this->label = $label;
714
		return $this;
715
	}
716
717
	/**
718
	 * Get a key-value array of attributes
719
	 *
720
	 * @return array
721
	 */
722
	public function get_attributes() {
723
		return $this->attributes;
724
	}
725
726
	/**
727
	 * Get an attribute value
728
	 *
729
	 * @param  string $name
730
	 * @return string
731
	 */
732
	public function get_attribute( $name ) {
733
		return isset( $this->attributes[ $name ] ) ? $this->attributes[ $name ] : '';
734
	}
735
736
	/**
737
	 * Set an attribute and its value or an array of attributes with values
738
	 *
739
	 * @param  string|array $name
740
	 * @param  string       $value
741
	 * @return Field        $this
742
	 */
743
	public function set_attribute( $name, $value = '' ) {
744
		$names = [];
745
		
746
		if ( is_array( $name ) ) {
747
			$names = $name;
748
		} else {
749
			$names[ $name ] = $value;
750
		}
751
		
752
		foreach ( $names as $name => $value ) {
753
			$is_data_attribute = substr( strtolower( $name ), 0, 5 ) === 'data-';
754
			if ( $is_data_attribute ) {
755
				$name = strtolower( $name );
756
				$name = preg_replace( '/[^a-z\-]/', '-', $name );
757
				$name = preg_replace( '/\-{2,}/', '-', $name );
758
				$name = preg_replace( '/^\-+|\-+$/', '', $name );
759
			}
760
			
761
			if ( ! $is_data_attribute && ! in_array( $name, $this->allowed_attributes ) ) {
762
				Incorrect_Syntax_Exception::raise( 'Only the following attributes are allowed: ' . implode( ', ', $this->allowed_attributes ) . ' and data-*.' );
763
				
764
				return $this;
765
			}
766
			
767
			$this->attributes[ $name ] = $value;
768
		}
769
		
770
		return $this;
771
	}
772
773
	/**
774
	 * Return the field help text
775
	 *
776
	 * @return object $this
777
	 */
778
	public function get_help_text() {
779
		return $this->help_text;
780
	}
781
782
	/**
783
	 * Set additional text to be displayed during field render,
784
	 * containing information and guidance for the user
785
	 *
786
	 * @return Field $this
787
	 */
788
	public function set_help_text( $help_text ) {
789
		$this->help_text = $help_text;
790
		return $this;
791
	}
792
793
	/**
794
	 * Alias for set_help_text()
795
	 *
796
	 * @see set_help_text()
797
	 * @return object $this
798
	 */
799
	public function help_text( $help_text ) {
800
		return $this->set_help_text( $help_text );
801
	}
802
803
	/**
804
	 * Return whether or not this value should be auto loaded.
805
	 *
806
	 * @return bool
807
	 */
808
	public function get_autoload() {
809
		return $this->autoload;
810
	}
811
812
	/**
813
	 * Whether or not this value should be auto loaded. Applicable to theme options only.
814
	 *
815
	 * @param  bool  $autoload
816
	 * @return Field $this
817
	 */
818
	public function set_autoload( $autoload ) {
819
		$this->autoload = $autoload;
820
		return $this;
821
	}
822
823
	/**
824
	 * Return whether or not this field should be lazyloaded.
825
	 *
826
	 * @return bool
827
	 */
828
	public function get_lazyload() {
829
		return $this->lazyload;
830
	}
831
832
	/**
833
	 * Whether or not this field will be initialized when the field is in the viewport (visible).
834
	 *
835
	 * @param  bool  $lazyload
836
	 * @return Field $this
837
	 */
838
	public function set_lazyload( $lazyload ) {
839
		$this->lazyload = $lazyload;
840
		return $this;
841
	}
842
843
	/**
844
	 * Get the field width.
845
	 *
846
	 * @return int $width
847
	 */
848
	public function get_width() {
849
		return $this->width;
850
	}
851
852
	/**
853
	 * Set the field width.
854
	 *
855
	 * @param  int   $width
856
	 * @return Field $this
857
	 */
858
	public function set_width( $width ) {
859
		$this->width = (int) $width;
860
		return $this;
861
	}
862
863
	/**
864
	 * Get custom CSS classes.
865
	 *
866
	 * @return array<string>
867
	 */
868
	public function get_classes() {
869
		return $this->classes;
870
	}
871
872
	/**
873
	 * Set CSS classes that the container should use.
874
	 *
875
	 * @param  string|array<string> $classes
876
	 * @return Field                $this
877
	 */
878
	public function set_classes( $classes ) {
879
		$this->classes = Helper::sanitize_classes( $classes );
880
		return $this;
881
	}
882
883
	/**
884
	 * Whether this field is mandatory for the user
885
	 *
886
	 * @param  bool  $required
887
	 * @return Field $this
888
	 */
889
	public function set_required( $required = true ) {
890
		$this->required = $required;
891
		return $this;
892
	}
893
894 1
	/**
895 1
	 * Return whether this field is mandatory for the user
896
	 *
897
	 * @return bool
898
	 */
899
	public function is_required() {
900
		return $this->required;
901
	}
902
903
	/**
904 1
	 * HTML id attribute getter.
905 1
	 * @return string
906 1
	 */
907
	public function get_id() {
908
		return $this->id;
909
	}
910
911
	/**
912
	 * HTML id attribute setter
913
	 *
914
	 * @param  string $id
915 8
	 * @return Field  $this
916 8
	 */
917 3
	public function set_id( $id ) {
918
		$this->id = $id;
919
		return $this;
920
	}
921
922
	/**
923
	 * Set the field visibility conditional logic.
924
	 *
925 3
	 * @param  array
926 3
	 * @return Field $this
927
	 */
928
	public function set_conditional_logic( $rules ) {
929
		$this->conditional_logic = $this->parse_conditional_rules( $rules );
930
		return $this;
931
	}
932
933
	/**
934
	 * Get the conditional logic rules
935
	 *
936
	 * @return array
937
	 */
938
	public function get_conditional_logic() {
939
		return $this->conditional_logic;
940
	}
941
942
	/**
943
	 * Validate and parse the conditional logic rules.
944
	 *
945
	 * @param array $rules
946
	 * @return array
947
	 */
948
	protected function parse_conditional_rules( $rules ) {
949
		if ( ! is_array( $rules ) ) {
950
			Incorrect_Syntax_Exception::raise( 'Conditional logic rules argument should be an array.' );
951
			return array();
952
		}
953
954
		$allowed_operators = array( '=', '!=', '>', '>=', '<', '<=', 'IN', 'NOT IN', 'INCLUDES', 'EXCLUDES' );
955
956
		$parsed_rules = array(
957
			'relation' => Helper::get_relation_type_from_array( $rules ),
958
			'rules' => array(),
959
		);
960
961
		foreach ( $rules as $key => $rule ) {
962
			if ( $key === 'relation' ) {
963
				continue; // Skip the relation key as it is already handled above
964
			}
965
966
			// Check if the rule is valid
967
			if ( ! is_array( $rule ) || empty( $rule['field'] ) ) {
968
				Incorrect_Syntax_Exception::raise( 'Invalid conditional logic rule format. The rule should be an array with the "field" key set.' );
969
				return array();
970
			}
971
972
			// Fill in optional keys with defaults
973
			$rule = array_merge( array(
974
				'compare' => '=',
975
				'value' => '',
976
			), $rule );
977
978 View Code Duplication
			if ( ! in_array( $rule['compare'], $allowed_operators ) ) {
979
				Incorrect_Syntax_Exception::raise( 'Invalid conditional logic compare operator: <code>' . $rule['compare'] . '</code><br>Allowed operators are: <code>' .
980
				implode( ', ', $allowed_operators ) . '</code>' );
981
				return array();
982
			}
983
984
			if ( in_array( $rule['compare'], array( 'IN', 'NOT IN' ) ) && ! is_array( $rule['value'] ) ) {
985
				Incorrect_Syntax_Exception::raise( 'Invalid conditional logic value format. An array is expected, when using the "' . $rule['compare'] . '" operator.' );
986
				return array();
987
			}
988
989
			$parsed_rules['rules'][] = $rule;
990
		}
991
992
		return $parsed_rules;
993
	}
994
995
	/**
996
	 * Set the REST visibility of the field
997
	 *
998
	 * @param  bool  $visible
999
	 * @return Field $this
1000
	 */
1001
	public function set_visible_in_rest_api( $visible = true ) {
1002
		$this->visible_in_rest_api = $visible;
1003
		return $this;
1004
	}
1005
1006
	/**
1007
	 * Get the REST visibility of the field
1008
	 *
1009
	 * @return bool
1010
	 */
1011
	public function get_visible_in_rest_api() {
1012
		return $this->visible_in_rest_api;
1013
	}
1014
1015
	/**
1016
	 * Returns an array that holds the field data, suitable for JSON representation.
1017
	 *
1018
	 * @param bool $load  Should the value be loaded from the database or use the value from the current instance.
1019
	 * @return array
1020
	 */
1021
	public function to_json( $load ) {
1022
		if ( $load ) {
1023
			$this->load();
1024
		}
1025
1026
		$field_data = array(
1027
			'id' => $this->get_id(),
1028
			'type' => $this->get_type(),
1029
			'label' => $this->get_label(),
1030
			'name' => $this->get_name(),
1031
			'base_name' => $this->get_base_name(),
1032
			'value' => $this->get_formatted_value(),
1033
			'default_value' => $this->get_default_value(),
1034
			'attributes' => (object) $this->get_attributes(),
1035
			'help_text' => $this->get_help_text(),
1036
			'context' => $this->get_context(),
1037
			'required' => $this->is_required(),
1038
			'lazyload' => $this->get_lazyload(),
1039
			'width' => $this->get_width(),
1040
			'classes' => $this->get_classes(),
1041
			'conditional_logic' => $this->get_conditional_logic(),
1042
		);
1043
1044
		return $field_data;
1045
	}
1046
1047
	/**
1048
	 * Hook administration scripts.
1049
	 */
1050
	public static function admin_hook_scripts() {
1051
		wp_enqueue_media();
1052
		wp_enqueue_script( 'thickbox' );
1053
		wp_enqueue_script( 'media-upload' );
1054
	}
1055
1056
	/**
1057
	 * Hook administration styles.
1058
	 */
1059
	public static function admin_hook_styles() {
1060
		wp_enqueue_style( 'thickbox' );
1061
	}
1062
}
1063