PW 3.0.153 – Core updates

[ryan]

This latest version of the core on the dev branch focuses on comments field updates, significant refactoring/improvements to ProcessWire’s core Template class and PagesLoader class (which is used by the $pages API variable), and we introduce a useful new $pages API method—

https://processwire.com/blog/posts/pw-3.0.153/

[horst]

Quote

Either of the methods above can also be used for setting the value when given an argument.

Thanks. Very nice template methods updates! Will come in handy! ?

 

[Robin S]

@ryan, great timing on the $pages->has() method - I requested essentially this just the other day: https://github.com/processwire/processwire-requests/issues/358

But the method name has() seems not so intuitive - if you didn't know better you would think this returns a true/false value. I think $pages->getID() would be more intuitive - maybe that could be added as an alias?

[ryan]

@Robin S The purpose I was focused on for the method is to see if the system has any page that matches the given criteria. An example of the use case appears in the Template class updates here. It verbally makes sense in code for what it's intended for. Usually I'd use a get or count for that, I didn't need any of the extras that $pages->get() or $pages->count() provide, so thought we could eliminate some overhead. Plus I can think several other other cases where the same was true, so the need has resurfaced enough times that it seemed like good method for PW to have. The method returns the ID just because it already has that info either way, and it seemed potentially more useful (and 0|1+ communicate the same thing as false|true). I had also seen where you'd mentioned a getID recently, and since this method already has the page ID, I thought this also seemed like a good opportunity to accommodate that need too. So far I haven't come across a good use case for getID() in my own projects, outside of checking for existence of something (which 'has' seems like a better term for). But it certainly makes sense alongside the existing findIDs() method, though that method is more about accommodating a scale that find() can't. But it sounds like you've had use cases for it which means others likely have too, and that's plenty good reason for me. I'll go ahead and add getID() it as an alias of has(). Depending on what need you are looking to solve, I imagine this will help people to find what they are looking for more easily. 

[tpr]

The naming of "has" sounds a bit unintuitive to me as well, since it involves getting a true/false, so it can lead to confusion when reading the code where the returned id is used.

Maybe something like this? (somewhat similarly to the C# TryGetValue())

$pages->tryGetId(selector);

[Robin S]

8 hours ago, ryan said:

But it sounds like you've had use cases for it which means others likely have too, and that's plenty good reason for me. I'll go ahead and add getID() it as an alias of has().

Thanks!

I use findIDs() when I'm using the PW API in conjunction with SQL queries where I only need the page IDs in the query. Sometimes I only need a single page ID and so having a getID() makes that simpler and corresponds to the find() and get() methods. 

[bernhard]

20 hours ago, Robin S said:

But the method name has() seems not so intuitive - if you didn't know better you would think this returns a true/false value. I think $pages->getID() would be more intuitive - maybe that could be added as an alias?

Exactly what I thought! I also find it counter intuitive that it does not return a boolean value! Your linked example looks good as-is, but it somehow does not feel right to have a ->has() return something else than yes/no. $pages->getID() is great to have and absolutely clear imho ? 

Ok, I've done some research and I see that we have several HAS... methods returning integers, for example:

$page->hasChildren()
$page->hasLinks
$page->hasReferences

Still not sure if it wouldn't be better to have those additionally for clearness:

$page->numChildrenVisible()
$page->numLinks
$page->numReferences

Of course that's nothing extremely important, but PW is known for it's awesome API, so it might be good to keep it as clean as possible. What do others think about those wordings?

[dotnetic]

I think Bernhard's ideas are very good and intuitive. I would also think that a ->has method would return a boolean.

[ryan]

If one's goal is to get an up or down from an API call, then zero vs. non-zero is functionally and effectively the same thing as boolean. If there's an opportunity to make a method more useful by taking advantage of that fact, then I'll always do it. So yes, you'll find many examples of this in PW. That's always the strategy I've tried to embrace in the PW API and plan to continue going forward.

To reiterate what I stated above, the primary purpose of the has() method is not to get an ID—it is instead to check if the system has a page matching the criteria or not, without actually loading the page. Whether the method returns 0 or false makes no difference in telling the caller that the system has no page matching the criteria. Likewise if the page does match the criteria (true vs 1+). Now if you are specifically looking for a getID() function, then yes of course the name "getID" is preferable. I'm happy to add getID() as an alias for times when one might be specifically looking for that particular need. But that's not what I was looking for here. And if anyone else's experience is similar to mine, we will more often be looking to see if the system has any page matching some criteria (whether we want the ID or not). Basically replacing instances where we might have used count() before, with a more efficient alternative. So I feel pretty strongly that the has method name and return value are optimal and consistent here.