Bring back (deprecated) support for using the |length filter on element queries

[mmikkel]

Since the 4.0 release, I'm seeing a lot of people getting tripped up by the fact that the |length filter no longer works when used on element queries (for example; #11129) – especially when upgrading sites from Craft 3.

Specifically, this has become a big gotcha because

a) There is no exception thrown for it in Craft 4. In fact it appears to still work, as the filter now returns the character count for the query's __toString() method, instead of the query result count as is probably expected.

b) There is no deprecation warning logged for it in Craft 3

Essentially, this silently breaks a lot of templates that are doing something similar to this:

{% if entry.images|length %}
    ...
{% endif %}

I get that |length on queries is a bad practice and that removing the support for it is probably for the better. However, considering the above points and the fact that using |length on queries seems like a pretty common thing for Craft developers to do, I feel pretty strongly that the current situation should be addressed, some way or another.

I propose that either

a) Support for using |length on element queries is restored in Craft 4, with a deprecation error, before being finally removed again in Craft 5. This option makes the most sense to me as a lot of developers are unaware that it was technically (albeit silently) deprecated in Craft 3, and there might already be sites upgraded to Craft 4 where the issue has gone undiscovered thus far.

b) Support is not restored for Craft 4, but a deprecation warning is added for Craft 3.

[mmikkel]

There might be neater ways to do it, but one idea that seems to me like a pretty straight-forward solve is to add a custom |length filter to craft\web\twig\Extension, i.e. something like

public function lengthFilter(TwigEnvironment $env, $thing): int
{
    if ($thing instanceof QueryInterface) {
        Craft::$app->getDeprecator()->log('length-queries', 'Using the `|length` filter on queries has been deprecated. Use the query\'s `count()` method to fetch the number of results instead.');
        return $thing->count();
    }
    return twig_length_filter($env, $thing);
}

[khalwat]

Would love to see this happen. If it didn't log a deprecation in Craft 3, it probably should still work in Craft 4, but now with a deprecation logged, and then it could be phased out in Craft 5

[brandonkelly]

Same idea occurred to me this morning as well 😄

Implemented for Craft 4.2, which we’ll release ASAP! f2ccc77

Also realized dropping element queries’ ArrayAccess and IteratorAggregate implementations in 4.0 was a bit heavy-handed; the only actual method signature conflict was with Countable. So I’ve brought those back for 4.2 as well, for all queries that extend craft\db\Query, not just element queries (3c24b99). That will re-enable myQuery[0] and looping over queries directly.

(And these are being brought back indefinitely, not as temporary deprecations.)

[alexanderloewe]

Hello Brandon,

So I understand that correctly | length is expected to remain in version 5 and 6 as well?

[brandonkelly]

@alexanderloewe Yep! It won’t be deprecated anymore.

[alexanderloewe]

👍🏻

[alexanderloewe]

What do you think, when will Craft 4.2 be published?

So that we have a time frame to roll out all our sites to Craft 4.

[brandonkelly]

In the next week or two.

[darylknight]

Ref: #11625 (comment)

Following this discussion, it looks like Craft is going to un-deprecate using the |length filter on element queries. While that's good (I think?) it has thrown up a lot of discussion on Discord about "well you shouldn't have been doing that anyway as it's a heavy query".

So while it's good that our sites won't break with the reversed change, it is making me wonder what the better way is to code these instances? I've been using |length fairly heavy-handidly on all sorts of things, and as there are no deprecation errors, and I'm not a PHP programmer, it's not clear when you should or shouldn't be using this. Is there anything in the docs that talks about this?

[brandonkelly]

@darylknight It’s bad practice to use a |length filter on an element query, because it will cause the query to be executed twice – once to get its count, and a second time when calling .all() to fetch the results for the for loop:

{% if myQuery|length %}
  {% for entry in myQuery.all() %}
    ...
  {% endfor %}
{% endif %}

Instead you can query for the entries up front, and check whether the resulting entry array has a length:

{% set entries = myQuery.all() %}
{% if entries|length %}
  {% for entry in entries %}
    ...
  {% endfor %}
{% endif %}

This only applies to things that aren’t eager-loaded. If you’re working with eager-loaded relations or Matrix blocks, etc., there’s no performance penalty for using |length since you’re already working with an array of the eager-loaded elements.

{% set entries = craft.entries()
  .section('news')
  .with(['myRelationalField'])
  .all() %}

{% for entry in entries %}
  {% if entry.myRelationalField|length %}
    {% for relatedEntry in entry.myRelationalField %}
      ...
    {% endfor %}
  {% endif %}
{% endfor %}

Make sense?

[darylknight]

That does make sense, thanks Brad! Ok, so yeah in future I'll be making sure to call .all() first, then check the length afterwards. Thanks for choosing to address in this 4.2 as well :)

[alexanderloewe]

Brad, I think that information should be added to the documentation, can't remember that I have seen tips for a better performance in the Craft CMS doc.

[mmikkel]

Also may be worth mentioning that in a situation where querying for the elements up front isn't feasible, myQuery|length can often be replaced with myQuery.exists(), which is a faster query.

[brandonkelly]

Craft 4.2.0 is out now with support for treating element queries as arrays 🎉

Craft 3.7.50 has also been released, dropping related deprecation warnings.