Cataly...le::ACL(3pm)

💖 Catalyst::ActionRole::ACL(3pm) 💖

okay bestie, so this is a page from the User Contributed Perl Documentation and it's literally the manual for Catalyst::ActionRole::ACL — a whole module that does user role-based authorization as an action class. yes, an action role. it's giving "who's allowed in the club" energy and honestly? iconic. 🎀

---

✨ NAME ✨

Catalyst::ActionRole::ACL — user role-based authorization action class. periodt. 👑

---

🌸 SYNOPSIS 🌸

 package MyApp::Controller::Foo;
 use Moose;
 use namespace::autoclean;

 BEGIN { extends 'Catalyst::Controller' }

 sub foo
 :Local
 :Does(ACL)
 :RequiresRole(admin)
 :ACLDetachTo(denied)
 {
     my ($self, $c) = @_;
     ...
 }

 sub denied :Private {
     my ($self, $c) = @_;

     $c->res->status('403');
     $c->res->body('Denied!');
 }

look at that little denied sub just sitting there with its 403 like "not today, babe". 💅

---

🦋 DESCRIPTION 🦋

So here's the vibe: this gives you a reusable action role for user role-based authorization. ACLs get applied by assigning attributes to your application's action subroutines. that's it. that's the whole thing. no cap. ✨

---

💜 REQUIRED ATTRIBUTES 💜

heads up bestie: if you forget the required attributes below, you get an exception when the ACL::Role action's constructor is called. so like… don't. 🙈

ACLDetachTo

The name of an action to which the request should be detached if it's determined that the ACLs are not satisfied for this user and the resource he is attempting to access. basically the "you shall not pass" exit door. 🚪

RequiresRole and AllowedRole

The action must include at least one of these attributes — otherwise the Role::ACL constructor will throw an exception. at least one. it's the law. 📜

🍓 Processing of ACLs

• One or more roles may be associated with an action.
• User roles are fetched via the invocation of the context user object's roles method.
• Roles specified with the RequiresRole attribute are checked before roles specified with the AllowedRole attribute.
• The mandatory ACLDetachTo attribute specifies the name of the action to which execution will detach on access violation.
• ACLs may be applied to chained actions so that different roles are required or allowed for each link in the chain (or no roles at all).
• ACLDetachTo allows us to short-circuit traversal of an action chain as soon as access is denied to one of the actions in the chain by its ACL.

🌈 Examples

 # this is an invalid action
 sub broken
 :Local
 :Does(ACL)
 {
     my ($self, $c) = @_;
     ...
 }

This action will cause an exception because it's missing the ACLDetachTo attribute and has neither a RequiresRole nor an AllowedRole attribute. A Role::ACL action must include at least one RequiresRole or AllowedRole attribute. 💀

 sub foo
 :Local
 :Does(ACL)
 :RequiresRole(admin)
 :ACLDetachTo(denied)
 {
     my ($self, $c) = @_;
     ...
 }

This action may only be executed by users with the 'admin' role. 👑

 sub bar :Local
 :Does(ACL)
 :RequiresRole(admin)
 :AllowedRole(editor)
 :AllowedRole(writer)
 :ACLDetachTo(denied)
 {
     my ($self, $c) = @_;
     ...
 }

This action requires that the user has the 'admin' role and either the 'editor' or 'writer' role (or both). 🫶

 sub easy :Local
 :Does(ACL)
 :AllowedRole(admin)
 :AllowedRole(user)
 :ACLDetachTo(denied)
 {
     my ($self, $c) = @_;
     ...
 }

Any user with either the 'admin' or 'user' role may execute this action. easy mode unlocked. ✨

---

🧚 WRAPPED METHODS 🧚

BUILD( $args )

Throws an exception if parameters are missing or invalid. simple as that, bestie.

execute( $controller, $c )

Overrides &Catalyst::Action::execute.

In order for delegation to occur, the context 'user' object must exist (authenticated user) and the can_visit method must return a true value.

See Catalyst::Action. 🔥

can_visit( $c )

Return true if the authenticated user can visit this action.

This method is useful for determining in advance if a user can execute a given action. it's the "let me check the guest list before the party" method. 🎀

---

👑 AUTHOR 👑

David P.C. Wollmann <converter42@gmail.com>

🌟 CONTRIBUTORS 🌟

Converted from an action class to an action role by Tomas Doran (t0m)

💀 BUGS 💀

This is new code. Find the bugs and report them, please. (not me volunteering you, but like… also yes, you. go find them. 🔍)

📜 COPYRIGHT & LICENSE 📜

Copyright 2009 by David P.C. Wollmann

This program 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 was pulled from the User Contributed Perl Documentation, perl v5.32.0, dated 2021-01-06 — so yeah, a lil vintage but still serving. slay responsibly and always check your roles before you detach. mwah. 💅✨🦋