diff --git a/reference/sqlite/functions/sqlite-register-aggregate.xml b/reference/sqlite/functions/sqlite-create-aggregate.xml similarity index 81% rename from reference/sqlite/functions/sqlite-register-aggregate.xml rename to reference/sqlite/functions/sqlite-create-aggregate.xml index b5460d35f4..d1b8174e71 100644 --- a/reference/sqlite/functions/sqlite-register-aggregate.xml +++ b/reference/sqlite/functions/sqlite-create-aggregate.xml @@ -1,13 +1,14 @@ - - + + - sqlite_register_aggregate - Register an aggregating UDF for use in SQL statements + sqlite_create_aggregate + Register an aggregating UDF for use in SQL statements + Description - boolsqlite_register_aggregate + boolsqlite_create_aggregate resourcedb stringfunction_name mixedstep_func @@ -15,7 +16,7 @@ intnum_args - sqlite_register_aggregate is similar to + sqlite_create_aggregate is similar to sqlite_create_function except that it registers functions that can be used to calculate a result aggregated across all the rows of a query. @@ -92,6 +93,14 @@ var_dump(sqlite_array_query($db, 'SELECT max_len(a) from strings')); though, we have been calculating the result as the query progressed, so we simply need to return the context value. + + + The example above will not work correctly if the column contains binary + data. Take a look at the manual page for + sqlite_udf_decode_binary for an explanation of why + this is so, and an example of how to make it respect the binary encoding. + + It is NOT recommended for you to store a copy of the values in the context @@ -101,8 +110,17 @@ var_dump(sqlite_array_query($db, 'SELECT max_len(a) from strings')); in length. + + + You can use sqlite_create_function and + sqlite_create_aggregate to override SQLite native + SQL functions. + + - See also sqlite_create_function. + See also sqlite_create_function, + sqlite_udf_encode_binary and + sqlite_udf_decode_binary. diff --git a/reference/sqlite/functions/sqlite-create-function.xml b/reference/sqlite/functions/sqlite-create-function.xml index 91ab9582fc..8d1b371741 100644 --- a/reference/sqlite/functions/sqlite-create-function.xml +++ b/reference/sqlite/functions/sqlite-create-function.xml @@ -1,5 +1,5 @@ - + sqlite_create_function @@ -90,7 +90,8 @@ $rows = sqlite_array_query($db, "SELECT php('md5', filename) from files"); For performance reasons, PHP will not automatically encode/decode binary data passed to and from your UDF's. You need to manually encode/decode the parameters and return values if you need to process binary data in - this way. + this way. Take a look at sqlite_udf_encode_binary + and sqlite_udf_decode_binary for more details. @@ -100,8 +101,15 @@ $rows = sqlite_array_query($db, "SELECT php('md5', filename) from files"); application. + + + You can use sqlite_create_function and + sqlite_create_aggregate to override SQLite native + SQL functions. + + - See also sqlite_register_aggregate. + See also sqlite_create_aggregate. diff --git a/reference/sqlite/functions/sqlite-escape-string.xml b/reference/sqlite/functions/sqlite-escape-string.xml index 710eb37bd7..22f819a61e 100644 --- a/reference/sqlite/functions/sqlite-escape-string.xml +++ b/reference/sqlite/functions/sqlite-escape-string.xml @@ -1,5 +1,5 @@ - + sqlite_escape_string @@ -39,6 +39,14 @@ when retrieving your data. + + + Do not use this function to encode the return values from UDF's created + using sqlite_create_function or + sqlite_create_aggregate - use + sqlite_udf_encode_binary instead. + + + sqlite_libencoding @@ -32,12 +32,14 @@ example), and some comparison operations may still not be carried out correctly. - - It is not recommended that you use PHP in a web-server configuration - with a version of the SQLite library compiled with UTF-8 support, since - libsqlite will abort the process if it detects a problem with the - UTF-8 encoding. - + + + It is not recommended that you use PHP in a web-server configuration + with a version of the SQLite library compiled with UTF-8 support, since + libsqlite will abort the process if it detects a problem with the + UTF-8 encoding. + + See also sqlite_libversion. diff --git a/reference/sqlite/functions/sqlite-udf-decode-binary.xml b/reference/sqlite/functions/sqlite-udf-decode-binary.xml new file mode 100644 index 0000000000..0e1f5f9cee --- /dev/null +++ b/reference/sqlite/functions/sqlite-udf-decode-binary.xml @@ -0,0 +1,98 @@ + + + + + sqlite_udf_decode_binary + Decode binary data passed as parameters to an UDF + + + Description + + stringsqlite_udf_decode_binary + stringdata + + + sqlite_udf_decode_binary decodes the binary encoding + that was applied to the parameter by either + sqlite_udf_encode_binary or + sqlite_escape_string. + + + You must call this function on parameters passed to your UDF if you need + them to handle binary data, as the binary encoding employed by PHP will + obscure the content and of the parameter in its natural, non-coded form. + + + PHP does not perform this encode/decode operation automatically as it would + severely impact performance if it did. + + + + binary-safe max_length aggregation function example + + $context) { + $context = strlen($string); + } +} + +function max_len_finalize(&$context) { + return $context; +} + +sqlite_create_aggregate($db, 'max_len', 'max_len_step', 'max_len_finalize'); + +var_dump(sqlite_array_query($db, 'SELECT max_len(a) from strings')); + +?>]]> + + + + + See also sqlite_udf_encode_binary, + sqlite_create_function and + sqlite_create_aggregate. + + + + diff --git a/reference/sqlite/functions/sqlite-udf-encode-binary.xml b/reference/sqlite/functions/sqlite-udf-encode-binary.xml new file mode 100644 index 0000000000..cca29b3e71 --- /dev/null +++ b/reference/sqlite/functions/sqlite-udf-encode-binary.xml @@ -0,0 +1,62 @@ + + + + + sqlite_udf_encode_binary + Encode binary data before returning it from an UDF + + + Description + + stringsqlite_udf_encode_binary + stringdata + + + sqlite_udf_encode_binary applies a binary encoding + to the data so that it can be safely returned from + queries (since the underlying libsqlite API is not binary safe). + + + If there is a chance that your data might be binary unsafe (eg: it + contains a NUL byte in the middle rather than at the end, or if it has and + 0x01 byte as the first character) then you must + call this function to encode the return value from your UDF. + + + PHP does not perform this encode/decode operation automatically as it would + severely impact performance if it did. + + + + Do not use sqlite_escape_string to quote strings + returned from UDF's as it will lead to double-quoting of the data. Use + this function instead! + + + + See also sqlite_udf_decode_binary, + sqlite_escape_string, + sqlite_create_function and + sqlite_create_aggregate. + + + + diff --git a/reference/sqlite/ini.xml b/reference/sqlite/ini.xml index 253ff6fb6c..e73ec21d8b 100644 --- a/reference/sqlite/ini.xml +++ b/reference/sqlite/ini.xml @@ -1,5 +1,5 @@ - +
&reftitle.runtime; &extension.runtime; @@ -18,7 +18,7 @@ sqlite.assoc_case 0 - PHP_INI_SYSTEM + PHP_INI_ALL diff --git a/reference/sqlite/reference.xml b/reference/sqlite/reference.xml index c82fe25192..41353570f0 100644 --- a/reference/sqlite/reference.xml +++ b/reference/sqlite/reference.xml @@ -1,11 +1,10 @@ - + SQLite SQLite - &warn.experimental;
&reftitle.intro;