[5.7] "Constraining Eager Loads" callout for unsupported eager load limit()

[derekmd]

The callout second sentence I came up with is kind of clunky so maybe we don't need the "why?" It's difficult to succinctly describe the groupwise-maximum query problem in a short warning alert.

This pull request covers issues:

• Constraints on eager-loaded hasMany doesn't retrieve data correctly framework#16217
• Eager-loading with a limit on collection only loads for last element in collection framework#18014
• Eloquent eager loading with limits framework#4835
• [5.3] Limit in eager loading doesn't feel right framework#15585

Since 2014, GitHub issues have frequently been submitted to the framework with a misunderstanding that limit() can be used by:

• Eloquent relationships
• Eager load queries

The underlying issue is that developers don't realize these active record queries are not "regular" queries since they must be built and run once to fetch many Eloquent models. So the limit() call applies to fetching relations for all models and it doesn't run an SQL LIMIT per model.

(Aside from not realizing the SQL being run) I think this confusion stems from these two phrases in the docs:

1. specify additional query constraints for the eager loading query

   "Constraints" implies that SQL keywords limit() and offset() can be used.

2. Of course, you may call other query builder methods

   This link to https://laravel.com/docs/5.7/queries implies all methods documented on that page can be used.

We can reduce developer confusion by:

• adjusting some grammar
  • For example, Rails docs uses the term "condition" instead of "constraint": https://guides.rubyonrails.org/active_record_querying.html#eager-loading-multiple-associations
  • although orderBy() still works and isn't a "condition".
• adding a callout to the "Eager Loading" section of the documentation to describe why limit() can't be called.

Suggesting a 3rd-party package solution

To go an extra step, the docs can link to Composer package "staudenmeir/eloquent-eager-limit" that supports eager load limit() with more recent databases. To communicate this is not a sanctioned package in the Laravel ecosystem, the docs should be clear support for that solution is external.

---

To call limit() while eager loading, some more recent database versions do support such groupwise-maximum database queries. Add the staudenmeir/eloquent-eager-limit dependency in your composer.json file and follow package instructions to enable this feature. Issues and support for this package should be directed to its author.