Sebastian Willing
and 1 contributors


YAWF::Object::MongoDB - Object of a MongoDB document


Version 0.03


This module has been written to be compatible to the YAWF::Object methods, but it can be used as a standalone MongoDB Object relational mapper (ORM) without YAWF even installed.


Abstraction layer for a MongoDB database

This module is used as @ISA or use base parent for object modules of your project, it won't work standalone.

    package My::Project::ObjectClass;

    # Typical use
    use YAWF::Object::MongoDB (collection => 'my_collection',
                               keys       => ['foo', 'bar'],

    my @ISA = ('YAWF::Object::MongoDB');

Within your script:

    use My::Project::ObjectClass;
    my $object = My::Project::ObjectClass->new();
    my $object = My::Project::ObjectClass->list();

Other definition options (you'll always need @ISA/use base in addition):

    # Custom database info
    use YAWF::Object::MongoDB (server     => 'localhost:28017',
                               database   => 'my_db',
                               collection => 'my_collection',
                               keys       => ['foo', 'bar'],

    # Complex key definition with sub-objects
    use YAWF::Object::MongoDB (collection => 'my_collection',
                               keys       => {
                                        foo => 1,
                                        bar => {
                                            baz  => 1, # Enables $object->bar->baz($new_value);
                                            true => sub { return 1; },

    # Provide server, database and collection at runtime:
    use YAWF::Object::MongoDB (keys       => ['foo', 'bar']);
    sub SERVER { return 'localhost:28017'; }    # Called at runtime during the first
    sub DATABASE { return 'my_database'; }      # access to the database, may even        
    sub COLLECTION { return 'my_collection'; }  # change during runtime.

    # MongoDB data my also be defined in yawf.yml:
        server: localhost:28017
        database: My_Database
        collection: 1_collection_for_everything
    # Bad way (may harm other projects running in the same mod_perl):
    $YAWF::Object::MongoDB::DEFAULT_SERVER = 'my.custom.server:99999';

Server, database and collection can be set at different places, priority order is: * sub in class * value given at "use"-time * YAWF config value * $DEFAULT_* values in YAWF::Object::MongoDB



  my @objects = YAWF::Object::MongoDB->list(); # Get all items of a table (could be big!)
  my @objects = YAWF::Object::MongoDB->list({ foo => bar }); # Search for a list of items


  my $count = YAWF::Object::MongoDB->count(); # Get the number of items in this table
  my $count = YAWF::Object::MongoDB->count({ foo => bar }); # Get the number of items for this search



  my $object = YAWF::Object::MongoDB->new(); # New item
  my $object = YAWF::Object::MongoDB->new($id); # Get item by primary key
  my $object = YAWF::Object::MongoDB->new(foo => 'bar'); # Search item (returns the first)
  my $object = YAWF::Object::MongoDB->new(foo => 'bar',
                                          baz => 'foo'); # Search item (returns the first)

The new constructor lets you create a new YAWF::Object::MongoDB object.

The first syntax creates a new, empty item while the others return an existing item from the database or undef if nothing was found.



Returns the current value of any key, no matter if it has been predefined.



Assign a new value to a key, no matter if it has been predefined. Returns the new value.



Returns the current value of any key, no matter if it has been predefined.

Sets the current values (and returns the new one) if a value (including undef) is given as the second argument.



Flags column $key as changed (will be flushed on next ->flush call).



Returns the unique document id.



Write a YAWF object into the database with automatic selection of insert or update depending on the objects state (new or existing).

Changes the variable used to call the method to the new object and also returns the new object.



Remove a document from the database.


  my $timestamp = $object->to_time($time_column);

Convertes an database timestamp to an unixtime value.


  my $timestamp = $object->from_time($time_column,$timestamp);

Inserts a timestamp into the database (converting it to database format).


Advoid calling them directly unless you really know what you're doing.


Copy some 'use' arguments to internal structures.


Reduce the parent object to a class name.


Get the current server name string


Get a server connection handler


Get the current database name string


Get a database handler


Get a collection handler


Resolv order_by - argument of ->list


Fetch a group of fields from the database, no return value.


Set environment variable YAWF_MONGODB_TRACE to 1 to enable debug warn's to STDERR.


Sebastian Willing, <sewi at>


Please report any bugs or feature requests to bug-yawf-object-mongodb at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc YAWF::Object::MongoDB

You can also look for information at:



Copyright 2011 Sebastian Willing.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.