The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


RPC::ExtDirect::API::Hook - Ext.Direct Method wrappers


Hooks are RPC::ExtDirect's way of implementing Method modifiers for the (relatively) rare cases when you need them but don't want to bring in the whole nine yards of Moose.


A hook is a Perl subroutine (can be anonymous, too). Hooks can be of three types:


before hook is called before a Method is invoked, and can be used to change Method arguments or cancel Method execution. This hook must return numeric value 1 to allow Method call. Any other value will be interpreted as an Ext.Direct Result; it will be returned to the client side and the Method never gets called.

Note that RPC::ExtDirect will not make any assumptions about this hook's return value; a false value like '' or 0 will probably not look too helpful from the client side's point of view.

If this hook throws an exception, it will be returned as an Ext.Direct Exception to the client side, and the Method does not execute.


instead hook replaces the Method it is assigned to. It is the hook sub's responsibility to invoke (or not) the Method code and return appropriate Result.

If this hook throws an exception, it is interpreted as if the Method threw it.

This hook is analogous to Moose's around method modifier, except that around would be a bit of a misnomer since the hook code is actually called instead of the Method. Hence the name.


after hook is called after the Method code or instead hook. This hook cannot affect Method execution, it is intended mostly for logging and testing purposes; its input includes Method's Result or Exception.

This hook's return value and thrown exceptions are ignored.


Hooks can be defined on three levels, in order of precedence: Method, Action, and global. For each Method, only one hook of each type can be applied. Hooks specified in Method definition take precedence over all other; if no Method hook is found then Action level hook applies; and if there is no Action hook then global hook gets called, if any.

To avoid using hooks for a particular method, use "NONE" or undef instead of coderef; this way you can specify global and/or Action hooks and exclude some specific Methods piecemeal.

See more in the documentation for the constructor: "new".


Hook subroutine is called as a class method, i.e. first argument is name of the package in which this sub was defined. Ignore it if you don't need it.

Hooks receive a hash of the following arguments:


Ext.Direct Action name for the Method.

DEPRECATED. Use method_ref instead: $method_ref->action


Ext.Direct Method name

DEPRECATED. Use method_ref instead: $method_ref->name


Name of the package (not Action) where the Method is declared

DEPRECATED. Use method_ref instead: $method_ref->package


Coderef to the Method subroutine

DEPRECATED. Use method_ref instead: $method_ref->code


Number of parameters when Method accepts ordered arguments

DEPRECATED. Use method_ref instead: $method_ref->len


Arrayref with names of parameters when Method accepts named arguments

DEPRECATED. Use method_ref instead: $method_ref->params


True if Method handles form submits

DEPRECATED. Use method_ref instead: $method_ref->formHandler


True if Method handles Event poll requests

DEPRECATED. Use method_ref instead: $method_ref->pollHandler


Arrayref with the invocation arguments when Method accepts ordered args, single Environment object for Poll handlers, hashref otherwise.

Note that this is a direct link to the Method's @_ so it is possible to modify the arguments in before hook if you need to.


Environment object for the invocation. Like arg, this is a direct reference to the same object that will be passed to the Method, so it's possible to modify the env object in the before hook.


Coderef to before hook for that Method, or undef

DEPRECATED. Use before_ref instead: $before_ref->code


Coderef to instead hook for that Method, or undef

DEPRECATED. Use instead_ref instead: $instead_ref->code


Coderef to "after" hook for that Method, or undef

DEPRECATED. Use after_ref instead: $after_ref->code


For after hooks, the Result returned by the Method or instead hook, whichever got called. Not defined for before and instead hooks.


For after hooks, an exception ($@) thrown by the Method or instead hook, if any. Not defined for before and instead hooks.


For after hooks, a reference to the actual code called as Method, if any. Can be either the Method code itself, instead hook or undef if the invocation was canceled.


A closure that binds Method coderef to its current arguments, allowing to call it as easily as $params{orig}->()


RPC::ExtDirect::API::Hook provides several public methods:


Class/instance method. Returns the list of supported hook types.


Constructor. Returns a new RPC::ExtDirect::API::Hook object. Accepts named arguments in a hash.



Hook type. This parameter is mandatory.


Hook code. This parameter is mandatory, and it can take one of the following forms:

  • 'NONE' or undef to cancel hook execution for the corresponding type

  • A coderef for the hook sub to run for the corresponding type

  • Package and subroutine address to call at the hook execution time, like 'Foo::Bar::baz'. This allows late code binding without loading the corresponding package early.


Run the hook and return the result. This method accepts named arguments in a hash.



An instance of RPC::ExtDirect::API.

This parameter is mandatory.


An environment object for this hook invocation.

This parameter is mandatory.


Method arguments, either array- or hashref depending on the Method's calling convention.

This parameter is mandatory.


The result of a Method's invocation for an after hook.

This parameter is mandatory for after hooks.


An exception thrown by a Method or a hook. This parameter is only meaningful for after hooks, and is optional.


An instance of RPC::ExtDirect::API::Method.

This parameter is mandatory.


A reference to the code executed for a Method; can be either the Method code, or its instead hook code.

This parameter is mandatory for after hooks.


For RPC::ExtDirect::API::Hook, the following accessor methods are provided:


Return the "type" of this Hook object.


Return the "code" of this Hook object.


Return the package name for the Hook code.


Return the subroutine name for the Hook code. This will yield meaningful result only when "code" was set to a string 'Package::sub'.


Return true if this Hook's code is runnable and can be executed.