PHPLIB-675 Add helpers to check collection types to CollectionInfo

[alcaeus]

PHPLIB-675

This adds getType, getInfo, and getIdIndex. Methods relating to capped collections have been deprecated in documentation.

[jmikola]

For a moment, let's ignore the capped method we already have. Based on https://docs.mongodb.com/manual/reference/command/listCollections/#mongodb-data-listCollections.cursor, would it make more sense to just create getters for the missing top-level fields?

These three methods could be replaced with getType() : string. Additionally, we could introduce getInfo() : array for the info field, which would presumably cast like getOptions does. I would be a bit concerned that "info" there might confuse users into thinking it returns the entire IndexInfo object as an array -- so I'm open to ways we can avoid the misunderstanding.

I have no idea what idIndex actually looks like, but I wonder if that'd be problematic to cast to an array as well.

While this class does implement ArrayAccess, I don't think it's easy to know exactly what can be accessed. It'd be lousy to call __debugInfo() directly, but that basically returns the value someone might want to have full access. I'm open to other ideas to make this most accessible.

[alcaeus]

I was considering this as well. I'm thinking this:

interface CollectionInfo
{
    /** Returns the name of the collection or view */
    public function getName() : string;

    /** Returns info.type */
    public function getType() : string;

    /** Returns info.options */
    public function getOptions() : array;

    /** Returns the raw collection info response from listCollections */
    public function getRawInfo() : array;
}

I'm not sure what to do with the isCapped helper though, whether to keep or deprecate it.

A different, more involved approach, would see different classes for the various types exposed through CollectionInfo:

/** @final */
class Collection implements CollectionInfo
{
}

final class CappedCollection extends Collection
{
    public function getMax() : ?int {}

    public function getSize() : ?int {}
}

final class View implements CollectionInfo
{
}

[jmikola]

Giving this some more though: If I knew nothing about this class, I think my first impression of getRawInfo would be the method that returns everything (like __debugInfo). I think getInfo makes more sense and we can just clearly document that it returns the "info" property of the server response.

I'm not sure what to do with the isCapped helper though, whether to keep or deprecate it.

I think we can deprecate it in documentation. That would give us something to point to if an idea for other specific helpers comes up down the line.

A different, more involved approach, would see different classes for the various types exposed through CollectionInfo:

While that would be very usable (folks could use instanceof), I don't think we have the data to invest in this API -- and that's basically taking us down a road of query builders where we'd need to maintain this for each server update. Perhaps worse because I don't think the server response is fully documented.

This does seem like something more fitting for an auxiliary library (PHPLIB-4), which is where we originally intended to build out APIs for other shell-like commands (e.g. user management, misc. helpers).

[alcaeus]

Good point. I've added getters for idIndex, info, and type which previously didn't have any. I also added @deprecated phpdoc comments to the isCapped, getCappedMax, and getCappedSize methods, but they don't trigger any deprecations warnings yet.

[jmikola]

LGTM with two suggestions.

[jmikola]

For consistency with the other two places we use @deprecated (ChangeStream and Collection), I think this should include the version in which we deprecate it. Consider:

@deprecated 1.9 Deprecated in favor of using getOptions

[jmikola]

FYI: you can use assertArrayNotHasKey here for more verbose messages. ArrayHasKey constraint supports ArrayAccess and invokes offsetExists.