getrecords() docblock says one thing, function does something else

4 posts by 2 authors in: Forums > CMS Builder
Last Post: about an hour ago   (RSS)

By kitsguru - Yesterday at 4:48pm

It appears that along the way, the getrecords function changed from a 2-value return to a 3-value return; a schema array is now added to the final output. The docblock shows only 2.

My AI agents are flagging this inconsistency. How is the schema to be used?


/* list($records, $details) = getRecords(array( ... */
function getRecords($options): ?array { 
    ...
    return array($rows, $listDetails, $schema);
}
Jeff Shields
yaadev.com

By Dave - 4 hours ago

Good catch, Jeff!

You're absolutely right that the docblock shows two return values while the function returns three.

The third value (schema) is intentionally undocumented as it's an internal feature we use within CMS Builder, but one we don't officially promote as part of the public API. It contains the same data you'd get from calling loadSchema('tableName') directly.

For the typical use case, the first two return values ($records and $details) provide everything needed for building viewers. The schema is returned primarily for internal functions and advanced customization scenarios. If you have a specific need for it, you're welcome to use it, just be aware that undocumented features aren't officially supported and could theoretically change without notice in future versions.

That said, this particular return structure has been stable for over 10 years, so it's highly unlikely to change. In general, if the documentation doesn't mention a feature, it usually means you won't need it for standard viewer development. But for developers who dig deeper into the code, the feature is there and available.

Good eye catching that detail!

Dave Edis - Senior Developer
interactivetools.com

By Dave - about an hour ago - edited: about an hour ago

Hi jeff, 

I'll convert the function comment to a proper PHPDoc block with an @return tag at the end as well.  That might help: 

*
* @return array|null [$records, $listMetaData, $schema] - schema for advanced use
*/
Dave Edis - Senior Developer
interactivetools.com