Feature. QueryBuilder. Query union.

[iRedds]

Description
This is the second attempt to add a query union to QueryBuilder.
Ref #4291

The implementation provides two methods:

• BaseBuilder::union(BaseBuilder|Closure $union)
• BaseBuilder::unionAll(BaseBuilder|Closure $union)

The union() method can be called in any order relative to the main query, but the union query will always be appended to the end. That is, the LIMIT or ORDER BY clauses will be relative to the main query.

$builder->union($union)->limit(1)->orderBy('id');
// SELECT * FROM table LIMIT 1 ORDER BY id UNION query

Since DBMSs (MSSQL and Oracle) are demanding on queries using LIMIT and ORDER BY, when generating SQL, all queries are wrapped in a SELECT * FROM(....) alias query.
The alias uwrp0 is used for the main query. Each subsequent query will have an alias with index +1.

$builder->union($union)->limit(1)->orderBy('id')->unionAll($union2);
// SELECT * (SELECT * FROM table LIMIT 1 ORDER BY id) uwrp0 
// UNION SELECT * FROM (query) uwrp1 
// UNION ALL SELECT * FROM (query2) uwrp2

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[iRedds]

I don't think replacing assertEquals() with assertSame() is the correct behavior for checking code style.

[kenjis]

With this PR, I understand we can't write a query to use an ORDER BY or LIMIT clause to sort or limit the entire UNION result like the following. Am I correct?

(SELECT a FROM t1 WHERE a=10 AND B=1)
UNION
(SELECT a FROM t2 WHERE a=11 AND B=2)
ORDER BY a LIMIT 10;

[iRedds]

Yes, such code is not possible by default. But it can be wrapped in another query using newQuery()->fromSubquery().
Like in a live test.

$union   = $this->db->table('user')->limit(1)->orderBy('id', 'ASC');

$builder = $this->db->table('user')->union($union)->limit(1)->orderBy('id', 'DESC');

$result   = $this->db->newQuery()->fromSubquery($builder, 'q')->orderBy('id', 'DESC')->get();

SELECT * FROM (
    SELECT * FROM (SELECT * FROM user ORDER BY id DESC LIMIT 1)
    UNION
    SELECT * FROM (SELECT * FROM user ORDER BY id ASC LIMIT 1)
) q ORDER BY id

[kenjis]

I would like the test code to follow the Arrange Act Assert pattern as much as possible.
http://wiki.c2.com/?ArrangeActAssert

There are many test codes that do not follow it, though.

[kenjis]

If there is a link to the detailed page, readers can go and see it easily.

[iRedds]

added

[kenjis]

@iRedds I think the query example to use an ORDER BY or LIMIT clause to sort or limit the entire UNION result should be documented.
And there are conflicts in the documentation.
Can you rebase this PR?

[iRedds]

@kenjis I've added an example to the documentation, but now @lonnieezell has nothing to add to the new version of the book )))

[kenjis]

Thank you!

[kenjis]

@iRedds Do you say about https://leanpub.com/codeigniter4foundations ?

[iRedds]

@kenjis yes, i do

[michalsn]

Excellent addition.

There are small additions to the docs I would like to see, though.

[iRedds]

Thanks to everyone who helped along this long journey.