Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Adding a doc block for notMatching
  • Loading branch information
lorenzo committed Jun 7, 2015
1 parent 60536a0 commit 30030fb
Showing 1 changed file with 50 additions and 0 deletions.
50 changes: 50 additions & 0 deletions src/ORM/Query.php
Expand Up @@ -455,6 +455,56 @@ public function innerJoinWith($assoc, callable $builder = null)
return $this;
}

/**
* Adds filtering conditions to this query to only bring rows that have no match
* to another from an associated table, based on conditions in the associated table.
*
* This function will add entries in the `contain` graph.
*
* ### Example:
*
* ```
* // Bring only articles that were not tagged with 'cake'
* $query->notMatching('Tags', function ($q) {
* return $q->where(['name' => 'cake']);
* );
* ```
*
* It is possible to filter by deep associations by using dot notation:
*
* ### Example:
*
* ```
* // Bring only articles that weren't commented by 'markstory'
* $query->notMatching('Comments.Users', function ($q) {
* return $q->where(['username' => 'markstory']);
* );
* ```
*
* As this function will create a `LEFT JOIN`, you might want to consider
* calling `distinct` on this query as you might get duplicate rows if
* your conditions don't filter them already. This might be the case, for example,
* of the same article having multiple comments.
*
* ### Example:
*
* ```
* // Bring unique articles that were commented by 'markstory'
* $query->distinct(['Articles.id'])
* ->notMatching('Comments.Users', function ($q) {
* return $q->where(['username' => 'markstory']);
* );
* ```
*
* Please note that the query passed to the closure will only accept calling
* `select`, `where`, `andWhere` and `orWhere` on it. If you wish to
* add more complex clauses you can do it directly in the main query.
*
* @param string $assoc The association to filter by
* @param callable $builder a function that will receive a pre-made query object
* that can be used to add custom conditions or selecting some fields
* @return $this
*/
public function notMatching($assoc, callable $builder = null)
{
$this->eagerLoader()->matching($assoc, $builder, [
Expand Down

0 comments on commit 30030fb

Please sign in to comment.