Page MenuHomePhabricator

function qsprintf($escaper, $pattern)
Phabricator Technical Documentation (Storage)

Format an SQL query. This function behaves like sprintf, except that all the normal conversions (like "%s") will be properly escaped, and additional conversions are supported:

%nd, %ns, %nf, %nB
  "Nullable" versions of %d, %s, %f and %B. Will produce 'NULL' if the
  argument is a strict null.

%=d, %=s, %=f
  "Nullable Test" versions of %d, %s and %f. If you pass a value, you
  get "= 3"; if you pass null, you get "IS NULL". For instance, this
  will work properly if `hatID' is a nullable column and $hat is null.

    qsprintf($escaper, 'WHERE hatID %=d', $hat);

%Ld, %Ls, %Lf, %LB
  "List" versions of %d, %s, %f and %B. These are appropriate for use in
  an "IN" clause. For example:

    qsprintf($escaper, 'WHERE hatID IN (%Ld)', $list_of_hats);

%B ("Binary String")
  Escapes a string for insertion into a pure binary column, ignoring
  tests for characters outside of the basic multilingual plane.

%C, %LC, %LK ("Column", "Key Column")
  Escapes a column name or a list of column names. The "%LK" variant
  escapes a list of key column specifications which may look like

%K ("Comment")
  Escapes a comment.

%Q, %LA, %LO, %LQ, %LJ ("Query Fragment")
  Injects a query fragment from a prior call to qsprintf(). The list
  variants join a list of query fragments with AND, OR, comma, or space.

%Z ("Raw Query")
  Injects a raw, unescaped query fragment. Dangerous!

%R ("Database and Table Reference")
  Behaves like "%T.%T" and prints a full reference to a table including
  the database. Accepts a AphrontDatabaseTableRefInterface.

%P ("Password or Secret")
  Behaves like "%s", but shows "********" when the query is printed in
  logs or traces. Accepts a PhutilOpaqueEnvelope.

%~ ("Substring")
  Escapes a substring query for a LIKE (or NOT LIKE) clause. For example:

    //  Find all rows with $search as a substring of `name`.
    qsprintf($escaper, 'WHERE name LIKE %~', $search);

  See also %> and %<.

%> ("Prefix")
  Escapes a prefix query for a LIKE clause. For example:

    //  Find all rows where `name` starts with $prefix.
    qsprintf($escaper, 'WHERE name LIKE %>', $prefix);

%< ("Suffix")
  Escapes a suffix query for a LIKE clause. For example:

    //  Find all rows where `name` ends with $suffix.
    qsprintf($escaper, 'WHERE name LIKE %<', $suffix);

%T ("Table")
  Escapes a table name. In most cases, you should use "%R" instead.