includes/libs/rdbms/encasing/RawSQLValue.php

   1 <?php
   2
   3 namespace Wikimedia\Rdbms;
   4
   5 /**
   6  * Raw SQL value to be used in query builders
   7  *
   8  * @note This should be used very rarely and NEVER with user input.
   9  *
  10  * @newable
  11  * @since 1.43
  12  */
  13 class RawSQLValue {
  14         private string $value = '';
  15
  16         /**
  17          * This should be used very rarely and NEVER with user input.
  18          *
  19          * Most common usecases is the value in a SET clause of UPDATE,
  20          * e.g. for updates like `total_pages = total_pages + 1`:
  21          *
  22          *   $queryBuilder->set( [ 'total_pages' => new RawSQLValue( 'total_pages + 1' ) ] )
  23          *
  24          * …or as one side of a comparison in a WHERE condition,
  25          * e.g. for conditions like `range_start = range_end`, `range_start != range_end`:
  26          *
  27          *   $queryBuilder->where( [ 'range_start' => new RawSQLValue( 'range_end' ) ] )
  28          *   $queryBuilder->where( $db->expr( 'range_start', '!=', new RawSQLValue( 'range_end' ) ) )
  29          *
  30          * (When all values are literals, consider whether using RawSQLExpression is more readable.)
  31          *
  32          * @param string $value Value (SQL fragment)
  33          * @param-taint $value exec_sql
  34          * @since 1.43
  35          */
  36         public function __construct( string $value ) {
  37                 $this->value = $value;
  38         }
  39
  40         /**
  41          * @internal to be used by rdbms library only
  42          */
  43         public function toSql(): string {
  44                 return $this->value;
  45         }
  46 }