Merge branch 'MDL-69583-master' of git://github.com/ferranrecio/moodle
[moodle.git] / admin / tool / customlang / classes / local / mlang / langstring.php
1 <?php
2 // This file is part of Moodle - http://moodle.org/
3 //
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
8 //
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 // GNU General Public License for more details.
13 //
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
17 /**
18  * Language string based on David Mudrak langstring from local_amos.
19  *
20  * @package    tool_customlang
21  * @copyright  2020 Ferran Recio <ferran@moodle.com>
22  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
23  */
25 namespace tool_customlang\local\mlang;
27 use moodle_exception;
28 use stdclass;
30 /**
31  * Class containing a lang string cleaned.
32  *
33  * @package    tool_customlang
34  * @copyright  2020 Ferran Recio <ferran@moodle.com>
35  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
36  */
38 /**
39  * Represents a single string
40  */
41 class langstring {
43     /** @var string identifier */
44     public $id = null;
46     /** @var string */
47     public $text = '';
49     /** @var int the time stamp when this string was saved */
50     public $timemodified = null;
52     /** @var bool is deleted */
53     public $deleted = false;
55     /** @var stdclass extra information about the string */
56     public $extra = null;
58     /**
59      * Class constructor.
60      *
61      * @param string $id string identifier
62      * @param string $text string text
63      * @param int $timemodified
64      * @param int $deleted
65      * @param stdclass $extra
66      */
67     public function __construct(string $id, string $text = '', int $timemodified = null,
68             int $deleted = 0, stdclass $extra = null) {
70         if (is_null($timemodified)) {
71             $timemodified = time();
72         }
73         $this->id           = $id;
74         $this->text         = $text;
75         $this->timemodified = $timemodified;
76         $this->deleted      = $deleted;
77         $this->extra        = $extra;
78     }
80     /**
81      * Given a string text, returns it being formatted properly for storing in AMOS repository.
82      *
83      * Note: This method is taken directly from local_amos as it is highly tested and robust.
84      * The Moodle 1.x part is keep on puspose to make it easier the copy paste from both codes.
85      * This could change in the future when AMOS stop suporting the 1.x langstrings.
86      *
87      * We need to know for what branch the string should be prepared due to internal changes in
88      * format required by get_string()
89      * - for get_string() in Moodle 1.6 - 1.9 use $format == 1
90      * - for get_string() in Moodle 2.0 and higher use $format == 2
91      *
92      * Typical usages of this methods:
93      *  $t = langstring::fix_syntax($t);          // sanity new translations of 2.x strings
94      *  $t = langstring::fix_syntax($t, 1);       // sanity legacy 1.x strings
95      *  $t = langstring::fix_syntax($t, 2, 1);    // convert format of 1.x strings into 2.x
96      *
97      * Backward converting 2.x format into 1.x is not supported
98      *
99      * @param string $text string text to be fixed
100      * @param int $format target get_string() format version
101      * @param int $from which format version does the text come from, defaults to the same as $format
102      * @return string
103      */
104     public static function fix_syntax(string $text, int $format = 2, ?int $from = null): string {
105         if (is_null($from)) {
106             $from = $format;
107         }
109         // Common filter.
110         $clean = trim($text);
111         $search = [
112             // Remove \r if it is part of \r\n.
113             '/\r(?=\n)/',
115             // Control characters to be replaced with \n
116             // LINE TABULATION, FORM FEED, CARRIAGE RETURN, END OF TRANSMISSION BLOCK,
117             // END OF MEDIUM, SUBSTITUTE, BREAK PERMITTED HERE, NEXT LINE, START OF STRING,
118             // STRING TERMINATOR and Unicode character categorys Zl and Zp.
119             '/[\x{0B}-\r\x{17}\x{19}\x{1A}\x{82}\x{85}\x{98}\x{9C}\p{Zl}\p{Zp}]/u',
121             // Control characters to be removed
122             // NULL, ENQUIRY, ACKNOWLEDGE, BELL, SHIFT {OUT,IN}, DATA LINK ESCAPE,
123             // DEVICE CONTROL {ONE,TWO,THREE,FOUR}, NEGATIVE ACKNOWLEDGE, SYNCHRONOUS IDLE, ESCAPE,
124             // DELETE, PADDING CHARACTER, HIGH OCTET PRESET, NO BREAK HERE, INDEX,
125             // {START,END} OF SELECTED AREA, CHARACTER TABULATION {SET,WITH JUSTIFICATION},
126             // LINE TABULATION SET, PARTIAL LINE {FORWARD,BACKWARD}, REVERSE LINE FEED,
127             // SINGLE SHIFT {TWO,THREE}, DEVICE CONTROL STRING, PRIVATE USE {ONE,TWO},
128             // SET TRANSMIT STATE, MESSAGE WAITING, {START,END} OF GUARDED AREA,
129             // {SINGLE {GRAPHIC,} CHARACTER,CONTROL SEQUENCE} INTRODUCER, OPERATING SYSTEM COMMAND,
130             // PRIVACY MESSAGE, APPLICATION PROGRAM COMMAND, ZERO WIDTH {,NO-BREAK} SPACE,
131             // REPLACEMENT CHARACTER.
132             '/[\0\x{05}-\x{07}\x{0E}-\x{16}\x{1B}\x{7F}\x{80}\x{81}\x{83}\x{84}\x{86}-\x{93}\x{95}-\x{97}\x{99}-\x{9B}\x{9D}-\x{9F}\x{200B}\x{FEFF}\x{FFFD}]++/u',
134             // Remove trailing whitespace at the end of lines in a multiline string.
135             '/[ \t]+(?=\n)/',
136         ];
137         $replace = [
138             '',
139             "\n",
140             '',
141             '',
142         ];
143         $clean = preg_replace($search, $replace, $clean);
145         if (($format === 2) && ($from === 2)) {
146             // Sanity translations of 2.x strings.
147             $clean = preg_replace("/\n{3,}/", "\n\n\n", $clean); // Collapse runs of blank lines.
149         } else if (($format === 2) && ($from === 1)) {
150             // Convert 1.x string into 2.x format.
151             $clean = preg_replace("/\n{3,}/", "\n\n\n", $clean); // Collapse runs of blank lines.
152             $clean = preg_replace('/%+/', '%', $clean); // Collapse % characters.
153             $clean = str_replace('\$', '@@@___XXX_ESCAPED_DOLLAR__@@@', $clean); // Remember for later.
154             $clean = str_replace("\\", '', $clean); // Delete all slashes.
155             $clean = preg_replace('/(^|[^{])\$a\b(\->[a-zA-Z0-9_]+)?/', '\\1{$a\\2}', $clean); // Wrap placeholders.
156             $clean = str_replace('@@@___XXX_ESCAPED_DOLLAR__@@@', '$', $clean);
157             $clean = str_replace('&#36;', '$', $clean);
159         } else if (($format === 1) && ($from === 1)) {
160             // Sanity legacy 1.x strings.
161             $clean = preg_replace("/\n{3,}/", "\n\n", $clean); // Collapse runs of blank lines.
162             $clean = str_replace('\$', '@@@___XXX_ESCAPED_DOLLAR__@@@', $clean);
163             $clean = str_replace("\\", '', $clean); // Delete all slashes.
164             $clean = str_replace('$', '\$', $clean); // Escape all embedded variables.
165             // Unescape placeholders: only $a and $a->something are allowed. All other $variables are left escaped.
166             $clean = preg_replace('/\\\\\$a\b(\->[a-zA-Z0-9_]+)?/', '$a\\1', $clean); // Unescape placeholders.
167             $clean = str_replace('@@@___XXX_ESCAPED_DOLLAR__@@@', '\$', $clean);
168             $clean = str_replace('"', "\\\"", $clean); // Add slashes for ".
169             $clean = preg_replace('/%+/', '%', $clean); // Collapse % characters.
170             $clean = str_replace('%', '%%', $clean); // Duplicate %.
172         } else {
173             throw new moodle_exception('Unknown get_string() format version');
174         }
175         return $clean;
176     }