Document <bind> and bound parameters in the user manual
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
cfdb3cbf57
commit
fd81bb877f
2 files changed
+81
No files matched your search
Binary file not shown.
@@ -377,6 +377,72 @@ variable parsing. This sequence is |> this is not parsed or resolved
|
||||
and is different from the <exclude /> tag as exclude may be further
|
||||
parsed if output is again evaluated.
|
||||
|
||||
\section{bind}
|
||||
|
||||
Use the bind tag inside an sql tag to supply the value for a ?
|
||||
placeholder in the statement. Each bind fills the next ? in order. The
|
||||
value is escaped or checked before it reaches the server, so whatever
|
||||
it contains can never change the meaning of the statement. Use bind for
|
||||
every value that comes from a request, a cookie or a session instead of
|
||||
writing \$[name] into the statement text.
|
||||
|
||||
The bind tag has no closing tag and produces no output. It must be
|
||||
inside an sql tag, although it may be inside other tags (if, for and so
|
||||
on) within that sql tag.
|
||||
|
||||
\begin{verbatim}
|
||||
<sql>select id, name from users where email=? and status=?
|
||||
<bind value="$[email]">
|
||||
<bind value="ACTIVE">
|
||||
</sql>
|
||||
\end{verbatim}
|
||||
|
||||
The attributes are:
|
||||
|
||||
value - the value to bind. Required. Any expression or variable
|
||||
reference may be used here.
|
||||
|
||||
type - how the value is checked and sent. The values are:
|
||||
|
||||
\begin{itemize}
|
||||
\item string - the default. Quoted and escaped.
|
||||
\item int - a whole number of up to 19 digits, optionally negative.
|
||||
Sent without quotes.
|
||||
\item decimal - a number with an optional fraction, for example
|
||||
-12.50. Sent without quotes.
|
||||
\item bool - 1, true, yes, 0, false or no (any case). Sent as 1 or 0.
|
||||
\item date - YYYY-MM-DD.
|
||||
\item datetime - YYYY-MM-DD HH:MM or YYYY-MM-DD HH:MM:SS.
|
||||
\item ident - a column or table name, or a sort direction, for the
|
||||
places SQL cannot take a value (ORDER BY and so on). Requires the allow
|
||||
attribute. Names are sent in backticks; ASC and DESC are sent as they
|
||||
are.
|
||||
\end{itemize}
|
||||
|
||||
null - set to empty to send SQL NULL when the value is empty. Without
|
||||
it an empty value is sent as an empty string (and is an error for int,
|
||||
decimal, bool, date and datetime).
|
||||
|
||||
allow - for type="ident" only. A comma separated list of the values
|
||||
that are permitted. Any other value is an error.
|
||||
|
||||
\begin{verbatim}
|
||||
<sql>select * from products order by ? ?
|
||||
<bind value="$[sort]" type="ident" allow="name,price,created">
|
||||
<bind value="$[dir]" type="ident" allow="ASC,DESC">
|
||||
</sql>
|
||||
\end{verbatim}
|
||||
|
||||
A ? inside a quoted string, a backtick name or a comment in the
|
||||
statement is not a placeholder. An sql tag that contains no bind tags
|
||||
is run exactly as written, so a ? in it is left alone.
|
||||
|
||||
These are errors, and can be caught with try/catch: a value that does
|
||||
not fit its type, an ident that is not in the allow list, a bind
|
||||
outside an sql tag, a bind with no value, an unknown type, and a
|
||||
statement whose number of ? placeholders differs from its number of
|
||||
bind tags. The error text never contains the bound value itself.
|
||||
|
||||
\section{call}
|
||||
|
||||
Use the call tag to evoke an executable file from a jet script.
|
||||
@@ -570,6 +636,21 @@ As long as sql statements are executed within the same mysql
|
||||
containing tag then the same mysql session is used for each sql
|
||||
statement.
|
||||
|
||||
Values that come from a request, a cookie or a session should be
|
||||
passed with bind tags and ? placeholders rather than written into the
|
||||
statement text. See the bind tag.
|
||||
|
||||
\begin{verbatim}
|
||||
<sql>delete from cart_item where session_uuid=? and sku=?
|
||||
<bind value="$[_session_id]">
|
||||
<bind value="$[sku]">
|
||||
</sql>
|
||||
\end{verbatim}
|
||||
|
||||
A statement that changes the connection character set (SET NAMES, SET
|
||||
CHARACTER SET and similar) is refused. The connection always uses
|
||||
utf8mb4.
|
||||
|
||||
The attributes are:
|
||||
|
||||
sessionid
|
||||
|
||||
Reference in new issue
Block a user