Skip to content

Commit eb695c6

Browse files
michalsnmichalsn
committed
Update user guide for new having clauses
1 parent 3cfecb6 commit eb695c6

1 file changed

Lines changed: 295 additions & 0 deletions

File tree

‎user_guide_src/source/database/query_builder.rst‎

Lines changed: 295 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,158 @@ setting it to FALSE.
516516

517517
Identical to having(), only separates multiple clauses with "OR".
518518

519+
**$builder->havingIn()**
520+
521+
Generates a HAVING field IN ('item', 'item') SQL query joined with AND if
522+
appropriate
523+
524+
::
525+
526+
$groups = [1, 2, 3];
527+
$builder->havingIn('group_id', $groups);
528+
// Produces: HAVING group_id IN (1, 2, 3)
529+
530+
You can use subqueries instead of an array of values.
531+
532+
::
533+
534+
$builder->havingIn('id', function(BaseBuilder $builder) {
535+
return $builder->select('user_id')->from('users_jobs')->where('group_id', 3);
536+
});
537+
// Produces: HAVING "id" IN (SELECT "user_id" FROM "users_jobs" WHERE "group_id" = 3)
538+
539+
**$builder->orHavingIn()**
540+
541+
Generates a HAVING field IN ('item', 'item') SQL query joined with OR if
542+
appropriate
543+
544+
::
545+
546+
$groups = [1, 2, 3];
547+
$builder->orHavingIn('group_id', $groups);
548+
// Produces: OR group_id IN (1, 2, 3)
549+
550+
You can use subqueries instead of an array of values.
551+
552+
::
553+
554+
$builder->orHavingIn('id', function(BaseBuilder $builder) {
555+
return $builder->select('user_id')->from('users_jobs')->where('group_id', 3);
556+
});
557+
558+
// Produces: OR "id" IN (SELECT "user_id" FROM "users_jobs" WHERE "group_id" = 3)
559+
560+
**$builder->havingNotIn()**
561+
562+
Generates a HAVING field NOT IN ('item', 'item') SQL query joined with
563+
AND if appropriate
564+
565+
::
566+
567+
$groups = [1, 2, 3];
568+
$builder->havingNotIn('group_id', $groups);
569+
// Produces: HAVING group_id NOT IN (1, 2, 3)
570+
571+
You can use subqueries instead of an array of values.
572+
573+
::
574+
575+
$builder->havingNotIn('id', function(BaseBuilder $builder) {
576+
return $builder->select('user_id')->from('users_jobs')->where('group_id', 3);
577+
});
578+
579+
// Produces: HAVING "id" NOT IN (SELECT "user_id" FROM "users_jobs" WHERE "group_id" = 3)
580+
581+
582+
**$builder->orHavingNotIn()**
583+
584+
Generates a HAVING field NOT IN ('item', 'item') SQL query joined with OR
585+
if appropriate
586+
587+
::
588+
589+
$groups = [1, 2, 3];
590+
$builder->havingNotIn('group_id', $groups);
591+
// Produces: OR group_id NOT IN (1, 2, 3)
592+
593+
You can use subqueries instead of an array of values.
594+
595+
::
596+
597+
$builder->orHavingNotIn('id', function(BaseBuilder $builder) {
598+
return $builder->select('user_id')->from('users_jobs')->where('group_id', 3);
599+
});
600+
601+
// Produces: OR "id" NOT IN (SELECT "user_id" FROM "users_jobs" WHERE "group_id" = 3)
602+
603+
**$builder->havingLike()**
604+
605+
This method enables you to generate **LIKE** clauses for HAVING part or the query, useful for doing
606+
searches.
607+
608+
.. note:: All values passed to this method are escaped automatically.
609+
610+
.. note:: All ``havingLike*`` method variations can be forced to perform case-insensitive searches by passing
611+
a fifth parameter of ``true`` to the method. This will use platform-specific features where available
612+
otherwise, will force the values to be lowercase, i.e. ``HAVING LOWER(column) LIKE '%search%'``. This
613+
may require indexes to be made for ``LOWER(column)`` instead of ``column`` to be effective.
614+
615+
#. **Simple key/value method:**
616+
617+
::
618+
619+
$builder->havingLike('title', 'match');
620+
// Produces: HAVING `title` LIKE '%match%' ESCAPE '!'
621+
622+
If you use multiple method calls they will be chained together with
623+
AND between them::
624+
625+
$builder->havingLike('title', 'match');
626+
$builder->havingLike('body', 'match');
627+
// HAVING `title` LIKE '%match%' ESCAPE '!' AND `body` LIKE '%match% ESCAPE '!'
628+
629+
If you want to control where the wildcard (%) is placed, you can use
630+
an optional third argument. Your options are 'before', 'after' and
631+
'both' (which is the default).
632+
633+
::
634+
635+
$builder->havingLike('title', 'match', 'before'); // Produces: HAVING `title` LIKE '%match' ESCAPE '!'
636+
$builder->havingLike('title', 'match', 'after'); // Produces: HAVING `title` LIKE 'match%' ESCAPE '!'
637+
$builder->havingLike('title', 'match', 'both'); // Produces: HAVING `title` LIKE '%match%' ESCAPE '!'
638+
639+
#. **Associative array method:**
640+
641+
::
642+
643+
$array = ['title' => $match, 'page1' => $match, 'page2' => $match];
644+
$builder->havingLike($array);
645+
// HAVING `title` LIKE '%match%' ESCAPE '!' AND `page1` LIKE '%match%' ESCAPE '!' AND `page2` LIKE '%match%' ESCAPE '!'
646+
647+
**$builder->orHavingLike()**
648+
649+
This method is identical to the one above, except that multiple
650+
instances are joined by OR::
651+
652+
$builder->havingLike('title', 'match'); $builder->orHavingLike('body', $match);
653+
// HAVING `title` LIKE '%match%' ESCAPE '!' OR `body` LIKE '%match%' ESCAPE '!'
654+
655+
**$builder->notHavingLike()**
656+
657+
This method is identical to ``havingLike()``, except that it generates
658+
NOT LIKE statements::
659+
660+
$builder->notHavingLike('title', 'match'); // HAVING `title` NOT LIKE '%match% ESCAPE '!'
661+
662+
**$builder->orNotHavingLike()**
663+
664+
This method is identical to ``notHavingLike()``, except that multiple
665+
instances are joined by OR::
666+
667+
$builder->havingLike('title', 'match');
668+
$builder->orNotHavingLike('body', 'match');
669+
// HAVING `title` LIKE '%match% OR `body` NOT LIKE '%match%' ESCAPE '!'
670+
519671
****************
520672
Ordering results
521673
****************
@@ -649,6 +801,26 @@ Starts a new group by adding an opening parenthesis to the WHERE clause of the q
649801

650802
Ends the current group by adding a closing parenthesis to the WHERE clause of the query.
651803

804+
**$builder->groupHavingStart()**
805+
806+
Starts a new group by adding an opening parenthesis to the HAVING clause of the query.
807+
808+
**$builder->orGroupHavingStart()**
809+
810+
Starts a new group by adding an opening parenthesis to the HAVING clause of the query, prefixing it with 'OR'.
811+
812+
**$builder->notGroupHavingStart()**
813+
814+
Starts a new group by adding an opening parenthesis to the HAVING clause of the query, prefixing it with 'NOT'.
815+
816+
**$builder->orNotGroupHavingStart()**
817+
818+
Starts a new group by adding an opening parenthesis to the HAVING clause of the query, prefixing it with 'OR NOT'.
819+
820+
**$builder->groupHavingEnd()**
821+
822+
Ends the current group by adding a closing parenthesis to the HAVING clause of the query.
823+
652824
**************
653825
Inserting Data
654826
**************
@@ -1332,6 +1504,129 @@ Class Reference
13321504

13331505
Adds a HAVING clause to a query, separating multiple calls with OR.
13341506

1507+
.. php:method:: orHavingIn([$key = NULL[, $values = NULL[, $escape = NULL]]])
1508+
1509+
:param string $key: The field to search
1510+
:param array|Closure $values: Array of target values, or anonymous function for subquery
1511+
:param bool $escape: Whether to escape values and identifiers
1512+
:returns: BaseBuilder instance
1513+
:rtype: object
1514+
1515+
Generates a HAVING field IN('item', 'item') SQL query,
1516+
joined with 'OR' if appropriate.
1517+
1518+
.. php:method:: orHavingNotIn([$key = NULL[, $values = NULL[, $escape = NULL]]])
1519+
1520+
:param string $key: The field to search
1521+
:param array|Closure $values: Array of target values, or anonymous function for subquery
1522+
:param bool $escape: Whether to escape values and identifiers
1523+
:returns: BaseBuilder instance
1524+
:rtype: object
1525+
1526+
Generates a HAVING field NOT IN('item', 'item') SQL query,
1527+
joined with 'OR' if appropriate.
1528+
1529+
.. php:method:: havingIn([$key = NULL[, $values = NULL[, $escape = NULL]]])
1530+
1531+
:param string $key: Name of field to examine
1532+
:param array|Closure $values: Array of target values, or anonymous function for subquery
1533+
:param bool $escape: Whether to escape values and identifiers
1534+
:returns: BaseBuilder instance
1535+
:rtype: object
1536+
1537+
Generates a HAVING field IN('item', 'item') SQL query,
1538+
joined with 'AND' if appropriate.
1539+
1540+
.. php:method:: havingNotIn([$key = NULL[, $values = NULL[, $escape = NULL]]])
1541+
1542+
:param string $key: Name of field to examine
1543+
:param array|Closure $values: Array of target values, or anonymous function for subquery
1544+
:param bool $escape: Whether to escape values and identifiers
1545+
:returns: BaseBuilder instance
1546+
:rtype: object
1547+
1548+
Generates a HAVING field NOT IN('item', 'item') SQL query,
1549+
joined with 'AND' if appropriate.
1550+
1551+
.. php:method:: havingLike($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
1552+
1553+
:param string $field: Field name
1554+
:param string $match: Text portion to match
1555+
:param string $side: Which side of the expression to put the '%' wildcard on
1556+
:param bool $escape: Whether to escape values and identifiers
1557+
:returns: BaseBuilder instance (method chaining)
1558+
:rtype: BaseBuilder
1559+
1560+
Adds a LIKE clause to a HAVING part of the query, separating multiple calls with AND.
1561+
1562+
.. php:method:: orHavingLike($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
1563+
1564+
:param string $field: Field name
1565+
:param string $match: Text portion to match
1566+
:param string $side: Which side of the expression to put the '%' wildcard on
1567+
:param bool $escape: Whether to escape values and identifiers
1568+
:returns: BaseBuilder instance (method chaining)
1569+
:rtype: BaseBuilder
1570+
1571+
Adds a LIKE clause to a HAVING part of the query, separating multiple class with OR.
1572+
1573+
.. php:method:: notHavingLike($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
1574+
1575+
:param string $field: Field name
1576+
:param string $match: Text portion to match
1577+
:param string $side: Which side of the expression to put the '%' wildcard on
1578+
:param bool $escape: Whether to escape values and identifiers
1579+
:returns: BaseBuilder instance (method chaining)
1580+
:rtype: BaseBuilder
1581+
1582+
Adds a NOT LIKE clause to a HAVING part of the query, separating multiple calls with AND.
1583+
1584+
.. php:method:: orNotHavingLike($field[, $match = ''[, $side = 'both'[, $escape = NULL]]])
1585+
1586+
:param string $field: Field name
1587+
:param string $match: Text portion to match
1588+
:param string $side: Which side of the expression to put the '%' wildcard on
1589+
:param bool $escape: Whether to escape values and identifiers
1590+
:returns: BaseBuilder instance (method chaining)
1591+
:rtype: BaseBuilder
1592+
1593+
Adds a NOT LIKE clause to a HAVING part of the query, separating multiple calls with OR.
1594+
1595+
.. php:method:: havingGroupStart()
1596+
1597+
:returns: BaseBuilder instance (method chaining)
1598+
:rtype: BaseBuilder
1599+
1600+
Starts a group expression for HAVING clause, using ANDs for the conditions inside it.
1601+
1602+
.. php:method:: orHavingGroupStart()
1603+
1604+
:returns: BaseBuilder instance (method chaining)
1605+
:rtype: BaseBuilder
1606+
1607+
Starts a group expression for HAVING clause, using ORs for the conditions inside it.
1608+
1609+
.. php:method:: notHavingGroupStart()
1610+
1611+
:returns: BaseBuilder instance (method chaining)
1612+
:rtype: BaseBuilder
1613+
1614+
Starts a group expression for HAVING clause, using AND NOTs for the conditions inside it.
1615+
1616+
.. php:method:: orNotHavingGroupStart()
1617+
1618+
:returns: BaseBuilder instance (method chaining)
1619+
:rtype: BaseBuilder
1620+
1621+
Starts a group expression for HAVING clause, using OR NOTs for the conditions inside it.
1622+
1623+
.. php:method:: havingGroupEnd()
1624+
1625+
:returns: BaseBuilder instance
1626+
:rtype: object
1627+
1628+
Ends a group expression for HAVING clause.
1629+
13351630
.. php:method:: groupBy($by[, $escape = NULL])
13361631
13371632
:param mixed $by: Field(s) to group by; string or array

0 commit comments

Comments
 (0)