Skip to content

PHPLIB-675 Document new CollectionInfo methods #841

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 5 commits into from
Jul 13, 2021
Merged

PHPLIB-675 Document new CollectionInfo methods #841

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4416beb
Document deprecation of capped collection helpers
alcaeus Jul 9, 2021
b81294c
Add detail about where collection information comes from
alcaeus Jul 9, 2021
9b4d103
Document new CollectionInfo helpers
alcaeus Jul 9, 2021
e7dfb43
Address review feedback
alcaeus Jul 12, 2021
022a319
Fix wrong backticks
alcaeus Jul 13, 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
3 changes: 3 additions & 0 deletions docs/reference/enumeration-classes.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,11 @@ Methods

/reference/method/MongoDBModelCollectionInfo-getCappedMax
/reference/method/MongoDBModelCollectionInfo-getCappedSize
/reference/method/MongoDBModelCollectionInfo-getIdIndex
/reference/method/MongoDBModelCollectionInfo-getInfo
/reference/method/MongoDBModelCollectionInfo-getName
/reference/method/MongoDBModelCollectionInfo-getOptions
/reference/method/MongoDBModelCollectionInfo-getType
/reference/method/MongoDBModelCollectionInfo-isCapped

----
Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBModelCollectionInfo-getCappedMax.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
MongoDB\\Model\\CollectionInfo::getCappedMax()
==============================================

.. deprecated:: 1.9

.. default-domain:: mongodb

.. contents:: On this page
Expand All @@ -28,6 +30,10 @@ Return Values
The document limit for the capped collection. If the collection is not capped,
``null`` will be returned.

This method is deprecated in favor of using
:phpmethod:`MongoDB\\Model\\CollectionInfo::getOptions()` and accessing the
``max`` key.

Examples
--------

Expand Down
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBModelCollectionInfo-getCappedSize.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
MongoDB\\Model\\CollectionInfo::getCappedSize()
===============================================

.. deprecated:: 1.9

.. default-domain:: mongodb

.. contents:: On this page
Expand Down Expand Up @@ -29,6 +31,10 @@ Return Values
The size limit for the capped collection in bytes. If the collection is not
capped, ``null`` will be returned.

This method is deprecated in favor of using
:phpmethod:`MongoDB\\Model\\CollectionInfo::getOptions()` and accessing the
``size`` key.

Examples
--------

Expand Down
73 changes: 73 additions & 0 deletions docs/reference/method/MongoDBModelCollectionInfo-getIdIndex.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
============================================
MongoDB\\Model\\CollectionInfo::getIdIndex()
============================================

.. versionadded:: 1.9

.. default-domain:: mongodb

.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol

Definition
----------

.. phpmethod:: MongoDB\\Model\\CollectionInfo::getIdIndex()

Returns information about the ``_id`` field index.

.. code-block:: php

function getIdIndex(): array

Return Values
-------------

An array containing information on the ``_id`` index. This corresponds to the
``idIndex`` field returned in the ``listCollections`` command reply.

Examples
--------

.. code-block:: php

<?php

$info = new CollectionInfo([
'type' => 'view',
'name' => 'foo',
'idIndex' => [
'v' => 2,
'key' => ['_id' => 1],
'name' => '_id',
'ns' => 'test.foo',
],
]);

var_dump($info->getIdIndex());
Comment on lines +39 to +50
Copy link
Member Author

Choose a reason for hiding this comment

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

I'm not sure if these examples are really helpful. I believe we could optimise these by creating a collection first, then getting a CollectionInfo object for a collection and dumping from there. Right now, the example doesn't really clarify that the info here is server dependent.

Copy link
Member

Choose a reason for hiding this comment

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

I concur. There's absolutely no reason to construct this directly, as that's not the intended use of this API.

It looks like these examples date back to PHPLIB-278, which I signed off on. In the meantime, I'd suggest not adding any new examples and making a ticket to either replace all of these with integration examples or remove them entirely and just point users to the corresponding enumeration method that would return these objects in the first place.

Copy link
Member Author

Choose a reason for hiding this comment

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

I'll leave these examples in for consistency and have created PHPLIB-689 to track improvements.


The output would then resemble::

array(4) {
["v"]=>
int(2)
["key"]=>
array(1) {
["_id"]=>
int(1)
}
["name"]=>
string(3) "_id"
["ns"]=>
string(8) "test.foo"
}

See Also
--------

- :phpmethod:`MongoDB\\Database::createCollection()`
- :manual:`listCollections </reference/command/listCollections>` command
reference in the MongoDB manual
59 changes: 59 additions & 0 deletions docs/reference/method/MongoDBModelCollectionInfo-getInfo.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
=========================================
MongoDB\\Model\\CollectionInfo::getInfo()
=========================================

.. versionadded:: 1.9

.. default-domain:: mongodb

.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol

Definition
----------

.. phpmethod:: MongoDB\\Model\\CollectionInfo::getInfo()

Returns additional information about the collection.

.. code-block:: php

function getInfo(): array
Copy link
Member

Choose a reason for hiding this comment

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

I had a thought about how this and getOptions cast the returned value to an array and how that might be inconsistent is a nested value was a document and was reported as a stdClass. I then remembered that ListCollections doesn't support a typeMap option at all and applies its own typeMap such that root and embedded docs become PHP arrays. So there's no reason to be concerned about inconsistency -- and I also don't worry about the MongoDB server returning a value that would be ambiguous (e.g. document with sequential numeric keys).


Return Values
-------------

An array containing extra information about the collection. This corresponds to
the ``info`` field returned in the ``listCollections`` command reply.

Examples
--------

.. code-block:: php

<?php

$info = new CollectionInfo([
'type' => 'view',
'name' => 'foo',
'info' => ['readOnly' => true]
]);

var_dump($info->getInfo());

The output would then resemble::

array(1) {
["readOnly"]=>
bool(true)
}

See Also
--------

- :phpmethod:`MongoDB\\Database::createCollection()`
- :manual:`listCollections </reference/command/listCollections>` command
reference in the MongoDB manual
3 changes: 2 additions & 1 deletion docs/reference/method/MongoDBModelCollectionInfo-getName.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ Definition
Return Values
-------------

The collection name.
The collection name. This corresponds to the ``name`` field returned in the
``listCollections`` command reply.

Examples
--------
Expand Down
3 changes: 2 additions & 1 deletion docs/reference/method/MongoDBModelCollectionInfo-getOptions.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ Definition
Return Values
-------------

The collection options.
The collection options. This corresponds to the ``options`` field returned in
the ``listCollections`` command reply.

Examples
--------
Expand Down
52 changes: 52 additions & 0 deletions docs/reference/method/MongoDBModelCollectionInfo-getType.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
=========================================
MongoDB\\Model\\CollectionInfo::getType()
=========================================

.. versionadded:: 1.9

.. default-domain:: mongodb

.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol

Definition
----------

.. phpmethod:: MongoDB\\Model\\CollectionInfo::getType()

Return the collection type.

.. code-block:: php

function getType(): string

Return Values
-------------

The collection type. This corresponds to the ``type`` field returned in the
``listCollections`` command reply.

Examples
--------

.. code-block:: php

<?php

$info = new CollectionInfo(['type' => 'collection', 'name' => 'foo']);

echo $info->getType();

The output would then resemble::

collection

See Also
--------

- :phpmethod:`MongoDB\\Database::createCollection()`
- :manual:`listCollections </reference/command/listCollections>` command
reference in the MongoDB manual
6 changes: 6 additions & 0 deletions docs/reference/method/MongoDBModelCollectionInfo-isCapped.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
MongoDB\\Model\\CollectionInfo::isCapped()
==========================================

.. deprecated:: 1.9

.. default-domain:: mongodb

.. contents:: On this page
Expand All @@ -27,6 +29,10 @@ Return Values

A boolean indicating whether the collection is a capped collection.

This method is deprecated in favor of using
:phpmethod:`MongoDB\\Model\\CollectionInfo::getOptions()` and accessing the
``capped`` key.

Examples
--------

Expand Down