NAME

Class::Hook - Add hooks on methods from other classes

SYNOPSIS

  use Class::Hook;

  Class::Hook->before(\&sub1);
  Class::Hook->after(\&sub2);
  Class::Hook->activate();
  # or
  Class::Hook->new(\&sub1, \&sub2);

  # and then
  Anotherclass->aMethod($someParam); # Hooked class

DESCRIPTION

Class::Hook enables you to trace methods calls from your code to other classes.

Instead of putting 'use Foo;' in your code, simply type 'use Class::Hook;'. The class Foo is unknown in your code. It will be magically catched by Class::Hook which will call Foo itself. You can see Class::Hook as a kind of relay.

You can setup a subroutine to be called before any call to Foo->amethod and a subroutine to be called after the call. Your subs will receive all the information that Foo->amethod will receive, so you can trace everything between your code and Foo.

METHODS

new($subref_before, $subref_after, $param)

Install subroutines to be called whenever a method from an unknown class is called. It is equivalent to the following code:

  Class::Hook->before($subref_before, $param);
  Class::Hook->after($subref_after, $param);
  Class::Hook->activate();

before($subref, $param)

Install subroutine to be called whenever a call to an unknown class is made. $param will be sent to your $subref if specified &$subref will receive the following parameters:

  ( $param, { class   => $class_or_object,
              method  => $method_called,
              param   => [@params_sent],
              counter => $no_calls_for_this_method } )
or the following parameters if $param undefined

  ({ class   => $class_or_object,
     method  => $method_called,
     param   => [@params_sent],
     counter => $no_calls_for_this_method } )

after($subref, $param)

Install subroutine to be called whenever a call to an unknown class returns. $param will be sent to your $subref if specified. &$subref will receive the following parameters

  ( $param, { class    => $class_or_object,
              method   => $method_called,
              param    => [@params_sent],
              counter  => $no_calls_for_this_method,
              'return' => [@return_values],
              duration => $duration in seconds } )
or the following parameters if $param undefined

  ( { class    => $class_or_object,
      method   => $method_called,
      param    => [@params_sent],
      counter  => $no_calls_for_this_method,
      'return' => [@return_values],
      duration => $duration in seconds } )

activate()

Activates the hooks on methods calls to unknown classes. Your subs before and after will be called at each call to an unknown package.

deactivate()

Stops hooks.

EXAMPLES

  You want to study calls to a class 'Foo'
  ========================================
  main.pl
  =======
  # Don't write 'use Foo;'!
  use Data::Dumper;
  use Class::Hook;
  Class::Hook->new(\&mybefore, \&myafter);

  Foo->new('bla', 'blu');
  Foo->bar( { key1 => 'value1',
              key2 => 'value2'} );
  Foo->xxxx(); # Non existing method

  sub mybefore {
      print "Before called: ".Dumper(\@_);
  }

  sub myafter {
      print "After called: ".Dumper(\@_);
  }


  Foo.pm
  ======
  package Foo;
  sub new {
      my ($class, @param) = @_;
      warn "Foo->new called";
      return bless { 'something' => 'whatever',
                     'init'      => \@param }
                     => $class;
  }

  sub bar {
      warn "Foo->bar called";
      return "Hello from bar";
  }

  1;

CAVEATS

It works only with method calls, not with subroutines calls. Foo->method will work Foo::method will NOT work UNIVSERAL::AUTOLOAD is overriden after Class::Hook->activate() has been called. Expect some strange behaviors if the module you use plays with it.

BUGS

Don't rely on it for production purpose. Has been tested on perl 5.6.0 only and probably will need some update with later perl versions.

AUTHOR

"Pierre Denis" <pierre@itrelease.net>

COPYRIGHT

Copyright (C) 2005, IT Release Ltd. All rights reserved.

This is free software. This software may be modified and/or distributed under the same terms as Perl itself.