Skip to content

PHPLIB-675 Add helpers to check collection types to CollectionInfo #839

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 8, 2021
Merged

PHPLIB-675 Add helpers to check collection types to CollectionInfo #839

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
49767fe
PHPLIB-675 Expose additional methods to access collection info
alcaeus Jul 7, 2021
2b2be26
Use arrayNotHasKey over isset in tests
alcaeus Jul 8, 2021
ec913b5
Add version information to deprecation messages
alcaeus Jul 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 41 additions & 1 deletion src/Model/CollectionInfo.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ public function __debugInfo()
/**
* Return the maximum number of documents to keep in the capped collection.
*
* @deprecated 1.0 Deprecated in favor of using getOptions
*
* @return integer|null
*/
public function getCappedMax()
Expand All @@ -71,6 +73,8 @@ public function getCappedMax()
/**
* Return the maximum size (in bytes) of the capped collection.
*
* @deprecated 1.0 Deprecated in favor of using getOptions
*
* @return integer|null
*/
public function getCappedSize()
Expand All @@ -79,9 +83,31 @@ public function getCappedSize()
return isset($this->info['options']['size']) ? (integer) $this->info['options']['size'] : null;
}

/**
* Return information about the _id index for the collection.
*
* @return array
*/
public function getIdIndex(): array
{
return (array) ($this->info['idIndex'] ?? []);
}

/**
* Return the "info" property of the server response.
*
* @see https://docs.mongodb.com/manual/reference/command/listCollections/#output
* @return array
*/
public function getInfo(): array
{
return (array) ($this->info['info'] ?? []);
}

/**
* Return the collection name.
*
* @see https://docs.mongodb.com/manual/reference/command/listCollections/#output
* @return string
*/
public function getName()
Expand All @@ -92,16 +118,30 @@ public function getName()
/**
* Return the collection options.
*
* @see https://docs.mongodb.com/manual/reference/command/listCollections/#output
* @return array
*/
public function getOptions()
{
return isset($this->info['options']) ? (array) $this->info['options'] : [];
return (array) ($this->info['options'] ?? []);
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@alcaeus alcaeus Jul 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
{
}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


/**
* Return the collection type.
*
* @see https://docs.mongodb.com/manual/reference/command/listCollections/#output
* @return string
*/
public function getType(): string
{
return (string) $this->info['type'];
}

/**
* Return whether the collection is a capped collection.
*
* @deprecated 1.0 Deprecated in favor of using getOptions
*
* @return boolean
*/
public function isCapped()
Expand Down
40 changes: 34 additions & 6 deletions tests/Model/CollectionInfoTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,19 +8,47 @@

class CollectionInfoTest extends TestCase
{
public function testGetName(): void
public function testGetBasicInformation(): void
{
$info = new CollectionInfo(['name' => 'foo']);
$info = new CollectionInfo([
'name' => 'foo',
'type' => 'view',
'options' => ['capped' => true, 'size' => 1048576],
'info' => ['readOnly' => true],
'idIndex' => ['idIndex' => true], // Dummy option
]);

$this->assertSame('foo', $info->getName());
$this->assertSame('foo', $info['name']);

$this->assertSame('view', $info->getType());
$this->assertSame('view', $info['type']);

$this->assertSame(['capped' => true, 'size' => 1048576], $info->getOptions());
$this->assertSame(['capped' => true, 'size' => 1048576], $info['options']);

$this->assertSame(['readOnly' => true], $info->getInfo());
$this->assertSame(['readOnly' => true], $info['info']);

$this->assertSame(['idIndex' => true], $info->getIdIndex());
$this->assertSame(['idIndex' => true], $info['idIndex']);
}

public function testGetOptions(): void
public function testMissingFields(): void
{
$info = new CollectionInfo(['name' => 'foo']);
$info = new CollectionInfo([
'name' => 'foo',
'type' => 'view',
]);

$this->assertSame([], $info->getOptions());
$this->assertArrayNotHasKey('options', $info);

$info = new CollectionInfo(['name' => 'foo', 'options' => ['capped' => true, 'size' => 1048576]]);
$this->assertSame(['capped' => true, 'size' => 1048576], $info->getOptions());
$this->assertSame([], $info->getInfo());
$this->assertArrayNotHasKey('info', $info);

$this->assertSame([], $info->getIdIndex());
$this->assertArrayNotHasKey('idIndex', $info);
}

public function testCappedCollectionMethods(): void
Expand Down