summaryrefslogtreecommitdiffstats
path: root/core/includes/form.inc
blob: b4c6a714805f51a4ad9ca7168098b60f23ee3ef7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
<?php

/**
 * @file
 * Functions for form and batch generation and processing.
 */

use Drupal\Component\Utility\UrlHelper;
use Drupal\Core\Render\Element;
use Drupal\Core\Render\Element\RenderElement;
use Drupal\Core\Template\Attribute;
use Drupal\Core\Url;
use Symfony\Component\HttpFoundation\RedirectResponse;

/**
 * Prepares variables for select element templates.
 *
 * Default template: select.html.twig.
 *
 * It is possible to group options together; to do this, change the format of
 * $options to an associative array in which the keys are group labels, and the
 * values are associative arrays in the normal $options format.
 *
 * @param $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #title, #value, #options, #description, #extra,
 *     #multiple, #required, #name, #attributes, #size.
 */
function template_preprocess_select(&$variables) {
  $element = $variables['element'];
  Element::setAttributes($element, array('id', 'name', 'size'));
  RenderElement::setAttributes($element, array('form-select'));

  $variables['attributes'] = $element['#attributes'];
  $variables['options'] = form_select_options($element);
}

/**
 * Converts an options form element into a structured array for output.
 *
 * This function calls itself recursively to obtain the values for each optgroup
 * within the list of options and when the function encounters an object with
 * an 'options' property inside $element['#options'].
 *
 * @param array $element
 *   An associative array containing the following key-value pairs:
 *   - #multiple: Optional Boolean indicating if the user may select more than
 *     one item.
 *   - #options: An associative array of options to render as HTML. Each array
 *     value can be a string, an array, or an object with an 'option' property:
 *     - A string or integer key whose value is a translated string is
 *       interpreted as a single HTML option element. Do not use placeholders
 *       that sanitize data: doing so will lead to double-escaping. Note that
 *       the key will be visible in the HTML and could be modified by malicious
 *       users, so don't put sensitive information in it.
 *     - A translated string key whose value is an array indicates a group of
 *       options. The translated string is used as the label attribute for the
 *       optgroup. Do not use placeholders to sanitize data: doing so will lead
 *       to double-escaping. The array should contain the options you wish to
 *       group and should follow the syntax of $element['#options'].
 *     - If the function encounters a string or integer key whose value is an
 *       object with an 'option' property, the key is ignored, the contents of
 *       the option property are interpreted as $element['#options'], and the
 *       resulting HTML is added to the output.
 *   - #value: Optional integer, string, or array representing which option(s)
 *     to pre-select when the list is first displayed. The integer or string
 *     must match the key of an option in the '#options' list. If '#multiple' is
 *     TRUE, this can be an array of integers or strings.
 * @param array|null $choices
 *   (optional) Either an associative array of options in the same format as
 *   $element['#options'] above, or NULL. This parameter is only used internally
 *   and is not intended to be passed in to the initial function call.
 *
 * @return mixed[]
 *   A structured, possibly nested, array of options and optgroups for use in a
 *   select form element.
 *   - label: A translated string whose value is the text of a single HTML
 *     option element, or the label attribute for an optgroup.
 *   - options: Optional, array of options for an optgroup.
 *   - selected: A boolean that indicates whether the option is selected when
 *     rendered.
 *   - type: A string that defines the element type. The value can be 'option'
 *     or 'optgroup'.
 *   - value: A string that contains the value attribute for the option.
 */
function form_select_options($element, $choices = NULL) {
  if (!isset($choices)) {
    if (empty($element['#options'])) {
      return [];
    }
    $choices = $element['#options'];
  }
  // array_key_exists() accommodates the rare event where $element['#value'] is NULL.
  // isset() fails in this situation.
  $value_valid = isset($element['#value']) || array_key_exists('#value', $element);
  $value_is_array = $value_valid && is_array($element['#value']);
  // Check if the element is multiple select and no value has been selected.
  $empty_value = (empty($element['#value']) && !empty($element['#multiple']));
  $options = [];
  foreach ($choices as $key => $choice) {
    if (is_array($choice)) {
      $options[] = [
        'type' => 'optgroup',
        'label' => $key,
        'options' => form_select_options($element, $choice),
      ];
    }
    elseif (is_object($choice) && isset($choice->option)) {
      $options = array_merge($options, form_select_options($element, $choice->option));
    }
    else {
      $option = [];
      $key = (string) $key;
      $empty_choice = $empty_value && $key == '_none';
      if ($value_valid && ((!$value_is_array && (string) $element['#value'] === $key || ($value_is_array && in_array($key, $element['#value']))) || $empty_choice)) {
        $option['selected'] = TRUE;
      }
      else {
        $option['selected'] = FALSE;
      }
      $option['type'] = 'option';
      $option['value'] = $key;
      $option['label'] = $choice;
      $options[] = $option;
    }
  }
  return $options;
}

/**
 * Returns the indexes of a select element's options matching a given key.
 *
 * This function is useful if you need to modify the options that are
 * already in a form element; for example, to remove choices which are
 * not valid because of additional filters imposed by another module.
 * One example might be altering the choices in a taxonomy selector.
 * To correctly handle the case of a multiple hierarchy taxonomy,
 * #options arrays can now hold an array of objects, instead of a
 * direct mapping of keys to labels, so that multiple choices in the
 * selector can have the same key (and label). This makes it difficult
 * to manipulate directly, which is why this helper function exists.
 *
 * This function does not support optgroups (when the elements of the
 * #options array are themselves arrays), and will return FALSE if
 * arrays are found. The caller must either flatten/restore or
 * manually do their manipulations in this case, since returning the
 * index is not sufficient, and supporting this would make the
 * "helper" too complicated and cumbersome to be of any help.
 *
 * As usual with functions that can return array() or FALSE, do not
 * forget to use === and !== if needed.
 *
 * @param $element
 *   The select element to search.
 * @param $key
 *   The key to look for.
 *
 * @return
 *   An array of indexes that match the given $key. Array will be
 *   empty if no elements were found. FALSE if optgroups were found.
 */
function form_get_options($element, $key) {
  $keys = array();
  foreach ($element['#options'] as $index => $choice) {
    if (is_array($choice)) {
      return FALSE;
    }
    elseif (is_object($choice)) {
      if (isset($choice->option[$key])) {
        $keys[] = $index;
      }
    }
    elseif ($index == $key) {
      $keys[] = $index;
    }
  }
  return $keys;
}

/**
 * Prepares variables for fieldset element templates.
 *
 * Default template: fieldset.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #attributes, #children, #description, #id, #title,
 *     #value.
 */
function template_preprocess_fieldset(&$variables) {
  $element = $variables['element'];
  Element::setAttributes($element, array('id'));
  RenderElement::setAttributes($element);
  $variables['attributes'] = isset($element['#attributes']) ? $element['#attributes'] : array();
  $variables['prefix'] = isset($element['#field_prefix']) ? $element['#field_prefix'] : NULL;
  $variables['suffix'] = isset($element['#field_suffix']) ? $element['#field_suffix'] : NULL;
  $variables['title_display'] = isset($element['#title_display']) ? $element['#title_display'] : NULL;
  $variables['children'] = $element['#children'];
  $variables['required'] = !empty($element['#required']) ? $element['#required'] : NULL;

  if (isset($element['#title']) && $element['#title'] !== '') {
    $variables['legend']['title'] = ['#markup' => $element['#title']];
  }

  $variables['legend']['attributes'] = new Attribute();
  // Add 'visually-hidden' class to legend span.
  if ($variables['title_display'] == 'invisible') {
    $variables['legend_span']['attributes'] = new Attribute(['class' => ['visually-hidden']]);
  }
  else {
    $variables['legend_span']['attributes'] = new Attribute();
  }

  if (!empty($element['#description'])) {
    $description_id = $element['#attributes']['id'] . '--description';
    $description_attributes['id'] = $description_id;
    $variables['description']['attributes'] = new Attribute($description_attributes);
    $variables['description']['content'] = $element['#description'];

    // Add the description's id to the fieldset aria attributes.
    $variables['attributes']['aria-describedby'] = $description_id;
  }

  // Suppress error messages.
  $variables['errors'] = NULL;
}

/**
 * Prepares variables for details element templates.
 *
 * Default template: details.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #attributes, #children, #open,
 *     #description, #id, #title, #value, #optional.
 */
function template_preprocess_details(&$variables) {
  $element = $variables['element'];
  $variables['attributes'] = $element['#attributes'];
  $variables['summary_attributes'] = new Attribute();
  if (!empty($element['#title'])) {
    $variables['summary_attributes']['role'] = 'button';
    if (!empty($element['#attributes']['id'])) {
      $variables['summary_attributes']['aria-controls'] = $element['#attributes']['id'];
    }
    $variables['summary_attributes']['aria-expanded'] = !empty($element['#attributes']['open']) ? 'true' : 'false';
    $variables['summary_attributes']['aria-pressed'] = $variables['summary_attributes']['aria-expanded'];
  }
  $variables['title'] = (!empty($element['#title'])) ? $element['#title'] : '';
  $variables['description'] = (!empty($element['#description'])) ? $element['#description'] : '';
  $variables['children'] = (isset($element['#children'])) ? $element['#children'] : '';
  $variables['value'] = (isset($element['#value'])) ? $element['#value'] : '';
  $variables['required'] = !empty($element['#required']) ? $element['#required'] : NULL;

  // Suppress error messages.
  $variables['errors'] = NULL;
}

/**
 * Prepares variables for radios templates.
 *
 * Default template: radios.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #title, #value, #options, #description, #required,
 *     #attributes, #children.
 */
function template_preprocess_radios(&$variables) {
  $element = $variables['element'];
  $variables['attributes'] = array();
  if (isset($element['#id'])) {
    $variables['attributes']['id'] = $element['#id'];
  }
  if (isset($element['#attributes']['title'])) {
    $variables['attributes']['title'] = $element['#attributes']['title'];
  }
  $variables['children'] = $element['#children'];
}

/**
 * Prepares variables for checkboxes templates.
 *
 * Default template: checkboxes.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #children, #attributes.
 */
function template_preprocess_checkboxes(&$variables) {
  $element = $variables['element'];
  $variables['attributes'] = array();
  if (isset($element['#id'])) {
    $variables['attributes']['id'] = $element['#id'];
  }
  if (isset($element['#attributes']['title'])) {
    $variables['attributes']['title'] = $element['#attributes']['title'];
  }
  $variables['children'] = $element['#children'];
}

/**
 * Prepares variables for vertical tabs templates.
 *
 * Default template: vertical-tabs.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties and children of
 *     the details element. Properties used: #children.
 */
function template_preprocess_vertical_tabs(&$variables) {
  $element = $variables['element'];
  $variables['children'] = (!empty($element['#children'])) ? $element['#children'] : '';
}

/**
 * Prepares variables for input templates.
 *
 * Default template: input.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #attributes.
 */
function template_preprocess_input(&$variables) {
  $element = $variables['element'];
  // Remove name attribute if empty, for W3C compliance.
  if (isset($variables['attributes']['name']) && empty((string) $variables['attributes']['name'])) {
    unset($variables['attributes']['name']);
  }
  $variables['children'] = $element['#children'];
}

/**
 * Prepares variables for form templates.
 *
 * Default template: form.html.twig.
 *
 * @param $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #action, #method, #attributes, #children
 */
function template_preprocess_form(&$variables) {
  $element = $variables['element'];
  if (isset($element['#action'])) {
    $element['#attributes']['action'] = UrlHelper::stripDangerousProtocols($element['#action']);
  }
  Element::setAttributes($element, array('method', 'id'));
  if (empty($element['#attributes']['accept-charset'])) {
    $element['#attributes']['accept-charset'] = "UTF-8";
  }
  $variables['attributes'] = $element['#attributes'];
  $variables['children'] = $element['#children'];
}

/**
 * Prepares variables for textarea templates.
 *
 * Default template: textarea.html.twig.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #title, #value, #description, #rows, #cols,
 *     #placeholder, #required, #attributes, #resizable
 */
function template_preprocess_textarea(&$variables) {
  $element = $variables['element'];
  Element::setAttributes($element, array('id', 'name', 'rows', 'cols', 'placeholder'));
  RenderElement::setAttributes($element, array('form-textarea'));
  $variables['wrapper_attributes'] = new Attribute();
  $variables['attributes'] = new Attribute($element['#attributes']);
  $variables['value'] = $element['#value'];
  $variables['resizable'] = !empty($element['#resizable']) ? $element['#resizable'] : NULL;
  $variables['required'] = !empty($element['#required']) ? $element['#required'] : NULL;
}

/**
 * Returns HTML for a form element.
 * Prepares variables for form element templates.
 *
 * Default template: form-element.html.twig.
 *
 * In addition to the element itself, the DIV contains a label for the element
 * based on the optional #title_display property, and an optional #description.
 *
 * The optional #title_display property can have these values:
 * - before: The label is output before the element. This is the default.
 *   The label includes the #title and the required marker, if #required.
 * - after: The label is output after the element. For example, this is used
 *   for radio and checkbox #type elements. If the #title is empty but the field
 *   is #required, the label will contain only the required marker.
 * - invisible: Labels are critical for screen readers to enable them to
 *   properly navigate through forms but can be visually distracting. This
 *   property hides the label for everyone except screen readers.
 * - attribute: Set the title attribute on the element to create a tooltip
 *   but output no label element. This is supported only for checkboxes
 *   and radios in
 *   \Drupal\Core\Render\Element\CompositeFormElementTrait::preRenderCompositeFormElement().
 *   It is used where a visual label is not needed, such as a table of
 *   checkboxes where the row and column provide the context. The tooltip will
 *   include the title and required marker.
 *
 * If the #title property is not set, then the label and any required marker
 * will not be output, regardless of the #title_display or #required values.
 * This can be useful in cases such as the password_confirm element, which
 * creates children elements that have their own labels and required markers,
 * but the parent element should have neither. Use this carefully because a
 * field without an associated label can cause accessibility challenges.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #title, #title_display, #description, #id, #required,
 *     #children, #type, #name.
 */
function template_preprocess_form_element(&$variables) {
  $element = &$variables['element'];

  // This function is invoked as theme wrapper, but the rendered form element
  // may not necessarily have been processed by
  // \Drupal::formBuilder()->doBuildForm().
  $element += array(
    '#title_display' => 'before',
    '#wrapper_attributes' => array(),
    '#label_attributes' => array(),
  );
  $variables['attributes'] = $element['#wrapper_attributes'];

  // Add element #id for #type 'item'.
  if (isset($element['#markup']) && !empty($element['#id'])) {
    $variables['attributes']['id'] = $element['#id'];
  }

  // Pass elements #type and #name to template.
  if (!empty($element['#type'])) {
    $variables['type'] = $element['#type'];
  }
  if (!empty($element['#name'])) {
    $variables['name'] = $element['#name'];
  }

  // Pass elements disabled status to template.
  $variables['disabled'] = !empty($element['#attributes']['disabled']) ? $element['#attributes']['disabled'] : NULL;

  // Suppress error messages.
  $variables['errors'] = NULL;

  // If #title is not set, we don't display any label.
  if (!isset($element['#title'])) {
    $element['#title_display'] = 'none';
  }

  $variables['title_display'] = $element['#title_display'];

  $variables['prefix'] = isset($element['#field_prefix']) ? $element['#field_prefix'] : NULL;
  $variables['suffix'] = isset($element['#field_suffix']) ? $element['#field_suffix'] : NULL;

  $variables['description'] = NULL;
  if (!empty($element['#description'])) {
    $variables['description_display'] = $element['#description_display'];
    $description_attributes = [];
    if (!empty($element['#id'])) {
      $description_attributes['id'] = $element['#id'] . '--description';
    }
    $variables['description']['attributes'] = new Attribute($description_attributes);
    $variables['description']['content'] = $element['#description'];
  }

  // Add label_display and label variables to template.
  $variables['label_display'] = $element['#title_display'];
  $variables['label'] = array('#theme' => 'form_element_label');
  $variables['label'] += array_intersect_key($element, array_flip(array('#id', '#required', '#title', '#title_display')));
  $variables['label']['#attributes'] = $element['#label_attributes'];

  $variables['children'] = $element['#children'];
}

/**
 * Prepares variables for form label templates.
 *
 * Form element labels include the #title and a #required marker. The label is
 * associated with the element itself by the element #id. Labels may appear
 * before or after elements, depending on form-element.html.twig and
 * #title_display.
 *
 * This function will not be called for elements with no labels, depending on
 * #title_display. For elements that have an empty #title and are not required,
 * this function will output no label (''). For required elements that have an
 * empty #title, this will output the required marker alone within the label.
 * The label will use the #id to associate the marker with the field that is
 * required. That is especially important for screenreader users to know
 * which field is required.
 *
 * @param array $variables
 *   An associative array containing:
 *   - element: An associative array containing the properties of the element.
 *     Properties used: #required, #title, #id, #value, #description.
 */
function template_preprocess_form_element_label(&$variables) {
  $element = $variables['element'];
  // If title and required marker are both empty, output no label.
  if (isset($element['#title']) && $element['#title'] !== '') {
    $variables['title'] = ['#markup' => $element['#title']];
  }

  // Pass elements title_display to template.
  $variables['title_display'] = $element['#title_display'];

  // A #for property of a dedicated #type 'label' element as precedence.
  if (!empty($element['#for'])) {
    $variables['attributes']['for'] = $element['#for'];
    // A custom #id allows the referenced form input element to refer back to
    // the label element; e.g., in the 'aria-labelledby' attribute.
    if (!empty($element['#id'])) {
      $variables['attributes']['id'] = $element['#id'];
    }
  }
  // Otherwise, point to the #id of the form input element.
  elseif (!empty($element['#id'])) {
    $variables['attributes']['for'] = $element['#id'];
  }

  // Pass elements required to template.
  $variables['required'] = !empty($element['#required']) ? $element['#required'] : NULL;
}

/**
 * @defgroup batch Batch operations
 * @{
 * Creates and processes batch operations.
 *
 * Functions allowing forms processing to be spread out over several page
 * requests, thus ensuring that the processing does not get interrupted
 * because of a PHP timeout, while allowing the user to receive feedback
 * on the progress of the ongoing operations.
 *
 * The API is primarily designed to integrate nicely with the Form API
 * workflow, but can also be used by non-Form API scripts (like update.php)
 * or even simple page callbacks (which should probably be used sparingly).
 *
 * Example:
 * @code
 * $batch = array(
 *   'title' => t('Exporting'),
 *   'operations' => array(
 *     array('my_function_1', array($account->id(), 'story')),
 *     array('my_function_2', array()),
 *   ),
 *   'finished' => 'my_finished_callback',
 *   'file' => 'path_to_file_containing_myfunctions',
 * );
 * batch_set($batch);
 * // Only needed if not inside a form _submit handler.
 * // Setting redirect in batch_process.
 * batch_process('node/1');
 * @endcode
 *
 * Note: if the batch 'title', 'init_message', 'progress_message', or
 * 'error_message' could contain any user input, it is the responsibility of
 * the code calling batch_set() to sanitize them first with a function like
 * \Drupal\Component\Utility\Html::escape() or
 * \Drupal\Component\Utility\Xss::filter(). Furthermore, if the batch operation
 * returns any user input in the 'results' or 'message' keys of $context, it
 * must also sanitize them first.
 *
 * Sample callback_batch_operation():
 * @code
 * // Simple and artificial: load a node of a given type for a given user
 * function my_function_1($uid, $type, &$context) {
 *   // The $context array gathers batch context information about the execution (read),
 *   // as well as 'return values' for the current operation (write)
 *   // The following keys are provided :
 *   // 'results' (read / write): The array of results gathered so far by
 *   //   the batch processing, for the current operation to append its own.
 *   // 'message' (write): A text message displayed in the progress page.
 *   // The following keys allow for multi-step operations :
 *   // 'sandbox' (read / write): An array that can be freely used to
 *   //   store persistent data between iterations. It is recommended to
 *   //   use this instead of $_SESSION, which is unsafe if the user
 *   //   continues browsing in a separate window while the batch is processing.
 *   // 'finished' (write): A float number between 0 and 1 informing
 *   //   the processing engine of the completion level for the operation.
 *   //   1 (or no value explicitly set) means the operation is finished
 *   //   and the batch processing can continue to the next operation.
 *
 *   $nodes = \Drupal::entityTypeManager()->getStorage('node')
 *     ->loadByProperties(['uid' => $uid, 'type' => $type]);
 *   $node = reset($nodes);
 *   $context['results'][] = $node->id() . ' : ' . Html::escape($node->label());
 *   $context['message'] = Html::escape($node->label());
 * }
 *
 * // A more advanced example is a multi-step operation that loads all rows,
 * // five by five.
 * function my_function_2(&$context) {
 *   if (empty($context['sandbox'])) {
 *     $context['sandbox']['progress'] = 0;
 *     $context['sandbox']['current_id'] = 0;
 *     $context['sandbox']['max'] = db_query('SELECT COUNT(DISTINCT id) FROM {example}')->fetchField();
 *   }
 *   $limit = 5;
 *   $result = db_select('example')
 *     ->fields('example', array('id'))
 *     ->condition('id', $context['sandbox']['current_id'], '>')
 *     ->orderBy('id')
 *     ->range(0, $limit)
 *     ->execute();
 *   foreach ($result as $row) {
 *     $context['results'][] = $row->id . ' : ' . Html::escape($row->title);
 *     $context['sandbox']['progress']++;
 *     $context['sandbox']['current_id'] = $row->id;
 *     $context['message'] = Html::escape($row->title);
 *   }
 *   if ($context['sandbox']['progress'] != $context['sandbox']['max']) {
 *     $context['finished'] = $context['sandbox']['progress'] / $context['sandbox']['max'];
 *   }
 * }
 * @endcode
 *
 * Sample callback_batch_finished():
 * @code
 * function my_finished_callback($success, $results, $operations) {
 *   // The 'success' parameter means no fatal PHP errors were detected. All
 *   // other error management should be handled using 'results'.
 *   if ($success) {
 *     $message = \Drupal::translation()->formatPlural(count($results), 'One post processed.', '@count posts processed.');
 *   }
 *   else {
 *     $message = t('Finished with an error.');
 *   }
 *   drupal_set_message($message);
 *   // Providing data for the redirected page is done through $_SESSION.
 *   foreach ($results as $result) {
 *     $items[] = t('Loaded node %title.', array('%title' => $result));
 *   }
 *   $_SESSION['my_batch_results'] = $items;
 * }
 * @endcode
 */

/**
 * Adds a new batch.
 *
 * Batch operations are added as new batch sets. Batch sets are used to spread
 * processing (primarily, but not exclusively, forms processing) over several
 * page requests. This helps to ensure that the processing is not interrupted
 * due to PHP timeouts, while users are still able to receive feedback on the
 * progress of the ongoing operations. Combining related operations into
 * distinct batch sets provides clean code independence for each batch set,
 * ensuring that two or more batches, submitted independently, can be processed
 * without mutual interference. Each batch set may specify its own set of
 * operations and results, produce its own UI messages, and trigger its own
 * 'finished' callback. Batch sets are processed sequentially, with the progress
 * bar starting afresh for each new set.
 *
 * @param $batch_definition
 *   An associative array defining the batch, with the following elements (all
 *   are optional except as noted):
 *   - operations: (required) Array of operations to be performed, where each
 *     item is an array consisting of the name of an implementation of
 *     callback_batch_operation() and an array of parameter.
 *     Example:
 *     @code
 *     array(
 *       array('callback_batch_operation_1', array($arg1)),
 *       array('callback_batch_operation_2', array($arg2_1, $arg2_2)),
 *     )
 *     @endcode
 *   - title: A safe, translated string to use as the title for the progress
 *     page. Defaults to t('Processing').
 *   - init_message: Message displayed while the processing is initialized.
 *     Defaults to t('Initializing.').
 *   - progress_message: Message displayed while processing the batch. Available
 *     placeholders are @current, @remaining, @total, @percentage, @estimate and
 *     @elapsed. Defaults to t('Completed @current of @total.').
 *   - error_message: Message displayed if an error occurred while processing
 *     the batch. Defaults to t('An error has occurred.').
 *   - finished: Name of an implementation of callback_batch_finished(). This is
 *     executed after the batch has completed. This should be used to perform
 *     any result massaging that may be needed, and possibly save data in
 *     $_SESSION for display after final page redirection.
 *   - file: Path to the file containing the definitions of the 'operations' and
 *     'finished' functions, for instance if they don't reside in the main
 *     .module file. The path should be relative to base_path(), and thus should
 *     be built using drupal_get_path().
 *   - library: An array of batch-specific CSS and JS libraries.
 *   - url_options: options passed to the \Drupal\Core\Url object when
 *     constructing redirect URLs for the batch.
 *   - progressive: A Boolean that indicates whether or not the batch needs to
 *     run progressively. TRUE indicates that the batch will run in more than
 *     one run. FALSE (default) indicates that the batch will finish in a single
 *     run.
 *   - queue: An override of the default queue (with name and class fields
 *     optional). An array containing two elements:
 *     - name: Unique identifier for the queue.
 *     - class: The name of a class that implements
 *       \Drupal\Core\Queue\QueueInterface, including the full namespace but not
 *       starting with a backslash. It must have a constructor with two
 *       arguments: $name and a \Drupal\Core\Database\Connection object.
 *       Typically, the class will either be \Drupal\Core\Queue\Batch or
 *       \Drupal\Core\Queue\BatchMemory. Defaults to Batch if progressive is
 *       TRUE, or to BatchMemory if progressive is FALSE.
 */
function batch_set($batch_definition) {
  if ($batch_definition) {
    $batch =& batch_get();

    // Initialize the batch if needed.
    if (empty($batch)) {
      $batch = array(
        'sets' => array(),
        'has_form_submits' => FALSE,
      );
    }

    // Base and default properties for the batch set.
    $init = array(
      'sandbox' => array(),
      'results' => array(),
      'success' => FALSE,
      'start' => 0,
      'elapsed' => 0,
    );
    $defaults = array(
      'title' => t('Processing'),
      'init_message' => t('Initializing.'),
      'progress_message' => t('Completed @current of @total.'),
      'error_message' => t('An error has occurred.'),
    );
    $batch_set = $init + $batch_definition + $defaults;

    // Tweak init_message to avoid the bottom of the page flickering down after
    // init phase.
    $batch_set['init_message'] .= '<br/>&nbsp;';

    // The non-concurrent workflow of batch execution allows us to save
    // numberOfItems() queries by handling our own counter.
    $batch_set['total'] = count($batch_set['operations']);
    $batch_set['count'] = $batch_set['total'];

    // Add the set to the batch.
    if (empty($batch['id'])) {
      // The batch is not running yet. Simply add the new set.
      $batch['sets'][] = $batch_set;
    }
    else {
      // The set is being added while the batch is running. Insert the new set
      // right after the current one to ensure execution order, and store its
      // operations in a queue.
      $index = $batch['current_set'] + 1;
      $slice1 = array_slice($batch['sets'], 0, $index);
      $slice2 = array_slice($batch['sets'], $index);
      $batch['sets'] = array_merge($slice1, array($batch_set), $slice2);
      _batch_populate_queue($batch, $index);
    }
  }
}

/**
 * Processes the batch.
 *
 * This function is generally not needed in form submit handlers;
 * Form API takes care of batches that were set during form submission.
 *
 * @param \Drupal\Core\Url|string $redirect
 *   (optional) Either path or Url object to redirect to when the batch has
 *   finished processing. Note that to simply force a batch to (conditionally)
 *   redirect to a custom location after it is finished processing but to
 *   otherwise allow the standard form API batch handling to occur, it is not
 *   necessary to call batch_process() and use this parameter. Instead, make
 *   the batch 'finished' callback return an instance of
 *   \Symfony\Component\HttpFoundation\RedirectResponse, which will be used
 *   automatically by the standard batch processing pipeline (and which takes
 *   precedence over this parameter).
 * @param \Drupal\Core\Url $url
 *   (optional - should only be used for separate scripts like update.php)
 *   URL of the batch processing page.
 * @param $redirect_callback
 *   (optional) Specify a function to be called to redirect to the progressive
 *   processing page.
 *
 * @return \Symfony\Component\HttpFoundation\RedirectResponse|null
 *   A redirect response if the batch is progressive. No return value otherwise.
 */
function batch_process($redirect = NULL, Url $url = NULL, $redirect_callback = NULL) {
  $batch =& batch_get();

  if (isset($batch)) {
    // Add process information
    $process_info = array(
      'current_set' => 0,
      'progressive' => TRUE,
      'url' => isset($url) ? $url : Url::fromRoute('system.batch_page.html'),
      'source_url' => Url::fromRouteMatch(\Drupal::routeMatch()),
      'batch_redirect' => $redirect,
      'theme' => \Drupal::theme()->getActiveTheme()->getName(),
      'redirect_callback' => $redirect_callback,
    );
    $batch += $process_info;

    // The batch is now completely built. Allow other modules to make changes
    // to the batch so that it is easier to reuse batch processes in other
    // environments.
    \Drupal::moduleHandler()->alter('batch', $batch);

    // Assign an arbitrary id: don't rely on a serial column in the 'batch'
    // table, since non-progressive batches skip database storage completely.
    $batch['id'] = db_next_id();

    // Move operations to a job queue. Non-progressive batches will use a
    // memory-based queue.
    foreach ($batch['sets'] as $key => $batch_set) {
      _batch_populate_queue($batch, $key);
    }

    // Initiate processing.
    if ($batch['progressive']) {
      // Now that we have a batch id, we can generate the redirection link in
      // the generic error message.
      /** @var \Drupal\Core\Url $batch_url */
      $batch_url = $batch['url'];
      /** @var \Drupal\Core\Url $error_url */
      $error_url = clone $batch_url;
      $query_options = $error_url->getOption('query');
      $query_options['id'] = $batch['id'];
      $query_options['op'] = 'finished';
      $error_url->setOption('query', $query_options);

      $batch['error_message'] = t('Please continue to <a href=":error_url">the error page</a>', array(':error_url' => $error_url->toString(TRUE)->getGeneratedUrl()));

      // Clear the way for the redirection to the batch processing page, by
      // saving and unsetting the 'destination', if there is any.
      $request = \Drupal::request();
      if ($request->query->has('destination')) {
        $batch['destination'] = $request->query->get('destination');
        $request->query->remove('destination');
      }

      // Store the batch.
      \Drupal::service('batch.storage')->create($batch);

      // Set the batch number in the session to guarantee that it will stay alive.
      $_SESSION['batches'][$batch['id']] = TRUE;

      // Redirect for processing.
      $query_options = $error_url->getOption('query');
      $query_options['op'] = 'start';
      $query_options['id'] = $batch['id'];
      $batch_url->setOption('query', $query_options);
      if (($function = $batch['redirect_callback']) && function_exists($function)) {
        $function($batch_url->toString(), ['query' => $query_options]);
      }
      else {
        return new RedirectResponse($batch_url->setAbsolute()->toString(TRUE)->getGeneratedUrl());
      }
    }
    else {
      // Non-progressive execution: bypass the whole progressbar workflow
      // and execute the batch in one pass.
      require_once __DIR__ . '/batch.inc';
      _batch_process();
    }
  }
}

/**
 * Retrieves the current batch.
 */
function &batch_get() {
  // Not drupal_static(), because Batch API operates at a lower level than most
  // use-cases for resetting static variables, and we specifically do not want a
  // global drupal_static_reset() resetting the batch information. Functions
  // that are part of the Batch API and need to reset the batch information may
  // call batch_get() and manipulate the result by reference. Functions that are
  // not part of the Batch API can also do this, but shouldn't.
  static $batch = array();
  return $batch;
}

/**
 * Populates a job queue with the operations of a batch set.
 *
 * Depending on whether the batch is progressive or not, the
 * Drupal\Core\Queue\Batch or Drupal\Core\Queue\BatchMemory handler classes will
 * be used. The name and class of the queue are added by reference to the
 * batch set.
 *
 * @param $batch
 *   The batch array.
 * @param $set_id
 *   The id of the set to process.
 */
function _batch_populate_queue(&$batch, $set_id) {
  $batch_set = &$batch['sets'][$set_id];

  if (isset($batch_set['operations'])) {
    $batch_set += array(
      'queue' => array(
        'name' => 'drupal_batch:' . $batch['id'] . ':' . $set_id,
        'class' => $batch['progressive'] ? 'Drupal\Core\Queue\Batch' : 'Drupal\Core\Queue\BatchMemory',
      ),
    );

    $queue = _batch_queue($batch_set);
    $queue->createQueue();
    foreach ($batch_set['operations'] as $operation) {
      $queue->createItem($operation);
    }

    unset($batch_set['operations']);
  }
}

/**
 * Returns a queue object for a batch set.
 *
 * @param $batch_set
 *   The batch set.
 *
 * @return
 *   The queue object.
 */
function _batch_queue($batch_set) {
  static $queues;

  if (!isset($queues)) {
    $queues = array();
  }

  if (isset($batch_set['queue'])) {
    $name = $batch_set['queue']['name'];
    $class = $batch_set['queue']['class'];

    if (!isset($queues[$class][$name])) {
      $queues[$class][$name] = new $class($name, \Drupal::database());
    }
    return $queues[$class][$name];
  }
}

/**
 * @} End of "defgroup batch".
 */