Net::LDAP::Class(3)

NAME
Net::LDAP::Class - object-relational mapper for Net::LDAP

SYNOPSIS
 # define your class

 package MyLDAPClass;
 use base qw( Net::LDAP::Class );

 __PACKAGE__->metadata->setup(
    attributes          => [qw( name address phone email )],
    unique_attributes   => [qw( email )],
    base_dn             => 'dc=mycompany,dc=com',
 );

 1;

 # then use your class

 use MyLDAPClass;
 use Net::LDAP;

 my $ldap = create_Net_LDAP_object_and_bind();  # you write this

 # create an instance of your class
 my $person = MyLDAPClass->new( ldap => $ldap, email => 'foo@bar.com' );

 # load from LDAP or write if not yet existing
 $person->read or $person->create;

 # set the 'name' attribute
 $person->name( 'Joe Foo' );

 # write your changes
 $person->update;

 # change your mind?
 $person->delete;

DESCRIPTION
Net::LDAP::Class (NLC) is an object-relational mapping for LDAP.

I know, it's all wrong to confuse the ORM model with LDAP since LDAP is not relational in the same way that a RDBMS is. But the ORM APIs of projects like DBIx::Class and Rose::DB::Object are so fun and easy to use, it seemed like LDAP management should be just as fun and easy.

The architecture of this package is based on Rose::DB::Object, which the author uses to great effect for RDBMS management.

METHODS
NLC uses the Rose::Object package to create methods and handle the mundane get/set features. In addition, Net::LDAP::Class::MethodMaker implements a new method type called related_objects which handles the get/set/fetch of NLC objects related to a given NLC object. Typically these are Users and Groups. A User is typically related to one or more Groups, and a Group is typically related to one or more Users. See Net::LDAP::Class::User and Net::LDAP::Class::Group for examples.

There are some methods which every NLC subclass must implement. See SUBCLASSING for details.

  init
Override this in a subclass. Be sure to call SUPER::init in your subclass.

  metadata_class
Returns 'Net::LDAP::Class::Metadata' by default.

  metadata
Returns an instance of the metadata_class() containing all the metadata for the NLC class. May be called as a class or object method.

  init_ldap
If you do not pass a Net::LDAP object to new(), you may instead set the ldap_uri() class method to a URI string and init_ldap() will create a Net::LDAP object and bind() it for you.

Returns a Net::LDAP object.

  init_debug
Sets the default debug flag to whatever the PERL_DEBUG or LDAP_DEBUG env variable is set to.

  init_ldap_entry
Returns undef by default.

  get_ldap_error( ldap_msg )
Stringify the error message for the ldap_msg object.

  stringify
Returns the first unique attribute value that is not undef. If no such value is found, returns the object.

By default all NLC-derived objects are overloaded with this method.

  find( opts )
Returns array (or array ref if called in scalar context) of objects matching opts.

opts may include:

ldap
    If not present, the ldap() method is called instead.

base_dn
    If not present, the base_dn() method is called instead.

Any other opts are passed directly to the Net::LDAP search() method.

Returns undef if no results matching opts are found.

  create
Write a new object to the database. Calls the action_for_create() method -- see SUBCLASSING.

  read
Read an object's attribute values from the database. You must have previously set at least one unique attribute in the object in order for the read() to work.

Returns the object on success, undef if the object was not found.

  update
Write changes to the database. Calls action_for_update() -- see SUBCLASSING.

If no changes are detected, aborts and returns undef.

On successful write, returns the value of read().

  delete
Remove the object from the database. You must call read() first.

Returns the value of do_batch().

  read_or_create
Convenience method. If read() returns undef, create() is called. Returns the object in any case.

  save
Convenience method. If ldap_entry() is set, update() is called. Otherwise, read_or_create() is called. The NLC object is returned in any case.

  validate( attr_name, attr_value )
Called by MethodMaker every time an attribute is set with a MethodMaker-created method.

If validate() returns true, attr_value is set. If validate() returns false, a fatal error is thrown and error() set.

This method should be overriden in your subclass to provide schema-specific validation. The default behaviour is a no-op (always returns true).

  do_batch( array_of_actions )
Creates (if batch() is not already set) and runs a Net::LDAP::Batch object, passing it the array_of_actions to run. Will croak on any error.

Returns the Net::LDAP::Batch object on success.

  add_to_batch( array_of_actions )
Initializes (if necessary) and adds array_of_actions to the Net::LDAP::Batch object in batch().

  rollback
Will call the rollback() method on the Net::LDAP::Batch object returned by batch(). If there is not batch() set, will croak.

  action_for_create
See SUBCLASSING.

  action_for_update
See SUBCLASSING.

  action_for_delete
See SUBCLASSING.

  check_unique_attributes_set
Returns true (1) if any unique attribute is set with a defined value.

Returns false (0) if no unique attributes are set.

  AUTOLOAD
Will croak() with a helpful message if you call a method that does not exist. Mostly useful for catching cases where you forget to predefine an attribute.

  dump
Returns Data::Dump::dump output for the NLC object. Useful for debugging. See also the Net::LDAP::Entry dump() method which can be called on the ldap_entry value.

 $nlc->dump;                # same as Data::Dump::dump( $nlc )
 $nlc->ldap_entry->dump;    # see Net::LDAP::Entry dump() method

  has_local_changes
Convenience method. Returns true if the object has had any values set since the last time it was written to the server.

  batch
Get/set the Net::LDAP::Batch object for the current transaction. Typically you don't want to mess with this but documented for completeness.

  prev_batch
Get/set the Net::LDAP::Batch object for the just-completed transaction. Typically you don't want to mess with this but documented for completeness.

  act_on_all( code_ref [, opts] )
Performs coderef sub reference on all records in LDAP. The coderef should expect one argument: a Net::LDAP::Class-derived object.

act_on_all() operates using Net::LDAP::Control::Paged, performing a search() using a filter based on unique_attributes() and iterating over all matches in groups of (by default) 500. You may set the pager size in opts. opts should be a hash ref. The following key/value pairs are supported:

page_size
    Default: 500. Sets the Net::LDAP::Control::Paged size.

filter
    Default: unique_atttributes->[0] = '*'

    Set the filter for the search.

ldap
    A Net::LDAP object. Required if you call act_on_all() as a class method.

Returns the number of Net::LDAP::Class results acted upon.

  isa_user
Convenience method. Just returns shift->isa('Net::LDAP::Class::User').

  isa_group
Just like isa_user() but checks the Net::LDAP::Class::Group.

SUBCLASSING
NLC is designed as a base class with basic default behaviours for most common usage. However, every subclass must implement some methods, usually because such methods are specific to the particular LDAP schema you are using with the subclass.

The following methods are required by every NLC subclass. These action_for_* methods should return either a Net::LDAP::Batch::Action-based object or an array of values that can be passed to the add_actions() method of the Net::LDAP::Batch class.

See Net::LDAP::Class::User::POSIX and Net::LDAP::Class::Group::POSIX for examples.

•   action_for_create

•   action_for_update

•   action_for_delete

In addition, if you use the related_objects MethodMaker feature, then your subclass must implement a fetch_method_name method for each related_objects method name. Again, see Net::LDAP::Class::User::POSIX and Net::LDAP::Class::Group::POSIX for examples.

AUTHOR
Peter Karman, "<karman at cpan.org>"

BUGS
Please report any bugs or feature requests to "bug-net-ldap-class at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-LDAP-Class>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

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

    perldoc Net::LDAP::Class

You can also look for information at:

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Net-LDAP-Class>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Net-LDAP-Class>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-LDAP-Class>

•   Search CPAN

    <http://search.cpan.org/dist/Net-LDAP-Class>

ACKNOWLEDGEMENTS
The Minnesota Supercomputing Institute "http://www.msi.umn.edu/" sponsored the development of this software.

COPYRIGHT
Copyright 2008 by the Regents of the University of Minnesota. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO
Net::LDAP, Net::LDAP::Batch