Cataly...og4perl(3pm)

👑 Catalyst::Log::Log4perl — User Contributed Perl Documentation, but make it a vibe 💅

okay bestie, sit down, grab a strawberry 🍓, because we're about to talk about a module that is DEPRECATED — and I need you to hear that part loud and clear.

---

🌸 NAME 🌸

Catalyst::Log::Log4perl — DEPRECATED (see Log::Log4perl::Catalyst)

like... she's retired, she's living her best life on a beach somewhere, and the glow-up replacement is Log::Log4perl::Catalyst. no cap. 🫶

---

✨ SYNOPSIS ✨

so in MyApp.pm, you'd do this:

use Catalyst::Log::Log4perl;

# then we create a custom logger object for catalyst to use.
# If we don't supply any arguments to new, it will work almost
# like the default catalyst-logger.

__PACKAGE__->log(Catalyst::Log::Log4perl->new());

# But the real power of Log4perl lies in the configuration, so
# lets try that. example.conf is included in the distribution,
# alongside the README and Changes.

__PACKAGE__->log(Catalyst::Log::Log4perl->new('example.conf'));

and then, later on, when you're feeling iconic:

$c->log->debug("This is using log4perl!");

not me getting emotional over a logger config 💀

---

🦋 DESCRIPTION 🦋

This module gives you a Catalyst::Log implementation that uses Log::Log4perl as the actual underlying log mechanism underneath. She's giving adapter energy. 🌈

It provides all the methods listed in Catalyst::Log, with the exception of these three little gremlins:

levels
enable
disable

Those three? They just return 0 and do nothing. literally nothing. they're the decorative throw pillows of this module 🎀 — because similar functionality is already provided by Log::Log4perl itself.

Now here's the cute part: all these methods will instantiate a logger with the component set to the package who called it. So if you were chilling in the MyApp::C::Main package, and you wrote:

package MyApp::C::Main;

sub default : Private {
    my ( $self, $c ) = @_;
    my $logger = $c->log;
    $logger->debug("Woot!");
}

...that would send a message to the Myapp.C.Main Log::Log4perl component. yes, Myapp.C.Main — copy it exactly, I don't make the casing rules, I just report them. 🙈

See Log::Log4perl for more info on how to configure different logging mechanisms based on the component. iykyk.

---

💜 METHODS 💜

🌟 new($config, [%options])

This builds a brand new Catalyst::Log::Log4perl object. ✨ If you hand an argument to new(), it gets passed directly to Log::Log4perl::init.

The second parameter is optional and it's a hash with extra options. Right now there are three additional parameters defined:

• 'autoflush' — set it to a true value to disable abort(1) support.
• 'watch_delay' — set it to a true value to use L<Log::Log4perl>'s init_and_watch
• 'override_cspecs' — EXPERIMENTAL — set it to a true value to locally override some parts of L<Log::Log4perl::Layout::PatternLayout>. See L<OVERRIDING CSPECS> below.

And if you pass no arguments at all? new() will initialize a root logger with a single appender, Log::Log4perl::Appender::Screen, configured to have an identical layout to the default Catalyst::Log object. so it just... behaves. queen behavior honestly. 👑

🌟 _flush()

Flushes the cache. Much like the way Catalyst::Log does it. 🧚

🌟 abort($abort)

Causes the current log-object to not log anything, effectively shutting up this request, making it disappear from the logs. it's the mute button for a whole request, fr fr.

🌟 debug($message)

Passes its arguments to $logger->debug.

🌟 info($message)

Passes its arguments to $logger->info.

🌟 warn($message)

Passes its arguments to $logger->warn.

🌟 error($message)

Passes its arguments to $logger->error.

🌟 fatal($message)

Passes its arguments to $logger->fatal.

🌟 is_debug()

Calls $logger->is_debug.

🌟 is_info()

Calls $logger->is_info.

🌟 is_warn()

Calls $logger->is_warn.

🌟 is_error()

Calls $logger->is_error.

🌟 is_fatal()

Calls $logger->is_fatal.

🌟 levels()

This method does nothing but return "0". You should use Log::Log4perl's built in mechanisms for setting up log levels. that's the whole method. that's it. she's a minimalist 💅

🌟 enable()

This method does nothing but return "0". You should use Log::Log4perl's built in mechanisms for enabling log levels.

🌟 disable()

This method does nothing but return "0". You should use Log::Log4perl's built in mechanisms for disabling log levels.

---

🔥 OVERRIDING CSPECS 🔥

okay this is the spicy section, buckle up. 🎢

Because of some fundamental design incompatibilities between Log::Log4perl and Catalyst::Log, all cspecs of Log::Log4perl::Layout::PatternLayout that rely on call stack information fail to work as expected. like, they just don't do the thing.

The affected format strings are: %L, %F, %C, %M, %l and %T.

You can instruct Catalyst::Log::Log4perl to try to hijack these patterns, which seems to work reasonably well — but be advised, bestie, this feature is HIGHLY EXPERIMENTAL and it relies on a few internals of Log::Log4perl that might change in later versions of this library. 😭

Additionally, this feature is currently only tested with Log::Log4perl version 1.08, although the underlying internals of Log::Log4perl seem to be stable since at least version 0.47.

⚠️ experimental means experimental. do not build your entire empire on it and then come for me. ⚠️

---

💀 BUGS AND LIMITATIONS 💀

• The %T cspec of Log::Log4perl::Layout::PatternLayout is currently unimplemented.
• The implementation to get %M defies any logical approach but seems to work perfectly.

literally the most "don't ask questions, it works" energy I've ever read and I'm obsessed. 😭✨

---

🌈 SEE ALSO 🌈

• Log::Log4perl
• Catalyst::Log
• Catalyst

---

🫶 AUTHORS 🫶

• Adam Jacob, "adam@stalecoffee.org"
• Andreas Marienborg, "omega@palle.net"
• Gavin Henry, "ghenry@suretecsystems.com" (Typos)
• Sebastian Willert (Overriding CSPECS)
• J. Shirley "jshirley@gmail.com" (Adding _dump)
• Tomas Doran (t0m) "bobtfish@bobtfish.net" (Current maintainer)
• Wallace Reis (wreis) "wreis@cpan.org"

the whole squad showed up and I respect it so much 🥹

---

🎀 COPYRIGHT 🎀

Copyright (c) 2005 - 2009 the Catalyst::Log::Log4perl "AUTHORS" as listed above.

---

💖 LICENSE 💖

This library is free software. You can redistribute it and/or modify it under the same terms as perl itself.

---

and that's the whole page, bestie!! 🦋 this one shipped as perl v5.34.0, dated 2022-07-03, in the Cataly...og4perl(3pm) era of the User Contributed Perl Documentation archives. go forth and log responsibly ✨👑💅