Add $conf['sync_chars_regex'] comment about allowed characters (#1269)

include/config_default.inc.php

@@ -824,7 +824,40 @@ $conf['themes_dir'] = PHPWG_ROOT_PATH.'themes';
 // enable the synchronization method for adding photos
 $conf['enable_synchronization'] = true;
 
-// permitted characters for files/directories during synchronization
+// Permitted characters for files/directories during synchronization.
+// Do not add the ' U+0027 single quote apostrophe character, it WILL make some
+// SQL queries fail. URI reserved characters (see
+// https://tools.ietf.org/html/rfc3986#section-2.2 ) MAY make things fail, this
+// is known for example for the & character leading to a query parameter
+// separator if the resulting URI path is not urlencoded. Adding accented
+// characters or characters of Unicode letter or digit classes in the basic
+// plane *usually* are fine iff the file system's names *and* the config file
+// content are both UTF-8 encoded, as is the MySQL database table, and the file
+// system does not use decomposed Unicode characters for accented characters.
+//
+// Possible expressions could be:
+// * Just add the space character:
+//   $conf['sync_chars_regex'] = '/^[a-zA-Z0-9-_. ]+$/';
+// * Add space character and German umlauts and sharp s (sz) (note this is
+//   UTF-8 encoded, if you see "odd" sequences then the encoding in your viewer
+//   or editor is wrong, and maybe your file system is as well), and
+//   parentheses and brackets; also note the trailing 'u' regex option to have
+//   PHP interpret the expression as UTF-8 string instead of ASCII:
+//   $conf['sync_chars_regex'] = '/^[a-zA-Z0-9-_. äÄöÖüÜßẞ()\[\]]+$/u';
+// * Allow all Unicode letter and numeric and whitespace characters (largely
+//   encoding independent but still might have quirks with file system's file
+//   name encoding) and parentheses and brackets; again with the 'u' regex
+//   option to let PHP match Unicode characters and properties:
+//   $conf['sync_chars_regex'] = '/^[-_.\p{L}\p{N}\p{Z}()\[\]]+$/u';
+// You may try your expression at https://regex101.com/ choosing the
+// PCRE2 (PHP >=7.3) flavor.
+// See also:
+// https://www.regular-expressions.info/unicode.html
+// https://www.regular-expressions.info/php.html#preg
+// https://www.php.net/manual/en/pcre.pattern.php
+//
+// The default expression is restrictive but safe and sane ASCII only
+// alphanumeric and hyphen-minus and underscore and dot.
 $conf['sync_chars_regex'] = '/^[a-zA-Z0-9-_.]+$/';
 
 // folders name excluded during synchronization