Class CaseStatementExpression

Clones the inner expression objects.

Returns

Constructor.

When a value is set, the syntax generated is CASE case_value WHEN when_value ... END (simple case), where the when_value's are compared against the case_value.

When no value is set, the syntax generated is CASE WHEN when_conditions ... END (searched case), where the conditions hold the comparisons.

Note that null is a valid case value, and thus should only be passed if you actually want to create the simple case expression variant!

Parameters

Conditionally converts the passed value to an ExpressionInterface object if the type class implements the ExpressionTypeInterface. Otherwise, returns the value unmodified.

Parameters

Returns

Returns an array with the types that require values to be casted to expressions, out of the list of type names passed as parameter.

Parameters

Returns

Returns the available data for the given clause.

Available clauses

The following clause names are available:

• value: The case value for a CASE case_value WHEN ... expression.
• when: An array of WHEN ... THEN ... expressions.
• else: The ELSE result value.

Parameters

Returns

Throws

Compiles a nullable value to SQL.

Parameters

Returns

Sets the ELSE result value.

Parameters

Returns

Throws

Gets default types of current type map.

Returns

Returns the abstract type that this expression will return.

If no type has been explicitly set via setReturnType(), this method will try to obtain the type from the result types of the then() and else()calls. All types must be identical in order for this to work, otherwise the type will default to string.

Returns

See Also

Returns the existing type map.

Returns

Infers the abstract type for the given value.

Parameters

Returns

Overwrite the default type mappings for fields in the implementing object.

This method is useful if you need to set type mappings that are shared across multiple functions/expressions in a query.

To add a default without overwriting existing ones use getTypeMap()->addDefaults()

Parameters

Returns

See Also

Sets the abstract type that this expression will return.

If no type is being explicitly set via this method, then the getReturnType() method will try to infer the type from the result types of the then() and else()calls.

Parameters

Returns

Creates a new TypeMap if $typeMap is an array, otherwise exchanges it for the given one.

Parameters

Returns

Converts the Node into a SQL string fragment.

Parameters

Returns

Sets the THEN result value for the last WHEN ... THEN ... statement that was opened using when().

Order based syntax

This method can only be invoked in case when() was previously used with a value other than a closure or an instance of \Cake\Database\Expression\WhenThenExpression:

$case
    ->when(['Table.column' => true])
    ->then('Yes')
    ->when(['Table.column' => false])
    ->then('No')
    ->else('Maybe');

The following would all fail with an exception:

$case
    ->when(['Table.column' => true])
    ->when(['Table.column' => false])
    // ...

$case
    ->when(['Table.column' => true])
    ->else('Maybe')
    // ...

$case
    ->then('Yes')
    // ...

$case
    ->when(['Table.column' => true])
    ->then('Yes')
    ->then('No')
    // ...

Parameters

Returns

Throws

Iterates over each part of the expression recursively for every level of the expressions tree and executes the callback, passing as first parameter the instance of the expression currently being iterated.

Parameters

Returns

Sets the WHEN value for a WHEN ... THEN ... expression, or a self-contained expression that holds both the value for WHEN and the value for THEN.

Order based syntax

When passing a value other than a self-contained \Cake\Database\Expression\WhenThenExpression, instance, the WHEN ... THEN ... statement must be closed off with a call to then() before invoking when() again or else():

$queryExpression
    ->case($query->identifier('Table.column'))
    ->when(true)
    ->then('Yes')
    ->when(false)
    ->then('No')
    ->else('Maybe');

Self-contained expressions

When passing an instance of \Cake\Database\Expression\WhenThenExpression, being it directly, or via a callable, then there is no need to close using then() on this object, instead the statement will be closed on the \Cake\Database\Expression\WhenThenExpression object using \Cake\Database\Expression\WhenThenExpression::then().

Callables will receive an instance of \Cake\Database\Expression\WhenThenExpression, and must return one, being it the same object, or a custom one:

$queryExpression
    ->case()
    ->when(function (\Cake\Database\Expression\WhenThenExpression $whenThen) {
        return $whenThen
            ->when(['Table.column' => true])
            ->then('Yes');
    })
    ->when(function (\Cake\Database\Expression\WhenThenExpression $whenThen) {
        return $whenThen
            ->when(['Table.column' => false])
            ->then('No');
    })
    ->else('Maybe');

Type handling

The types provided via the $type argument will be merged with the type map set for this expression. When using callables for $when, the \Cake\Database\Expression\WhenThenExpression instance received by the callables will inherit that type map, however the types passed here will not be merged in case of using callables, instead the types must be passed in \Cake\Database\Expression\WhenThenExpression::when():

$queryExpression
    ->case()
    ->when(function (\Cake\Database\Expression\WhenThenExpression $whenThen) {
        return $whenThen
            ->when(['unmapped_column' => true], ['unmapped_column' => 'bool'])
            ->then('Yes');
    })
    ->when(function (\Cake\Database\Expression\WhenThenExpression $whenThen) {
        return $whenThen
            ->when(['unmapped_column' => false], ['unmapped_column' => 'bool'])
            ->then('No');
    })
    ->else('Maybe');

User data safety

When passing user data, be aware that allowing a user defined array to be passed, is a potential SQL injection vulnerability, as it allows for raw SQL to slip in!

The following is unsafe usage that must be avoided:

$case
     ->when($userData)

A safe variant for the above would be to define a single type for the value:

$case
     ->when($userData, 'integer')

This way an exception would be triggered when an array is passed for the value, thus preventing raw SQL from slipping in, and all other types of values would be forced to be bound as an integer.

Another way to safely pass user data is when using a conditions array, and passing user data only on the value side of the array entries, which will cause them to be bound:

$case
     ->when([
         'Table.column' => $userData,
     ])

Lastly, data can also be bound manually:

$query
     ->select([
         'val' => $query->newExpr()
             ->case()
             ->when($query->newExpr(':userData'))
             ->then(123)
     ])
     ->bind(':userData', $userData, 'integer')

Parameters

Returns

Throws