# BSON::DBRef - phpMan

## NAME
    [BSON::DBRef] - BSON type wrapper for MongoDB DBRefs

## VERSION
    version v1.12.2

## SYNOPSIS
        use [BSON::Types] ':all';

        my $dbref = bson_dbref( $oid, $collection_name );

## DESCRIPTION
    This module provides a BSON type wrapper for MongoDB Database References
    <<http://docs.mongodb.org/manual/reference/database-references/>>.

    A DBRef is a special document format which references another document
    in the database. DBRefs are not the same as foreign keys and do not
    provide any referential integrity or constraint checking. For example, a
    DBRef may point to a document that no longer exists (or never existed.)

    Use of DBRefs is discouraged, so this module is provided for backwards
    compatibility. "Manual references"
    <<https://docs.mongodb.com/manual/reference/database-references/#document>
    -references> are preferred when there is a need to reference other
    documents.

## ATTRIBUTES
  id
    Required. The "_id" value of the referenced document. If the "_id" is an
    ObjectID, then you must use a [BSON::OID] object.

  ref
    Required. The name of the collection in which the referenced document
    lives. Either a [MongoDB::Collection] object or a string containing the
    collection name. The object will be coerced to string form.

    This may also be specified in the constructor as '$ref'.

  db
    Optional. The database in which the referenced document lives. Either a
    [MongoDB::Database] object or a string containing the database name. The
    object will be coerced to string form.

    Not all other language drivers support the $db field, so using this
    field is not recommended.

    This may also be specified in the constructor as '$db'.

  extra
    Optional. A hash reference of additional fields in the DBRef document.
    Not all MongoDB drivers support this feature and you should not rely on
    it. This attribute exists solely to ensure DBRefs generated by drivers
    that do allow extra fields will round-trip correctly.

    USE OF THIS FIELD FOR NEW DBREFS IS NOT RECOMMENDED.

## METHODS
  TO_JSON
    If the "BSON_EXTJSON" option is true, returns a hashref compatible with
    MongoDB's extended JSON
    <<https://github.com/mongodb/specifications/blob/master/source/extended-j>
    son.rst> format, which represents it as a document as follows:

        { "$ref": "<collection name>", "$id": "<id>" }

    If the "BSON_EXTJSON" option is false, an error is thrown, as this value
    can't otherwise be represented in JSON.

## AUTHORS
    *   David Golden <<david@mongodb.com>>

    *   Stefan G. <<minimalist@lavabit.com>>

## COPYRIGHT AND LICENSE
    This software is Copyright (c) 2020 by Stefan G. and MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004